GeNN is based on the idea of code generation for the involved GPU or CPU simulation code for neuronal network models but leaves a lot of freedom how to use the generated code in the final application. To facilitate the use of GeNN on the background of this philosophy, it comes with a number of complete examples containing both the model description code that is used by GeNN for code generation and the "user side code" to run the generated model and safe the results. Running these complete examples should be achievable in a few minutes. The necessary steps are described below.

Running an Example Model in Unix

In order to get a quick start and run a provided model, open a shell, navigate to GeNN/tools and type

make

This will compile additional tools for creating and running example projects. For a first complete test, the system is best used with a full driver program such as in the Insect olfaction model example:

./generate_run <0 (CPU) / 1 (GPU) / n (GPU n+2)> <nAL> <nMB> <nLHI> <nLb> <gscale> <outdir> <model name> <OPTIONS>

Possible options:
DEBUG=0 or DEBUG=1 (default 0): Whether to run in a debugger,
FTYPE=DOUBLE of FTYPE=FLOAT (default FLOAT): What floating point type to use,
REUSE=0 or REUSE=1 (default 0): Whether to reuse generated connectivity from an earlier run,
CPU_ONLY=0 or CPU_ONLY=1 (default 0): Whether to compile in (CUDA independent) "CPU only" mode.

To compile generate_run.cc, navigate to the userproject/MBody1_project directory and type

make

This will generate an executable that you can invoke with, e.g.,

./generate_run 1 100 1000 20 100 0.0025 test1 MBody1

which would generate and simulate a model of the locust olfactory system with 100 projection neurons, 1000 Kenyon cells, 20 lateral horn interneurons and 100 output neurons in the mushroom body lobes.

The tool generate_run will generate connectivity matrices for the model MBody1 and store them into files, compile and run the model on an automatically chosen GPU, using these files as inputs and output the resulting spiking activity. To fix the GPU used, replace the first argument 1 with the device number of the desired GPU plus 2, e.g., 2 for GPU 0. All input and output files will be prefixed with test1 and will be created in a sub-directory with the name test1_output. More about the DEBUG flag in the debugging section . The parameter FLOAT will run the model in float (single precision floating point), using DOUBLE would use double precision. The REUSE parameter regulates whether previously generated files for connectivity and input should be reused (1) or files should be generated anew (0).

The MBody1 example is already a highly integrated example that showcases many of the features of GeNN and how to program the user-side code for a GeNN application. More details in the User Manual .

Running an Example Model in Windows

All interaction with GeNN programs are command-line based and hence are executed within a cmd window. Open a Visual Studio cmd window via Start: All Programs: Visual Studio: Tools: Native Tools Command Prompt, and navigate to the userprojects\tools directory.

cd %GENN_PATH%\userprojects\tools

Then type

nmake /f WINmakefile

to compile a number of tools that are used by the example projects to generate connectivity and inputs to model networks. Then navigate to the userproject/MBody1_project directory.

cd ..\MBody1_project

By typing

nmake /f WINmakefile

you can compile the generate_run engine that allows to run a Insect olfaction model of the insect mushroom body:

generate_run <0 (CPU) / 1 (GPU) / n (GPU n+2)> <nAL> <nMB> <nLHI> <nLb> <gscale> <outdir> <model name> <OPTIONS>

To invoke generate_run.exe type, e.g.,

generate_run 1 100 1000 20 100 0.0025 test1 MBody1

which would generate and simulate a model of the locust olfactory system with 100 projection neurons, 1000 Kenyon cells, 20 lateral horn interneurons and 100 output neurons in the mushroom body lobes.

The tool generate_run.exe will generate connectivity matrices for the model MBody1 and store them into files, compile and run the model on an automatically chosen GPU, using these files as inputs and output the resulting spiking activity. To fix the GPU used, replace the first argument 1 with the device number of the desired GPU plus 2, e.g., 2 for GPU 0. All input and output files will be prefixed with test1 and will be created in a sub-directory with the name test1_output. More about the DEBUG flag in the debugging section . The parameter FLOAT will run the model in float (single precision floating point), using DOUBLE would use double precision. The REUSE parameter regulates whether previously generated files for connectivity and input should be reused (1) or files should be generated anew (0).

The MBody1 example is already a highly integrated example that showcases many of the features of GeNN and how to program the user-side code for a GeNN application. More details in the User Manual .

How to use GeNN for New Projects

Creating and running projects in GeNN involves a few steps ranging from defining the fundamentals of the model, inputs to the model, details of the model like specific connectivity matrices or initial values, running the model, and analyzing or saving the data.

GeNN code is generally created by passing the C / C++ model file (see below) directly to the genn-buildmodel script. Another way to use GeNN is to create or modify a script or executable such as userproject/MBody1_project/generate_run.cc that wraps around the other programs that are used for each of the steps listed above. In more detail, the GeNN workflow consists of:

Either using tools (programs) to generate connectivity and input matrix files, which are then loaded into the user's simulation code at runtime, or generating these matrices directly inside the user's simulation code.
Building the source code of a model simulation using genn-buildmodel.sh (On Linux or Mac) or genn-buildmodel.bat (on Windows). In the example of the MBody1_project this entails writing neuron numbers into userproject/include/sizes.h, and executing
genn-buildmodel.sh MBody1.cc
The genn-buildmodel script compiles the installed GeNN code generator in conjunction with the user-provided model description model/MBody1.cc. It then executes the GeNN code generator to generate the complete model simulation code for the MBody1 model.
Compiling the generated code, found in model/MBody1_CODE/, by calling:
make clean all
It is at this stage that GeNN generated model simulation code is combined with user-side code. In this example, classol_sim.cu (classify-olfaction-simulation) which uses the map_classol (map-neuron-based-classifier-olfaction) class.
Finally, running the resulting stand-alone simulator executable. In the MBody1 example classol_sim in the model directory.

The generate_run tool is only a suggested usage scenario of GeNN. Users have more control by manually executing the four steps above, or integrating GeNN into the development environment of their choice.

Note: The usage scenario described was made explicit for Unix environments. In Windows the setup is essentially the same except for the usual operating system dependent syntax differences, e.g. the build script is named genn-buildmodel.bat, compilation of the generated model simulator would be nmake /f WINmakefile clean all, and the resulting executable would be named classol_sim.exe.

GeNN comes with several example projects which showcase its features. The MBody1 example discussed above is one of the many provided examples that are described in more detail in Example projects.

Defining a New Model in GeNN

According to the work flow outlined above, there are several steps to be completed to define a neuronal network model.

The neuronal network of interest is defined in a model definition file, e.g. Example1.cc.
Within the the model definition file Example1.cc, the following tasks need to be completed:

a) The GeNN file modelSpec.h needs to be included,
#include "modelSpec.h"
b) The values for initial variables and parameters for neuron and synapse populations need to be defined, e.g.
float myPOI_p[4] = {
0.1, // 0 - firing rate
2.5, // 1 - refractory period
20.0, // 2 - Vspike
-60.0 // 3 - Vrest
};
would define the (homogeneous) parameters for a population of Poisson neurons.
Note
The number of required parameters and their meaning is defined by the neuron or synapse type. Refer to the User Manual for details. We recommend, however, to use comments like in the above example to achieve maximal clarity of each parameter's meaning.

If heterogeneous parameter values are needed for any particular population of neurons (synapses), a new neuron (synapse) type needs to be defined in which these parameters are defined as "variables" rather than parameters. See the User Manual for how to define new neuron (synapse) types.

c) The actual network needs to be defined in the form of a function modelDefinition, i.e.
void modelDefinition(NNmodel &model);

Note
The name modelDefinition and its parameter of type NNmodel& are fixed and cannot be changed if GeNN is to recognize it as a model definition.

d) Inside modelDefinition(), The time step DT needs to be defined, e.g.
model.setDT(0.1);

Note
All provided examples and pre-defined model elements in GeNN work with units of mV, ms, nF and muS. However, the choice of units is entirely left to the user if custom model elements are used.

MBody1.cc shows a typical example of a model definition function. In its core it contains calls to model.addNeuronPopulation and model.addSynapsePopulation to build up the network. For a full range of options for defining a network, refer to the User Manual.
The programmer defines their own "user-side" modeling code similar to the code in userproject/MBody1_project/model/map_classol.* and userproject/MBody1_project/model/classol_sim.*. In this code,

a) They define the connectivity matrices between neuron groups. (In the MBody1 example those are read from files). Refer to the User Manual for the required format of connectivity matrices for dense or sparse connectivities.

b) They define input patterns (e.g. for Poisson neurons like in the MBody1 example) or individual initial values for neuron and / or synapse variables.
Note
The initial values given in the modelDefinition are automatically applied homogeneously to every individual neuron or synapse in each of the neuron or synapse groups.

c) They use stepTimeGPU(...); to run one time step on the GPU or stepTimeCPU(...); to run one on the CPU. (both GPU and CPU versions are always compiled, unless -c is used with genn-buildmodel).
Note
However, mixing CPU and GPU execution does not make too much sense. Among other things, The CPU version uses the same host side memory where to results from the GPU version are copied, which would lead to collisions between what is calculated on the CPU and on the GPU (see next point). However, in certain circumstances, expert users may want to split the calculation and calculate parts (e.g. neurons) on the GPU and parts (e.g. synapses) on the CPU. In such cases the fundamental kernel and function calls contained in stepTimeXXX need to be used and appropriate copies of the data from the CPU to the GPU and vice versa need to be performed.

d) They use functions like copyStateFromDevice() etc to transfer the results from GPU calculations to the main memory of the host computer for further processing.

e) They analyze the results. In the most simple case this could just be writing the relevant data to output files.

Previous | Top | Next