noise_generator – Generate a Gaussian white noise current
=========================================================

Description
+++++++++++

This device can be used to inject a Gaussian "white" noise current into a node.

The current is not really white, but a piecewise constant current with
Gaussian distributed amplitude. The current changes at intervals of
dt. dt must be a multiple of the simulation step size, the default is
10 times the simulation resolution (equating to 1.0 ms, corresponding
to a 1 kHz cut-off).

Additionally a second sinusodial modulated term can be added to the standard
deviation of the noise.

The current generated is given by

.. math::

  I(t) = mean + std \cdot N_j  \text{ for } t_0 + j dt \leq t < t_0 + (j-1) dt

where :math:`N_j` are Gaussian random numbers with unit standard deviation and
:math:`t_0` is the device onset time.
If the modulation is added the current is given by

.. math::

   I(t) = mean + \sqrt(std^2 + std_{mod}^2 \cdot \sin(\omega \cdot t + phase)) \cdot N_j \\
                              \text{ for } t_0 + j dt \leq t < t_0 + (j-1) dt

For a detailed discussion of the properties of the noise generator, please see
`noise_generator <../model_details/noise_generator.ipynb>`_
notebook included in the NEST source code.

All targets receive different currents, but the currents for all
targets change at the same points in time. The interval between
changes, ``dt``, must be a multiple of the time step.

The effect of this noise current on a neuron depends on ``dt``. Consider
the membrane potential fluctuations evoked when a noise current is
injected into a neuron. The standard deviation of these fluctuations
across an ensemble will increase with ``dt`` for a given value of ``std``.
For the leaky integrate-and-fire neuron with time constant ``tau_m`` and
capacity ``C_m``, membrane potential fluctuations Sigma at time
:math:`t_j+delay` are given by

.. math::

   \Sigma = std \cdot \tau_m / C_m \cdot \sqrt( (1-x) / (1+x) )  \\
                          \text{where } x = exp(-dt/\tau_m)

for large :math:`t_j`. In the white noise limit, :math:`dt \rightarrow 0`, one has

.. math::

   \Sigma \rightarrow std / C_m * \sqrt(dt \cdot \tau / 2).

To obtain comparable results for different values of dt, you must adapt std.

As the noise generator provides a different current for each of its targets,
the current recorded represents the instantaneous average of all the
currents computed. When there exists only a single target, this would be
equivalent to the actual current provided to that target.

.. include:: ../models/stimulation_device.rst

mean
    The mean value of the noise current (pA)

std
    The standard deviation of noise current (pA)

dt
    The interval between changes in current (ms; default: 10 * resolution)

std_mod
    The modulated standard deviation of noise current (pA)

phase
    The phase of sine modulation (0-360 deg)

frequency
    The frequency of the sine modulation

Setting parameters from a stimulation backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The parameters in this stimulation device can be updated with input
coming from a stimulation backend. The data structure used for the
update holds one value for each of the parameters mentioned above.
The indexing is as follows:

 0. mean
 1. std
 2. std_mod
 3. frequency
 4. phase

Sends
+++++

CurrentEvent

See also
++++++++
:doc:`Device <index_device>`, :doc:`Generator <index_generator>`