Writing an extension module

Note

The example extension module is hosted on its own repository, at: https://github.com/nest/nest-extension-module/

NEST has a modular architecture which allows you to add your own neuron and synapse models without any need to modify the NEST source code itself, but by just adding a new module. You can then either load this module dynamically at runtime (preferred) or you can link NEST against your module.

By writing a new module, you can add

your own neuron models
your own synapse types
your own connection (or other) functions

to NEST. For the benefit of the NEST Community at large, we would encourage you to share your modules with other NEST users. Please see the contributing page to find out how to initiate the inclusion by issuing a pull request.

On this page, you will find an overview of how to create your own module, based on the example MyModule, which you will find at https://github.com/nest/nest-extension-module/.

If you have questions, problems, or feedback about your experience with external modules, please join the mailing list to share it with us ·and other users.

Note

For developing custom neuron and synapse models, please consider using the NESTML modeling language.

Prerequisites

Download, build, and install NEST. NEST should be built outside the source code directory. The instructions for building NEST from source can be found here.
The NEST source code and installation directory must be accessible for building modules.
Define the environment variable NEST_INSTALL_DIR to contain the path to which you have installed NEST, e.g., using bash,
```
export NEST_INSTALL_DIR=<path/to/NEST/install/dir>
```
This environment variable is not strictly necessary, but saves you typing later.

Building MyModule

Create a build directory outside the source code directory for the extension module (and outside the build directory for NEST itself).
```
mkdir build-ext
cd build-ext
```
Configure. The configure process uses the script nest-config to find out where NEST is installed, where the source code resides, and which compiler options were used for compiling NEST. You should provide it explicitly as a CMake option to be sure for which NEST you are building (and later installing) the module:
```
cmake -Dwith-nest=${NEST_INSTALL_DIR}/bin/nest-config <path/to/module/source>
```
All necessary configuration and compiler flags will be set automatically based on information collected from nest-config. You should not provide any other flags to CMake unless you are absolutely sure about what you are doing.
Compile and install:
```
make
make install
```
MyModule (mymodule.so) will then be installed to ${NEST_INSTALL_DIR}.

Using MyModule

To use the new module in NEST Simulator, ensure that the PYTHONPATH environment variable is set point to the NEST python libraries, and then use the nest.Install() API call to load the module:

export PYTHONPATH=${NEST_INSTALL_DIR}/lib/python..../site-packages
python -c 'import nest; nest.Install("mymodule")'

After loading the module, you should be able to see pif_psc_alpha in nest.node_models and drop_odd_spike in nest.synapse_models.

Creating your own module

Start with the code from MyModule.
Replace anything called mymodule in any form of camelcasing by the name of your module, and proceed as above.
When you change names of source code files or add/remove files, you need to update the variable MODULE_SOURCES in CMakeLists.txt.
make dist will roll a tarball of your module for distribution to others.

Linking MyModule into NEST

Build NEST and MyModule as described above.
Change back to the NEST build directory.
Reconfigure NEST informing it about your MyModule. Note that the module MUST be installed in the NEST installation directory tree!
```
cmake [...] -Dexternal-modules=my ../src
```
Several modules can be given, separated by semicolon.

Note

Instead of giving the full module name mymodule, only give the SHORT_NAME my for the option -Dexternal-modules=....
Recompile and install NEST.
The module should now be available as soon as NEST has started up. It will also be available in PyNEST.
When you make any change to your module, you must first re-compile and re-install your module.
Then move to the NEST build directory and issue
```
make -C nest clean
make
make install
```
This rebuilds only the NEST executable.