GeNN  4.9.0
GPU enhanced Neuronal Networks (GeNN)
Quickstart

GeNN is based on the idea of code generation for the code that simulates neuronal network models, either on GPU or CPU. At the same time, it leaves a lot of freedom to users, how to use the generated code in their final applications. 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 as well as save the results. Some of the example models, such as the Insect olfaction model, uses a generate_run executable which automates the building and simulation of the model. Using these executables, running the complete examples should be achievable in a few minutes. The necessary steps are described below.

Running an Example Model

Unix

In order to build the generate_run executable as well as other additional tools required for the model, open a shell and navigate to the userproject/MBody1_project directory. Then type

make

to generate an executable that you can invoke with

./generate_run test1

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 --cpu-only test1

Windows

While GeNN can be used from within Visual Studio, in this example we will use a cmd window. Open a Visual Studio cmd window via Start: All Programs: Visual Studio: Tools: x86 Native Tools Command Prompt, and navigate to the userproject\tools directory. Then compile the additional tools and the generate_run executable for creating and running the project:

msbuild ..\userprojects.sln /t:generate_mbody1_runner /p:Configuration=Release

to generate an executable that you can invoke with

generate_run test1

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 --cpu-only test1

Visualising results

These steps build and simulate a model of the locust olfactory system with default parameters of 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 executable generates input patterns and writes them to a 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 results of the simulation can be plotted with

python plot.py test1

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 C++ 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 the file MBody1Sim.cc). On Linux or Mac a suitable GNU makefile can be created by running:
    genn-create-user-project.sh MBody1 MBody1Sim.cc
    And on Windows an MSBuild project can be created by running:
    genn-create-user-project.bat MBody1 MBody1Sim.cc
  4. Compile the simulator executable by invoking GNU make on Linux or Mac:
    make clean all
    or MSbuild on Windows:
    msbuild MBody1.sln /t:MBody1 /p:Configuration=Release
  5. Finally, run the resulting stand-alone simulator executable. In the MBody1 example, this is called MBody1 on Linux and MBody1_Release.exe on Windows.

Defining a new model in GeNN using C++

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(ModelSpec &model);
    Note
    The name modelDefinition and its parameter of type ModelSpec& 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 uS. 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 ModelSpec::addNeuronPopulation and ModelSpec::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 "simulation" code similar to the code in userproject/MBody1_project/model/MBody1Sim.cc. In this code,

    a) They can manually define the connectivity matrices between neuron groups. Refer to the Synaptic matrix types section for the required format of connectivity matrices for dense or sparse connectivities.

    b) They can define input patterns or individual initial values for neuron and / or synapse variables.

    Note
    The initial values or initialisation "snippets" given in the modelDefinition are automatically applied.

    c) They use stepTime() to run one time step on either the CPU or GPU depending on the options passed to genn-buildmodel.

    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.

Defining a new model in GeNN using Python

There are several steps to be completed to define a neuronal network model.

  1. The neuronal network of interest is defined in a script, e.g. Example1.py.

  2. Within the the script Example1.py, the following tasks need to be completed:

    a) Required PyGeNN classes needs to be imported,

    from pygenn.genn_model import GeNNModel

    b) The values for initial variables and parameters for neuron and synapse populations need to be defined, e.g.

    poisson_params = {"rate": 10.0}

    would define the (homogeneous) parameters for a population of Poisson neurons.

    Note
    The names of required parameters and their meaning is defined by the neuron or synapse type. Refer to the User Manual for details.

    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) A pygenn.GeNNModel object needs to be created and the floating point precision to use should be set (see Floating point precision for more information on floating point precision), i.e.

    model = GeNNModel("float", "example")

    d) The model's simulation time step DT needs to be defined, e.g.

    model.dT = 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.

    For a full range of options for defining a network, refer to the User Manual.

  3. Within the same script, the programmer builds the model – running the GeNN code generator – and loads it into Python, i.e.
    model.build()
    model.load()
    Note
    If the model isn't changed, pygenn.GeNNModel.build doesn't need to be called.

  4. Also, within the same script, the programmer defines their own "simulation" code. In this code,

    a) They can manually define the connectivity matrices between neuron groups. Refer to the Synaptic matrix types section for the required format of connectivity matrices for dense or sparse connectivities.

    b) They can define input patterns or individual initial values for neuron and / or synapse variables.

    Note
    The initial values or initialisation "snippets" specified when defining the model are automatically applied.

    c) They use pygenn.GeNNModel.step_time() to run one time step on either the CPU or GPU depending on the available hardware.

    d) They use functions like pygenn.genn_groups.Group.pull_state_from_device 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 involve plotting it from within the script using Matplotlib.

    Previous | Top | Next