Merge pull request #3084 from ackurth/iaf_psc_model_doc

Update documentation for ```iaf_psc_exp```

models/iaf_psc_exp.h

@@ -34,43 +34,99 @@
 
 namespace nest
 {
-
+// Disable clang-formatting for documentation due to over-wide table.
+// clang-format off
 /* BeginUserDocs: neuron, integrate-and-fire, current-based
 
 Short description
 +++++++++++++++++
 
-Leaky integrate-and-fire neuron model with exponential PSCs
+Leaky integrate-and-fire neuron model with exponential-shaped input currents
 
 Description
 +++++++++++
 
-``iaf_psc_exp`` is an implementation of a leaky integrate-and-fire model
-with exponential shaped postsynaptic currents (PSCs) according to [1]_.
-Thus, postsynaptic currents have an infinitely short rise time.
+``iaf_psc_exp``  a leaky integrate-and-fire model with
+
+* a hard threshold (if :math:`\delta=0`, see below)
+* a fixed refractory period,
+* no adaptation mechanisms,
+* exponential-shaped synaptic input currents according to [1]_.
+
+Membrane potential evolution, spike emission, and refractoriness
+................................................................
+
+The membrane potential evolves according to
+
+.. math::
+
+   \frac{dV_\text{m}}{dt} = -\frac{V_{\text{m}} - E_\text{L}}{\tau_{\text{m}}} + \frac{I_{\text{syn}} + I_\text{e}}{C_{\text{m}}}
+
+where the synaptic input current :math:`I_{\text{syn}}(t)` is discussed below and :math:`I_\text{e}` is
+a constant input current set as a model parameter.
+
+A spike is emitted at time step :math:`t^*=t_{k+1}` if
+
+.. math::
+
+   V_\text{m}(t_k) < V_{\text{th}} \quad\text{and}\quad V_\text{m}(t_{k+1})\geq V_\text{th} \;.
+
+Subsequently,
+
+.. math::
+
+   V_\text{m}(t) = V_{\text{reset}} \quad\text{for}\quad t^* \leq t < t^* + t_{\text{ref}} \;,
+
+that is, the membrane potential is clamped to :math:`V_{\text{reset}}` during the refractory period.
+
+.. note::
+
+	Spiking in this model can be either deterministic (:math:`\delta=0`) or stochastic (:math:`\delta > 0`).
+	In the stochastic case, this model implements a type of spike response model with escape noise.
+	Spiking is given by an inhomogeneous Poisson process with rate
+
+	.. math::
+		\rho \exp \left( \frac{V_{\text{m}} - V_{\text{th}}}{\delta} \right).
+
+Synaptic input
+..............
+
+The synaptic input current has an excitatory and an inhibitory component
+
+.. math::
+
+   I_{\text{syn}}(t) = I_{\text{syn, ex}}(t) + I_{\text{syn, in}}(t)
+
+where
+
+.. math::
 
-The threshold crossing is followed by an absolute refractory period (``t_ref``)
-during which the membrane potential is clamped to the resting potential
-and spiking is prohibited.
+   I_{\text{syn, X}}(t) = \sum_{j} w_j \sum_k i_{\text{syn, X}}(t-t_j^k-d_j) \;,
 
-The neuron dynamics is solved on the time grid given by the computation step
-size. Incoming as well as emitted spikes are forced to that grid.
+where :math:`j` indexes either excitatory (:math:`\text{X} = \text{ex}`)
+or inhibitory (:math:`\text{X} = \text{in}`) presynaptic neurons,
+:math:`k` indexes the spike times of neuron :math:`j`, and :math:`d_j`
+is the delay from neuron :math:`j`.
 
-The linear subthreshold dynamics is integrated by the Exact
-Integration scheme [2]_, which is more precise, but different from the
-implementation in [1]_, which uses the forward Euler integration scheme.
-This precludes an exact numerical reproduction of the results from [1]_.
+The individual post-synaptic currents (PSCs) are given by
 
-An additional state variable and the corresponding differential
-equation represents a piecewise constant external current.
+.. math::
 
-The general framework for the consistent formulation of systems with
-neuron like dynamics interacting by point events is described in
-[2]_. A flow chart can be found in [3]_.
+   i_{\text{syn, X}}(t) = w \cdot e^{-\frac{t}{\tau_{\text{syn, X}}}} \cdot \Theta(t)
+
+where :math:`w` is a weight (excitatory if :math:`w > 0` or inhibitory if :math:`w < 0`), and :math:`\Theta(x)` is the Heaviside step function. The time dependent components of the PSCs are normalized to unit maximum, so that,
+
+.. math::
+
+   i_{\text{syn, X}}(t= 0) = w \;.
+
+As a consequence, the total charge :math:`q` transferred by a single PSC depends
+on the synaptic time constant according to
+
+.. math::
+
+   q = \int_0^{\infty}  i_{\text{syn, X}}(t) dt = w \cdot \tau_{\text{syn, X}} \;.
 
-Spiking in this model can be either deterministic (delta=0) or stochastic (delta
-> 0). In the stochastic case this model implements a type of spike response
-model with escape noise [4]_.
 
 .. note::
 
@@ -108,21 +164,33 @@ Parameters
 
 The following parameters can be set in the status dictionary.
 
-===========  =======  ========================================================
- E_L          mV      Resting membrane potential
- C_m          pF      Capacity of the membrane
- tau_m        ms      Membrane time constant
- tau_syn_ex   ms      Exponential decay time constant of excitatory synaptic
-                      current kernel
- tau_syn_in   ms      Exponential decay time constant of inhibitory synaptic
-                      current kernel
- t_ref        ms      Duration of refractory period (V_m = V_reset)
- V_m          mV      Membrane potential in mV
- V_th         mV      Spike threshold in mV
- V_reset      mV      Reset membrane potential after a spike
- I_e          pA      Constant input current
- t_spike      ms      Point in time of last spike
-===========  =======  ========================================================
+
+=============== ================== =============================== ========================================================================
+**Parameter**   **Default**        **Math equivalent**             **Description**
+=============== ================== =============================== ========================================================================
+``E_L``         -70 mV             :math:`E_\text{L}`              Resting membrane potential
+``C_m``         250 pF             :math:`C_{\text{m}}`            Capacity of the membrane
+``tau_m``       10 ms              :math:`\tau_{\text{m}}`         Membrane time constant
+``t_ref``       2 ms               :math:`t_{\text{ref}}`          Duration of refractory period
+``V_th``        -55 mV             :math:`V_{\text{th}}`           Spike threshold
+``V_reset``     -70 mV             :math:`V_{\text{reset}}`        Reset potential of the membrane
+``tau_syn_ex``  2 ms               :math:`\tau_{\text{syn, ex}}`   Rise time of the excitatory synaptic alpha function
+``tau_syn_in``  2 ms               :math:`\tau_{\text{syn, in}}`   Rise time of the inhibitory synaptic alpha function
+``I_e``         0 pA               :math:`I_\text{e}`              Constant input current
+``delta``       0 mV               :math:`\delta`                  Parameter scaling stochastic spiking
+``rho``         0.01 1/s           :math:`\rho`                    Baseline stochastic spiking
+=============== ================== =============================== ========================================================================
+
+The following state variables evolve during simulation and are available either as neuron properties or as recordables.
+
+================== ================= ========================== =================================
+**State variable** **Initial value** **Math equivalent**        **Description**
+================== ================= ========================== =================================
+``V_m``            -70 mV            :math:`V_{\text{m}}`       Membrane potential
+``I_syn_ex``       0 pA              :math:`I_{\text{syn, ex}}` Excitatory synaptic input current
+``I_syn_in``       0 pA              :math:`I_{\text{syn, in}}` Inhibitory synaptic input current
+================== ================= ========================== =================================
+
 
 References
 ++++++++++