Merge pull request #2011 from sarakonradi/update_urbanczik_models_rst

Add documentation on multicompartment models

doc/userdoc/examples/index.rst

@@ -34,6 +34,7 @@ PyNEST examples
    ../auto_examples/clopath_synapse_small_network
    ../auto_examples/tsodyks_depressing
    ../auto_examples/tsodyks_facilitating
+   ../auto_examples/urbanczik_synapse_example
 
 
 .. toctree::

doc/userdoc/guides/index.rst

@@ -30,4 +30,5 @@ Here you can find details on a variety of topics in NEST.
     :maxdepth: 1
     :caption: Model Details
 
-    exact-integration
+    exact-integration
+    Multicompartment models and synaptic delays <../models/pp_cond_exp_mc_urbanczik>

models/iaf_cond_alpha_mc.h

@@ -77,8 +77,8 @@ FULLY TESTED. USE AT YOUR OWN PERIL!
 
 iaf_cond_alpha_mc is an implementation of a multi-compartment spiking
 neuron using IAF dynamics with conductance-based synapses. It serves
-mainly to illustrate the implementation of multicompartment models in
-NEST.
+mainly to illustrate the implementation of ref:`multicompartment models
+<multicompartment-models>` in NEST.
 
 The model has three compartments: soma, proximal and distal dendrite,
 labeled as s, p, and d, respectively. Compartments are connected through

models/pp_cond_exp_mc_urbanczik.h

@@ -105,82 +105,145 @@ class pp_cond_exp_mc_urbanczik_parameters
   double tau_syn_in[ NCOMP ]; //!< Rise time of inhibitory synaptic conductance in ms
 };
 
+/* BeginUserDocs: neuron, point process, conductance-based
 
-/** @BeginDocumentation
-@ingroup Neurons
-@ingroup pp
-@ingroup cond
-
+Short description
++++++++++++++++++
 
-Name: pp_cond_exp_mc_urbanczik - Two-compartment point process neuron with conductance-based synapses
+Two-compartment point process neuron with conductance-based synapses
 
-Description:
+Description
++++++++++++
 
 pp_cond_exp_mc_urbanczik is an implementation of a two-compartment spiking
 point process neuron with conductance-based synapses as it is used
-in [1]. It is capable of connecting to a Urbanczik synapse.
+in [1]_. It is capable of connecting to an :doc:`Urbanczik synapse
+<urbanczik_synapse>`.
 
-The model has two compartments: soma and dendrite, labeled as s and p, respectively.
-There is one excitatory and one inhibitory conductance-based synapse onto each compartment.
-Each compartment can also receive current input from a current generator, and an external
-(rheobase) current can be set for each compartment.
+The model has two compartments: soma and dendrite, labeled as s and p,
+respectively. Each compartment can receive spike events and current input
+from a current generator. Additionally, an external (rheobase) current can be
+set for each compartment.
 
 Synapses, including those for injection external currents, are addressed through
 the receptor types given in the receptor_types entry of the state dictionary.
 Note that in contrast to the single-compartment models, all
-synaptic weights must be positive numbers!
-
-
-Parameters:
+synaptic weights must be positive numbers! The distinction between excitatory
+and inhibitory synapses is made explicitly by specifying the receptor type of
+the synapse. For example, receptor_type=dendritic_exc results in an excitatory
+input and receptor_type=dendritic_inh results in an inhibitory input to the
+dendritic compartment.
+
+.. _multicompartment-models:
+
+Multicompartment models and synaptic delays
++++++++++++++++++++++++++++++++++++++++++++
+
+Note that in case of multicompartment models that represent the dendrite
+explicitly, the interpretation of the synaptic delay in NEST requires careful
+consideration. In NEST, the delay is at least one simulation time step and is
+assumed to be located entirely at the postsynaptic side. For point neurons, it
+represents the time it takes for an incoming spike to travel along the
+postsynaptic dendrite before it reaches the soma, see :ref:`panel a)
+<fig-multicompartment>`. Conversely, if the synaptic weight depends on the
+state of the postsynaptic neuron, the delay also represents the time it takes
+for the information on the state to propagate back through the dendrite to the
+synapse.
+
+For multicompartment models in NEST, this means the delay is positioned directly
+behind the incoming synapse, that is, before the first dendritic compartment on the
+postsynaptic side, see :ref:`panel b) <fig-multicompartment>`. Therefore, the
+delay specified in the synapse model does *not* account for any delay that might
+be associated with information traveling through the explicitly modeled
+dendritic compartments.
+
+In the :ref:`Urbanczik synapse <urbanczik_synapse>`, the change of the synaptic
+weight is driven by an error signal, which is the difference between the firing
+rate of the soma (derived from the somatic spike train :math:`S_{post}`) and the
+dendritic prediction of the firing rate of the soma (derived from the dendritic
+membrane potential :math:`V`). The original publication [1]_ does not assume any
+delay in the interaction between the soma and the dendritic compartment.
+Therefore, we evaluate the firing rate and the dendritic prediction at equal
+time points to calculate the error signal at that time point. Due to the
+synaptic delay :math:`d`, the synapse combines a delayed version of the error
+signal with the presynaptic spike train (:math:`S_{pre}`), see :ref:`panel c)
+<fig-multicompartment>`.
+
+.. _fig-multicompartment::
+
+.. figure:: ../static/img/multicompartment.png
+   :width: 75 %
+
+   a) Two point neurons (red circles *pre* and *post*) connected via a synapse.
+   In NEST, the delay is entirely on the postsynaptic side, and in the case of point
+   neurons, it is interpreted as the dendritic delay. b) Two two-compartment
+   neuron models composed of a somatic (green) and a dendritic (blue)
+   compartment. The soma of the presynaptic neuron is connected to the dendrite
+   of the postsynaptic neuron. The synaptic delay is located behind the synapse
+   and before the dendrite. c) Time trace of the State variables that enter the
+   Urbanczik-Senn rule. Due to the synaptic delay :math:`d`, the presynaptic
+   spike train (top) is combined with a delayed version of the postsynaptic
+   quantities; the dendritic membrane potential (middle) and the somatic spike
+   train (bottom).
+
+
+Parameters
+++++++++++
 
 The following parameters can be set in the status dictionary. Parameters
 for each compartment are collected in a sub-dictionary; these sub-dictionaries
 are called "soma" and "dendritic", respectively. In the list below,
 these parameters are marked with an asterisk.
 
-\verbatim embed:rst
-
-============ ======= ==========================================================
- V_m*        mV      Membrane potential
- E_L*        mV      Leak reversal potential
- C_m*        pF      Capacity of the membrane
- E_ex*       mV      Excitatory reversal potential
- E_in*       mV      Inhibitory reversal potential
- g_L*        nS      Leak conductance
- tau_syn_ex* ms      Rise time of the excitatory synaptic alpha function
- tau_syn_in* ms      Rise time of the inhibitory synaptic alpha function
- I_e*        pA      Constant input current
- g_sp        nS      Coupling between soma and dendrite
- g_ps        nS      Coupling between dendrite and soma
- t_ref       ms      Duration of refractory period
-============ ======= ==========================================================
-\endverbatim
-
-Example:
-See pynest/examples/urbanczik_synapse_example.py.
+============   =====   =====================================================
+ V_m*           mV      Membrane potential
+ E_L*           mV      Leak reversal potential
+ C_m*           pF      Capacity of the membrane
+ E_ex*          mV      Excitatory reversal potential
+ E_in*          mV      Inhibitory reversal potential
+ g_L*           nS      Leak conductance
+ tau_syn_ex*    ms      Rise time of the excitatory synaptic alpha function
+ tau_syn_in*    ms      Rise time of the inhibitory synaptic alpha function
+ I_e*           pA      Constant input current
+ g_sp           nS      Coupling between soma and dendrite
+ g_ps           nS      Coupling between dendrite and soma
+ t_ref          ms      Duration of refractory period
+============   =====   =====================================================
+
+See :doc:`../auto_examples/urbanczik_synapse_example` to learn more.
 
 Remarks:
 
-The neuron model uses standard units instead of the unitless quantities used in [1].
+The neuron model uses standard units of NEST instead of the unitless quantities
+used in [1]_.
 
-@note All parameters that occur for both compartments
-are stored as C arrays, with index 0 being soma.
+.. note::
+   All parameters that occur for both compartments are stored as C arrays, with
+   index 0 being soma.
 
-Sends: SpikeEvent
+Sends
++++++
 
-Receives: SpikeEvent, CurrentEvent, DataLoggingRequest
+SpikeEvent
 
-References:
+Receives
+++++++++
 
-\verbatim embed:rst
-.. [1] R. Urbanczik, W. Senn (2014). Learning by the Dendritic Prediction of Somatic Spiking. Neuron, 81, 521 - 528.
-\endverbatim
+SpikeEvent, CurrentEvent, DataLoggingRequest
 
-Author: Jonas Stapmanns, David Dahmen, Jan Hahne
+References
+++++++++++
 
-SeeAlso: urbanczik_synapse
+.. [1] R. Urbanczik, W. Senn (2014). Learning by the Dendritic Prediction of
+       Somatic Spiking. Neuron, 81, 521 - 528.
+
+See also
+++++++++
+
+urbanczik_synapse
+
+EndUserDocs */
 
-*/
 class pp_cond_exp_mc_urbanczik : public UrbanczikArchivingNode< pp_cond_exp_mc_urbanczik_parameters >
 {
 

models/urbanczik_synapse.h

@@ -40,51 +40,66 @@
 namespace nest
 {
 
-/** @BeginDocumentation
-@ingroup Synapses
-@ingroup stdp
+/* BeginUserDocs: synapse, spike-timing-dependent plasticity
 
-Name: urbanczik_synapse - Synapse type for a plastic synapse after Urbanczik and Senn.
+Short description
++++++++++++++++++
 
-Description:
+Synapse type for a plastic synapse after Urbanczik and Senn
 
-urbanczik_synapse is a connector to create Urbanczik synapses as defined in [1] that can connect suitable
-multicompartment models. In contrast to usual STDP, the change of the synaptic weight does not only depend on the pre-
-and postsynaptic spike timing but also on the postsynaptic dendritic potential.
+Description
++++++++++++
 
-Urbanczik synapses require archiving of continuous quantities. Therefore they can only be connected to neuron models
-that are capable of doing this archiving. So far, the only compatible model is pp_cond_exp_mc_urbanczik.
+urbanczik_synapse is a connector to create Urbanczik synapses as defined in
+[1]_ that can connect suitable :ref:`multicompartment models
+<multicompartment-models>`. In contrast to most STDP models, the synaptic weight
+depends on the postsynaptic dendritic potential, in addition to the pre- and
+postsynaptic spike timing.
 
-Parameters:
+Urbanczik synapses require the archiving of the dendritic membrane potential
+which is continuous in time. Therefore they can only be connected to neuron
+models that are capable of doing this archiving. So far, the only compatible
+model is :doc:`pp_cond_exp_mc_urbanczik <pp_cond_exp_mc_urbanczik>`.
 
-\verbatim embed:rst
-=======   ======  ==========================================================
-eta       real    Learning rate
-tau_Delta real    Time constant of low pass filtering of the weight change
-Wmax      real    Maximum allowed weight
-Wmin      real    Minimum allowed weight
-=======   ======  ==========================================================
-\endverbatim
+Parameters
+++++++++++
 
-All other parameters are stored in in the neuron models that are compatible with the Urbanczik synapse.
+=========   ====   =========================================================
+eta         real   Learning rate
+tau_Delta   real   Time constant of low pass filtering of the weight change
+Wmax        real   Maximum allowed weight
+Wmin        real   Minimum allowed weight
+=========   ====   =========================================================
+
+All other parameters are stored in the neuron models that are compatible
+with the Urbanczik synapse.
 
 Remarks:
 
-So far the implementation of the urbanczik_synapse only supports two-compartment neurons.
+So far the implementation of the urbanczik_synapse only supports
+two-compartment neurons.
+
+Transmits
++++++++++
+
+SpikeEvent
 
-Transmits: SpikeEvent
+References
+++++++++++
 
-References:
+.. [1] Urbanczik R. and Senn W (2014). Learning by the dendritic prediction of
+       somatic spiking. Neuron, 81:521 - 528. https://doi.org/10.1016/j.neuron.2013.11.030
 
-\verbatim embed:rst
-.. [1] R. Urbanczik, W. Senn (2014). Learning by the Dendritic Prediction of Somatic Spiking. Neuron, 81, 521 - 528.
-\endverbatim
-Authors: Jonas Stapmanns, David Dahmen, Jan Hahne
+See also
+++++++++
+
+stdp_synapse, clopath_synapse, pp_cond_exp_mc_urbanczik
+
+EndUserDocs */
 
-SeeAlso: stdp_synapse, clopath_synapse, pp_cond_exp_mc_urbanczik
-*/
 // connections are templates of target identifier type (used for pointer /
 // target index addressing) derived from generic connection template
+
 template < typename targetidentifierT >
 class urbanczik_synapse : public Connection< targetidentifierT >
 {
@@ -219,7 +234,7 @@ urbanczik_synapse< targetidentifierT >::send( Event& e, thread t, const CommonSy
       ( tau_L_trace_ * exp( minus_delta_t_up / tau_L ) - tau_s_trace_ * exp( minus_delta_t_up / tau_s ) ) * start->dw_;
     PI_integral_ += PI;
     dPI_exp_integral += exp( minus_t_down / tau_Delta_ ) * PI;
-    start++;
+    ++start;
   }
 
   PI_exp_integral_ = ( exp( ( t_lastspike_ - t_spike ) / tau_Delta_ ) * PI_exp_integral_ + dPI_exp_integral );