CARLsim
3.0.3
CARLsim: a GPU-accelerated SNN simulator
|
CARLsim currently requires the NVIDIA CUDA parallel computing platform to be installed even if one does not plan to use the GPU implementation. Future version are planned that allow users to run the CPU implementation without having CUDA installed.
CARLsim requires GPUs with a compute capability of 2.0 or higher. To find the compute capability of your device please refer to the CUDA article on Wikipedia.
CARLsim also requires CUDA Toolkit 5.0 or higher. For platform-specific CUDA installation instructions, please navigate to the NVIDIA CUDA Zone.
The rest of the chapter assumes you have successfully installed CUDA on appropriate hardware.
CARLsim has been tested on the following platforms:
Below is the directory layout of the CARLsim source code. All source code of the core library is contained in the directory carlsim
. The sub-directories are key components to the CARLsim simulation library.
The doc
directory contains doxygen-related source files in source
and the pre-compiled HTML version of the documentation in html
.
The projects
directory contains a template for writing your first CARLsim program. Users will start here when they begin writing their first program.
The tools
directory contains a number of CARLsim plugins that may be useful to users such as parameter tuning frameworks, MATLAB scripts, spike generators, and tools for visual stimuli.
To install CARLsim, first download and unzip the zip file from the CARL website. For installation instructions on Linux and Mac OS X platforms, please refer to 1.2.1 Linux / Mac OS X below. For installation instructions on Windows platforms, please refer to 1.2.2 Windows below.
Instructions for Linux/Mac OS X installation assume you are using the Bash shell. Additionally, the GNU GCC compiler collection and GNU Make build environment should be installed. On most platforms, these are already installed by default. After you have unzipped the downloaded CARLsim files, you next have to set installation-specific environment variables such as information about GPU devices, CUDA Toolkit version, and the desired installation location.
The easiest way to set all relevant environment variables is to add the following lines to your ~/.bashrc
file:
The desired installation location of the CARLsim library is specified with the CARLSIM_LIB_DIR
variable. The major and minor compute capability numbers of your CUDA-capable GPU device must be specified by setting the CUDA_MAJOR_NUM
and CUDA_MINOR_NUM
variables, respectively. Next CUDA_INSTALL_PATH
variable must be set. This variable points to where CUDA is installed. Finally, the CUDA Toolkit version must be set with the CARLSIM_CUDAVER
variable. CARLSIM_FASTMATH
(GCC fast-math flag) and CARLSIM_CUOPTLEVEL
(optimization level, disable with value 0, enable with values 1-3) are optional settings.
To make sure these settings go into effect, you can either type:
or close the shell and open another one.
An alternative way to set the required environment variable is to edit the user.mk
file found in the CARLsim root directory. This can be helpful in case multiple users share the same CARLsim installation and want to use global configuration settings. The '=?' sign in user.mk
indicates the value the variable will be assigned if it is not already defined in the ~/.bashrc
. For example, the following line from user.mk
would assign value 5 to environment variable CARLSIM_CUDAVER
if the variable does not already exist:
The CUDA Toolkit version can be found via:
You need only input the major number of the toolkit version (e.g. 6 for 6.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.
For CUDA Toolkits other than version 6.5, the paths above need to be changed accordingly.
After the environment variables have been set, CARLsim can be compiled and installed via:
This is will install the CARLsim library in the location pointed to by CARLSIM_LIB_DIR
(see 1.2.1.1 Environment Variables above).
CARLsim comes with an optional automated parameter tuning framework. For more information about how to install the framework please see Chapter 10: ECJ. Additionally, CARLsim now comes with a regression suite that uses Google Test. For more information on how to use the regression suite, please see Chapter 11: Regression Suite.
CARLsim provides solution files for Microsoft Visual Studio (VS) 2012 and CUDA 5.5. The solution file is called CARLsim.sln
and is located in the CARLsim root directory. In addition, every project, tutorial, and the regression suite have their own .vcxproj projects file in the appropriate directory.
Before building the solution, Configuration
should be set to x64
. Release
should be selected for project executables, and Debug
should be selected for compiling the regression suite.
VS 2012 will then generate all executables (.exe) and the static library (.lib) via "Build Solution".
Newer VS versions will automatically upgrade the solution file (CARLsim.sln
) and all project files (*.vcxproj
). For newer CUDA Toolkit versions, the strings "CUDA 5.5.props" and "CUDA 5.5.targets" that are present in every .vcxproj file have to be manually updated to reflect the right CUDA Toolkit version number.
CARLsim comes with an optional automated parameter tuning framework. For more information about how to install the framework please see Chapter 10: ECJ. Additionally, CARLsim now comes with a regression suite that uses Google Test. For more information on how to use the regression suite, please see Chapter 11: Regression Suite.
A sample "Hello World" project is provided in the projects/hello_world
directory. The project includes a single source file main_hello_world.cpp
that creates a network with two groups, connected with random weights, and can be used as a skeleton to create new projects.
Any output files created by the simulation will be automatically placed in the results/
directory.
All MATLAB scripts should be placed in the scripts/
directory. This directory already contains two MATLAB scripts to aid in using the OAT (see Chapter 9: MATLAB Offline Analysis Toolbox (OAT)). The script initOAT.m
adds the OAT directory to the MATLAB path, whereas demoOAT.m
will open a NetworkMonitor to visualize network activity. Note that for demoOAT.m
to work, the executable must be run first (see 1.3.1.1 Compiling and Running the "Hello World" Project in Linux / Mac OS X and 1.3.2.1 Compiling and Running the "Hello World" Project in Windows below). In order to run the OAT, open MATLAB, change to projects/hello_world/scripts/
, then type:
The "Hello World" project comes with its own Makefile that compiles the file main_hello_world.cpp
and links it with the CARLsim library. The project can be compiled and run with the following set of commands:
Any output files created by the simulation will be automatically placed in the results/
directory. This may include any spike files created by SpikeMonitor, a debug log file, and a network structure file.
All local objects and executables can be deleted via:
All output files, including local objects, executables, and files in the results/
directory can be deleted via:
make distclean
is called, all data files in the results directory will be deleted!The easiest way to create a new project in Linux/Mac OS X is to make a copy of the projects/hello_world/
directory and all its corresponding subdirectories, rename the directory accordingly, and place it alongside hello_world/
in the projects/
directory. Then only minimal changes to the Makefile must be made in order for the project to compile correctly.
The Makefile provided in the directory was made so that users only have to modify a small portion of the file to build a custom project. Below is the modifiable portion of the Makefile:
The USER_MK_PATH
variable points to the user.mk
file in the CARLsim root directory. This file is needed because it contains all necessary compilation and linking flags. If the user.mk
is moved to a different location, the USER_MK_PATH
needs to be updated accordingly.
The name of the project can be changed via variable project
. Whatever string is assigned here will influence the name of the Makefile target as well as the name of the C++ source file. For example, setting project
to "hello_world" will assume that a source file main_hello_world.cpp
exists, and will create an executable called hello_world
.
Finally, files and/or file extensions to be deleted with the make clean
and make distclean
commands can be edited by changing the output
variable.
main_{project name}.cpp
for the Makefile to compile correctly, where {project_name}
is the string assigned to the project
variable in the Makefile.The "Hello World" project comes with its own .vcxproj
project file that has already been added to the CARLsim.sln
solution file. Thus the project can be built simply by opening the CARLsim.sln
solution file in VS, right-clicking the project directory and choosing "Build project".
The easiest way to create new project in Windows is to make a copy of the directory projects/hello_world
and all its corresponding subdirectories, to rename the directory accordingly, and to place it alongside hello_world/
in the projects/
directory. Then only minimal changes to the project and solution file need to be made in order for the project to compile correctly.
First, the project file in the new project directory needs to be named according to the new project name: {project name}.vcxproj
. The C++ source file should be renamed for consistency: main_{project name}.cpp
.
Second, the projects file needs to be added to the CARLsim.sln
solution file.
Then the new project is ready to be built, rebuilt, or cleaned directly through VS.
To uninstall CARLsim on a Unix platform, open a terminal, navigate to the CARLsim root directory, and type:
This will remove the directory pointed to by the environment variable CARLSIM_LIB_DIR
. By default, this variable points to the location "/opt/CARL/CARLsim"
.
~/.bashrc
must be removed manually. CARLSIM_LIB_DIR
is properly set.On Windows, simply move all downloaded and unzipped CARLsim files to the recycle bin.