CARLsim  3.0.3
CARLsim: a GPU-accelerated SNN simulator
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Chapter 1: Getting Started

1.1 Pre-Installation

Author
Kristofor D. Carlson

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.

1.1.1 Supported Operating Systems

CARLsim has been tested on the following platforms:

  • Windows 7
  • Ubuntu 12.04
  • Ubuntu 12.10
  • Ubuntu 13.04
  • Ubuntu 13.10
  • Ubuntu 14.04
  • Arch Linux
  • CentOS 6
  • OpenSUSE 13.1
  • Mac OS X

1.1.2 Source Directory Layout

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 # CARLsim source code directory
│   ├── connection_monitor # Utility to record synaptic data
│   ├── group_monitor # Utility to record neuron group data
│   ├── interface # CARLsim interface (public user interface)
│   ├── kernel # CARLsim core functionality
│   ├── server # Utility to implement real-time server functionality
│   ├── spike_monitor # Utility to record neuron spike data
│   └── test # Google test regression suite tests
├── doc # CARLsim documentation generation directory
│   ├── html # Generated documentation in html
│   └── source # Documentation source code
├── projects # User projects directory
│   └── hello_world # Project template for new users
└── tools # CARLsim tools that are not built-in
    ├── ecj_pti # Automated parameter-tuning interface using ECJ
    ├── eo_pti # Automated parameter-tuning interface using EO (deprecated)
    ├── offline_analysis_toolbox # Collection of MATLAB scripts for data analysis
    ├── simple_weight_tuner # Simple weight parameter-tuning tool
    ├── spike_generators # Collection of input spike generation tools
    └── visual_stimulus # Collection of MATLAB/CARLsim tools for visual stimuli
Since
v3.0

1.2 Installation

Author
Kristofor D. Carlson
Ting-Shuo Chou
Michael Beyeler

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.

1.2.1 Linux / Mac OS X

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.

1.2.1.1 Environment Variables

The easiest way to set all relevant environment variables is to add the following lines to your ~/.bashrc file:

# CARLsim mandatory variables
export CARLSIM_LIB_DIR=/opt/CARL/CARLsim
export CUDA_INSTALL_PATH=/usr/local/cuda
export CARLSIM_CUDAVER=6
export CUDA_MAJOR_NUM=3
export CUDA_MINOR_NUM=5
# CARLsim optional variables
export CARLSIM_FASTMATH=0
export CARLSIM_CUOPTLEVEL=3

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:

$ source ~/.bashrc

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:

CARLSIM_CUDAVER ?= 5

1.2.1.2 Finding CUDA Toolkit Version and Compute Capability

The CUDA Toolkit version can be found via:

$ nvcc --version

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.

# copy NVIDIA Toolkit to home directory
$ cd /usr/local/cuda/bin
$ ./cuda-install-samples-6.5.sh ~
$ cd ~/NVIDIA_CUDA-6.5_Samples/1_Utilities/deviceQuery
# compile and run deviceQuery
$ make
$ ./deviceQuery

For CUDA Toolkits other than version 6.5, the paths above need to be changed accordingly.

1.2.1.3 Compiling the CARLsim Library

After the environment variables have been set, CARLsim can be compiled and installed via:

$ make
$ sudo make install

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.

Since
v3.0

1.2.2 Windows

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.

1.3 Project Workflow

Author
Kristofor D. Carlson
Ting-Shuo Chou

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:

>> initOAT % adds OAT relative path to MATLAB paths
>> demoOAT % opens a NetworkMonitor on the simulation file

1.3.1 Linux / Mac OS X

1.3.1.1 Compiling and Running the "Hello World" Project in Linux / Mac OS X

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:

$ cd projects/hello_world
$ make
$ ./hello_world

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:

$ make clean

All output files, including local objects, executables, and files in the results/ directory can be deleted via:

$ make distclean
Warning
When make distclean is called, all data files in the results directory will be deleted!

1.3.1.2 Creating a New Project in Linux / Mac OS X

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:

# Makefile for building project program from the CARLsim library
# NOTE: if you are compiling your code in a directory different from
# examples/<example_name> or projects/<project_name> then you need to either
# move the configured user.mk file to this directory or set the path to
# where CARLsim can find the user.mk.
USER_MK_PATH = ../../
include $(USER_MK_PATH)user.mk
project := hello_world
output := *.dot *.dat *.log *.csv

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.

Note
The C++ source file must be named main_{project name}.cpp for the Makefile to compile correctly, where {project_name} is the string assigned to the project variable in the Makefile.

1.3.2 Windows

1.3.2.1 Compiling and Running the "Hello World" Project in Windows

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".

1.3.2.2 Creating a New Project in Windows

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.

Since
v3.0

1.4 Uninstallation

Author
Michael Beyeler

1.4.1 Linux / Mac OS X

To uninstall CARLsim on a Unix platform, open a terminal, navigate to the CARLsim root directory, and type:

$ sudo make uninstall

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".

Note
Any environments that have been added to ~/.bashrc must be removed manually.
Attention
Before uninstalling, make sure that the environment variable CARLSIM_LIB_DIR is properly set.

1.4.2 Windows

On Windows, simply move all downloaded and unzipped CARLsim files to the recycle bin.