Skip to content

Commit

Permalink
Merge pull request #13 from UCI-CARL/fix/fixpack3
Browse files Browse the repository at this point in the history 
* Fixpack3 contains the following fixes and improvements
  • Loading branch information
@kexinchenn
kexinchenn authored Jul 15, 2022
2 parents 70af74a + e996859 commit fcb9c45
Show file tree
Hide file tree
Showing 10 changed files with 401 additions and 310 deletions.
187 changes: 41 additions & 146 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
7 changes: 4 additions & 3 deletions doc/CARLsim.config.doxy
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down Expand Up @@ -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 \
Expand Down
28 changes: 13 additions & 15 deletions doc/CARLsimLayout.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,11 +53,9 @@
<tab type="user" visible="no" title="9.5 Reading Raw Data" url="@ref ch9s5_reading_raw_data"/>
<tab type="user" visible="no" title="9.6 Migrating from CARLsim 2.2" url="@ref ch9s6_migrating_scripts"/>
</tab>
<tab type="usergroup" visible="yes" title="10. ECJ" url="@ref ch10_ecj">
<tab type="user" visible="no" title="10.1 Overview" url="@ref ch10s1_overview"/>
<tab type="user" visible="no" title="10.2 Installation" url="@ref ch10s2_installation"/>
<tab type="user" visible="no" title="10.3 Usage" url="@ref ch10s3_usage"/>
<tab type="user" visible="no" title="10.4 References" url="@ref ch10s4_references"/>
<tab type="usergroup" visible="yes" title="10. Parameter-Tuning ECJ and LEAP" url="@ref ch10_ecj_leap">
<tab type="user" visible="no" title="10.1 Framework Overview" url="@ref ch10s1_overview"/>
<tab type="user" visible="no" title="10.2 References" url="@ref ch10s4_references"/>
</tab>
<tab type="usergroup" visible="yes" title="11. Regression Suite" url="@ref ch11_regression_suite">
<tab type="user" visible="no" title="11.1 Installing Google Test" url="@ref ch11s1_installation"/>
Expand All @@ -76,16 +74,16 @@
<tab type="user" visible="no" title="13.2 Installation" url="@ref ch14s2_installation"/>
<tab type="user" visible="no" title="13.3 Supported Features" url="@ref ch14s3_features"/>
</tab>


<tab type="usergroup" visible="yes" title="20. Neuromodulation" url="@ref ch20_neuromodulation">
<tab type="user" visible="no" title="20.1 Neuromodulators (NM)" url="@ref ch20s1_neuromodulators_overview"/>
<tab type="user" visible="no" title="20.2 NM-ergic targetgroups" url="@ref ch20s2_nm4"/>
<tab type="user" visible="no" title="20.3 PKA/PLC modulated STDP" url="@ref ch20s3_pka_plc_mod"/>
<tab type="user" visible="no" title="20.4 Eligibiity based STDP" url="@ref ch20s4_nmstdp"/>
<tab type="user" visible="no" title="20.5 GRPC impacted STP" url="@ref ch20s5_nm4stp"/>
<tab type="user" visible="no" title="20.6 Nonlinear Excitabilty" url="@ref ch20s6_icalc_nm4w"/>
<tab type="user" visible="no" title="20.7 References" url="@ref ch20s7_references"/>
<tab type="usergroup" visible="yes" title="14. Neuromodulation" url="@ref ch20_neuromodulation">
<tab type="user" visible="no" title="14.1 Neuromodulators (NM)" url="@ref ch20s1_neuromodulators_overview"/>
<tab type="user" visible="no" title="14.2 NM-ergic targetgroups" url="@ref ch20s2_nm4"/>
<tab type="user" visible="no" title="14.3 PKA/PLC modulated STDP" url="@ref ch20s3_pka_plc_stdp"/>
<tab type="user" visible="no" title="14.4 Eligibiity based STDP" url="@ref ch20s4_nmstdp"/>
<tab type="user" visible="no" title="14.5 GRPC impacted STP" url="@ref ch20s5_nm4stp"/>
<tab type="user" visible="no" title="14.6 Nonlinear Excitabilty" url="@ref ch20s6_icalc"/>
<tab type="user" visible="no" title="14.7 Conductance Modulation" url="@ref ch20s7_mcoba"/>
<tab type="user" visible="no" title="14.8 Further readings" url="@ref ch20s8_misc"/>
<tab type="user" visible="no" title="14.9 References" url="@ref ch20s9_references"/>
</tab>

</tab>
Expand Down
6 changes: 3 additions & 3 deletions doc/source/user_guide/10_ecj/chapter10.dox
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions doc/source/user_guide/12_advanced_topics/chapter12.dox
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.


Expand Down
Loading

0 comments on commit fcb9c45

Please sign in to comment.