GeNN  3.3.0
GPU enhanced Neuronal Networks (GeNN)
Quickstart

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 and navigate to the userproject/tools directory:

cd $GENN_PATH/userproject/tools

Then compile the additional tools for creating and running example projects:

make

Some of the example models such as the Insect olfaction model use an generate_run executable which automates the building and simulation of the model. To build this executable for the Insect olfaction model example, navigate to the userproject/MBody1_project directory:

cd ../MBody1_project

Then type

make

to generate an executable that you can invoke with

./generate_run 1 100 1000 20 100 0.0025 test1 MBody1

or, if you don't have an NVIDIA GPU and are running GeNN in CPU_ONLY mode, you can instead invoke this executable with

./generate_run 0 100 1000 20 100 0.0025 test1 MBody1 CPU_ONLY=1

both invocations will build 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.

Note
If the model isn't build in CPU_ONLY mode it will be simulated on an automatically chosen GPU.

The generate_run tool generates connectivity matrices for the model MBody1 and writes them to file, compiles and runs the model using these files as inputs and finally output the resulting spiking activity. For more information of the options passed to this command see the Insect olfaction model section.

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 userproject\tools directory.

cd %GENN_PATH%\userproject\tools

Then compile the additional tools for creating and running example projects:

nmake /f WINmakefile

Some of the example models such as the Insect olfaction model use an generate_run executable which automates the building and simulation of the model. To build this executable for the Insect olfaction model example, navigate to the userproject\MBody1_project directory:

cd ..\MBody1_project

Then type

nmake /f WINmakefile

to generate an executable that you can invoke with

generate_run 1 100 1000 20 100 0.0025 test1 MBody1

or, if you don't have an NVIDIA GPU and are running GeNN in CPU_ONLY mode, you can instead invoke this executable with

generate_run 0 100 1000 20 100 0.0025 test1 MBody1 CPU_ONLY=1

both invocations will build 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.

Note
If the model isn't build in CPU_ONLY mode it will be simulated on an automatically chosen GPU.

The generate_run tool generates connectivity matrices for the model MBody1 and writes them to file, compiles and runs the model using these files as inputs and finally output the resulting spiking activity. For more information of the options passed to this command see the Insect olfaction model section.

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++ 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:

  1. Either use external programs to generate connectivity and input files to be loaded into the user side code at runtime or generate these matrices directly inside the user side code.
  2. Generating the model simulation code using genn-buildmodel.sh (On Linux or Mac) or genn-buildmodel.bat (on Windows). For example, inside the generate_run engine used by the MBody1_project, the following command is executed on Linux:
    genn-buildmodel.sh MBody1.cc
    or, if you don't have an NVIDIA GPU and are running GeNN in CPU_ONLY mode, the following command is executed:
    genn-buildmodel.sh -c MBody1.cc
    The genn-buildmodel script compiles the 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 model.
  3. Provide a build script to compile the generated model simulation and the user side code into a simulator executable (in the case of the MBody1 example this consists of two files classol_sim.cc and map_classol.cc). On Linux or Mac this typically consists of a GNU makefile:
    EXECUTABLE := classol_sim
    SOURCES := classol_sim.cc map_classol.cc
    include $(GENN_PATH)/userproject/include/makefile_common_gnu.mk
    And on Windows an MSBuild script:
    <?xml version="1.0" encoding="utf-8"?>
    <Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Import Project="MBody1_CODE\generated_code.props" />
    <ItemGroup>
    <ClCompile Include="classol_sim.cc" />
    <ClCompile Include="map_classol.cc" />
    </ItemGroup>
    </Project>
  4. Compile the simulator executable by invoking GNU make on Linux or Mac:
    make clean all
    or MSbuild on Windows:
    msbuild MBody1.vcxproj /p:Configuration=Release
    If you don't have an NVIDIA GPU and are running GeNN in CPU_ONLY mode, you should compile the simulator by passing the following options to GNU make on Linux or Mac:
    make clean all CPU_ONLY=1
    or, on Windows, by selecting a CPU_ONLY MSBuild configuration:
    msbuild MBody1.vcxproj /p:Configuration=Release_CPU_ONLY
  5. Finally, run the resulting stand-alone simulator executable. In the MBody1 example, this is called classol_sim on Linux and MBody1.exe on Windows.

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.

  1. The neuronal network of interest is defined in a model definition file, e.g. Example1.cc.

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

    NeuronModels::PoissonNew::ParamValues poissonParams(
    10.0); // 0 - firing rate

    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 required for a particular population of neurons (or synapses), they need to be defined as "variables" rather than parameters. See the User Manual for how to define new neuron (or synapse) types and the Defining a new variable initialisation snippet section for more information on initialising these variables to hetererogenous values.

    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 NNmodel::addNeuronPopulation and NNmodel::addSynapsePopulation to build up the network. For a full range of options for defining a network, refer to the User Manual.

  3. 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 Synaptic matrix types section 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.

    Note
    Both GPU and CPU versions are always compiled, unless -c is used with genn-buildmodel to build a CPU-only model or the model uses features not supported by the CPU simulator. 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