diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 641400e..6db4e32 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -14,7 +14,7 @@ jobs: os: ubuntu-latest - cpp_compiler: "gcc" os: macos-latest - + steps: # Checkout the repository - name: Checkout nest-extension-module code @@ -40,7 +40,7 @@ jobs: if: runner.os == 'macOS' run: | brew install coreutils gsl open-mpi automake autoconf libtool - + # Install python dependencies - name: Install Python dependencies run: | @@ -50,6 +50,60 @@ jobs: # Run the build script - name: Build script run: | - chmod +x build.sh - set -o pipefail - ./build.sh + # We need to do this, because update-alternatives is not available on MacOS + if [ "$xNEST_BUILD_COMPILER" = "CLANG" ]; then + export CC=clang-11 + export CXX=clang++-11 + fi + + if [ "$(uname -s)" = 'Linux' ]; then + CONFIGURE_MPI="-Dwith-mpi=ON" + CONFIGURE_OPENMP="-Dwith-openmp=ON" + else + CONFIGURE_MPI="-Dwith-mpi=OFF" + CONFIGURE_OPENMP="-Dwith-openmp=OFF" + fi + + SOURCEDIR=$PWD + echo "SOURCEDIR = $SOURCEDIR" + cd .. + + # Install current NEST version. + git clone https://github.com/nest/nest-simulator.git + cd nest-simulator + + # Explicitly allow MPI oversubscription. This is required by Open MPI versions > 3.0. + # Not having this in place leads to a "not enough slots available" error. + NEST_RESULT=result + if [ "$(uname -s)" = 'Linux' ]; then + NEST_RESULT=$(readlink -f $NEST_RESULT) + else + NEST_RESULT=$(greadlink -f $NEST_RESULT) + fi + mkdir "$NEST_RESULT" + echo "NEST_RESULT = $NEST_RESULT" + mkdir build && cd build + cmake \ + -Dwith-optimize=ON -Dwith-warning=ON \ + $CONFIGURE_MPI \ + $CONFIGURE_OPENMP \ + -DCMAKE_INSTALL_PREFIX=$NEST_RESULT\ + .. + + VERBOSE=1 make -j 2 + make install + + cd $SOURCEDIR + mkdir build && cd build + cmake \ + -Dwith-optimize=ON -Dwith-warning=ON \ + -Dwith-nest=$NEST_RESULT/bin/nest-config \ + $CONFIGURE_MPI \ + $CONFIGURE_OPENMP \ + .. + + VERBOSE=1 make -j 2 + make install + + . $NEST_RESULT/bin/nest_vars.sh + python -c 'import nest; nest.Install("mymodule")' diff --git a/README.rst b/README.rst index 015e228..0bedbf4 100644 --- a/README.rst +++ b/README.rst @@ -1,49 +1,27 @@ NEST Extension Module Example ============================= -.. attention:: - - This version of the extension module code will not work with NEST - 3.6 or earlier. It is adapted to NEST Master as of 15 December 2023. - This repository contains an example extension module (i.e a "plugin") for the `NEST Simulator `_. Extension modules allow -users to extend the functionality of NEST without messing with the source +users to extend the functionality of NEST without altering the source code of NEST itself, thus making pulls from upstream easy, while allowing to extend NEST and sharing the extensions with other researchers. -In order to showcase the possibilites of extension modules and their use, -this extension module example contains the following (intentionally simple -and more or less silly) custom example components: +For the full documentation of this feature and further instructions, please see +https://nest-extension-module.readthedocs.io/. -* A **neuron model** called ``pif_psc_alpha``, which implements a - *non*-leaky integrate-and-fire model with alpha-function shaped - post-synaptic potentials. -* A **synapse model** called ``drop_odd_spike_connection``, which drops - all spikes that arrive at odd-numbered points on the simulation time - grid and delivers only those arriving at even-numbered grid points. -* A **connection builder** called ``step_pattern_builder``, which - creates step-pattern connectivity between the neurons of a source - and a target population. -* A **recording backend** called ``RecordingBackendSocket``, which - streams out the data from spike recorders to an external (or local) - server via UDP. -* A **recording backend** called ``RecordingBackendSoundClick``, which - creates the illusion of a realistic sound from an electrophysiological - spike recording device. +.. attention:: -For a list of modules developed by other users you can check out the -`list of forks `_ -of this repository. + Please note that the code in this repository will not work with NEST + 3.6 or earlier. It is adapted to NEST Master as of 15 December 2023. + It will in general be kept up-to-date with the git "master" branch on + https://github.com/nest/nest-simulator. For 2.x versions of NEST, see the + extension module example in ``examples/MyModule`` of the source distribution. -Adapting ``MyModule`` ---------------------- -If you want to create your own custom extension module using MyModule -as a start, you have to perform the following steps: +License +------- -1. Replace all occurences of the strings ``MyModule``, ``mymodule`` - and ``my`` by something more descriptive and appropriate for your - module. -2. Remove the example functionality you do not need. -3. Adapt the example functionality you do need to your needs. +NEST is open source software and is licensed under the `GNU General Public +License v2 `_ or +later. diff --git a/build.sh b/build.sh deleted file mode 100755 index 659e557..0000000 --- a/build.sh +++ /dev/null @@ -1,89 +0,0 @@ -#!/bin/bash - -# build.sh -# -# This file is part of the NEST example module. -# -# Copyright (C) 2004 The NEST Initiative -# -# NEST is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 2 of the License, or -# (at your option) any later version. -# -# NEST is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with NEST. If not, see . - - -# This shell script is part of the NEST example module Github Actions build -# and test environment. It is invoked by the top-level script '.github/workflows/build.yml'. -# - -# Exit shell if any subcommand or pipline returns a non-zero status. -set -e - -# THIS BUILD SCRIPT IS OUTDATED! - -# We need to do this, because update-alternatives is not available on MacOS -if [ "$xNEST_BUILD_COMPILER" = "CLANG" ]; then - export CC=clang-11 - export CXX=clang++-11 -fi - -if [ "$(uname -s)" = 'Linux' ]; then - CONFIGURE_MPI="-Dwith-mpi=ON" - CONFIGURE_OPENMP="-Dwith-openmp=ON" -else - CONFIGURE_MPI="-Dwith-mpi=OFF" - CONFIGURE_OPENMP="-Dwith-openmp=OFF" -fi - -SOURCEDIR=$PWD -echo "SOURCEDIR = $SOURCEDIR" -cd .. - -# Install current NEST version. -git clone https://github.com/nest/nest-simulator.git -cd nest-simulator - -# Explicitly allow MPI oversubscription. This is required by Open MPI versions > 3.0. -# Not having this in place leads to a "not enough slots available" error. -NEST_RESULT=result -if [ "$(uname -s)" = 'Linux' ]; then - NEST_RESULT=$(readlink -f $NEST_RESULT) -else - NEST_RESULT=$(greadlink -f $NEST_RESULT) -fi -mkdir "$NEST_RESULT" -echo "NEST_RESULT = $NEST_RESULT" -mkdir build && cd build -cmake \ - -Dwith-optimize=ON -Dwith-warning=ON \ - $CONFIGURE_MPI \ - $CONFIGURE_OPENMP \ - -DCMAKE_INSTALL_PREFIX=$NEST_RESULT\ - .. - -VERBOSE=1 make -j 2 -make install - -cd $SOURCEDIR -mkdir build && cd build -cmake \ - -Dwith-optimize=ON -Dwith-warning=ON \ - -Dwith-nest=$NEST_RESULT/bin/nest-config \ - $CONFIGURE_MPI \ - $CONFIGURE_OPENMP \ - .. - -VERBOSE=1 make -j 2 -make install - -. $NEST_RESULT/bin/nest_vars.sh -python -c 'import nest; nest.Install("mymodule")' -exit $? diff --git a/doc/conf.py b/doc/conf.py index f85c60b..09e22c2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -177,5 +177,3 @@ def setup(app): (master_doc, 'NESTextmod.tex', u'NEST Simulator extension module documentation', u'NEST Developer Community', 'manual'), ] - -copyfile('../README.rst', 'README.rst') diff --git a/doc/extension_modules.rst b/doc/extension_modules.rst index 8fc57b8..a0185b7 100644 --- a/doc/extension_modules.rst +++ b/doc/extension_modules.rst @@ -6,11 +6,7 @@ Writing an extension module 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 to the NEST simulator without any need to -modify the NEST software 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. +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 @@ -18,22 +14,16 @@ By writing a new module, you can add * 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. +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 a (brief) overview over how to create your -own module, based on the example ``MyModule``, which you find at -https://github.com/nest/nest-extension-module/. For information about -how to write new neuron or synapse models or functions as part of your -module, please see the corresponding documentation linked on the -:doc:`developer documentation index `. +On this page, you will find an overview of how to create your own module, based on the example ``MyModule``, which you 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 `_. -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. Prerequisites ------------- @@ -52,76 +42,53 @@ Prerequisites Building MyModule ----------------- -As a starting point, try to build MyModule as follows: - -1. From the NEST source directory, copy directory ``MyModule`` to somewhere outside the NEST source, build or install directories. -2. Create a build directory for it on the same level as MyModule (e.g. mmb) +1. Create a build directory: .. code-block:: sh - cd /path/to/MyModule - cd .. - mkdir mmb - cd mmb + mkdir build + cd build -3. 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. If ``nest-config`` is not in your path, you need to provided it explicitly like this +3. 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. If ``nest-config`` is not in your path, you need to provide it explicitly like this .. code-block:: sh - cmake -Dwith-nest=${NEST_INSTALL_DIR}/bin/nest-config ../MyModule + cmake -Dwith-nest=${NEST_INSTALL_DIR}/bin/nest-config .. - MyModule will then be installed to ``${NEST_INSTALL_DIR}``. This ensures that NEST will be able to find initializing SLI files for the module. + Please ensure that any other custom CMake flags (such as ``with-optimize``, ``with-mpi``, ``with-openmp`` and so on) are the same as were used for the NEST Simulator build. - You should not use the `-DCMAKE_INSTALL_PREFIX` to select a different installation destination. If you do, you must make sure to use ``addpath`` in SLI before loading the module to ensure that NEST will find the SLI initialization file for your module. + It is not recommended to use ``-DCMAKE_INSTALL_PREFIX`` to select a different installation destination. If you do, you must make sure to use environment variables like ``LD_LIBRARY_PATH`` to ensure NEST can locate the module. -4. Compile. +4. Compile and install: .. code-block:: sh make make install -5. The previous command installed MyModule to the NEST installation directory, including help files generated from the source code. + MyModule will then be installed to ``${NEST_INSTALL_DIR}``. Using MyModule -------------- -1. Start NEST. -2. Load the module using - - .. code-block:: - - SLI ] (mymodule) Install - Apr 30 17:06:11: *** Info: Install - Apr 30 17:06:11: loaded module My NEST Module - -3. You should now see ``pif_psc_alpha`` in the ``modeldict`` and ``drop_odd_spike`` in the ``synapsedict``. You can learn more about these models and the additional (meaningless) connection function supplied by the model by typing - - ``` - /pif_psc_alpha help - /drop_odd_spike help - /StepPatternConnect help - ``` - -4. In PyNEST, use +To use the new module in NEST Simulator, first source the ``nest_vars.sh`` script in the installation directory, and then use the ``nest.Install()`` API call to load the module: - .. code-block:: Python +.. code-block:: sh - nest.Install("mymodule") + source $NEST_INSTALL_DIR/bin/nest_vars.sh + python -c 'import nest; nest.Install("mymodule")' - This is available under Linux and MacOS. Link the module into NEST as described below if you run into problems. +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. Follow the instructions (1. - 4.) at the top of the ``CMakeLists.txt`` file in the MyModule directory. -3. Replace anything called "mymodule" in any form of camelcasing by the name of your module, and proceed as above. -4. When you change names of source code files or add/remove files, you need to update the variable `MODULE_SOURCES` in `CMakeLists.txt` . -5. ``make dist`` will roll a tarball of your module for distribution to others. -6. ``mymodule.cpp`` and ``sli/mymodule.sli`` contain versioning information that you may want to update. It helps to keep the C++ code and SLI wrapper of your module in sync. +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 @@ -141,10 +108,10 @@ Linking MyModule into NEST Instead of giving the full module name ``mymodule``, only give the ``SHORT_NAME`` ``my`` for the option ``-Dexternal-modules=...``. -1. Recompile and install NEST. -2. The module should now be available as soon as NEST has started up. It will also be available in PyNEST. -3. When you make any change to your module, you must first re-compile and re-install your module. -4. Then move to the NEST build directory and issue +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 diff --git a/doc/index.rst b/doc/index.rst index 9a4b4c8..7d0590e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,12 +1,11 @@ -.. include:: README.rst +.. include:: overview.rst .. toctree:: :hidden: :titlesonly: :maxdepth: 1 - README + overview extension_modules neuron_models - synapses_overview synapse_models diff --git a/doc/neuron_models.rst b/doc/neuron_models.rst index 5524f8b..4956dba 100644 --- a/doc/neuron_models.rst +++ b/doc/neuron_models.rst @@ -3,18 +3,7 @@ Writing neuron models .. note:: - We are currently in the process of transitioning from the old way of - writing models for NEST (i.e manually by implementing a C++ class) to - our new modeling language NESTML, which allows to write neuron models - using domain concepts from computational neuroscience as first level - objects and generate the source code automatically. - - If you intend to write your own neuron model, please have a look - at `the NESTML GitHub page `_. In case - of questions, feel free to subscribe to - the `NEST mailing list `_. If - you find any problems with NESTML, we kindly ask you to open an issue - on the `NESTML issue tracker `_. + For developing custom neuron and synapse models, please consider using `the NESTML modeling language `_. All models in NEST are derived from the base class Node. Neuron models are derived directly from the base class, whereas devices use the base diff --git a/doc/overview.rst b/doc/overview.rst new file mode 100644 index 0000000..1e39057 --- /dev/null +++ b/doc/overview.rst @@ -0,0 +1,57 @@ +NEST Extension Module Example +============================= + +This repository contains an example extension module (i.e., a "plugin") for +the `NEST Simulator `_. Extension modules allow +users to extend the functionality of NEST without messing with the source +code of NEST itself, thus making pulls from upstream easy, while allowing +to extend NEST and sharing the extensions with other researchers. + +In order to showcase the possibilites of extension modules and their use, +this extension module example contains the following (intentionally simple +and more or less silly) custom example components: + +* A **neuron model** called ``pif_psc_alpha``, which implements a + *non*-leaky integrate-and-fire model with alpha-function shaped + post-synaptic potentials. +* A **synapse model** called ``drop_odd_spike_connection``, which drops + all spikes that arrive at odd-numbered points on the simulation time + grid and delivers only those arriving at even-numbered grid points. +* A **connection builder** called ``step_pattern_builder``, which + creates step-pattern connectivity between the neurons of a source + and a target population. +* A **recording backend** called ``RecordingBackendSocket``, which + streams out the data from spike recorders to an external (or local) + server via UDP. +* A **recording backend** called ``RecordingBackendSoundClick``, which + creates the illusion of a realistic sound from an electrophysiological + spike recording device. + +For a list of modules developed by other users you can check out the +`list of forks `_ +of this repository. + +.. note:: + + For developing custom neuron and synapse models, please consider using `the NESTML modeling language `_. + +.. attention:: + + Please note that the code in this repository will not work with NEST + 3.6 or earlier. It is adapted to NEST Master as of 15 December 2023. + It will in general be kept up-to-date with the git "master" branch on + https://github.com/nest/nest-simulator. For 2.x versions of NEST, see the + extension module example in ``examples/MyModule`` of the source distribution. + + +Adapting ``MyModule`` +--------------------- + +If you want to create your own custom extension module using MyModule +as a start, you have to perform the following steps: + +1. Replace all occurences of the strings ``MyModule``, ``mymodule`` + and ``my`` by something more descriptive and appropriate for your + module. +2. Remove the example functionality you do not need. +3. Adapt the example functionality you do need to your needs. diff --git a/doc/synapse_models.rst b/doc/synapse_models.rst index e1a0df0..065ed1e 100644 --- a/doc/synapse_models.rst +++ b/doc/synapse_models.rst @@ -1,20 +1,83 @@ Writing synapse models ====================== -NEST has a very flexible system to allow users to write their own -synapse types. Synapses in NEST can either have static parameters or -apply some dynamics on them. Each connection needs to have at least -the following parameters: +.. note:: + + For developing custom neuron and synapse models, please consider using `the NESTML modeling language `_. + +NEST has a very flexible system to allow users to write their own synapse types. Synapses in NEST can either have static parameters or apply some dynamics on them. Each connection needs to have at least the following parameters: * The connection delay * The connection weight * The target node of the connection * The receiver port, which identifies the connection on the postsynaptic side -The source node of a connection is implicitly stored by the position -in the data structure that is used internally. These parameters are -implemented in the StaticConnection synapse type, which can be used as -a base class for more advanced synapse types. +These parameters are implemented in the ``static_synapse`` synapse type, which can be used as a base class for more advanced synapse types. + +Note that the source node of a connection is implicitly stored by the position in the data structure that is used internally in the NEST kernel. + + +Synapses in NEST +---------------- + +This section gives a brief overview over how synapses are currently implemented in NEST. Synapses in NEST come in two parts: + +1. a Connection object that manages synaptic weight and delay, and + +2. code implementing the synaptic currents or conductances resulting from a spike arrival; the latter is always coded in the model neuron class. + +Both parts will be discussed in turn. Some of the discussion below is simplified, ignoring issues of parallelization; the intent is to give you the general idea. + + +Storage of synapses +^^^^^^^^^^^^^^^^^^^ + +All targets of a given neuron are stored in a target list containing one ``Connection`` object per target. When a spike is sent, NEST traverses the target list and sends information about the spike, that is, weight, delay and spike time to each receiving neuron. + +Some synapses implement spike-time dependent plasticity, that is, they modify the synaptic weight stored in the ``Connection`` object. To compute the weight update, these synapses typically access the spike history through special member functions of the receiving neuron class, which must be derived from ``ArchivingNode`` (most models are). + +The details of connection storage infrastructure are explained in [1]_. + + +Event delivery +^^^^^^^^^^^^^^ + +When a spike arrives at a neuron by a call to its ``handle(SpikeEvent&)`` method, the ``SpikeEvent`` provides information about the synaptic weight, the spike time, and the delay, so that the actual arrival time of the spike can be calculated. + +It is entirely up to the neuron class to handle this information. In particular, all dynamics of synaptic currents or conductances must be implemented in the neuron model. + + +Using different receptor ports +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Introducing different receptor channels (NMDA, AMPA, GABA, etc.) raises the question of how to differentiate input to different types of channels on a neuron. + +Most NEST models are very simplistic in this respect: they differentiate mainly between an excitatory and an inhibitory synapse. +All input with positive weight is handled by the excitatory synapse, and all with input with negative weight is handled by the inhibitory synapse. + +More channels can be handled using the receptor type/receiver port mechanism in NEST. Please see the ``iaf_psc_alpha_multisynapse`` NEST model for an example. + + +Temporal aspects +^^^^^^^^^^^^^^^^ + +Time is a very important issue when processing spikes. Especially when the effect of a spike on the neuron depends on the history or state of the neuron, it is crucial that one considers causality carefully. + +This is the reason why spiking history information about a neuron is available only via the ``ArchivingNode`` interface. The paper [2]_ has more on spike history handling. + + +Spike handling +^^^^^^^^^^^^^^ + +NEST delivers spikes in batches. Simulation proceeds for ``min_delay`` (minimum delay) time. During this time, any generated spikes are stored in a central spike queue. After each ``min_delay`` interval, spikes are delivered from the central queue via the ``ConnectionManager`` and the Connection objects to the individual neurons. + +All delays are handled inside the neuron, as described above. This means that when a spike "passes through" the ``Connection`` object, the actual biological arrival time (time when spike occurred at sender plus delay) of the spike may be up to ``max_delay`` (maximum delay) time units in the future. This means, in particular, that ``Connection`` objects cannot perform any computations that depend on the state of the neuron at the time of "biological" spike arrival; they can only use historic information. + +Another important point is that spikes do NOT pass the Connection object in correct order of biological arrival time---they are unordered in time. + + +Writing synapse models +---------------------- Writing a synapse type is basically very simple. You can directly derive your new connection type from StaticConnection, which provides @@ -22,8 +85,6 @@ all mechanisms to register and send a connection. A synapse type consist of two files, a header and an implementation. Skeletons for both of them are shown shown in the following listings: -``NESTSRC/models/my_synapse.h`` - .. code-block:: C++ #ifndef MY_SYNAPSE @@ -65,8 +126,6 @@ connection with the ConnectionManager of NEST, for storing the mandatory parameters weight and delay and functions to set and retrieve these parameters from within the SLI interpreter. -``NESTSRC/models/my_connection.cpp`` - .. code-block:: C++ #include "my_synapse.h" @@ -88,19 +147,27 @@ Registering the new synapse type -------------------------------- After your files are written, you have to add their names to the -``CMakeLists.txt`` file in ``NESTSRC/models`` to have it be compiled +``CMakeLists.txt`` file in ``src/`` to have it be compiled and linked to NEST. To make the synapse type available inside of NEST scripts, you have to include and register it with the module. Add the following line to the -beginning of ``NESTSRC/models/modelmodule.cpp``: +beginning of ``src/mymodule.cpp``: .. code-block:: C++ #include "my_synapse.h" -And the following line to the end of the file: +And the following line to the ``init()`` method of the module: .. code-block:: C++ register_connection_model< my_synapse >( "my_synapse" ); + +References +---------- + +.. [1] Kunkel et al. (2014), Spiking network simulation code for petascale computers. Front. Neuroinform. 8:78. `doi:10.3389/fninf.2014.00078 `_. + +.. [2] `Morrison et al. (2007) `_ + diff --git a/doc/synapses_overview.rst b/doc/synapses_overview.rst deleted file mode 100644 index d2ac864..0000000 --- a/doc/synapses_overview.rst +++ /dev/null @@ -1,115 +0,0 @@ -Synapses in NEST -================ - -This document gives a brief overview over how synapses are currently -implemented in NEST. Synapses in NEST come in two parts: - -1. a Connection object that manages synaptic weight and delay, and - -2. code implementing the synaptic currents or conductances resulting - from a spike arrival; the latter is always coded in the model - neuron class. - -Both parts will be discussed in turn. Some of the discussion below is -simplified, ignoring issues of parallelization; the intent is to give -you the general idea. - -Storage of synapses -------------------- - -All targets of a given neuron are stored in a target list containing -one ``Connection`` object per target. When a spike is sent, NEST -traverses the target list and sends information about the spike, i.e., -weight, delay and spike time to each receiving neuron. - -Some synapses implement spike-time dependent plasticity, i.e., they -modify the synaptic weight stored in the ``Connection`` object based on -the spike history of the receiving neuron. These synapses access the -spike history through special member functions of the receiving neuron -class, which must be derived from ``ArchivingNode`` (most models are). - -The details of connection storage infrastructure are explained in -Kunkel et al. (2014), Spiking network simulation code for petascale -computers. Front. Neuroinform. 8:78. `doi:10.3389/fninf.2014.00078 `_. - -Event delivery --------------- - -When a spike arrives at a neuron by a call to its ``handle(SpikeEvent&)`` -method, the ``SpikeEvent`` provides information about the synaptic weight, -the spike time, and the delay, so that the actual arrival time of the -spike can be calculated. - -It is now entirely up to the neuron class to handle this -information. In particular, all dynamics of synaptic currents or -conductances must be implemented in the neuron model. See the -:doc:`model development guide ` for examples -of how this is done. - -NEST currently does not have any models with voltage-dependent -synapses, such as NMDA channels. A simple way to introduce such a -voltage dependency in, e.g., the ``iaf_cond_alpha`` model would be to -multiply the synaptic conductance ``g(t)`` with a sigmoidal function -``m(V)`` in the expression computing the right-hand side of the membrane -potential equation. - -It is a bit unfortunate that one needs to include the code for the -synaptic currents/conductances anew in each new neuron model, but for -many simpler models this leads to more efficient code than one would -obtain if synaptic current dynamics were represented by separate -objects. We will consider changing this in the future, though. - - -Using different receptor ports ------------------------------- - -Introducing NMDA channels obviously raises the question of how to -differentiate input to different types of channels on a neuron, e.g., -AMPA, GABA_A, GABA_B, and NMDA channels. - -Most NEST models are very simplistic in this respect so far: they -differentiate at most between an excitatory and an inhibitory synapse, -and all input with positive weight is handled by the excitatory, all -with negative weight by the inhibitory synapse. - -More channels can be handled using the receptor type/receiver port -mechanism in NEST. Please see ``iaf_alpha_cond_mc`` or -``iaf_psc_alpha_multisynapse`` for examples. - - -Temporal aspects ----------------- - -Time is a very important issue when processing spikes. Especially when -the effect of a spike on the neuron depends on the history or state of -the neuron, it is crucial that one considers causality carefully. - -This is the reason why history information about a neuron is available -only via the ArchivingNode interface, while state information is -currently "exported" only through the UniversalDataLogger interface -(under development, available in few neurons today). The paper -`Morrison et al. (2007) `_ -paper has more on spike history handling. - - -Spike handling --------------- - -NEST delivers spikes in batches. Simulation proceeds for min_delay -(minimum delay) time. During this time, any generated spikes are -stored in a central spike queue. After each min_delay interval, spikes -are delivered from the central queue via the ConnectionManager and the -Connection objects to the individual neurons. - -All delays are handled inside the neuron, as described above. This -means that when a spike "passes through" the Connection object, the -actual biological arrival time (time when spike occured at sender plus -delay) of the spike may be up to max_delay (maximum delay) time units -in the future. This means, in particular, that Connection objects -cannot perform any computations that depend on the state of the neuron -at the time of "biological" spike arrival; they can only use historic -information. - -Another important point is that spikes do NOT pass the Connection -object in correct order of biological arrival time---they are -unordered in time.