Home
Multiple simulation architectures:
- Single-threaded
- Multi-threaded
- GPU (CUDA)
- GPU (AMP)
- GPU (OpenMP) --not yet implemented--
- GPU (IOCP) --not yet implemented--
- GPU (OpenCL) --not yet implemented--
Supported operating systems:
- Microsoft Windows
- Linux Distributions
Tools
- GitHub
- MATLAB
Running the simulator
Upon downloading and extracting the contents of the project, the following steps should be followed to run the simulation.
- In a terminal window, navigate to the main project folder.
- Run the make growth the command
./growth -t <input file>where<input file>is the full address of the configuration file, examples of which were in theconfigfolder. - The program will then run and display the current step and epoc of the simulation. The output of the simulation (after the end of the simulation) will be saved in the
outputfolder. - If you wish to provide the output file name on the command line, you can use this syntax:
./growth -t <input file> -o <output file>. - “-w” option specifies the name of an output file, which saves the memory image of neurons, synapses, firing rate, and radii of the final state.
- “-r” option specifies the name of an input files, which was saved by “-w” option. When the option is added, the simulator restores the previous state and continues simulation.
- “-d” option is for the GPU version only, and specifies the device ID of GPU.
- “-s” option specifies the name of stimulus input file that provides parameters for external stimulus input.
Advanced Use
Use of the UNIX command |screen| is recommended in order to allow the process to run in the background. As the simulation is running, the |Ctrl+A and D| keys will detach the currently running screen. The simulation will continue running in the background, while recording the output of the simulation to the seperate screen. At this point the user is free to log out of the machine. To resume viewing the seperate screen, log back into the machine and use the command |screen -r|. This reattaches the screen. As you might imagine using the unix |screen| tool is essential to running the simulation on a remote machine.
For advanced users, the GCC compiler offers multiple optimization options that may provide some additional speed boost for the CPU-side simulation. It is recommended that, for each level of optimization, the output be verified against less optimized output. The BrainGrid team DOES NOT recommend using any optimization levels above -02. This level of optimization seems to be unstable, and does not seem to maintain consistent output results.
Microsoft Windows
TODO
File Formats
Configuration File
- The configuration file provides simulation parameters, the name of the output file, and the name of layout files.
- The name of the output file is specified in
OutputParams stateOutputFileName. - The extension of the output file might be ".xml" or ".h5", and xml or hdf5 format of the output file will be generated.
- The name of layout files for active, inhibitory, and probed (optional) neurons lists are specified in
LayoutFiles activeNListFileName, inhNListFileName, and probedNListFileNamerespectively. - Following is an example.
<?xml version="1.0" standalone=no?>
<!-- Parameter file for for the DCT growth modeling -->
<!-- This file holds constants, not state information -->
<SimParams>
<!-- Parameters for LSM -->
<LsmParams frac_EXC="0.9" starter_neurons="0.10"/>
<!-- size of pool of neurons [x y z] -->
<PoolSize x="10" y="10" z="1"/>
<!-- Interval of constant injected current -->
<Iinject min="13.5e-09" max="13.5e-09"/>
<!-- Interval of STD of (gaussian) noise current -->
<Inoise min="1.0e-09" max="1.5e-09"/>
<!-- Interval of firing threshold -->
<Vthresh min="15.0e-03" max="15.0e-03"/>
<!-- Interval of asymptotic voltage -->
<Vresting min="0.0" max="0.0"/>
<!-- Interval of reset voltage -->
<Vreset min="13.5e-03" max="13.5e-03"/>
<!-- Interval of initial membrance voltage -->
<Vinit min="13.0e-03" max="13.0e-03"/>
<!-- Starter firing threshold -->
<starter_vthresh min="13.565e-3" max="13.655e-3"/>
<!-- Starter reset voltage -->
<starter_vreset min="13.0e-3" max="13.0e-3"/>
<!-- Growth parameters -->
<GrowthParams epsilon="0.60" beta="0.10" rho="0.0001" targetRate="1.0" minRadius="0.1" startRadius="0.4"/>
<!-- Simulation Parameters -->
<SimParams Tsim="100.0" numSims="600" maxFiringRate="200" maxSynapsesPerNeuron="200"/>
<OutputParams stateOutputFileName="results/tR_1.0--fE_0.90_historyDump.xml"/>
<!-- Random seed - set to zero to use /dev/random -->
<Seed value="1" />
<!-- If FixedLayout is present, the grid will be laid out according to the positions below, rather than randomly based on LsmParams -->
<FixedLayout>
<LayoutFiles activeNListFileName="NList/activeNList_0.10.xml" inhNListFileName="NList/inhNList_0.90.xml"
probedNListFileName="NList/probedNList.xml"/>
</FixedLayout>
</SimParams>
Stimulus Input File
- Stimulus input parameters are specified by a stimulus input parameter file (xml format), which is specified by ‘-s’ option.
- In the file, stimulus input method is specified.
- Currently, two stimulus methods, SInputRegular and SInputPoisson, are implemented.
- For the SInputRegular stimulus input method, the stimulus input is a sequence of pulses, which are defined by duration, interval, sync, wave or async, and values.
- For the SInputPoisson stimulus input method, the stimulus input is a Poisson spike train injected to input synapse layer, which is defined by mean firing rate, synaptic weight, and a mask (optional).
- Followings are examples.
<?xml version="1.0" standalone=no?>
<!-- Parameter file for the timulus input -->
<!-- The stimulus input is a seaqunce of pulses, which are defined by duration, interval, and values -->
<InputParams>
<!-- Input Method -->
<IMethod name="SInputRegular"/>
<!-- duration and interval in second -->
<IntParams duration="0.010" interval="0.990" sync="no"/>
<!-- values in ampere -->
<!-- The 10x10 values are used to fill NxN neurons matrix -->
<!-- 0 1 2 3 4 5 6 7 8 9 -->
<Values>
<I>
0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0.0 0.0 0.0 1e-8 0.0 0.0 0.0 1e-8 0.0 0.0
0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0.0 0.0 1e-8 0.0 0.0 0.0 0.0 1e-8 0.0 0.0
0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
</I>
</Values>
</InputParams>
<?xml version="1.0" standalone=no?>
<!-- Parameter file for the stimulus input -->
<!-- The stimulus input is a Poisson spike train, which are defined by mean firing rate, and synapse weight -->
<InputParams>
<!-- Input Method -->
<IMethod name="SInputPoisson"/>
<!-- mean firing rate and synapse weight -->
<IntParams fr_mean="100" weight="25"/>
<!-- optional mask that is a list of neurons. Only specified neurons will get stimulus input -->
<Masks>
<LayoutFiles maskNListFileName="SInputPoisson/maskNList.xml" />
</Masks>
</InputParams>
This installation guideline will assume that you are using Ubuntu as your primary Linux (sorry, GNU/Linux) operating system. The basic steps however, should translate across most distros.
- Download CUDA from nVidia
- Install any needed libraries and tools (e.g. gcc, linux-source, etc.)
- Install nVidia Driver
- Update your PATH, and LD_LIBRARY_PATH prior to installing
- Install CUDA
GitHub is a source-control system oriented towards the open source community. It offers multiple different >features that are advantageous for the project, the most important of which the ability to manage multiple >separate versions of the project’s code. This allows the project’s developers the ability to tackle >multiple different features and/or bugs.
In order to use GitHub, several tools have been released. The Microsoft Windows, Apple Macintosh software >are available on their website. On Linux distributions, the console is used to manipulate code. As such, >the following are instructions on how to install and use GitHub on Linux distributions, focusing on the >Ubuntu variety. These instructions assume that the user has already registered with GitHub.
First, the operating system must be updated, and then use apt-get to install GitHub:
sudo apt-get update
sudo apt-get install git
Next, the username and email settings must be configured properly.
git config --global user.name <USERNAME HERE>
git config --global user.email <EMAIL HERE>
This is when the source code needs to be downloaded from the remote repository. Navigate to the folder where the source code is to be held:
git clone git://github.com/UWB-Biocomputing/BrainGrid.git
Once the source code is downloaded, the BrainGrid subfolder will be where all the code modifications will occur. Navigate to this subfolder, and use:
git branch -r
To view the multiple available remote branches (different variations of the code that exist outside the local computer). The GitHub webpage will contain more information about each branch, and how the source code varies in between them. In order to checkout a remote branch, use:
git branch <LOCAL NAME> origin/<REMOTE BRANCH NAME>
Where \verb|| is the name that will represent the local copy of the code. Once this is done, switching in between different local branches can be done by using:
git checkout <LOCAL NAME>
To update a local branch with code on the remote version of the branch, use:
git pull
To save the modifications to the local branch, use:
git commit -a -m "`<MESSAGE HERE>"'
To move those changes to the remote branch, use:
git push
Note that Git will prompt the user for additional information.
Additional information can be found here:
Git Crash Course
MatLab
For users with MathWork's MATLAB, a subfolder is included with the some sample files that correctly parse BrainGrid's output for use in MATLAB. The project currently only supports output generation during the end of the simulation, but pseudo real-time output may be implemented in the future.
Linux Crash Course
Getting Things Running
Udacity Introduction to Parallel Programming
Udacity Introduction to Parallel Programming Wiki
- What Is BrainGrid?
- What Is BrainGrid For?
- What Problem Does BrainGrid Solve?
- What Scientific Principles Underlie BrainGrid?
- How Does BrainGrid Accomplish Its Goals?
- What are the limitations?
BrainGrid is an open-source spiking neural network simulator that is intended to aid scientists and researchers by providing prebuilt code that can be easily modified to fit different models. The program also offers the ability to easily transition to a GPU-centered model with little additional work, which can provide a potential speedup of up to a twentieth of the original runtime.
## What Is BrainGrid For?BrainGrid is designed to do the following:
- Simulate spiking neural networks with built-in models (leaky integrate and fire, Izhikevich)
- Provide a framework to make it easier to code models of your own
- Make these models FAST - provide code to make it easy to migrate models to single or multiple GPUs, providing a huge speedup from single or multi-threaded host-side models.
BrainGrid is a framework for quickly implementing potentially GPU-sped-up spiking neural networks. If you have a mathematical model for a spiking neural network, or if you have an idea for one, BrainGrid will provide you with a quick way of getting that network implemented in code and running on CPUs or GPUs.
## What Scientific Principles Underlie BrainGrid?
BrainGrid is a framework for spiking neural networks, which are neural networks in which the neurons model differential equations to mimic biological activity. Specifically, the differential equations that model these neurons model their activity over time such that, in a given time bin, the neuron either spikes (fires an action potential) or doesn't.
## How Does BrainGrid Accomplish Its Goals?BrainGrid does this by: * Learn more about How It Works and How To Use.
## LimitationsAlthough BrainGrid is designed to be easy to use and fast to simulate with, it does have some limitations:
- First, and perhaps most importantly: it uses CUDA for GPU coding. So if you want to use BrainGrid for migrating your model to a GPU, your GPU HAS TO BE NVIDIA. And the GPU has to be CUDA compliant. Check NVIDIA's website for an up-to-date list of CUDA-compliant devices: https://developer.nvidia.com/cuda-gpus.
- Second, the shape of the network has to be a two-dimensional rectangle. No 3D model support quite yet, and no irregular webs or cones, etc., just good old-fashioned rectangular networks of neurons.