|
CARLsim
3.1.3
CARLsim: a GPU-accelerated SNN simulator
|
|
CARLsim
3.1.3
CARLsim: a GPU-accelerated SNN simulator
|
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 1.2.1.3 Installing CARLsim Without GPU Support).
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.
helper_cuda.h, which usually resides in /usr/local/cuda/samples/common/inc.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.
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. This will give you a way to access the latest stable and development versions of the code, and allow you to easily update your codebase later on.
This can be done in three steps:
Fork box in the top-right corner.YourUsername is your GitHub user name. Note the –recursive option: It will make sure all external software dependencies get installed (e.g., Google Test).stable branch: master branch.Alternatively, you may download the latest stable release from the GitHub Release page (.zip or .tar.gz).
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.
CARLsim 3 allows configuration via environment variables. The easiest way to set these is to add them to your ~/.bashrc file.
The following options are available:
/usr/local/lib, and CARLsim include files live in /usr/local/include/carlsim. You can overwrite these by exporting an evironment variable called CARLSIM3_INSTALL_DIR: CARLSIM3_NO_CUDA and set it to 1: /usr/local/cuda. If this is not the case on your system, make sure to set adjust an environment variable called CUDA_PATH: /opt/CARL/carlsim_ecj_pti, with the JAR file located at /opt/ecj/jar/ecj.23.jar. If these paths are not correct and you wish to use the Parameter Tuning Interface (see Chapter 10: ECJ), please update your environment variables accordingly: CARLSIM3_COVERAGE: Once you have made changes to your ~/.bashrc, make sure they go into effect by either typing:
or by closing the shell and opening another one.
Older versions of CARLsim used a configuration file called user.mk. This file is obsolete as of CARLsim 3.1.2.
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.
helper_cuda.h, which usually resides in /usr/local/cuda/samples/common/inc.As mentioned above, GPU support can be disabled by exporting an environment variable called CARLSIM3_NO_CUDA and by setting it to 1:
In this case, the NVIDIA CUDA toolkit is not required. But, obviously you will not be able to run CARLsim in GPU_MODE.
When it comes to compiling and installing CARLsim, you have two options:
release version: -O3 and -ffast-math compile flags.debug version: -O0) and enable extensive debug prints (via -g -Wall).-E flag in the commands above, which will cause sudo to remember any environment variables you set above (such as CARLSIM3_INSTALL_DIR and CARLSIM3_NO_CUDA). You don't need this flag if you're not installing with sudo.-j4 flag, which will install CARLsim using four workers. 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 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.
In order to make sure the installation was successful, you can run the regression suite:
For more information on the regression suite, please refer to 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.
1.8.11