Merge pull request #2137 from clinssen/synaptic-plasticity-precise-sp…

…ikes-warn

Add warning about synaptic plasticity mechanisms and precise spike timing

models/clopath_synapse.h

@@ -60,6 +60,13 @@ synapses can only be connected to neuron models that are capable of doing this
 archiving. So far, compatible models are aeif_psc_delta_clopath and
 hh_psc_alpha_clopath.
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/ht_synapse.h

@@ -54,6 +54,13 @@ Synaptic dynamics are given by
 For implementation details see:
 `HillTononi_model <../model_details/HillTononiModels.ipynb>`_
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/jonke_synapse.h

@@ -39,50 +39,87 @@
 namespace nest
 {
 
-/* BeginDocumentation
-  Name: jonke_synapse - Synapse type for spike-timing dependent
-    plasticity with additional additive factors.
-  Description:
-    jonke_synapse is a connector to create synapses with spike time
-    dependent plasticity. Unlike stdp_synapse, we use the update equations:
-    \Delta w = \lambda * w_{max} * (K_+(w) * F_+(t) - beta)            if t - t_j^(k) > 0
-    \Delta w = \lambda * w_{max} * (-alpha * K_-(w) * F_-(t) - beta)   else
-    where
-    K_+(w) = exp(\nu_+ w)
-    K_-(w) = exp(\nu_- w)
-    and
-    F_+(t) = exp((t - t_j^(k))/tau_+)
-    F_-(t) = exp((t - t_j^(k))/tau_-)
-    This makes it possible to implement update rules which approximate the
-    rule of [1], e.g. the rules given in [2] and [3].
-  Parameters:
-    lambda          double - Step size
-    Wmax            double - Maximum allowed weight, note that this scales each
-                            weight update
-    alpha           double - Determine shape of depression term
-    mu_plus         double - Set weight dependency of facilitating update
-    mu_minus        double - Set weight dependency of depressing update
-    tau_plus        double - Time constant of STDP window, potentiation in ms
-    beta            double - Set negative offset for both updates
-    (tau_minus is defined in the postsynaptic neuron.)
-  Transmits: SpikeEvent
-  References:
-    [1] Nessler, Bernhard, et al. "Bayesian computation emerges in generic
-        cortical microcircuits through spike-timing-dependent plasticity." PLoS
-        computational biology 9.4 (2013): e1003037.
-    [2] Legenstein, Robert, et al. "Assembly pointers for variable binding in
-        networks of spiking neurons." arXiv preprint arXiv:1611.03698 (2016).
-    [3] Jonke, Zeno, et al. "Feedback inhibition shapes emergent computational
-        properties of cortical microcircuit motifs." arXiv preprint
-        arXiv:1705.07614 (2017).
-  Adapted from stdp_synapse:
-      FirstVersion: March 2006
-      Author: Moritz Helias, Abigail Morrison
-      Adapted by: Philipp Weidel
-  Author: Michael Mueller
-          Adapted by: Loïc Jeanningros ([email protected])
-  SeeAlso: synapsedict, stdp_synapse
-*/
+/* BeginUserDocs: synapse, spike-timing-dependent plasticity
+
+Short description
++++++++++++++++++
+
+Synapse type for spike-timing dependent plasticity with additional additive factors.
+
+Description
++++++++++++
+
+jonke_synapse is a connector to create synapses with spike time
+dependent plasticity. Unlike stdp_synapse, we use the update equations:
+
+.. math::
+
+   \Delta w &= \lambda * w_{max} * (K_+(w) * F_+(t) - \beta)           & \quad  if t - t_j^(k) > 0 \\
+   \Delta w &= \lambda * w_{max} * (-alpha * K_-(w) * F_-(t) - \beta)  & \quad  else
+
+where
+
+.. math::
+
+   K_+(w) &= \exp(\nu_+ w) \\
+   K_-(w) &= \exp(\nu_- w)
+
+and
+
+.. math::
+
+   F_+(t) &= \exp((t - t_j^(k))/\tau_+) \\
+   F_-(t) &= \exp((t - t_j^(k))/\tau_-)
+
+This makes it possible to implement update rules which approximate the
+rule stated in [1]_, and for examples, the rules given in [2]_ and [3]_.
+
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
+Parameters
+++++++++++
+
+========== ========  ======================================================
+ lambda     double    Step size
+ Wmax       double    Maximum allowed weight, note that this scales each
+                      weight update
+ alpha      double    Determine shape of depression term
+ mu_plus    double    Set weight dependency of facilitating update
+ mu_minus   double    Set weight dependency of depressing update
+ tau_plus   double    Time constant of STDP window, potentiation in ms
+ beta       double    Set negative offset for both updates
+========== ========  ======================================================
+
+(tau_minus is defined in the postsynaptic neuron.)
+
+Transmits
++++++++++
+
+SpikeEvent
+
+References
+++++++++++
+
+.. [1] Nessler, Bernhard, et al. "Bayesian computation emerges in generic
+       cortical microcircuits through spike-timing-dependent plasticity." PLoS
+       computational biology 9.4 (2013): e1003037.
+.. [2] Legenstein, Robert, et al. "Assembly pointers for variable binding in
+       networks of spiking neurons." arXiv preprint arXiv:1611.03698 (2016).
+.. [3] Jonke, Zeno, et al. "Feedback inhibition shapes emergent computational
+       properties of cortical microcircuit motifs." arXiv preprint
+       arXiv:1705.07614 (2017).
+
+See also
+++++++++
+
+synapsedict, stdp_synapse
+
+EndUserDocs */
 
 
 /**

models/quantal_stp_synapse.h

@@ -52,6 +52,13 @@ equations is taken from Maass and Markram 2002 [3]_.
 The connection weight is interpreted as the maximal weight that can
 be obtained if all n release sites are activated.
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/stdp_dopamine_synapse.h

@@ -54,6 +54,13 @@ of neurons. The spikes emitted by the pool of dopamine neurons are
 delivered to the synapse via the assigned volume transmitter. The
 dopaminergic dynamics is calculated in the synapse itself.
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/stdp_nn_pre_centered_synapse.h

@@ -76,6 +76,13 @@ occurrence, and is reset to 0 on a post-spike occurrence. The postsynaptic
 trace (implemented on the postsynaptic neuron side) decays with the time
 constant tau_minus and increases to 1 on a post-spike occurrence.
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/stdp_nn_restr_synapse.h

@@ -73,6 +73,13 @@ eligibility trace [1]_ (implemented on the postsynaptic neuron side). It
 decays exponentially with the time constant tau_minus and increases to 1 on
 a post-spike occurrence (instead of increasing by 1 as in stdp_synapse).
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/stdp_nn_symm_synapse.h

@@ -73,6 +73,13 @@ occurrence. The postsynaptic trace (implemented on the postsynaptic neuron
 side) decays with the time constant tau_minus and increases to 1 on a
 post-spike occurrence.
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/stdp_pl_synapse_hom.h

@@ -62,6 +62,13 @@ Parameters
 The parameters can only be set by SetDefaults and apply to all synapses of
 the model.
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 References
 ++++++++++
 

models/stdp_synapse.h

@@ -53,6 +53,13 @@ stdp_synapse is a connector to create synapses with spike time
 dependent plasticity (as defined in [1]_). Here the weight dependence
 exponent can be set separately for potentiation and depression.
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/stdp_synapse_facetshw_hom.h

@@ -54,6 +54,13 @@ The modified spike pairing scheme requires the calculation of tau_minus_
 within this synapse and not at the neuron site via Kplus_ like in
 stdp_synapse_hom.
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/stdp_synapse_hom.h

@@ -56,6 +56,13 @@ exponent can be set separately for potentiation and depression.
 * Guetig STDP         [1]_  mu_plus = mu_minus = [0.0,1.0]
 * van Rossum STDP     [4]_  mu_plus = 0.0 mu_minus = 1.0
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/stdp_triplet_synapse.h

@@ -56,6 +56,13 @@ plasticity accounting for spike triplet effects (as defined in [1]_).
   without changing the postsynaptic archiving-node (clip the traces to a
   maximum of 1).
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/tsodyks2_synapse.h

@@ -54,6 +54,13 @@ The parameter A_se from the publications is represented by the
 synaptic weight. The variable x in the synapse properties is the
 factor that scales the synaptic weight.
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/tsodyks_synapse.h

@@ -86,6 +86,13 @@ might choose to have a synaptic current that is not necessarily identical to
 the concentration of transmitter y(t) in the synaptic cleft. It may realize
 an arbitrary postsynaptic effect depending on y(t).
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/tsodyks_synapse_hom.h

@@ -84,6 +84,13 @@ might choose to have a synaptic current that is not necessarily identical to
 the concentration of transmitter y(t) in the synaptic cleft. It may realize
 an arbitrary postsynaptic effect depending on y(t).
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/urbanczik_synapse.h

@@ -61,6 +61,13 @@ 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>`.
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++
 

models/vogels_sprekeler_synapse.h

@@ -47,6 +47,13 @@ irrespective of the order of the pre- and postsynaptic spikes. Each
 pre-synaptic spike also causes a constant depression of the synaptic weight
 which differentiates this rule from other classical stdp rules.
 
+.. warning::
+
+   This synaptic plasticity rule does not take
+   :doc:`precise spike timing <simulations_with_precise_spike_times>` into
+   account. When calculating the weight update, the precise spike time part
+   of the timestamp is ignored.
+
 Parameters
 ++++++++++