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 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 * 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 * \sin(\omega * t + phase)) * 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 <../neuron_docs/model_details/noise_generator.ipynb>`_
notebook included in the NEST source code.

Remarks
+++++++

 - All targets receive different currents.

 - 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 :math:`\tau_m` and
   capacity :math:`C_m`, membrane potential fluctuations Sigma at time
   :math:`t_j+delay` are given by

   .. math::

      \Sigma = std * \tau_m / C_m * \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 * \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 in ms (default: 1.0)

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

Set 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>`