View on GitHub

BrainGrid

A project to facilitate construction of high-performance neural simulations

3. Quickstart

3.1 Quick Sanity Test

As a quick start and sanity test, let’s run a small, prepackaged simulation to make sure everything is good to go.

In a terminal window, navigate to the main project folder
```
$ cd YOUR_PATH_TO_BRAINGRID/BrainGrid
```
Unless you have the necessary HDF5 stuff installed, go into the Makefile and set the conditional flag CUSEHDF5 to “no” to use default XML output. Set to “yes” if you wish to use HDF5. See the snippet of Makefile below:
```
################################################################################
# Conditional Flags
# -----------------------------------------------------------------------------
# CUSEHDF5:	 yes - use hdf5 file format 
#		 	 no  - use default xml 
# CPMETRICS: yes - see performance of large function calls  
#		 	 no  - not showing performance results
################################################################################
CUSEHDF5 = no
CPMETRICS = yes
```
- HDF5 is useful for making the data analysis easier for Matlab, which has native HDF5 support, after a simulation - especially a very long one; but it is fine to use the default XML output.
- If you like to use HDF5 or have issues with using HDF5, see Using BrainGrid with HDF5
!!! Note: Make sure your output file extension in the configuration file (under BrainGrid/configfiles/) matches your choice of CUSEHDF5 flag. Otherwise an error will be thrown upon compilation.

For example, if you are using HDF5, the output file extension should be .h5 instead of .xml. At runtime, the simulator will select the output format based on the filename extension. So, the compile flag merely builds in support for HDF5; the filename is what selects which format will actually be used.
```
<OutputParams name="OutputParams">
  <stateOutputFileName name="stateOutputFileName">results/static_izh_historyDump.h5
  </stateOutputFileName>
</OutputParams>
```
The details of configuration file will be discussed in the next section 4. Configuration.
Compile the single threaded version
```
$ make growth
```
Compile the GPU version:
```
$ make growth_cuda
```

Run it with one of our numerous test files

$ ./growth -t ./configfiles/test-small.xml

or run with GPU support:

$ ./growth_cuda -t ./configfiles/test-small.xml

or run in multithreaded mode:

$ ./growth -c # -t ./configfiles/test-small.xml

The program will then run and display the current step and epoch of the simulation. The output of the simulation (after the end of the simulation) will be saved in the output folder.

The run time of this test is small-ish on a fast computer (maybe a couple minutes), but this particular test also doesn’t do much. The output will be mostly nothing - but it shouldn’t crash or give you anything weird.

If you want to run a real test, you could use test-small-connected.xml, but be noted that using the single threaded version of this (or any larger test) will result in hours of waiting, but the output will be much more interesting. You can take a look at the next section on Screen for how to deal with these wait times.

3.2 Use of Screen

When you run a simulation with BrainGrid, you may not want to wait around for it to run to completion. This is especially true if running it remotely. To help with this, you can use the built in screen command in Linux.

The screen command will essentially allow you to start a simulation and then detach it so that it runs in the background. This has the huge advantage of allowing you to log out of the server you are remotely connected to. Here is how:

Before running the simulation, start a screen by typing:
```
$ screen
```

Start the Simulation

$ ./growth -t ./configfiles/test-small-connected.xml

Detach the screen by pressing the following key combinations: "Ctrl+A" then "Ctrl+D"
Allow the simulation to run as long as you want. During this time, you can log out without any problem.
Reattach the screen whenever you want to check in on it.
```
$ screen -r
```
If it isn’t done yet, detach again and come back later.

» Next: 4. Configuration

« Go back to BrainGrid Home page