Update Izhikevich model documentation

models/izhikevich.h

@@ -33,67 +33,81 @@
 
 namespace nest
 {
-
+// Disable clang-formatting for documentation due to over-wide table.
+// clang-format off
 /* BeginUserDocs: neuron, integrate-and-fire, adaptation, soft threshold
 
 Short description
 +++++++++++++++++
 
-Izhikevich neuron model
+Izhikevich Neuron Model
 
 Description
-+++++++++++
+++++++++++++
+
+``izhikevich`` implements the simple spiking neuron model introduced by Izhikevich [1]_.
+This model reproduces spiking and bursting behavior of known types of cortical neurons.
+
+Membrane potential evolution, spike emission, and refractoriness
+................................................................
+
+The model is defined by the following differential equations:
+
+.. math::
 
-Implementation of the simple spiking neuron model introduced by Izhikevich
-[1]_. The dynamics are given by:
+   \frac{dV_{\text{m}}}{dt} = 0.04 V_{\text{m}}^2 + 5 V_{\text{m}} + 140 - U_{\text{m}} + I_{\text{e}}
 
 .. math::
-   &dV_m/dt = 0.04 {V_m}^2 + 5 V_m + 140 - U_m + I \\
-   &dU_m/dt = a (b V_m - U_m) \\
+
+   \frac{dU_{\text{m}}}{dt} = a (b V_{\text{m}} - U_{\text{m}})
+
+where :math:`V_{\text{m}}` is the membrane potential, :math:`U_{\text{m}}` is the recovery variable, and
+:math:`I_{\text{e}}` is the input current.
+
+A spike is emitted when :math:`V_{\text{m}}` reaches a threshold :math:`V_{\text{th}}`.
+At this point, the membrane potential and recovery variable are updated according to:
 
 .. math::
 
-   &\text{if}\;\;\; V_m \geq V_{th}:\\
-   &\;\;\;\; V_m \text{ is set to } c\\
-   &\;\;\;\; U_m \text{ is incremented by } d\\
-   & \, \\
-   &V_m \text{ jumps on each spike arrival by the weight of the spike}
+   &\text{if}\;\ V_m \geq V_{th}:\\
+   &\;\ V_m \text{ is set to } c\\
+   &\;\ U_m \text{ is incremented by } d\\
+
+In addition, each incoming spike increases :math:`V_{\text{m}}` by the synaptic weight associated with the spike.
+
+As published in [1]_, the numerics differs from the standard forward Euler technique in two ways:
+
+ * the recovery variable :math:`U_{\text{m}}` is updated based on the new value of :math:`V_{\text{m}}`, rather than the previous one.
+ * the membrane potential :math:`V_{\text{m}}` is updated with a time step half the size of that used for :math:`U_{\text{m}}`.
 
-As published in [1]_, the numerics differs from the standard forward Euler
-technique in two ways:
+This model offers both forms of integration, they can be selected using the boolean parameter ``consistent_integration``:
 
-1) the new value of :math:`U_m` is calculated based on the new value of
-   :math:`V_m`, rather than the previous value
-2) the variable :math:`V_m` is updated using a time step half the size of that
-   used to update variable :math:`U_m`.
+ * ``consistent_integration = false``: use the published form of the dynamics (for replicating published results).
+ * ``consistent_integration = true`` *(default)*: use the standard Euler method (recommended for general use).
 
-This model offers both forms of integration, they can be selected using the
-boolean parameter ``consistent_integration``. To reproduce some results
-published on the basis of this model, it is necessary to use the published form
-of the dynamics. In this case, ``consistent_integration`` must be set to false.
-For all other purposes, it is recommended to use the standard technique for
-forward Euler integration. In this case, ``consistent_integration`` must be set
-to true (default).
+.. note::
 
-For a detailed analysis and discussion of the numerical issues in the original publication, see [2]_.
+   For a detailed analysis of the numerical differences between these integration schemes and their impact on simulation results, see [2]_.
 
 Parameters
 ++++++++++
 
 The following parameters can be set in the status dictionary.
 
-======================= =======  ==============================================
- V_m                    mV       Membrane potential
- U_m                    mV       Membrane potential recovery variable
- V_th                   mV       Spike threshold
- I_e                    pA       Constant input current (R=1)
- V_min                  mV       Absolute lower value for the membrane potential
- a                      real     Describes time scale of recovery variable
- b                      real     Sensitivity of recovery variable
- c                      mV       After-spike reset value of V_m
- d                      mV       After-spike reset value of U_m
- consistent_integration boolean  Use standard integration technique
-======================= =======  ==============================================
+======================= ============ ====================== ===================================================
+**Parameter**           **Default**  **Math equivalent**    **Description**
+======================= ============ ====================== ===================================================
+ V_m                    -65 mV       :math:`V_{\text{m}}`   Membrane potential
+ U_m                    -13 mV       :math:`U_{\text{m}}`   Membrane potential recovery variable
+ V_th                   30 mV        :math:`V_{\text{th}}`  Spike threshold
+ I_e                    0 pA         :math:`I_{\text{e}}`   Constant input current (R=1)
+ V_min                  -1.79 mV     :math:`V_{\text{min}}` Absolute lower value for the membrane potential
+ a                      0.02 real    :math:`a`              Describes time scale of recovery variable
+ b                      0.2 real     :math:`b`              Sensitivity of recovery variable
+ c                      -65 mV       :math:`c`              After-spike reset value of V_m
+ d                      8 mV         :math:`d`              After-spike reset value of U_m
+ consistent_integration ``true``     None                   Use standard integration technique
+======================= ============ ====================== ===================================================
 
 References
 ++++++++++