Add Ornstein–Uhlenbeck noise generator #3541

FinnBurkhardt · 2025-08-01T10:05:04Z

Add Ornstein–Uhlenbeck Noise Generator

This pull request adds a new ou_noise_generator device and corresponding pytest-based tests. The device generates temporally correlated current following an Ornstein–Uhlenbeck (OU). The tests verify both parameter handling and statistical properties.

Model Implementation

Files added
- models/ou_noise_generator.h
- models/ou_noise_generator.cpp
- pytests/sli2py_stimulating/test_ou_noise_generator.py
Process equation
The state variable (x) evolves as

$$ dx = \frac{1}{\tau}(\mu - x)\ dt + \sigma\ dW $$

where

($\mu$) (mean parameter) is the long-term mean of the process,
($\sigma$) (std parameter) its stationary standard deviation,
($\tau$) (tau parameter) is the time constant,
dt is the internal integration step.
Integration and output
- Internally integrates the OU equation at user-specified dt.
- On each simulation step it emits the current (x) to connected targets.

Tests (`test_ou_noise_generator.py`)

Parameter setting and defaults
- Verifies that set() and SetDefaults() both correctly configure all parameters (mean, std, tau, dt).
Error conditions
- Asserts that attempting to create the generator with a dt not divisible by nest.resolution raises StepMultipleRequired.
Mean and variance
- Runs 100 trials of 1000 ms each, records the last current value, and checks that the sample mean and variance match the target $\mu$ and $\sigma^2$ within reasonable statistical bounds.
Autocorrelation
- Collects a long trace, discards the initial $10\tau$ burn-in, and computes the empirical lag-1 autocorrelation.
- Confirms it matches $\exp(-\text{dt}/\tau)$ within a small tolerance.
Cross-correlation
- Connects a single OU generator to two independent neurons and records their membrane potentials.
- Computes the cross-correlation of the two voltage traces and verifies it remains near zero.

jessica-mitchell

Thanks for the contribution!
I have a minor change for the docs, and a question if there is a good use case we can use an example for this generator?

models/ou_noise_generator.h

models/ou_noise_generator.cpp

heplesser · 2025-09-10T20:10:07Z

@FinnBurkhardt Would you be able to address the open issues within a few days? I also added two minor suggestions. Please merge master into your branch for this PR to ensure that the testsuite works properly.

FinnBurkhardt · 2025-09-12T08:17:48Z

Thanks for the contribution! I have a minor change for the docs, and a question if there is a good use case we can use an example for this generator?

Thanks, I’ve applied the suggested changes.

For examples, I’d have two candidates at hand:

Single neuron driven by the OU noise generator.
White vs. OU noise (matched mean/variance), comparing firing rate and coefficient of variation.

Would one (or both) be useful for the docs?

jessica-mitchell · 2025-09-12T09:31:11Z

@FinnBurkhardt if they are ready then we could take both.
You can add them to pynest/examples/ (please adhere to the style of docstring as in the other examples)

And you can add it to the doc/htmldoc/examples/index.rst page:
I think in the 'stimulating network' section would make sense?

 .. grid-item-card:: Stimulating networks :img-top: ../static/img/pynest/sensitivitypertubation.png * :doc:`../auto_examples/sinusoidal_poisson_generator` * :doc:`../auto_examples/sinusoidal_gamma_generator` * :doc:`../auto_examples/repeated_stimulation` * :doc:`../auto_examples/sensitivity_to_perturbation` * :doc:`../auto_examples/intrinsic_currents_spiking` * :doc:`../auto_examples/intrinsic_currents_subthreshold`

It also needs to be added to the .. toctree::

I can also help with this if it's confusing!

jessica-mitchell

Thanks @FinnBurkhardt looks good, just a few minor formatting suggestions

pynest/examples/ou_noise_single_neuron.py

pynest/examples/ou_vs_white_noise.py

jessica-mitchell

thanks!

clinssen · 2025-11-03T11:13:43Z

models/ou_noise_generator.h

+mean
+ The mean value :math:`\mu` to which the process reverts (pA).
+
+std


On line 66 of models/ou_noise_generator.cpp, this unit is given as pA/sqrt(s)

clinssen · 2025-11-03T11:14:30Z

models/ou_noise_generator.h

+ struct Parameters_
+ {
+ double mean_; //!< mean current, in pA
+ double std_; //!< standard deviation of current, in pA


clinssen · 2025-11-03T11:14:42Z

models/ou_noise_generator.h

+ {
+ double mean_; //!< mean current, in pA
+ double std_; //!< standard deviation of current, in pA
+ double tau_; //!< Standard frequency in Hz


unit here seems wrong

clinssen · 2025-11-03T11:16:08Z

models/ou_noise_generator.h

+
+ /**
+ * Number of targets.
+ * This is a hidden parameter; must be placed in parameters,


Just curious why not put it into Variables?

I am wondering the same thing, but it is the same in noise_generator and several other generators. This comment may be very old, from the time when we still had a (non-working) ResetNetwork command. But changing that should be done for all pertaining generators. I have created #3617 for follow-up and suggest we keep it as is here.

clinssen

Thanks for the PR! I just have some small comments/questions.

heplesser

Thanks for the revisions. I noticed a few more details and added one principal questions concerning the return from periods of inactivity.

heplesser · 2025-11-06T03:59:15Z

models/ou_noise_generator.h

+public:
+ ou_noise_generator();
+ ou_noise_generator( const ou_noise_generator& );
+


Suggested change

heplesser · 2025-11-06T04:04:42Z

models/ou_noise_generator.h

+ double noise_amp_; //!<
+ double tau_inv_; //!<


Comment texts are missing here. I find tau_inv_ misleading (would expect value 1/tau from the name), while it is 1-exp(-h/tau). Can you find a better name? Further, if I understand the code right, it is only used in in the combination P_.mean_ * V_.tau_inv_, so why not store that value in a variable mean_decayed_ (or whatever would be a good name)?

heplesser · 2025-11-06T04:13:25Z

models/ou_noise_generator.h

+
+ /**
+ * Number of targets.
+ * This is a hidden parameter; must be placed in parameters,


I am wondering the same thing, but it is the same in noise_generator and several other generators. This comment may be very old, from the time when we still had a (non-working) ResetNetwork command. But changing that should be done for all pertaining generators. I have created #3617 for follow-up and suggest we keep it as is here.

heplesser · 2025-11-06T04:16:54Z

models/ou_noise_generator.cpp

+ const double h = Time::get_resolution().get_ms();
+ const double t = kernel().simulation_manager.get_time().get_ms();
+
+ // scale Hz to ms


This comment seems to make no sense here.

heplesser · 2025-11-06T04:18:28Z

models/ou_noise_generator.cpp

+ const double noise_amp = P_.std_ * std::sqrt( -1 * std::expm1( -2 * h / P_.tau_ ) );
+ const double prop = std::exp( -1 * h / P_.tau_ );
+ const double tau_inv = -std::expm1( -h / P_.tau_ );
+
+ V_.noise_amp_ = noise_amp;
+ V_.prop_ = prop;
+ V_.tau_inv_ = tau_inv;


I would simplify this a bit

Suggested change

const double noise_amp = P_.std_ * std::sqrt( -1 * std::expm1( -2 * h / P_.tau_ ) );

const double prop = std::exp( -1 * h / P_.tau_ );

const double tau_inv = -std::expm1( -h / P_.tau_ );

V_.noise_amp_ = noise_amp;

V_.prop_ = prop;

V_.tau_inv_ = tau_inv;

V_.noise_amp_ = P_.std_ * std::sqrt( -1 * std::expm1( -2 * h / P_.tau_ ) );

V_.prop_ = std::exp( -1 * h / P_.tau_ );

V_.tau_inv_ = -std::expm1( -h / P_.tau_ );

heplesser · 2025-11-06T04:27:23Z

models/ou_noise_generator.cpp

+ }
+
+ // >= in case we woke from inactivity
+ if ( now >= B_.next_step_ )


I wonder if the logic for handling inactivity is correct here. Consider a situation like the following:

ou = nest.Create('ou_noise_generator', params={'start': 200, 'stop': 500'}) for k in range(10): ou.offset = k * 1000 nest.Simulate(1000)

This runs a simulation in sections of 1000 ms and in each section the generator is on from 200 to 500 ms and off in between.

With the code as it is now, we freeze the OU process while the generator is inactive. But would it not make more sense to assume that the process runs permanently and we only send its values out between start and stop? Then, amp should always be updated and only I_amp should be kept to 0 and no events sent out while the generator is inactive. Or does this not matter? Or could on be more efficient and correct in probability by updating according to the time that has passed since the generator was last active?

heplesser · 2025-11-06T04:29:47Z

models/ou_noise_generator.h

+ You can use a :doc:`multimeter <multimeter>` to record the average current sent to all targets for each time step if
+ simulating on a single thread; multiple MPI processes with one thread each also work. In this case, the recording
+ interval of the multimeter should be equal to the `dt` of the generator to avoid aliasing effects. In multi-threaded
+ mode, recording of noise currents is prohibited for technical reasons.


I did not see that prohibition in the code.

heplesser · 2025-11-06T04:32:34Z

testsuite/pytests/sli2py_stimulating/test_ou_noise_generator.py

@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-


This file should be directly in pytests. The sli2py_* directories are only for tests ported from SLI.

JoshuaBoettcher and others added 8 commits July 31, 2025 23:34

added first draft of ou_noise_gererator model

da3b29a

add unfinished ou_noise_generator test

82b48c0

bug fix in ou_noise_generator

500c332

Fix minor error

1f02f0b

fix and add tests

8be0909

cleanup tests

d583852

formatting

d33e09c

rewrite UserDocs

f8f0511

heplesser requested a review from jessica-mitchell August 7, 2025 14:10

heplesser added T: Enhancement New functionality, model or documentation S: Normal Handle this with default priority I: No breaking change Previously written code will work as before, no one should note anything changing (aside the fix) labels Aug 7, 2025

heplesser added this to Models Aug 7, 2025

github-project-automation bot moved this to To do in Models Aug 7, 2025

FinnBurkhardt added 3 commits August 10, 2025 17:37

Improve code style and correct copyright header

fc8fa54

Skip ou_noise_generator in multimeter stepping test

8fe0262

Skip ou_noise_generator in tic-base tests

f3b27c3

jessica-mitchell changed the title ~~Add ou generator~~ Add Ornstein–Uhlenbeck noise generator Aug 11, 2025

jessica-mitchell requested changes Aug 11, 2025

View reviewed changes

models/ou_noise_generator.h Outdated Show resolved Hide resolved

models/ou_noise_generator.h Outdated Show resolved Hide resolved

models/ou_noise_generator.h Outdated Show resolved Hide resolved

github-project-automation bot moved this from To do to Review in Models Aug 11, 2025

Apply doc suggestions

c0e77e7

terhorstd requested a review from jakobkramp August 13, 2025 07:26

clinssen reviewed Aug 25, 2025

View reviewed changes

models/ou_noise_generator.h Outdated Show resolved Hide resolved

jakobkramp approved these changes Sep 2, 2025

View reviewed changes

heplesser reviewed Sep 10, 2025

View reviewed changes

models/ou_noise_generator.cpp Outdated Show resolved Hide resolved

heplesser reviewed Sep 10, 2025

View reviewed changes

models/ou_noise_generator.cpp Show resolved Hide resolved

FinnBurkhardt added 2 commits September 11, 2025 17:40

Tau validation and cleanup

e7aa371

Merge remote-tracking branch 'upstream/master' into add_ou_generator

079b240

heplesser requested a review from jessica-mitchell September 11, 2025 17:44

heplesser requested a review from clinssen September 11, 2025 17:44

FinnBurkhardt added 2 commits September 11, 2025 19:50

cleanup

7637ff0

Set tau default to 1

a012822

Add example scripts

791beed

jessica-mitchell requested changes Oct 8, 2025

View reviewed changes

Improve formatting in example scripts

19b4e8f

jessica-mitchell approved these changes Oct 23, 2025

View reviewed changes

clinssen reviewed Nov 3, 2025

View reviewed changes

heplesser requested changes Nov 6, 2025

View reviewed changes

Add Ornstein–Uhlenbeck noise generator #3541

Are you sure you want to change the base?

Add Ornstein–Uhlenbeck noise generator #3541

Uh oh!

Conversation

FinnBurkhardt commented Aug 1, 2025

Add Ornstein–Uhlenbeck Noise Generator

Model Implementation

Tests (test_ou_noise_generator.py)

jessica-mitchell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

heplesser commented Sep 10, 2025

FinnBurkhardt commented Sep 12, 2025

jessica-mitchell commented Sep 12, 2025

jessica-mitchell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jessica-mitchell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

clinssen left a comment

Choose a reason for hiding this comment

heplesser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Labels

6 participants

Tests (`test_ou_noise_generator.py`)