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 <https://nest-simulator.readthedocs.io/en/stable/developer_space/index.html>`_ 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 <https://nest-simulator.readthedocs.io/en/stable/community.html>`_ to share it with us ·and other users.

.. note::

   For developing custom neuron and synapse models, please consider using `the NESTML modeling language <https://nestml.readthedocs.org/>`_.


Prerequisites
-------------

1. 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 <https://nest-simulator.readthedocs.io/en/stable/installation/developer.html#dev-install>`_.
2. The NEST source code and installation directory must be accessible for building modules.
3. Define the environment variable ``NEST_INSTALL_DIR`` to contain the path to which you have installed NEST, e.g., using bash,

   .. code-block:: sh

      export NEST_INSTALL_DIR=<path/to/NEST/install/dir>

   This environment variable is not strictly necessary, but saves you typing later.


Building MyModule
-----------------

1. Create a build directory outside the source code directory for the extension module (and outside the build directory for NEST itself).

   .. code-block:: sh

      mkdir build-ext
      cd build-ext

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

   .. code-block:: sh

      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.

3. Compile and install:

   .. code-block:: sh

      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:

.. code-block:: sh

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

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


Linking MyModule into NEST
--------------------------

1. Build NEST and MyModule as described above.
2. Change back to the NEST build directory.
3. Reconfigure NEST informing it about your MyModule. Note that the module MUST be installed in the NEST installation directory tree!

   .. code-block:: sh

      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=...``.

4. Recompile and install NEST.
5. The module should now be available as soon as NEST has started up. It will also be available in PyNEST.
6. When you make any change to your module, you must first re-compile and re-install your module.
7. Then move to the NEST build directory and issue

   .. code-block:: sh

      make -C nest clean
      make
      make install

   This rebuilds only the NEST executable.