From e9968596304715f57308540fc175197a74c37ef5 Mon Sep 17 00:00:00 2001 From: larsnm <35173567+larsnm@users.noreply.github.com> Date: Thu, 14 Jul 2022 05:43:26 +0200 Subject: [PATCH] * Fixpack3 contains the following fixes and improvements 1. Updated README.md 2. Updated Gitup Pages (UserGuide, Tutorials) --- README.md | 187 +++------- doc/CARLsim.config.doxy | 7 +- doc/CARLsimLayout.xml | 28 +- doc/source/user_guide/10_ecj/chapter10.dox | 6 +- .../12_advanced_topics/chapter12.dox | 4 +- .../user_guide/1_getting_started/chapter1.dox | 322 ++++++++++++++---- .../1_getting_started/cmake-gui.png | Bin 0 -> 55725 bytes .../20_neuromodulation/chapter20.dox | 105 +++--- .../user_guide/7_monitoring/chapter7.dox | 6 +- doc/source/user_guide/main_page.dox | 46 ++- 10 files changed, 401 insertions(+), 310 deletions(-) create mode 100644 doc/source/user_guide/1_getting_started/cmake-gui.png diff --git a/README.md b/README.md index f77257d2..24dd0c39 100644 --- a/README.md +++ b/README.md @@ -4,119 +4,39 @@ # CARLsim 6 -## Prerequisites +[![Build Status](https://travis-ci.org/UCI-CARL/CARLsim5.svg?branch=master)](https://github.com/UCI-CARL/CARLsim6/actions/runs/1684806099) +[![Coverage Status](https://coveralls.io/repos/github/UCI-CARL/CARLsim4/badge.svg?branch=master)](https://coveralls.io/github/UCI-CARL/CARLsim4?branch=master) +[![Docs](https://img.shields.io/badge/docs-v6.0.0-blue.svg)](http://uci-carl.github.io/CARLsim6) +[![Google group](https://img.shields.io/badge/Google-Discussion%20group-blue.svg)](https://groups.google.com/forum/#!forum/carlsim-snn-simulator) -CARLsim 6 comes with the following requirements: -- CMake 3.20 or higher -- CUDA Toolkit 11.0 or higher. For platform-specific CUDA installation instructions, please navigate to - the [NVIDIA CUDA Zone](https://developer.nvidia.com/cuda-zone). - This is only required if you want to run CARLsim in `GPU_MODE`. Make sure to install the - CUDA samples, too, as CARLsim relies on the file `helper_cuda.h`. -- (optional) A GPU with compute capability 6.0 or higher. To find the compute capability of your device please - refer to the [CUDA article on Wikipedia](http://en.wikipedia.org/wiki/CUDA). - This is only required if you want to run CARLsim in `GPU_MODE`. -- (optional) MATLAB R2014a or Octave. This is only required if you want to use the Offline Analysis Toolbox (OAT). - -If the Prerequisites cannot be met consider using a former version like CARLsim5 or CARLsim4. - - -The latest release was tested on the following platforms: -Linux: Ubuntu 20.04 LTS -Windows: Windows 10 Professional, Windows 11 Education -Mac OS X: -CUDA: 11.2, 11.4, 11.5 -GPUs: Titan Xp, 1080ti, RTX 3090, A100 - -... - - - -# Setup CARLsim6 as data scientist - -## Preliminaries - -This setup guide is intended for data scientists using Linux. -Usually the models and experiments are developed on a workstation having a NVIDIA GeForce -and to be evaluated later on a supercomputer like the DGX A100. -The following preliminaries are derived from the NVIDIA documentation for CUDA 11.5: -1. Linux: Ubuntu 20.04 LTS -2. cMake: 3.22 -3. Google Test: 1.11 - -In this guide, the following file structure is used as a reference for the local development. -Please replace the placeholder user1 with the actual user name: -``` -/home/user1/ - carlsim6/ # local installation CARLsim6 - includes/ - lib/ - samples/ - cmake-3.22/ # local installation of cMake - bin/ - share/ - gtest-1.11/ # local installation of Google Test - inclues/ - lib/ - git/ # cloned repositories from Github - CARLsim6/ - googletest/ -``` - - -## Setup Ubuntu - -Ideally Ubuntu 20.04 LTS Desktop is installed from scratch on the workstation. -For CUDA 11.5 please follow the official [setup guides](https://developer.nvidia.com/cuda-downloads?target_os=Linux&target_arch=x86_64&Distribution=Ubuntu&target_version=20.04&target_type=deb_local). -Also the user should be setup from scratch to avoid any side effects. -While it is technically possible to use multiple CUDA and CARLsim versions side by side -and switching between them utilizing some kind of `setenv.sh` script, -such szenarios also depend strongly on the specific requirements and are therefore out of scope. -A dedicated environment is furthermore essential to find the root cause of potential issues. - -Prepare the .bashrc like the following (replace user1 with the actual user name). -``` -export PATH=/home/user1/cmake-3.22/bin${PATH:+:${PATH}} -export LD_LIBRARY_PATH=/home/user1/gtest-1.11/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} -export LD_LIBRARY_PATH=/home/user1/carlsim6/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} -``` +CARLsim is an efficient, easy-to-use, GPU-accelerated library for simulating large-scale spiking neural network (SNN) models +with a high degree of biological detail. +CARLsim allows execution of networks of Izhikevich spiking neurons with realistic synaptic dynamics on both +generic x86 CPUs and standard off-the-shelf GPUs. +The simulator provides a PyNN-like programming interface in C/C++, +which allows for details and parameters to be specified at the synapse, neuron, and network level. -Validate that the CUDA 11.5 installation has added the following lines: -``` -export PATH=/usr/local/cuda-11.5/bin${PATH:+:${PATH}} -export LD_LIBRARY_PATH=/usr/local/cuda-11.5/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} -``` +New features in CARLsim 6 include: +- CUDA 11 support +- CMake build system +- Neuromodulatory features +- Integration of Python LEAP -Install *pthreads* from the distribution: `sudo apt-get install libpthreads-dev` +If you use CARLsim 6 in your research, please cite this [paper](https://www.socsci.uci.edu/~jkrichma/CARLsim6-IJCNN2022.pdf): +Niedermeier, L., Chen, K., Xing, J., Das, A., Kopsick, J., Scott, E., Sutton, N., Weber, K., Dutt, N., and Krichmar, J.L. (2022). +"CARLsim 6: An Open Source Library for Large-Scale, Biologically Detailed Spiking Neural Network Simulation." +In Proceedings of IEEE International Joint Conference on Neural Networks (IJCNN), (To appear in WCCI IJCNN 2022). -## Setup cMake -Download the latest binary (e.g. 3.22) from Kitware and install it to `/home/user1/cMake-3.22`. +## Quickstart for Linux -Restart the terminal and validate the installation with `cmake --version`. -``` -$ cmake --version -cmake version 3.22.0-rc2 -CMake suite maintained and supported by Kitware (kitware.com/cmake). -``` +Detailed instructions for installing the latest stable release of CARLsim on Linux and Windows +can be found in our [User Guide](http://uci-carl.github.io/CARLsim6/ch1_getting_started.html). -## Setup Google Test +### Build and Install -Clone the latest stable version (e.g. 1.11) of [Googletest at GitHub](https://github.com/google/googletest) and build it from source. - -``` -cd ~/git -git clone https://github.com/google/googletest.git -cd googletest -mkdir .build -cd .build -cmake -DCMAKE_INSTALL_PREFIX=/home/user1/gtest-1.11 -DBUILD_SHARED_LIBS=1 -DGTEST_HAS_PTHREAD=1 -DBUILD_GMOCK=OFF ../. -make install -``` - - -## Setup CARLsim6 ``` cd ~/git @@ -128,56 +48,31 @@ cmake -DCMAKE_INSTALL_PREFIX=/home/user1/carlsim6 -DCMAKE_BUILD_TYPE=Release ../ make install ``` -> Hint: If cmake does not find the *GTest_DIR* set it manually in cmake-gui to `/home/user1/gtest/lib/cmake/GTest`. -> Also, setting the following environment variables in Linux in ~/.bashrc may help (replace user1 with username): -> ``` -> export GTEST_LIBRARY=/home/user1/gtest-1.11/lib/libgtest.a -> export GTEST_MAIN_LIBRARY=/home/user1/gtest-1.11/lib/libgtest_main.a -> export GTEST_ROOT=/home/user1/gtest-1.11/ -> ``` - -Follow the following sequence to repeat builds -``` -make clean -make -j8 -make install -``` - -> Hint: The defaults for cMake are configured to support the latest version of CUDA -> and the current generation of GeForce graphics card (Ampere achritecture). -> Check which compute capability your your GPU actually has and adopt *CARLSIM_CUDA_GENCODE* accordingly -> either in `cmake-gui` or by passing it as a parameter to the CLI. -> E.g. for a Titan Xp the parameter is set by `-DCARLSIM_CUDA_GENCODE=-gencode arch=compute_61,code=sm_61` - - -## Validate the installation +### Run simple SNN simulation Open a new terminal and validate the settings with `env`. Start `~/carlsim6/samples/hello_world` -Run the unit tests, e.g. -``` -cd ~/git/CARLsim6/.build/carlsim/test -./carlsim-tests -``` - -To run all tests in parallel with monitoring the GPU utilization -``` -gnome-terminal -- /bin/sh -c '~/git/CARLsim6/.build/carlsim/test/carlsim-tests;exec bash' & -gnome-terminal -- /bin/sh -c '~/git/CARLsim6/.build/carlsim/test6/carlsim-tests6;exec bash' & -gnome-terminal -- /bin/sh -c '~/git/CARLsim6/.build/carlsim/testadv/carlsim-testsadv --gtest_filter=-*GPU_MultiGPU*;exec bash' & -gnome-terminal -- /bin/sh -c 'nvidia-smi -l 1' & -``` - +## Prerequisites -## Running the samples +CARLsim 6 comes with the following requirements: +- CMake 3.20 or higher +- CUDA Toolkit 11.0 or higher. For platform-specific CUDA installation instructions, please navigate to + the [NVIDIA CUDA Zone](https://developer.nvidia.com/cuda-zone). + This is only required if you want to run CARLsim in `GPU_MODE`. Make sure to install the + CUDA samples, too, as CARLsim relies on the file `helper_cuda.h`. +- (optional) A GPU with compute capability 6.0 or higher. To find the compute capability of your device please + refer to the [CUDA article on Wikipedia](http://en.wikipedia.org/wiki/CUDA). + This is only required if you want to run CARLsim in `GPU_MODE`. +- (optional) MATLAB R2014a or Octave. This is only required if you want to use the Offline Analysis Toolbox (OAT). -The executables of the samples are installed to $CMAKE_INSTALL_PREFIX/carlsim6/samples. -Add the path to the .bashrc to repetitive start it from the bash. -As most of the samples create a result directory or write other files, -create a new working directory to capture the indiviual runs. +If the Prerequisites cannot be met consider using a former version like CARLsim 5 or CARLsim 4. -Alternative the samples can run directly from the build directory. +The latest release was tested on the following platforms: +- Linux: Ubuntu 20.04 LTS +- Windows: Windows 10 Professional, Windows 11 Education +- CUDA: 11.2, 11.4, 11.5, 11.7 +- GPUs: Titan Xp, 1080ti, RTX 3090, A100 diff --git a/doc/CARLsim.config.doxy b/doc/CARLsim.config.doxy index 6c9d806e..3bc618b6 100644 --- a/doc/CARLsim.config.doxy +++ b/doc/CARLsim.config.doxy @@ -684,12 +684,12 @@ INPUT = ../carlsim/interface/inc \ source/user_guide/7_monitoring \ source/user_guide/8_saving_and_loading \ source/user_guide/9_visualization \ - source/user_guide/10_ecj_leap \ + source/user_guide/10_ecj \ source/user_guide/11_regression_suite \ source/user_guide/12_advanced_topics \ source/user_guide/13_example_networks \ source/user_guide/14_pycarl \ - source/user_guide/20_neuromodulation \ + source/user_guide/20_neuromodulation \ source/tutorial/1_basic_concepts/doc \ source/tutorial/2_random_spnet/doc \ source/tutorial/3_plasticity/doc \ @@ -796,10 +796,11 @@ IMAGE_PATH = source/user_guide \ source/user_guide/7_monitoring \ source/user_guide/8_saving_and_loading \ source/user_guide/9_visualization \ - source/user_guide/10_ecj_leap \ + source/user_guide/10_ecj \ source/user_guide/11_regression_suite \ source/user_guide/12_advanced_topics \ source/user_guide/13_example_networks \ + source/user_guide/14_pycarl \ source/user_guide/20_neuromodulation \ source/tutorial/1_basic_concepts/doc \ source/tutorial/2_random_spnet/doc \ diff --git a/doc/CARLsimLayout.xml b/doc/CARLsimLayout.xml index 1ab9b976..50781fcc 100644 --- a/doc/CARLsimLayout.xml +++ b/doc/CARLsimLayout.xml @@ -53,11 +53,9 @@ - - - - - + + + @@ -76,16 +74,16 @@ - - - - - - - - - - + + + + + + + + + + diff --git a/doc/source/user_guide/10_ecj/chapter10.dox b/doc/source/user_guide/10_ecj/chapter10.dox index 619c5f4d..97dc6d45 100644 --- a/doc/source/user_guide/10_ecj/chapter10.dox +++ b/doc/source/user_guide/10_ecj/chapter10.dox @@ -1,10 +1,10 @@ /*! -\page ch10_ecj_leap Chapter 10: ECJ and LEAP +\page ch10_ecj_leap 10. Parameter-Tuning ECJ and LEAP \tableofcontents -\section ch10s1_overview CARLsim-ECJ Parameter-Tuning Framework Overview +\section ch10s1_overview 10.1 Framework Overview CARLsim provides a software interface for exposing the parameters of a model an external process so that they can be automatically tune to maximize some @@ -31,7 +31,7 @@ tree. \since v3.0 -\section ch10_references References +\section ch10_references 10.2 References Scott, E. and Luke, S., ECJ at 20: toward a general metaheuristics toolkit. Proceedings of the Genetic and Evolutionary Computation Conference Companion diff --git a/doc/source/user_guide/12_advanced_topics/chapter12.dox b/doc/source/user_guide/12_advanced_topics/chapter12.dox index 080fff8d..8a7e2ff6 100644 --- a/doc/source/user_guide/12_advanced_topics/chapter12.dox +++ b/doc/source/user_guide/12_advanced_topics/chapter12.dox @@ -98,7 +98,7 @@ CARLsim is now threadsafe so a distinct CARLsim simulation can be run on every G machine. We call simulations using multiple GPUs as multi-GPU simulation, using multiple CPUs as multi-CPU simulation, and using multiple GPUs and CPUs as hybrid simulation. The user can easily control simulations on multiple CPU/GPU by specifying the preferred partition while creating each group. Currently, upto 8 GPUs and 24 CPU cores can be used concurrently in a single simulation. -The available processors are indexed from 0. By default, CARLsim5 places all the neuron groups on CPU 0 partition. +The available processors are indexed from 0. By default, CARLsim places all the neuron groups on CPU 0 partition. The following examples show how to specify the preferred processor for each neuron group For example, to create a group of Izhikevich neurons on a GPU partition using CARLsim::createGroup, simply specify a name (e.g., "exc1"), the number of neurons @@ -118,7 +118,7 @@ Similarly, the following method call creates a LIF neuron group named "inh1" and int gInh1 = sim.createGroupLIF("inh1", 2018, INHIBITORY_NEURON, 3, CPU_CORES); \endcode -An example CARLsim5 simulation using heterogeneous processors (CPU and GPU) and heterogeneous neurons (Izhikevich and LIF) is shown in the lif_izhi_random_spnet +An example CARLsim simulation using heterogeneous processors (CPU and GPU) and heterogeneous neurons (Izhikevich and LIF) is shown in the lif_izhi_random_spnet project under the projects/ directory. The example implements the clasic Izhikevich 80-20 network using LIF neurons and fast spiking Izhikevich neurons. diff --git a/doc/source/user_guide/1_getting_started/chapter1.dox b/doc/source/user_guide/1_getting_started/chapter1.dox index f87838be..b1e43dd5 100644 --- a/doc/source/user_guide/1_getting_started/chapter1.dox +++ b/doc/source/user_guide/1_getting_started/chapter1.dox @@ -8,16 +8,17 @@ \author Kristofor D. Carlson \author Michael Beyeler \author Ting-Shuo Chou +\author Lars Niedermeier CARLsim runs on both generic x86 CPUs and off-the-shelf NVIDIA GPUs. Full support of all CARLsim features requires that the NVIDIA CUDA parallel computing platform be installed. -It is now also possible to compile CARLsim without GPU support (see \ref ch1s2s1s3_compiling). +It is also possible to compile CARLsim without GPU support (see \ref ch1s2s1s3_compiling). -CARLsim requires GPUs with a compute capability of 2.0 or higher. +CARLsim 6 requires GPUs with a compute capability of 5.0 (Maxwell) or higher. To find the compute capability of your device please refer to the CUDA article on Wikipedia. -CARLsim also requires CUDA Toolkit 6.0 or higher. +CARLsim also requires CUDA Toolkit 11.0 or higher. For platform-specific CUDA installation instructions, please navigate to the NVIDIA CUDA Zone. @@ -28,9 +29,14 @@ the file helper_cuda.h, which usually resides in /usr/local/cuda/samples/common/inc. \subsection ch1s1s1_os 1.1.1 Supported Operating Systems -CARLsim has been tested on the following platforms: -- Mac OSX 10.11 -- Ubuntu 16.04 +CARLsim has been tested primarily on the following platforms: +- Ubuntu 20.04 LTS +- Windows 10 Professional, Windows 11 Education +- CUDA 11.2, 11.4, 11.5, 11.7 +- GPUs: Titan Xp, 1080ti, RTX 3090, A100 + +Due to the many possible combinations of operating systems, development stacks, CUDA versions, and GPUs, +the GitHub wiki lists those that were tested by the community as well. \subsection ch1s1s2_os 1.1.2 Source Directory Layout @@ -54,7 +60,9 @@ scripts, spike generators, and tools for visual stimuli. │   ├── kernel # CARLsim core functionality │   ├── monitor # Monitors for groups, connections, spikes, etc. │   ├── server # Utility to implement real-time server functionality -│   └── test # Google test regression suite tests +│   ├── test # Google test regression suite tests +│   ├── test6 # Google test suite for features of version 6 +│   └── testadv # Tests that are long running or require specific hardware ├── doc # CARLsim documentation generation directory │   ├── html # Generated documentation in html │   └── source # Documentation source code @@ -78,8 +86,9 @@ scripts, spike generators, and tools for visual stimuli. \author Kristofor D. Carlson \author Ting-Shuo Chou \author Michael Beyeler +\author Lars Niedermeier -CARLsim is now available on GitHub. +CARLsim is now available on GitHub. If you are familiar with Git and GitHub, the preferred way to obtain the software is to fork and clone the GitHub repository. @@ -89,22 +98,22 @@ and allow you to easily update your codebase later on. This can be done in three steps: -# Navigate to CARLsim's - GitHub page and click on the - Fork box in the + GitHub page and click on the + Fork box in the top-right corner. -# Switch to a terminal (or GitHub Desktop) and clone the repository: \code - $ git clone --recursive https://github.com/UCI-CARL/CARLsim5.git - $ cd CARLsim5 + $ git clone --recursive https://github.com/UCI-CARL/CARLsim6.git + $ cd CARLsim6 \endcode where YourUsername is your GitHub user name. Note the --recursive option: It will make sure all external software dependencies get installed (e.g., Google Test). Alternatively, you may download the latest stable release from the -GitHub Release page (.zip or .tar.gz). +GitHub Release page (.zip or .tar.gz). For installation instructions on Linux and Mac OS X platforms, please refer to \ref ch1s2s1_linux below. For installation instructions on any platform using CMake, refer to \ref ch1s2s2_cmake below. @@ -161,26 +170,254 @@ The CUDA Toolkit version can be found via: $ nvcc --version \endcode You need only input the major number of the toolkit version -(e.g. 7 for 7.5). +(e.g. 11 for 11.5). The compute capability of the GPU device can be found by compiling the deviceQuery sample in the directory 1_Utilities of the CUDA Toolkit. \code # copy NVIDIA Toolkit to home directory $ cd /usr/local/cuda/bin -$ ./cuda-install-samples-9.0.sh ~ -$ cd ~/NVIDIA_CUDA-9.0_Samples/1_Utilities/deviceQuery +$ ./cuda-install-samples-11.0.sh ~ +$ cd ~/NVIDIA_CUDA-11.0_Samples/1_Utilities/deviceQuery # compile and run deviceQuery $ make $ ./deviceQuery \endcode -For CUDA Toolkits other than version 9.0, the paths above need to be changed accordingly. +For CUDA Toolkits other than version 11.0, the paths above need to be changed accordingly. \note Please make sure you install the CUDA SDK samples, as CARLsim relies on the file helper_cuda.h, which usually resides in /usr/local/cuda/samples/common/inc. + +\subsubsection ch1s2s1s3_localdev 1.2.1.3 Setup for local development + +The following information are intended for developers using Linux. +Usually the models and experiments are developed on a workstation having a NVIDIA GeForce +and to be evaluated later on a supercomputer like the DGX A100. +The following preliminaries are derived from the NVIDIA documentation for CUDA 11.5: +-# Linux: Ubuntu 20.04 LTS +-# CMake: 3.22 +-# Google Test: 1.11 + +In this guide, the following file structure is used as a reference for the local development. +Please replace the placeholder user1 with the actual user name: + + ``` + /home/user1/ + carlsim6/ # local installation CARLsim6 + includes/ + lib/ + samples/ + cmake-3.22/ # local installation of CMake + bin/ + share/ + gtest-1.11/ # local installation of Google Test + inclues/ + lib/ + git/ # cloned repositories from Github + CARLsim6/ + googletest/ + ``` + +\subsubsection ch1s2s1s4_ubuntu 1.2.1.4 Setup Ubuntu + +Ideally Ubuntu 20.04 LTS Desktop is installed from scratch on the workstation. +For CUDA 11.5 please follow the official setup guide. +Also the user should be setup from scratch to avoid any side effects. +While it is technically possible to use multiple CUDA and CARLsim versions side by side +and switching between them utilizing some kind of `setenv.sh` script, +such szenarios also depend strongly on the specific requirements and are therefore out of scope. +A dedicated environment is furthermore essential to find the root cause of potential issues. + +Prepare the .bashrc like the following (replace user1 with the actual user name). + + ``` + export PATH=/home/user1/cmake-3.22/bin${PATH:+:${PATH}} + export LD_LIBRARY_PATH=/home/user1/gtest-1.11/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} + export LD_LIBRARY_PATH=/home/user1/carlsim6/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} + ``` + +Validate that the CUDA 11.5 installation has added the following lines: + + ``` + export PATH=/usr/local/cuda-11.5/bin${PATH:+:${PATH}} + export LD_LIBRARY_PATH=/usr/local/cuda-11.5/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} + ``` + +Install *pthreads* from the distribution: `sudo apt-get install libpthreads-dev` + + +\subsubsection ch1s2s1s5_cmake 1.2.1.5 Setup CMake + +Download the latest binary (e.g. 3.22) from Kitware and install it to `/home/user1/CMake-3.22`. + +Restart the terminal and validate the installation with `cmake --version`. + + ``` + $ cmake --version + cmake version 3.22.0-rc2 + CMake suite maintained and supported by Kitware (kitware.com/cmake). + ``` + +\subsubsection ch1s2s1s6_gtest 1.2.1.6 Setup Google Test + +Clone the latest stable version (e.g. 1.11) of Googletest at GitHub +and build it from source. + + ``` + cd ~/git + git clone https://github.com/google/googletest.git + cd googletest + mkdir .build + cd .build + cmake -DCMAKE_INSTALL_PREFIX=/home/user1/gtest-1.11 -DBUILD_SHARED_LIBS=1 -DGTEST_HAS_PTHREAD=1 -DBUILD_GMOCK=OFF ../. + make install + ``` + + +\subsection ch1s2s2_cmake 1.2.2 Build and Install with cMake + +Fast track for experienced users with cMake: + +\code +cd ~/git +git clone https://github.com/UCI-CARL/CARLsim6.git CARLsim6 +cd CARLsim6 +mkdir .build +cd .build +cmake -DCMAKE_INSTALL_PREFIX=/home/user1/carlsim6 -DCMAKE_BUILD_TYPE=Release ../. +make install +\endcode + +First you run cMake to configure with what options CARLsim is to be built. +Then the project files for the desired development environment of the platform +are generated, e.g. gcc on Linux or Visual Studio on Windows. +The configuration is stored in a cache file +and can be either changed by the command line interface (CLI) or +with platform independent graphical user interface cmake-gui. + +\image html cmake-gui.png "Configure CARLsim 6 with CMake-GUI" + +Further information can be found at About CMake. + + +\subsection ch1s2s2s1_cmake 1.2.2.1 Run CMake + + +Create a build directory (you can make it anywhere) + + ``` + $ mkdir + ``` + +Proceed into build directory and do configuration: + + ``` + $ cd + $ cmake \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX= \ + -DCARLSIM_NO_CUDA=OFF \ + + ``` + +As you can see `cmake` accepts several options +`-D=`: +they define cmake variables. + `CMAKE_BUILD_TYPE` +being assigned `Release`, which means that we are going to build release version of the library. +If you need debug version then pass `Debug`. +`CMAKE_INSTALL_PREFIX` +specifies a directory which we are going to install the library into. +`CARLSIM_NO_CUDA` switches on/off support of CUDA inside the library. + +Build: + + ``` + $ cmake --build + ``` + +Install: + + ``` + $ cmake --build --target install + ``` +Alternatively, the library can be built and installed from an IDE, in case you specified the IDE's +CMake Generator +during the configuration step. + + + +\subsubsection ch1s2s2s2_advanced 1.2.2.2 Advanced installation for Linux + + ``` + cd ~/git + git clone --recursive https://github.com/UCI-CARL/CARLsim6.git CARLsim6 + cd CARLsim6 + mkdir .build + cd .build + cmake -DCMAKE_INSTALL_PREFIX=/home/user1/carlsim6 -DCMAKE_BUILD_TYPE=Release ../. + make install + ``` + +> Hint: If cmake does not find the *GTest_DIR* set it manually in cmake-gui to `/home/user1/gtest/lib/cmake/GTest`. +> Also, setting the following environment variables in Linux in ~/.bashrc may help (replace user1 with username): + + ``` + export GTEST_LIBRARY=/home/user1/gtest-1.11/lib/libgtest.a + export GTEST_MAIN_LIBRARY=/home/user1/gtest-1.11/lib/libgtest_main.a + export GTEST_ROOT=/home/user1/gtest-1.11/ + ``` + + +Follow the following sequence to repeat builds + ``` + make clean + make -j8 + make install + ``` + +> Hint: The defaults for CMake are configured to support the latest version of CUDA +> and the current generation of GeForce graphics card (Ampere achritecture). +> Check which compute capability your your GPU actually has and adopt *CARLSIM_CUDA_GENCODE* accordingly +> either in `cmake-gui` or by passing it as a parameter to the CLI. +> E.g. for a Titan Xp the parameter is set by `-DCARLSIM_CUDA_GENCODE=-gencode arch=compute_61,code=sm_61` + + + +\subsubsection ch1s2s2s3_validation 1.2.2.3 Validate the installation + +Open a new terminal and validate the settings with `env`. + +Start `~/carlsim6/samples/hello_world` + +Run the unit tests, e.g. +``` +cd ~/git/CARLsim6/.build/carlsim/test +./carlsim-tests +``` + +To run all tests in parallel with monitoring the GPU utilization +``` +gnome-terminal -- /bin/sh -c '~/git/CARLsim6/.build/carlsim/test/carlsim-tests;exec bash' & +gnome-terminal -- /bin/sh -c '~/git/CARLsim6/.build/carlsim/test6/carlsim-tests6;exec bash' & +gnome-terminal -- /bin/sh -c '~/git/CARLsim6/.build/carlsim/testadv/carlsim-testsadv --gtest_filter=-*GPU_MultiGPU*;exec bash' & +gnome-terminal -- /bin/sh -c 'nvidia-smi -l 1' & +``` + + +\subsubsection ch1s2s2s4_samples 1.2.2.4 Running the samples + +The executables of the samples are installed to $CMAKE_INSTALL_PREFIX/carlsim6/samples. +Add the path to the .bashrc to repetitive start it from the bash. +As most of the samples create a result directory or write other files, +create a new working directory to capture the indiviual runs. + +Alternatively the samples can be run directly from the build directory. + + \subsubsection ch1s2s1s3_compiling 1.2.1.3 Compiling the CARLsim Library When it comes to compiling CARLsim, you have several options: @@ -196,7 +433,7 @@ When it comes to compiling CARLsim, you have several options: This will enable hardware accelerations using the -O3 and -ffast-math compile flags. --# Comiple a debug version: +-# Compile a debug version: \code $ make debug -j4 \endcode @@ -237,7 +474,6 @@ You can increase the number on systems with more than four cores if you wish, or omit the flag if you're working on a single-core machine. - CARLsim comes with an optional automated parameter tuning framework. For more information about how to install the framework please see \ref ch10_ecj. Additionally, CARLsim now comes with a regression suite that uses Google Test. @@ -265,58 +501,10 @@ To run the regression suite, you can type: $ ./carlsim/test/carlsim_tests \endcode - For more information on the regression suite, please refer to \ref ch11_regression_suite. - -\subsection ch1s2s2_cmake 1.2.2 CMake - -Create a build directory (you can make it anywhere) - - ``` - $ mkdir - ``` - -Proceed into build directory and do configuration: - - ``` - $ cd - $ cmake \ - -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_INSTALL_PREFIX= \ - -DCARLSIM_NO_CUDA=OFF \ - - ``` - -As you can see `cmake` accepts several options -`-D=`: -they define cmake variables. - `CMAKE_BUILD_TYPE` -being assigned `Release`, which means that we are going to build release version of the library. -If you need debug version then pass `Debug`. -`CMAKE_INSTALL_PREFIX` -specifies a directory which we are going to install the library into. -`CARLSIM_NO_CUDA` switches on/off support of CUDA inside the library. - -Build: - - ``` - $ cmake --build - ``` - -Install: - - ``` - $ cmake --build --target install - ``` -Alternatively, the library can be built and installed from an IDE, in case you specified the IDE's -CMake Generator -during the configuration step. - - - \section ch1s3_project_workflow 1.3 Project Workflow \author Kristofor D. Carlson \author Ting-Shuo Chou diff --git a/doc/source/user_guide/1_getting_started/cmake-gui.png b/doc/source/user_guide/1_getting_started/cmake-gui.png new file mode 100644 index 0000000000000000000000000000000000000000..1d2ac32ff927b9fc071a2335b3c43bdf576f7bdf GIT binary patch literal 55725 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ΠVIoI}}0Q{ymHL9&_)~y5} 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 Dm@@4; literal 0 HcmV?d00001 diff --git a/doc/source/user_guide/20_neuromodulation/chapter20.dox b/doc/source/user_guide/20_neuromodulation/chapter20.dox index 72dab7a8..7a0a74e8 100644 --- a/doc/source/user_guide/20_neuromodulation/chapter20.dox +++ b/doc/source/user_guide/20_neuromodulation/chapter20.dox @@ -1,8 +1,8 @@ /*! -\page ch20_neuromodulation Chapter 20: Neuromodulation +\page ch20_neuromodulation Chapter 14: Neuromodulation \tableofcontents -\section ch20s1_neuromodulators_overview 20.1 Neuromodulation +\section ch20s1_neuromodulators_overview 14.1 Neuromodulation \author Lars Niedermeier Neuromodulation is the key mechanism in shaping electrophysiological activity. @@ -17,7 +17,7 @@ rather than just excitablitly or synaptic strength (Nadim & Bucher, 2014). \image html Neuromodulation_Fig2a_NadimBucher2014.png "Fig. 1. Neuromodulators can have convergent or divergent actions in a cell. Different modulators can converge on the same pathways to target the same or different ion channel types. One neuromodulator may activate different intracellular pathways depending on the receptor type (Nadim & Bucher, 2014, Fig. 2a, with permission)." -\subsection ch20s1s1 20.1.1 New neuromodulation features with CARLsim 6.0 +\subsection ch20s1s1 14.1.1 New neuromodulation features with CARLsim 6 CARLsim neuromodulation features: - Equal support for the four major neuromodulators (NM4): DA, 5-HT, ACh, NE @@ -39,7 +39,7 @@ Also the existing quality assurance given by the matured unit test suite does ho \since v6.0 -\subsection ch20s1s2 20.1.2 Neuromodulators vs. Neurotransmitters +\subsection ch20s1s2 14.1.2 Neuromodulators vs. Neurotransmitters Neuromodulators (NM) and neurotransmitters (NT) are often used interchageable. @@ -60,13 +60,13 @@ Differences | Affects the group of the post-synaptic neuron | Affects the post-synaptic neuron | | Indirectly effects on the post-synaptic targets via second messengers | Affects the adjected post-synaptic target directly | | dissolves slow | ligand is consumed fast | -| metobtropic, indirect (enzyme) | ionotropic, direct | +| metabotropic, indirect (enzyme) | ionotropic, direct | -\note A NT may become an NM when it does leak out of the synptic cleft. +\note A NT may become an NM when it does leak out of the synaptic cleft. This may happen due to phasic activity of the NM-ergic neuron. -\subsection ch20s13 20.1.3 Receptors +\subsection ch20s13 14.1.3 Receptors Basically the receptor defines, if a ligand acts as a neurotransmitter or a neuromodulator. Receptors can be classified as iontropic and metabotropic (Breedlove & Watson, 2019). @@ -90,7 +90,7 @@ The following table gives a quick overview of the relevant receptors for CARLsim | Peptides | | opiates, neurotensin, and dozens more | many differnt functions | -\subsection ch20s1s4 20.1.4 GPCRs and pathways +\subsection ch20s1s4 14.1.4 GPCRs and pathways As Fig. 1. suggests, the actual processes are far more complicate than originally thought. @@ -103,7 +103,7 @@ Here for instance all known GPCRs can be search by providing the lingand like do The actual effect the NM then has is further defined by its pathways and in which other NMs are in its context. -\subsection ch20s1s5 20.1.5 Summary - Neuromodulators in CARLsim +\subsection ch20s1s5 14.1.5 Summary - Neuromodulators in CARLsim An NM is defined by the following properties that are implemented in CARLsim as follows. @@ -122,15 +122,15 @@ An NM is defined by the following properties that are implemented in CARLsim as \since v6.0 -\section ch20s2_nm4 20.2 NM-ergic targetgroups +\section ch20s2_nm4 14.2 NM-ergic targetgroups \author Lars Niedermeier -\subsection ch20s2s1_example 20.2.1 Target groups of modulatory systems +\subsection ch20s2s1_example 14.2.1 Target groups of modulatory systems In the last decades, the areas in the brain which produces the neuromodulators, like the Substancia Nigra for DA, or the Raphe Nucleus for ACh have been clearly identified. Also the pathways are well understood to which areas the nm-ergic neurons project, for instance the neo cortex. -Furthermore the neuromodury systems is highly interconnected and influence each other, so that the source might also become a target, +Furthermore the neuromodulatory system is highly interconnected and influence each other, so that the source might also become a target, like the Raphe Nucleus projects to VTA (Krichmar 2008, Krichmar & Avery 2017). Such a target area can be modelled by one or more neuron groups depending on the requirements. @@ -139,12 +139,12 @@ An example in which each of the major targed brain areas of a rodent is modelled by a single neuron group is presented in Fig. 2. The amount of neurons had been sized accordingly. -\image html sim_groupMon_krichmar2008_rodent.png "Fig. 2., Example target groups of neuromodulary system (similar to Krichmar, 2008)" +\image html sim_groupMon_krichmar2008_rodent.png "Fig. 2. Example target groups of neuromodulary system (similar to Krichmar, 2008)" \since v6.0 -\subsection ch20s2s2_config 20.2.2 Configuration of targetgroups +\subsection ch20s2s2_config 14.2.2 Configuration of targetgroups Configuration example for nm-ergic target groups \code{.cpp} @@ -193,7 +193,7 @@ Configuration example for nm-ergic target groups \since v6.0 -\section ch20s3_pka_plc_stdp 20.3 PKA/PLC modulated STDP +\section ch20s3_pka_plc_stdp 14.3 PKA/PLC modulated STDP \author Lars Niedermeier Neuromodulators play an important role in long-term potentiation (LTP) and depression (LTD) of mammalian central synapses. @@ -206,7 +206,7 @@ plasticity that seems to be independent of the underlying mechanisms of LTP and \image html Neuromodulation_Fig1b_NadimBucher2014.png "Fig. 3. Modulator controlled LTP/LTD (Nadim & Bucher 2014, Fig. 1b, with permission)." -\subsection ch20s3s1_pka_plc_mod 20.3.1 Dynamic PKA/PLC modulated SDTP +\subsection ch20s3s1_pka_plc_mod 14.3.1 Dynamic PKA/PLC modulated SDTP With CARLsim the PKA/PLC modulation is accomplished not only for the described scenario. The two modulators induce a dynamic adoptation of the learning with seamless transformation of the usually statically configured parameters of STDP. @@ -216,13 +216,13 @@ of the usually statically configured parameters of STDP. \sa \ref ch5s2s1_phenemological_model -\subsection ch20s3s2_configuration 20.3.2 configuration of the PKA/PLC pathways +\subsection ch20s3s2_configuration 14.3.2 configuration of the PKA/PLC pathways Below the configuration of the PKA/PLC pathways as described as shown in the figures. -It is validated with the Unit Test case of STDP where - -\note the actual configuration takes place in a single line by calling the setESDTP interface function -with STDPType PKA_PLC_MOD and just assiging the modulators to PKA/PLC. + +\note It is validated with the Unit Test case of STDP where +the actual configuration takes place in a single line by calling the setESDTP interface function +with STDPType PKA_PLC_MOD and just assigned the modulators to PKA/PLC. \code int nm_pka = NM_NE; @@ -266,13 +266,13 @@ Validation: compare reference against modulated for pre-post and post-pro \since v6.0 -\section ch20s4_nmstdp 20.4 Eligibiity based STDP +\section ch20s4_nmstdp 14.4 Eligibiity based STDP \author Lars Niedermeier -\subsection ch20s4s1_nmstdp_nm4 20.4.1 NM4 support +\subsection ch20s4s1_nmstdp_nm4 14.4.1 NM4 support With CARLsim all four neuromodulator can be configured for eligibility trace -based STDP. Also important to note is, that with CARLsim6 the STDP take now +based STDP. Also important to note is, that with CARLsim 6 the STDP take now place on the connection level (not as before on the group level). This enables a full new range of applications. @@ -292,18 +292,17 @@ enum STDPType { \since v6.0 -\subsection ch20s4s2_nmstdp_mon 20.4.2 NMstdp monitoring OAT +\subsection ch20s4s2_nmstdp_mon 14.4.2 NM-STDP monitoring OAT -For it is essential The OAT was extended to support the monitoring of the DA level and the eligibilit trace the the configured NM (e.g. DA). Please refer to tutorial 9 for more details. -\image html damstdpOAT.png "Fig. 5., Increase of synaptic weight according to reward induced DA." +\image html damstdpOAT.png "Fig. 5. Increase of synaptic weight according to reward induced DA." \since v6.0 -\section ch20s5_nm4stp 20.5 GRPC impacted STP +\section ch20s5_nm4stp 14.5 GRPC impacted STP \author Lars Niedermeier Neuromodulators can also act on short-term synaptic plasticity (STP). @@ -314,7 +313,7 @@ modifying synaptic strength as a function of the frequency of presynaptic activi \image html Neuromodulation_Fig1a_NadimBucher2014.png "Fig. 6. Neuromodulators can target synaptic strength, which modifies the response to a single presynaptic input, as well as short-term synaptic plasticity, which modifies the synaptic efficacy in response to sustained input. These two effects can be functionally opposite (Nadim & Bucher, 2014, Fig 1a, with permission)." -\subsection ch20s5s1_nm4stp 20.5.1 Configuration NM4STP +\subsection ch20s5s1_nm4stp 14.5.1 Configuration NM4STP The configuring of NM4 modulated STP (NM4STP) is shown in a unit test, that validats the NM4STP against static variants. @@ -375,7 +374,7 @@ The configuring of NM4 modulated STP (NM4STP) is shown in a unit test, that vali \since v6.0 -\section ch20s6_icalc 20.6 Nonlinear Excitabilty +\section ch20s6_icalc 14.6 Nonlinear Excitabilty \author Lars Niedermeier Multiple modulators can act on the same synapse to modify its strength, @@ -384,12 +383,12 @@ functionally silence synapses, whereas dopamine can unmask synapses that are nor The combined action of multiple neuromodulators on synapses can be more than simply additive, and the same neuromodulator can have opposing actions on synaptic strength (Nadim & Bucher, 2014). -\image html Neuromodulation_Fig2b_NadimBucher2014.png "Fig. 8. , (Nadim & Bucher, 2014, Fig. 2b, with permission)." +\image html Neuromodulation_Fig2b_NadimBucher2014.png "Fig. 8. Neuromodulators can act on STP (Nadim & Bucher, 2014, Fig. 2b, with permission)." \since v6.0 -\subsection ch20s6s1_icalc_nm4 20.6.1 Neurons as dynamic system +\subsection ch20s6s1_icalc_nm4 14.6.1 Neurons as dynamic system Choosing the right Izhikevich neuron configuration allows modelling of non-linear excitabilty. @@ -404,7 +403,7 @@ The goal of the design is, that the neuron shall implement the transformation fr merely due its input current (following the Izhikevich representation [Simple Model of Spiking Neurons](https://www.izhikevich.org/publications/izhik.pdf) and therefor significantly simplify the algorithmic description "formulas" of the neuromodulated excitability. -\image html optimized_phasic_neuron.png "Fig. 9., Izhikevich neurons, e.g. RS for tonic, optimized variant for phasic crossover." +\image html optimized_phasic_neuron.png "Fig. 9. Izhikevich neurons, e.g. RS for tonic, optimized variant for phasic crossover." The regular spiking neuron (RS) shows linear frequence curve (I_c) that denotes tonic mode. I_c is the constant current for neuron. e.g. neuron[9] receives 9_muA input @@ -417,30 +416,30 @@ The chattering neuron (CH) as a clear cut over at 15 and toggles instananousely Below is the chattering range which can be seen as some mix of tonic and phasic. The custom design (LN) defines a clear tonic mode, that maps more linar with a dedicated -transformation to phasic at 25 but without the hard cut over (Unstetigkeitsstelle) seen at CH. +transformation to phasic at 25 but without the hard cut over (point of discontinuity) seen at CH. \since v6.0 -\subsection ch20s6s2_icalc_phasic 20.6.2 Tonic to phasic crossover with synergistic neuromodulators +\subsection ch20s6s2_icalc_phasic 14.6.2 Tonic to phasic crossover with synergistic neuromodulators -The transmission from tonic to phasic that is essential for attention effort Krichmar2008, .. +The transmission from tonic to phasic that is essential for attention effort as described in Krichmar2008. -\image html nonlinear_excitabilty_1.png "Fig. 10., Nonlinear from tonic to phasic by synergetic NE ACh" +\image html nonlinear_excitabilty_1.png "Fig. 10. Nonlinear from tonic to phasic by synergetic NE ACh" \since v6.0 -\subsection ch20s6s4_icalc_types 20.6.4 IcalcTypes at neuron group level +\subsection ch20s6s4_icalc_types 14.6.4 IcalcTypes at neuron group level CARLsim extends the current calculation for the post synaptic neuron -that was CUBA and COBA in the following ways: +that was CUBA and COBA only before, in the following ways: it now can be configured at neuron group level, for instance one group to CUBA and the other to COBA. Also the conductance parameters can be configured individually on distinct groups to be more bio-realistic. More than that, CARlsim respects now the distinct neuromodulator state in the target neuron group -that affects the receptors and so the the effective input current used by the Izhikevich model. +that affects the receptors so the effective input current used by the Izhikevich model. \code enum IcalcType { @@ -470,20 +469,20 @@ configuring input current calculation of the nm-target groups \since v6.0 -\subsection ch20s6s3_icalc_anta 20.6.3 Example antagonistic neuromodulators +\subsection ch20s6s3_icalc_anta 14.6.3 Example antagonistic neuromodulators Interaction of NE and 5HT -\image html nonlinear_excitabilty_2.png "Fig. 11., Exploration by NE, subression by 5-HT, tonic at eliquibrium" +\image html nonlinear_excitabilty_2.png "Fig. 11. Exploration by NE, subpression by 5-HT, neutralization at eliquibrium" \since v6.0 -\section ch20s7_mcoba 20.7 Conductance Modulation +\section ch20s7_mcoba 14.7 Conductance Modulation \author Lars Niedermeier -\subsection ch20s7s1_m_coba 20.7.1 Example working memory at optimal DA/NE levels +\subsection ch20s7s1_m_coba 14.7.1 Example working memory at optimal DA/NE levels Fig. 12 shows the working memory designed after Avery, Dutt, Krichmar (2013) with dopaminergic receptor D1 and noadrenergic receptors alpha1 and alpha2A. It exposes the same spiking behavior for storing, keeping, and releasing a cue in the deep supragranular layer (layer 3) of the dorsal lateral prefrontal cortex (dlPFC). @@ -491,7 +490,7 @@ The bivariate optimal levels of DA and NE were translated to the descrete normal At 1.0s the spacial information of the cue is simulated by a 500ms Poisson spike train. The activation is kept for 2.5s in the corresponding L3e column and then cleared by a simulated corolliary discharge. -\image html alpha1_da_opt_ne_opt.png "Fig. 12., Working memory at optimal DA/NE levels (similar to Avery, Dutt, Krichmar, 2013)" +\image html alpha1_da_opt_ne_opt.png "Fig. 12. Working memory at optimal DA/NE levels (similar to Avery, Dutt, Krichmar, 2013)" The noadrenergic alpha2A receptor is configured for the recurrent connection by providing its pre- and postsynaptic group and the IcalcType. @@ -515,21 +514,21 @@ The dopaminergic D2 receptor defined by Avery & Krichmar (2015) is configured th Fig. 13 shows the low, optimal, and high implemented a continuous function with stable plateaus with an eps of 1/24 and soft crossovers. -\image html d2_mu_adk15.png "Fig. 13., Continous mapping of D2 discrete levels that were defined by Avery & Krichmar (2015)" +\image html d2_mu_adk15.png "Fig. 13. Continous mapping of D2 discrete levels that were defined by Avery & Krichmar (2015)" \note The configuration of the receptors alpha2A and D1, D2 is at connection level. \since v6.0 -\subsection ch20s7s2_m_coba 20.7.2 Impact of insufficient NE on working memory +\subsection ch20s7s2_m_coba 14.7.2 Impact of insufficient NE on working memory -\image html wm_impacts_by_ne.png "Fig. 14., Impact of insufficient NE on working memory. A) Drain of NE at 2.5s induces memory loss. B) Insufficient NE prevents storing content in memory." +\image html wm_impacts_by_ne.png "Fig. 14. Impact of insufficient NE on working memory. A) Drain of NE at 2.5s induces memory loss. B) Insufficient NE prevents storing content in memory." \since v6.0 -\subsection ch20s7s3_m_coba 20.7.3 Memory impairment due high levels of DA/NE +\subsection ch20s7s3_m_coba 14.7.3 Memory impairment due high levels of DA/NE Stress increases the levels of NE and DA to high levels (e.g. flight and fight situation). The input to neurons of working memory is markable decreased making it functionally disconnect (Avery, Dutt, & Krichmar , 2013) @@ -538,7 +537,7 @@ Fig. 15 shows how the discrete bivariate levels of DA and NE (low, optimum, high are mapped to a grid of 1/3 in a two dimensional normalized space (plane with length 1). For instance, high (optimal) levels of DA and NE are mapped to the field with 5/6 (1/2) as its center marked red (green). -\image html mu_alpha1_da_ne._L3e.png "Fig. 15., Continuous bivariate _mu_alpha1 of L3e fitting discrete bivariate levels" +\image html mu_alpha1_da_ne._L3e.png "Fig. 15. Continuous bivariate _mu_alpha1 of L3e fitting discrete bivariate levels" In order to avoid points of discontinuity (Unstetigkeitsstellen), a continuous function is integrated in CARLsim that fits the experimental data. It is configured by providing the icalctype and @@ -551,13 +550,13 @@ the boost parameter. Fig. 16 shows, how high levels DA and NE at the alpha1 receptor effectively disable the working memory. As _mu_apha1 is bivariate and continuous, a more detailed analysis will be possible of how exactly the working memory will be impared. -\image html alpha1_da_high_ne_high.png "Fig. 16., Impairment of working memory at high levels of DA/NE" +\image html alpha1_da_high_ne_high.png "Fig. 16. Impairment of working memory at high levels of DA/NE" \since v6.0 -\section ch20s8_misc 20.8 Further readings +\section ch20s8_misc 14.8 Further readings \author Lars Niedermeier Farzan Nadim: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4252488 @@ -567,7 +566,7 @@ Dirk Bucher: https://doi.org/10.1016/j.cell.2013.09.047 \br -\section ch20s9_references 20.9 References +\section ch20s9_references 14.9 References Asher*, D.A., Craig*, A.B., Zaldivar*, A., Brewer, A.A., and Krichmar, J.L. (2013). A dynamic, embodied paradigm to investigate the role of serotonin in cost and decision-making. Frontiers in Integrative Neuroscience 7(78). (*co-first authors) diff --git a/doc/source/user_guide/7_monitoring/chapter7.dox b/doc/source/user_guide/7_monitoring/chapter7.dox index 5753170a..852035dd 100644 --- a/doc/source/user_guide/7_monitoring/chapter7.dox +++ b/doc/source/user_guide/7_monitoring/chapter7.dox @@ -350,11 +350,11 @@ NeuronMonitor* spkMon = sim.setNeuronMonitor(g0,"DEFAULT"); \subsection ch7s3s3_setting_up 7.3.3 Neuron State Information Data Neuron state information can be accessed with the following functions: \code -# Voltage information +// Voltage information std::vector< std::vector< float > > vectorV = spkMon->getVectorV(); -# Current information +// Current information std::vector< std::vector< float > > vectorI = spkMon->getVectorI(); -# Refactory variable +// Refactory variable std::vector< std::vector< float > > vectorU = spkMon->getVectorU(); \endcode diff --git a/doc/source/user_guide/main_page.dox b/doc/source/user_guide/main_page.dox index fed2b832..c2ad43b1 100644 --- a/doc/source/user_guide/main_page.dox +++ b/doc/source/user_guide/main_page.dox @@ -3,7 +3,7 @@ \tableofcontents -\section main_carlsim CARLsim5 +\section main_carlsim CARLsim 6 CARLsim is an efficient, easy-to-use, GPU-accelerated library for simulating large-scale spiking neural network (SNN) models with a high degree of biological detail. CARLsim allows execution of networks of Izhikevich spiking neurons with realistic synaptic dynamics @@ -11,33 +11,32 @@ on both generic x86 CPUs and standard off-the-shelf GPUs. The simulator provides a PyNN-like programming interface (C/C++), which allows for details and parameters to be specified at the synapse, neuron, and network level. -The present release, CARLsim5, builds on the efficiency and scalability of earlier releases (Nageswaran et al., 2009; -Richert et al., 2011). +The present release, CARLsim 6, builds on the efficiency and scalability of releases 4 and 5. The functionality of the simulator has been greatly expanded by the addition of a number of features that enable and simplify the creation, tuning, and simulation of complex networks with spatial structure. -All software is available on the -CARL Website. - New features include: -- a python interface pyCARL (see https://arxiv.org/abs/2003.09696) -- improved saving and loading of neural networks (see \ref ch8_saving_and_loading) -- adjusted platform compatibility (Linux, Mac OS X) -- real-time and offline data analysis tools (see \ref ch7_monitoring and \ref ch9_matlab_oat) -- a more complete STDP implementation which includes neuromodulatory mechanisms (see \ref ch5_synaptic_plasticity) -- an automated parameter tuning interface that utilizes evolutionary algorithms to construct functional SNNs - (see \ref ch10_ecj) -- a test suite for functional code verification (see \ref ch11_regression_suite) +- CUDA 11 support and cMake build system (see \ref ch1_getting_started) +- Neuromodulatory features (see \ref ch20_neuromodulation) +- Automated parameter tuning interface that utilizes evolutionary algorithms for Python (LEAP) + (see \ref ch10_ecj_leap) +- Extended test suite for functional code verification (see \ref ch11_regression_suite) + +All software is available on GitHub. +The project is managed by CARL, +the Cognitive Anteater Robotics Laboratory +of the departments Cognitive Sciences and Computer Science, University of California, Irvine. The simulator was first introduced in 2009 (now referred to as CARLsim_v1.0), where it demonstrated near real-time performance for 100,000 spiking neurons on a single NVIDIA GTX 280 (Nageswaran et al., 2009). CARLsim_v2.0 added basic support for synaptic conductances, spike-timing dependent plasticity (STDP), -and short-term plasticity (STP) (Richert et al., 2011). -The present release, CARLsim3, greatly expands the functionality of the simulator by adding a number of features -that enable and simplify the creation, tuning, and simulation of complex networks with spatial structure. +and short-term plasticity (STP) (Richert et al., 2011). CARLsim_v3.1 supported CUDA 7, +9-parameter Izhikevich, Runge-Kutta integration method (Beyeler et. al., 2014) and intergrated ECJ from George Mason University. +CARLsim_v4.0 allowed to run SNNs on multiple GPU cards and/or multiple CPU cores (Chou, Kashyap, et. al, 2018). +CARLsim_v5.0 integrateed PyCARL from Drexel University (Balaji et. al., 2020). CARLsim was originally written by Jayram Moorkanikara Nageswaran and Micah Richert. The code is now being -maintained and extended by Hirak Kashyap, Jinwei Xing and Kexin Chen. For a full list of contributors, +maintained and extended by Lars Niedermeier, Jinwei Xing and Kexin Chen. For a full list of contributors, see file AUTHORS. @@ -58,6 +57,17 @@ Info mailing list. The simulator—along with its various releases, computational studies, and sample code—has previously been published in the following studies: + +- Niedermeier, L., Chen, K., Xing, J., Das, A., Kopsick, J., Scott, E., Sutton, N., Weber, K., Dutt, N., and Krichmar, J.L. (2022). + CARLsim6: An Open Source Library for Large-Scale, Biologically Detailed Spiking Neural Network Simulation. + (To appear in WCCI IJCNN 2022) (CARLsim_6.0) +- Balaji, A., Adiraju, P., Kashyap, H. J., Das, A., Krichmar, J. L., Dutt, N. D., & Catthoor, F. (2020). + PyCARL: A PyNN Interface for Hardware-Software Co-Simulation of Spiking Neural Network. arXiv preprint arXiv:2003.09696. + (To appear in IJCNN 2020) (CARLsim_v5.0) +- Chou, T.-S.*, Kashyap, H.J.*, Xing, J., Listopad, S., Rounds, E., Beyeler, M., Dutt, N., and Krichmar, J.L. (2018). + CARLsim4: An Open Source Library for Large Scale, Biologically Detailed Spiking Neural Network Simulation using + Heterogeneous Clusters. Paper presented at: International Joint Conference on Neural Networks (Rio de Janeiro, Brazil). + (*equal contribution) (CARLsim_v4.0) - Beyeler*, M., Carlson*, K.D., Chou*, T.S., Dutt, N., and Krichmar, J.L. (2014). CARLsim3: A user-friendly and highly optimized library for the creation of neurobiologically detailed spiking neural networks. IEEE International Joint Conference on Neural Networks. (*co-first authors)