Noise Operators

🎲 Stochastic Noise

sim_add_stochastic_noise_operator(ctx, field, opts)

Add coloured stochastic noise with configurable spectral characteristics and stochastic calculus law. Implements Ornstein-Uhlenbeck processes with fractional noise extensions for modeling physical fluctuations, turbulence, and thermal noise.

Method Signature

sim_add_stochastic_noise_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Mathematical Formulation

Ornstein-Uhlenbeck Process:

$$d\xi = -\frac{\xi}{\tau} dt + \sigma \cdot dW_t$$

where:

• $\xi$ is the noise state
• $\tau$ is the autocorrelation time
• $\sigma$ is the noise intensity
• $dW_t$ is a Wiener increment

Spectral Characteristics:

The noise has power spectral density:

$$S(f) \propto \frac{1}{1 + (2\pi f \tau)^2} \cdot |f|^{-\alpha}$$

where $\alpha$ controls the spectral color:

• $\alpha = 0$: White noise (flat spectrum)
• $\alpha = 1$: Pink/flicker noise ($1/f$)
• $\alpha = 2$: Brownian/red noise ($1/f^2$)

Stochastic Calculus Laws:

• Itô: Standard interpretation; $dW$ independent of current state
• Stratonovich: Midpoint rule; preserves chain rule; often preferred for physical systems

Parameters

Parameter	Type	Default	Range	Description
sigma	double	≥0	Noise intensity (standard deviation) (required)
tau	double	0.0	≥0	Autocorrelation decay time (0 = white noise)
alpha	double	0.0	[0, 2.5]	Spectral exponent controlling color
seed	integer	0	≥0	RNG seed (0 = auto from system)
law	enum	"ito"	ito, stratonovich	Stochastic calculus convention

Boundary & Initial Conditions

• Operates elementwise; no boundary handling required
• Internal state initialized to zero; transient period ≈ $3\tau$
• For reproducible results, set explicit seed

Stability & Convergence

• White noise ($\tau = 0$): Uncorrelated samples; scales with $\sqrt{\Delta t}$
• Colored noise ($\tau > 0$): Requires $\Delta t \ll \tau$ for accurate dynamics
• Large $\alpha$ values produce slowly-varying (low-frequency dominated) noise
• Stratonovich interpretation avoids spurious drift in multiplicative noise contexts

Performance Notes

• One random number generation per element per timestep
• Colored noise maintains per-element state (O(N) memory)
• Seed affects entire field; use different operators for independent noise sources

Examples

-- Simple white noise
ooc.sim_add_stochastic_noise_operator(ctx, field, {
    sigma = 0.1
})

-- Colored noise with Stratonovich interpretation
ooc.sim_add_stochastic_noise_operator(ctx, field, {
    sigma = 0.15,
    law = "stratonovich"
})

-- Ornstein-Uhlenbeck process
ooc.sim_add_stochastic_noise_operator(ctx, field, {
    sigma = 0.05,
    tau = 0.1
})

-- Pink noise (1/f spectrum)
ooc.sim_add_stochastic_noise_operator(ctx, field, {
    sigma = 0.05,
    tau = 0.1,
    alpha = 1.0,
    seed = 42
})

-- Brownian noise (1/f² spectrum)
ooc.sim_add_stochastic_noise_operator(ctx, field, {
    sigma = 0.02,
    tau = 0.5,
    alpha = 2.0
})

-- Reproducible noise for testing
ooc.sim_add_stochastic_noise_operator(ctx, field, {
    sigma = 0.1,
    seed = 12345
})

---

🎵 Random Fourier

sim_add_stimulus_operator(ctx, field, opts)

Generate spatially-correlated random fields using random Fourier features. Creates band-limited noise patterns with controllable spectral content, useful for initial conditions, driving forces, and procedural textures.

Method Signature

sim_add_stimulus_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_random_fourier".

Mathematical Formulation

The field is constructed as a superposition of random sinusoids:

$$u(\mathbf{x}, t) = A \sum_{n=1}^{N} w_n \cos(\mathbf{k}_n \cdot \mathbf{x} + \phi_n + \omega t)$$

where:

• $A$ is the amplitude
• $N$ is feature_count
• $\mathbf{k}_n$ are random wavenumbers in $[k_{\min}, k_{\max}]$
• $\phi_n$ are random phases in $[0, 2\pi]$
• $w_n$ are weights from the spectral slope: $w_n \propto |k_n|^{-\beta/2}$
• $\omega$ is the temporal frequency (optional)

Spectral Slope:

When spectral_slope ($\beta$) is specified, the power spectral density follows:

$$S(k) \propto |k|^{-\beta}$$

Parameters

Core Parameters:

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_random_fourier"
amplitude	double	unbounded	Overall scale of features (required)
feature_count	integer	16	≥1	Number of random basis functions
seed	integer	1	≥1	RNG seed for reproducibility

Spectral Parameters:

Parameter	Type	Default	Range	Description
k_min	double	0.1	≥0	Minimum wavenumber (rad/unit)
k_max	double	1.0	>k_min	Maximum wavenumber (rad/unit)
spectral_slope	double	0.0	unbounded	Spectral decay exponent $\beta$

Temporal Parameters:

Parameter	Type	Default	Range	Description
omega	double	0.0	unbounded	Temporal angular frequency (rad/s)
time_offset	double	0.0	unbounded	Additional time shift
nominal_dt	double	0.0	≥0	Lock time to fixed timestep
fixed_clock	boolean	false	—	Use nominal_dt for time evolution

Coordinate Mapping:

Parameter	Type	Default	Description
coord_mode	enum	"axis"	Coordinate mode: axis, angle, radial, separable
coord_axis	enum	"x"	Axis for 1D mapping
coord_combine	enum	"multiply"	Combine rule for separable: multiply, add
coord_angle	double	0.0	Angle for angle-mode (radians)
origin_x, origin_y	double	0.0	Coordinate origin
spacing_x, spacing_y	double	1.0	Grid spacing
coord_center_x, coord_center_y	double	0.0	Center for radial mode
coord_velocity_x, coord_velocity_y	double	0.0	Moving center velocity

Output Parameters:

Parameter	Type	Default	Description
scale_by_dt	boolean	true	Scale writes by dt

Boundary & Initial Conditions

• Generates field values based on coordinates; no explicit boundaries
• Periodic by nature due to sinusoidal basis
• Same seed produces identical patterns

Stability & Convergence

• Output is bounded by $A \cdot N$ (sum of all features)
• spectral_slope > 0 produces smoother fields (low-frequency dominated)
• spectral_slope < 0 produces rougher fields (high-frequency dominated)
• More features improve statistical convergence at cost of computation

Performance Notes

• Computational cost: O(N × feature_count) per timestep
• Features are precomputed once at creation; only phases advance
• Use fixed_clock for deterministic, frame-rate-independent animation

Examples

-- Basic random Fourier field
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_random_fourier",
    amplitude = 0.5,
    k_min = 0.1,
    k_max = 2.0,
    feature_count = 32,
    seed = 99
})

-- Red noise spectrum (smooth variations)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_random_fourier",
    amplitude = 0.2,
    spectral_slope = 2.0,  -- 1/k² falloff
    feature_count = 64
})

-- Pink noise spectrum (1/f)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_random_fourier",
    amplitude = 0.3,
    spectral_slope = 1.0,
    k_min = 0.05,
    k_max = 5.0,
    feature_count = 48
})

-- Time-varying random field
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_random_fourier",
    amplitude = 0.4,
    omega = 0.5,  -- slow temporal variation
    feature_count = 24
})

-- Narrow-band noise (limited wavenumber range)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_random_fourier",
    amplitude = 0.3,
    k_min = 0.8,
    k_max = 1.2,  -- centered around k=1
    feature_count = 16
})

-- Radial coordinate mapping
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_random_fourier",
    amplitude = 0.5,
    coord_mode = "radial",
    coord_center_x = 128,
    coord_center_y = 128,
    k_min = 0.1,
    k_max = 1.0
})

---

❄️ White Noise

sim_add_stimulus_operator(ctx, field, opts)

Generate Gaussian white noise with configurable mean and variance. Fundamental building block for stochastic simulations, Monte Carlo methods, and noise injection.

Method Signature

sim_add_stimulus_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_white_noise".

Mathematical Formulation

Each sample is drawn independently from a Gaussian distribution:

$$\xi_i \sim \mathcal{N}(\mu, \sigma^2)$$

When scale_by_dt = true, the noise is scaled for proper stochastic integration:

$$\xi_i \sim \mathcal{N}\left(\mu, \frac{\sigma^2}{\Delta t}\right) \cdot \Delta t = \mathcal{N}(\mu \cdot \Delta t, \sigma^2 \cdot \Delta t)$$

This ensures that the integrated noise has variance proportional to time (Wiener process behavior).

Parameters

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_white_noise"
sigma	double	≥0	Standard deviation (required)
mean	double	0.0	unbounded	Mean offset
seed	integer	1	≥1	RNG seed for reproducibility
scale_by_dt	boolean	true	—	Scale by sqrt(dt) for stochastic integration
nominal_dt	double	0.0	≥0	Lock scaling to fixed timestep
fixed_clock	boolean	false	—	Use nominal_dt for scaling

Boundary & Initial Conditions

• Operates elementwise; no boundary handling required
• Each call generates fresh noise; no temporal correlation
• Same seed produces identical noise sequence

Stability & Convergence

• Uncorrelated in space and time (delta-correlated)
• Proper scaling (scale_by_dt = true) essential for SDE integration
• Mean shifts the distribution; does not affect variance
• For non-Gaussian noise, consider combining with nonlinear transformations

Performance Notes

• Uses Box-Muller or similar transform for Gaussian generation
• One random number per element per timestep
• Very fast; typically memory-bandwidth limited

Examples

-- Basic white noise
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_white_noise",
    sigma = 0.05,
    seed = 12345
})

-- White noise with nonzero mean
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_white_noise",
    sigma = 0.2,
    mean = 0.1
})

-- Unscaled noise (for non-SDE applications)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_white_noise",
    sigma = 0.1,
    scale_by_dt = false
})

-- Fixed timestep scaling (for variable dt simulations)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_white_noise",
    sigma = 0.1,
    nominal_dt = 0.01,
    fixed_clock = true
})

-- High-intensity noise for testing
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_white_noise",
    sigma = 1.0,
    seed = 42
})

---

🌫️ Fractional Brownian Motion

sim_add_stimulus_operator(ctx, field, opts)

Generate fractional Brownian motion (fBm) noise with configurable roughness and multi-octave structure. Creates natural-looking textures and spatially-correlated noise with long-range dependence.

Method Signature

sim_add_stimulus_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Note: Requires type = "stimulus_fbm".

Mathematical Formulation

Fractional Brownian motion is constructed by summing multiple octaves of noise:

$$\text{fBm}(\mathbf{x}) = \sum_{i=0}^{O-1} A \cdot \lambda^{-iH} \cdot \text{noise}(\lambda^i \mathbf{x})$$

where:

• $O$ is the number of octaves
• $A$ is the base amplitude
• $\lambda$ is the lacunarity (frequency multiplier)
• $H$ is the Hurst exponent

Hurst Exponent:

The Hurst exponent $H \in (0, 1)$ controls the roughness:

• $H = 0.5$: Standard Brownian motion (random walk)
• $H > 0.5$: Persistent (smoother, trending)
• $H < 0.5$: Anti-persistent (rougher, mean-reverting)

Spectral Properties:

The power spectral density follows:

$$S(f) \propto f^{-(2H+1)}$$

Parameters

Parameter	Type	Default	Range	Description
type	string	—	—	Must be "stimulus_fbm"
amplitude	double	unbounded	Scale of coarsest octave (required)
hurst	double	0.5	(0, 1)	Hurst exponent controlling roughness
lacunarity	double	2.0	>1	Octave frequency multiplier
octaves	integer	4	[1, 16]	Number of octaves
seed	integer	1	≥1	RNG seed for reproducibility
scale_by_dt	boolean	true	—	Scale writes by dt

Boundary & Initial Conditions

• Generates based on coordinates; no explicit boundaries
• Underlying noise is typically periodic or uses value noise
• Same seed produces identical patterns

Stability & Convergence

• Output bounded approximately by $A \cdot \sum_{i=0}^{O-1} \lambda^{-iH}$
• Higher octaves adds fine detail but increases computation
• lacunarity = 2 is standard; other values change frequency spacing
• hurst > 0.5 produces visually smoother terrain; hurst < 0.5 produces rougher textures

Performance Notes

• Cost: O(N × octaves) per timestep
• Each octave requires noise evaluation at different frequency
• Higher octaves contribute diminishing detail; often 4-8 octaves sufficient
• Consider caching for static fBm fields

Examples

-- Standard fBm (Hurst = 0.5)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_fbm",
    amplitude = 0.5,
    octaves = 6,
    seed = 123
})

-- Smooth terrain (persistent fBm)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_fbm",
    amplitude = 0.5,
    hurst = 0.7,  -- smoother
    octaves = 6,
    lacunarity = 2.0,
    seed = 123
})

-- Rough texture (anti-persistent)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_fbm",
    amplitude = 0.25,
    hurst = 0.3,  -- rougher
    octaves = 8
})

-- Low-octave (broad features only)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_fbm",
    amplitude = 1.0,
    hurst = 0.5,
    octaves = 2
})

-- High-octave detail
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_fbm",
    amplitude = 0.3,
    hurst = 0.5,
    octaves = 12,
    lacunarity = 2.0
})

-- Custom lacunarity (non-power-of-2 spacing)
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_fbm",
    amplitude = 0.4,
    hurst = 0.6,
    octaves = 5,
    lacunarity = 1.87  -- golden ratio-ish
})

-- Low amplitude for subtle texture
ooc.sim_add_stimulus_operator(ctx, field, {
    type = "stimulus_fbm",
    amplitude = 0.1,
    hurst = 0.5,
    octaves = 4
})