add note about pecularitites issue 3088

Author: jessica-mitchell

models/aeif_cond_alpha.h

@@ -103,7 +103,15 @@ and
 For the reference implementation of this model, see
 `aeif_models_implementation <../model_details/aeif_models_implementation.ipynb>`_ notebook.
 
-See also [1]_.
+
+.. note::
+
+    The default refractory period for ``aeif`` models is zero, consistent with the model definition in
+    Brette & Gerstner [1]_.
+    This means if the refractory period is zero, the ``aeif`` neurons can fire multiple spikes in a single time step,
+    which can lead to exploding spike numbers and extreme slow-down of simulations.
+
+    We recommend users set ``t_ref > 0``.
 
 Parameters
 ++++++++++

models/aeif_cond_alpha_astro.h

@@ -110,7 +110,15 @@ For implementation details of the adaptive exponential integrate-and-fire neuron
 model, see the
 `aeif_models_implementation <../model_details/aeif_models_implementation.ipynb>`_ notebook.
 
-See also [1]_.
+
+.. note::
+
+    The default refractory period for ``aeif`` models is zero, consistent with the model definition in
+    Brette & Gerstner [1]_.
+    This means if the refractory period is zero, the ``aeif`` neurons can fire multiple spikes in a single time step,
+    which can lead to exploding spike numbers and extreme slow-down of simulations.
+
+    We recommend users set ``t_ref > 0``.
 
 Parameters
 ++++++++++

models/aeif_cond_alpha_multisynapse.h

@@ -96,6 +96,15 @@ When the neuron fires a spike, the adaptation current :math:`w <- w + b`.
 For implementation details see the
 `aeif_models_implementation <../model_details/aeif_models_implementation.ipynb>`_ notebook.
 
+.. note::
+
+    The default refractory period for ``aeif`` models is zero, consistent with the model definition in
+    Brette & Gerstner [1]_.
+    This means if the refractory period is zero, the ``aeif`` neurons can fire multiple spikes in a single time step,
+    which can lead to exploding spike numbers and extreme slow-down of simulations.
+
+    We recommend users set ``t_ref > 0``.
+
 Parameters
 ++++++++++
 
@@ -155,6 +164,14 @@ Receives
 
 SpikeEvent, CurrentEvent, DataLoggingRequest
 
+References
+++++++++++
+
+.. [1] Brette R and Gerstner W (2005). Adaptive exponential
+       integrate-and-fire model as an effective description of neuronal
+       activity. Journal of Neurophysiology. 943637-3642
+       DOI: https://doi.org/10.1152/jn.00686.2005
+
 See also
 ++++++++
 

models/aeif_cond_beta_multisynapse.h

@@ -113,6 +113,15 @@ When the neuron fires a spike, the adaptation current `w <- w + b`.
 For implementation details see the
 `aeif_models_implementation <../model_details/aeif_models_implementation.ipynb>`_ notebook.
 
+.. note::
+
+    The default refractory period for ``aeif`` models is zero, consistent with the model definition in
+    Brette & Gerstner [1]_.
+    This means if the refractory period is zero, the ``aeif`` neurons can fire multiple spikes in a single time step,
+    which can lead to exploding spike numbers and extreme slow-down of simulations.
+
+    We recommend users set ``t_ref > 0``.
+
 Parameters
 ++++++++++
 
@@ -172,6 +181,14 @@ Receives
 
 SpikeEvent, CurrentEvent, DataLoggingRequest
 
+References
+++++++++++
+
+.. [1] Brette R and Gerstner W (2005). Adaptive exponential
+       integrate-and-fire model as an effective description of neuronal
+       activity. Journal of Neurophysiology. 943637-3642
+       DOI: https://doi.org/10.1152/jn.00686.2005
+
 See also
 ++++++++
 

models/aeif_cond_exp.h

@@ -105,7 +105,15 @@ setting V_peak too high.
 For implementation details see the
 `aeif_models_implementation <../model_details/aeif_models_implementation.ipynb>`_ notebook.
 
-See also [1]_.
+
+.. note::
+
+    The default refractory period for ``aeif`` models is zero, consistent with the model definition in
+    Brette & Gerstner [1]_.
+    This means if the refractory period is zero, the ``aeif`` neurons can fire multiple spikes in a single time step,
+    which can lead to exploding spike numbers and extreme slow-down of simulations.
+
+    We recommend users set ``t_ref > 0``.
 
 
 Parameters:

models/aeif_psc_alpha.h

@@ -95,7 +95,14 @@ Here :math:`H(t)` is the Heaviside step function and `k` indexes incoming spikes
 For implementation details see the
 `aeif_models_implementation <../model_details/aeif_models_implementation.ipynb>`_ notebook.
 
-See also [1]_.
+.. note::
+
+    The default refractory period for ``aeif`` models is zero, consistent with the model definition in
+    Brette & Gerstner [1]_.
+    This means if the refractory period is zero, the ``aeif`` neurons can fire multiple spikes in a single time step,
+    which can lead to exploding spike numbers and extreme slow-down of simulations.
+
+    We recommend users set ``t_ref > 0``.
 
 Parameters
 ++++++++++

models/aeif_psc_delta.h

@@ -97,7 +97,14 @@ the value of `J` after a spike.
 For implementation details see the
 `aeif_models_implementation <../model_details/aeif_models_implementation.ipynb>`_ notebook.
 
-See also [1]_.
+.. note::
+
+    The default refractory period for ``aeif`` models is zero, consistent with the model definition in
+    Brette & Gerstner [1]_.
+    This means if the refractory period is zero, the ``aeif`` neurons can fire multiple spikes in a single time step,
+    which can lead to exploding spike numbers and extreme slow-down of simulations.
+
+    We recommend users set ``t_ref > 0``.
 
 Parameters
 ++++++++++

models/aeif_psc_delta_clopath.h

@@ -93,6 +93,15 @@ For implementation details see the
 
 See also [2]_.
 
+.. note::
+
+    The default refractory period for ``aeif`` models is zero, consistent with the model definition in
+    Brette & Gerstner [4]_.
+    This means if the refractory period is zero, the ``aeif`` neurons can fire multiple spikes in a single time step,
+    which can lead to exploding spike numbers and extreme slow-down of simulations.
+
+    We recommend users set ``t_ref > 0``.
+
 Parameters
 ++++++++++
 
@@ -190,6 +199,11 @@ References
 .. [3] Voltage-based STDP synapse (Clopath et al. 2010) on ModelDB
        https://modeldb.science/144566?tab=1
 
+.. [4] Brette R and Gerstner W (2005). Adaptive exponential
+       integrate-and-fire model as an effective description of neuronal
+       activity. Journal of Neurophysiology. 943637-3642
+       DOI: https://doi.org/10.1152/jn.00686.2005
+
 See also
 ++++++++
 

models/aeif_psc_exp.h

@@ -95,7 +95,14 @@ Here :math:`H(t)` is the Heaviside step function and `k` indexes incoming spikes
 For implementation details see the
 `aeif_models_implementation <../model_details/aeif_models_implementation.ipynb>`_ notebook.
 
-See also [1]_.
+.. note::
+
+    The default refractory period for ``aeif`` models is zero, consistent with the model definition in
+    Brette & Gerstner [1]_.
+    This means if the refractory period is zero, the ``aeif`` neurons can fire multiple spikes in a single time step,
+    which can lead to exploding spike numbers and extreme slow-down of simulations.
+
+    We recommend users set ``t_ref > 0``.
 
 Parameters
 ++++++++++