Noise Process Interface

This page documents the interface functions for working with noise processes.

Process Contract

All noise objects in this package are subtypes of SciMLBase.AbstractNoiseProcess. The four type parameters are the scalar element type, array rank, saved-value array type, and the isinplace mutation convention. A concrete process must also behave like an AbstractDiffEqArray: saved values are indexed through the usual array interface, and callable processes evaluate (W, Z) at a time.

The callable forms are:

W(t)                    # returns (primary_value, auxiliary_value)
W(u, p, t)              # state- and parameter-aware form
W(out1, out2, u, p, t)  # in-place form when isinplace(W) is true

When no auxiliary process exists, the second returned value is nothing. The in-place form writes into out1 and, when applicable, out2; it must not replace those caller-owned buffers.

Solver Lifecycle

SDE and noise solvers use the exported lifecycle functions in this order:

setup_next_step!(W, u, p) prepares the pending increment for W.dt.
calculate_step!(W, dt, u, p) recomputes a pending increment without committing it.
accept_step!(W, dt, u, p, setup_next) commits the pending increment once and optionally prepares the next one.
reject_step!(W, dtnew, u, p) replaces a rejected increment while preserving its conditional distribution. A process that cannot support rejection must raise an explicit error; it must not silently reuse the old increment.
save_noise!(W) records the current point for history-backed processes.

The u and p arguments are nothing for state-independent noise. A process with state-dependent callbacks must forward them unchanged. Implementations must keep primary and auxiliary state synchronized. accept_step!, reject_step!, setup_next_step!, and save_noise! return nothing; calculate_step! may additionally return the selected step width for grid-backed processes, but callers should use the process state.

The step functions are developer-facing extension points for solver packages; the process's stack, cache, and scratch-buffer fields are not part of this contract. Use the lifecycle functions rather than mutating those fields.

Step Management

DiffEqNoiseProcess.accept_step! — Function

accept_step!(W::AbstractNoiseProcess, dt, u, p, setup_next = true)

Commit the pending increment prepared by calculate_step! or setup_next_step!. A concrete implementation must advance the current time by the pending step, update primary and auxiliary values exactly once, and store the proposed next step dt.

Arguments

W: Noise process being advanced.
dt: Proposed width of the next step; it may differ from the pending width.
u: Current differential-equation state, or nothing when unused.
p: Current parameters, or nothing when unused.
setup_next: If true, prepare the next pending increment before returning.

Returns

nothing.

DiffEqNoiseProcess.reject_step! — Function

reject_step!(W::AbstractNoiseProcess, dtnew, u, p)

Replace the pending step after an adaptive solver rejects the current proposal.

Interface rules

The replacement increment must have the same conditional distribution as the original process over dtnew; implementations with rejection memory may retain the unused portion for later steps. dtnew has the sign of the current step and is normally smaller in magnitude. A process that cannot preserve this contract must throw an informative error instead of silently reusing an invalid increment.

Arguments

W: Noise process with a pending step.
dtnew: Replacement step width.
u: Current differential-equation state, or nothing when unused.
p: Current parameters, or nothing when unused.

Returns

nothing.

DiffEqNoiseProcess.calculate_step! — Function

calculate_step!(W::AbstractNoiseProcess, dt, u, p)

Calculate and store the pending noise increment for a proposed step.

Interface rules

The pending increment must represent the process change over dt from the current state. Implementations must update pending-step state without committing the step; accept_step! performs the commit. In-place processes write into existing increment buffers, while out-of-place processes may allocate values.

Arguments

W: Noise process whose increment is prepared.
dt: Proposed step width.
u: Current differential-equation state, or nothing when unused.
p: Current parameters, or nothing when unused.

Returns

The concrete process may return nothing or the selected step width. Callers should use the process state rather than depend on this return value.

DiffEqNoiseProcess.setup_next_step! — Function

setup_next_step!(W::AbstractNoiseProcess, u, p)

Prepare the pending increment for the process's current W.dt.

Interface rules

The method is called before the first step and after an accepted step. It must leave a valid pending increment for calculate_step!/accept_step!, and it must preserve the distributional contract of the concrete process when adaptive steps are reused. NoiseProcess uses RSwM stacks; function, transport, grid, and VBT implementations may prepare a value directly.

Arguments

W: Noise process to prepare.
u: Current differential-equation state, or nothing when unused.
p: Current parameters, or nothing when unused.

Returns

nothing.

DiffEqNoiseProcess.save_noise! — Function

save_noise!(W::AbstractNoiseProcess)

Save the current time and noise value to the process history when the concrete process stores a history. Solver integrations call this after an accepted step.

Interface rules

Implementations must be idempotent when the current time is already the last saved time.
Primary and optional auxiliary values must remain aligned with the saved times.
Function- and transport-based processes may implement this as a no-op because they evaluate values lazily.

Returns

nothing.

Configuration

Rejection Sampling with Memory (RSWM)

DiffEqNoiseProcess.RSWM — Type

RSWM(; discard_length = 1e-15, adaptivealg = :RSwM3)

Rejection Sampling with Memory (RSWM) algorithm configuration for noise processes.

RSWM ensures distributional exactness when adaptive time stepping is used with noise processes. It maintains memory of rejected values to avoid biasing the noise distribution.

Fields

discard_length: Threshold for discarding stored values to save memory. Smaller values use more memory but are more accurate.
adaptivealg: The adaptive algorithm variant to use (:RSwM3 is recommended for Brownian motion)

Algorithm Variants

:RSwM1: Basic rejection sampling with single stack
:RSwM2: Improved version with better memory management
:RSwM3: Most advanced version with two-stack system (recommended for Brownian motion)
:RSwM0: No memory storage variant for state-dependent noise processes

About :RSwM0 (No Memory)

For tau-leaping with state-dependent rates, the rate λ is approximated as constant over each step. When a step is rejected and you use a Poisson bridge to pull back to a smaller dt, storing the "future" portion doesn't make sense because you don't know the correct λ anyway - it's always an approximation. Both storing and discarding have errors, but recalculating fresh is more appropriate for this use case.

:RSwM0 uses bridging/interpolation for rejected steps but discards future values instead of storing them. This is the appropriate choice for:

Compound Poisson processes with state-dependent rates
Tau-leaping with post-leap adaptivity (Anderson's algorithm)

Reference: Anderson, D.F. "Incorporating postleap checks in tau-leaping" J. Chem. Phys. 128, 054103 (2008); https://doi.org/10.1063/1.2819665

Examples

# Conservative (high accuracy) for Brownian motion
rswm_accurate = RSWM(discard_length = 1e-12)

# Aggressive (lower memory usage) for Brownian motion
rswm_fast = RSWM(discard_length = 1e-6)

# No memory for state-dependent Poisson processes
rswm_nomem = RSWM(adaptivealg = :RSwM0)

# Use in noise process
W = WienerProcess(0.0, 0.0, 1.0; rswm = rswm_accurate)

DiffEqNoiseProcess.adaptive_alg — Function

adaptive_alg(rswm::RSWM)

Get the adaptive algorithm type from an RSWM configuration.

Developer Callback Helpers

The following callback helpers are documented for package developers who need to understand or compose the built-in process implementations. They are not the stable user-facing process API and are not exported. New solver code should use the lifecycle functions above.

Distribution Functions

DiffEqNoiseProcess.WHITE_NOISE_DIST — Function

WHITE_NOISE_DIST(dW, W, dt, u, p, t, rng)

Generate white noise distributed according to N(0, dt) for use in Wiener processes.

Arguments

dW: Noise increment container
W: Current noise value (unused for white noise)
dt: Time step
u: Current state (for state-dependent noise)
p: Parameters
t: Current time
rng: Random number generator

Returns

Random values distributed as N(0, dt), scaled by √dt

DiffEqNoiseProcess.WHITE_NOISE_BRIDGE — Function

WHITE_NOISE_BRIDGE(dW, W, W0, Wh, q, h, u, p, t, rng)

Generate white noise for Brownian bridge interpolation between two points.

Arguments

dW: Noise increment container
W: Current noise value
W0: Starting noise value
Wh: Target noise value at end of interval
q: Interpolation parameter (0 to 1)
h: Total time interval
u, p, t: State, parameters, and time (for compatibility)
rng: Random number generator

Returns

Interpolated noise value that maintains correct distribution

DiffEqNoiseProcess.VBT_BRIDGE — Function

VBT_BRIDGE(dW, W, W0, Wh, q, h, u, p, t, rng)

Generate noise for Virtual Brownian Tree (VBT) bridge interpolation.

The VBT bridge is a memory-efficient method for generating Brownian paths that can be evaluated at arbitrary time points without storing the entire path.

Arguments

dW: Noise increment container
W: Current noise value
W0: Starting noise value
Wh: Target noise value at end of interval
q: Interpolation parameter (0 to 1)
h: Total time interval
u, p, t: State, parameters, and time (for compatibility)
rng: Random number generator

Returns

Interpolated noise value using the VBT bridge formula

DiffEqNoiseProcess.INPLACE_WHITE_NOISE_DIST — Function

INPLACE_WHITE_NOISE_DIST(rand_vec, W, dt, u, p, t, rng)

Generate white noise distributed according to N(0, dt) in-place.

This is the in-place version of WHITENOISEDIST, modifying the provided array rather than allocating a new one.

Arguments

rand_vec: Array to fill with noise values
W: Current noise value (unused for white noise)
dt: Time step
u: Current state (for state-dependent noise)
p: Parameters
t: Current time
rng: Random number generator

Effects

Modifies rand_vec to contain random values distributed as N(0, dt)

DiffEqNoiseProcess.INPLACE_WHITE_NOISE_BRIDGE — Function

INPLACE_WHITE_NOISE_BRIDGE(rand_vec, W, W0, Wh, q, h, u, p, t, rng)

Generate white noise for Brownian bridge interpolation in-place.

This is the in-place version of WHITENOISEBRIDGE, modifying the provided array rather than allocating a new one.

Arguments

rand_vec: Array to fill with interpolated noise values
W: Current noise value
W0: Starting noise value
Wh: Target noise value at end of interval
q: Interpolation parameter (0 to 1)
h: Total time interval
u, p, t: State, parameters, and time (for compatibility)
rng: Random number generator

Effects

Modifies rand_vec to contain interpolated noise values

DiffEqNoiseProcess.INPLACE_VBT_BRIDGE — Function

INPLACE_VBT_BRIDGE(rand_vec, W, W0, Wh, q, h, u, p, t, rng)

Generate noise for Virtual Brownian Tree (VBT) bridge interpolation in-place.

This is the in-place version of VBT_BRIDGE, modifying the provided array rather than allocating a new one.

Arguments

rand_vec: Array to fill with interpolated noise values
W: Current noise value
W0: Starting noise value
Wh: Target noise value at end of interval
q: Interpolation parameter (0 to 1)
h: Total time interval
u, p, t: State, parameters, and time (for compatibility)
rng: Random number generator

Effects

Modifies rand_vec to contain VBT-interpolated noise values

DiffEqNoiseProcess.REAL_WHITE_NOISE_DIST — Function

REAL_WHITE_NOISE_DIST(dW, W, dt, u, p, t, rng)

Generate real-valued white noise distributed according to N(0, dt).

Unlike WHITENOISEDIST, this function always generates real-valued noise, even if the input type would normally support complex values.

Arguments

dW: Noise increment container
W: Current noise value (unused for white noise)
dt: Time step
u: Current state (for state-dependent noise)
p: Parameters
t: Current time
rng: Random number generator

Returns

Real-valued random numbers distributed as N(0, dt), scaled by √dt

DiffEqNoiseProcess.REAL_WHITE_NOISE_BRIDGE — Function

REAL_WHITE_NOISE_BRIDGE(dW, W, W0, Wh, q, h, u, p, t, rng)

Generate real-valued white noise for Brownian bridge interpolation.

This function ensures the generated noise is always real-valued, even for complex-valued endpoints.

Arguments

dW: Noise increment container
W: Current noise value
W0: Starting noise value
Wh: Target noise value at end of interval
q: Interpolation parameter (0 to 1)
h: Total time interval
u, p, t: State, parameters, and time (for compatibility)
rng: Random number generator

Returns

Real-valued interpolated noise value

DiffEqNoiseProcess.REAL_INPLACE_WHITE_NOISE_DIST — Function

REAL_INPLACE_WHITE_NOISE_DIST(rand_vec, W, dt, u, p, t, rng)

Generate real-valued white noise distributed according to N(0, dt) in-place.

This is the in-place version of REALWHITENOISE_DIST.

Arguments

rand_vec: Array to fill with noise values
W: Current noise value (unused for white noise)
dt: Time step
u: Current state (for state-dependent noise)
p: Parameters
t: Current time
rng: Random number generator

Effects

Modifies rand_vec to contain real-valued random numbers distributed as N(0, dt)

DiffEqNoiseProcess.REAL_INPLACE_WHITE_NOISE_BRIDGE — Function

REAL_INPLACE_WHITE_NOISE_BRIDGE(rand_vec, W, W0, Wh, q, h, u, p, t, rng)

Generate real-valued white noise for Brownian bridge interpolation in-place.

This is the in-place version of REALWHITENOISE_BRIDGE.

Arguments

rand_vec: Array to fill with interpolated noise values
W: Current noise value
W0: Starting noise value
Wh: Target noise value at end of interval
q: Interpolation parameter (0 to 1)
h: Total time interval
u, p, t: State, parameters, and time (for compatibility)
rng: Random number generator

Effects

Modifies rand_vec to contain real-valued interpolated noise values

Random Number Generation

DiffEqNoiseProcess.wiener_randn — Function

wiener_randn(rng::AbstractRNG, ::Type{T}) where {T}

Generate a random number from the standard normal distribution for type T.

Arguments

rng: Random number generator
T: Type of the random number to generate

Returns

A random number of type T from the standard normal distribution

wiener_randn(rng::AbstractRNG, proto::AbstractArray{T}) where {T <: Number}

Generate an array of random numbers from the standard normal distribution, matching the size of the prototype array.

Arguments

rng: Random number generator
proto: Prototype array whose size determines the output size

Returns

An array of random numbers from the standard normal distribution with the same size as proto

wiener_randn(rng::AbstractRNG, proto::T) where {T <: StaticArraysCore.SArray}

Generate a static array of random numbers from the standard normal distribution.

Arguments

rng: Random number generator
proto: Prototype static array

Returns

A static array of the same type as proto filled with standard normal random numbers

wiener_randn(rng::AbstractRNG, proto)

Generate random numbers from the standard normal distribution for arbitrary types.

Arguments

rng: Random number generator
proto: Prototype object whose type and size determine the output

Returns

Random values converted to the same type as proto

DiffEqNoiseProcess.wiener_randn! — Function

wiener_randn!(rng::AbstractRNG, rand_vec::AbstractArray)

Fill an array with random numbers from the standard normal distribution in-place.

Arguments

rng: Random number generator
rand_vec: Array to fill with random values

Returns

The modified rand_vec filled with standard normal random numbers

wiener_randn!(rng::AbstractRNG, rand_vec)

Fill an arbitrary container with random numbers from the standard normal distribution in-place using broadcasting.

Arguments

rng: Random number generator (not used in this fallback)
rand_vec: Container to fill with random values

Returns

The modified rand_vec filled with standard normal random numbers

wiener_randn!(rng::AbstractRNG, rand_vec::GPUArraysCore.AbstractGPUArray)

Fill a GPU array with random numbers from the standard normal distribution in-place.

This specialized method works for GPUs because it doesn't pass the RNG to the GPU kernel, which may not be supported on all GPU backends.

Arguments

rng: Random number generator (not passed to GPU)
rand_vec: GPU array to fill with random values

Returns

The modified rand_vec filled with standard normal random numbers

wiener_randn!(y::AbstractRNG, x::AbstractArray{<:Complex{T}}) where {T <: Number}

Fill an array of complex numbers with random values from the standard complex normal distribution in-place.

Each complex number is generated as (a + bi)/√2 where a and b are independent standard normal random variables.

Arguments

y: Random number generator
x: Array of complex numbers to fill

Returns

The modified array filled with complex normal random numbers

Ornstein-Uhlenbeck Specific

DiffEqNoiseProcess.OrnsteinUhlenbeck — Type

OrnsteinUhlenbeck{T1, T2, T3}

Parameters for the Ornstein-Uhlenbeck process.

Fields

Θ: Mean reversion rate (higher values mean faster reversion)
μ: Long-term mean (the value the process reverts to)
σ: Volatility/diffusion coefficient

The process follows the SDE: dXt = Θ(μ - Xt)dt + σ dW_t

DiffEqNoiseProcess.OrnsteinUhlenbeck! — Type

OrnsteinUhlenbeck!{T1, T2, T3}

In-place version of OrnsteinUhlenbeck parameters.

Fields

Θ: Mean reversion rate (higher values mean faster reversion)
μ: Long-term mean (the value the process reverts to)
σ: Volatility/diffusion coefficient

The process follows the SDE: dXt = Θ(μ - Xt)dt + σ dW_t

DiffEqNoiseProcess.ou_bridge — Function

ou_bridge(dW, ou, W, W0, Wh, q, h, u, p, t, rng)

Generate Ornstein-Uhlenbeck bridge interpolation between two points.

Provides exact sampling from an OU process conditioned on both endpoints, useful for adaptive time-stepping and interpolation.

Arguments

dW: Noise increment container
ou: OrnsteinUhlenbeck parameters
W: Current noise process state
W0: Starting value
Wh: Target value at end of interval
q: Interpolation parameter (0 to 1)
h: Total time interval
u, p, t: State, parameters, and time (for compatibility)
rng: Random number generator

Returns

Interpolated OU process value that maintains the correct distribution

References

http://www.tandfonline.com/doi/pdf/10.1080/14697688.2014.941913
https://arxiv.org/pdf/1011.0067.pdf (page 18)

DiffEqNoiseProcess.ou_bridge! — Function

ou_bridge!(rand_vec, ou, W, W0, Wh, q, h, u, p, t, rng)

Generate Ornstein-Uhlenbeck bridge interpolation in-place.

This is the in-place version of ou_bridge, modifying the provided array rather than allocating a new one.

Arguments

rand_vec: Array to fill with interpolated values
ou: OrnsteinUhlenbeck parameters
W: Current noise process state
W0: Starting value
Wh: Target value at end of interval
q: Interpolation parameter (0 to 1)
h: Total time interval
u, p, t: State, parameters, and time (for compatibility)
rng: Random number generator

Effects

Modifies rand_vec to contain the interpolated OU process values

Geometric Brownian Motion Specific

DiffEqNoiseProcess.GeometricBrownianMotion — Type

GeometricBrownianMotion{T1, T2}

Parameters for the geometric Brownian motion process.

Fields

μ: Drift parameter (expected return rate)
σ: Volatility parameter (standard deviation of returns)

The process follows the SDE: dXt = μXt dt + σXt dWt

This is commonly used in financial models, particularly the Black-Scholes model.

DiffEqNoiseProcess.GeometricBrownianMotion! — Type

GeometricBrownianMotion!{T1, T2}

In-place version of GeometricBrownianMotion parameters.

Fields

μ: Drift parameter (expected return rate)
σ: Volatility parameter (standard deviation of returns)

The process follows the SDE: dXt = μXt dt + σXt dWt

DiffEqNoiseProcess.gbm_bridge — Function

gbm_bridge(dW, gbm, W, W0, Wh, q, h, u, p, t, rng)

Generate geometric Brownian motion bridge interpolation between two points.

Provides exact sampling from a GBM process conditioned on both endpoints, useful for adaptive time-stepping and interpolation.

Arguments

dW: Noise increment container
gbm: GeometricBrownianMotion parameters
W: Current noise process state
W0: Starting value
Wh: Target value at end of interval
q: Interpolation parameter (0 to 1)
h: Total time interval
u, p, t: State, parameters, and time (for compatibility)
rng: Random number generator

Returns

Interpolated GBM process value that maintains the correct log-normal distribution

Reference

https://math.stackexchange.com/questions/412470/conditional-distribution-in-brownian-motion

DiffEqNoiseProcess.gbm_bridge! — Function

gbm_bridge!(rand_vec, gbm, W, W0, Wh, q, h, u, p, t, rng)

Generate geometric Brownian motion bridge interpolation in-place.

This is the in-place version of gbm_bridge, modifying the provided array rather than allocating a new one.

Arguments

rand_vec: Array to fill with interpolated values
gbm: GeometricBrownianMotion parameters
W: Current noise process state
W0: Starting value
Wh: Target value at end of interval
q: Interpolation parameter (0 to 1)
h: Total time interval
u, p, t: State, parameters, and time (for compatibility)
rng: Random number generator

Effects

Modifies rand_vec to contain the interpolated GBM process values

Compound Poisson Specific

DiffEqNoiseProcess.cpp_bridge — Function

cpp_bridge(dW, cpp, W, W0, Wh, q, h, u, p, t, rng)

Generate compound Poisson process bridge interpolation between two points.

Uses binomial thinning to distribute jumps appropriately between endpoints.

Arguments

dW: Noise increment container
cpp: CompoundPoissonProcess parameters
W: Current noise process state
W0: Starting value
Wh: Jump count difference (must be integer)
q: Interpolation parameter (0 to 1)
h: Total time interval
u, p, t: State, parameters, and time (for compatibility)
rng: Random number generator

Returns

Number of jumps distributed according to binomial thinning

DiffEqNoiseProcess.cpp_bridge! — Function

cpp_bridge!(rand_vec, cpp, W, W0, Wh, q, h, u, p, t, rng)

In-place version of cpp_bridge.

Effects

Modifies rand_vec to contain binomially distributed jump counts