Deterministic RNG streams and reusable noise update helpers. More...

#include "field.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for sim_noise_source.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	SimNoiseSourceRng
	Mutable deterministic RNG state with cached normal sample. More...

Macros
#define	SIM_NOISE_SOURCE_STREAM_STIMULUS_WHITE 0x85EBCA77C2B2AE63ULL

#define	SIM_NOISE_SOURCE_STREAM_STOCHASTIC 0x000000000BAD5EEDULL

#define	SIM_NOISE_SOURCE_STREAM_ORNSTEIN 0xD8D12A6C9B4E41B7ULL

Typedefs
typedef struct SimNoiseSourceRng	SimNoiseSourceRng
	Mutable deterministic RNG state with cached normal sample.

Functions
void	sim_noise_source_seed (SimNoiseSourceRng *rng, uint64_t initstate, uint64_t initseq)
	Seed a deterministic RNG stream.

double	sim_noise_source_uniform (SimNoiseSourceRng *rng)
	Draw a uniform variate in [0, 1).

void	sim_noise_source_normal_pair (SimNoiseSourceRng rng, double n0, double *n1)
	Draw a pair of independent standard-normal variates.

double	sim_noise_source_normal (SimNoiseSourceRng *rng)
	Draw one standard-normal variate.

double	sim_noise_source_gaussian_gain (double sigma, double dt, bool scale_by_dt)
	Compute the finite gain used by Gaussian white-noise updates.

SimResult	sim_noise_source_ensure_capacity (double real_state, SimComplexDouble complex_state, size_t *capacity, size_t count, bool is_complex)
	Ensure reusable temporal-noise state storage has at least `count` entries.

void	sim_noise_source_apply_white_real (double dst, size_t count, double mean, double gain, SimNoiseSourceRng rng)
	Add real-valued white Gaussian noise to an array in place.

void	sim_noise_source_apply_white_complex (SimComplexDouble dst, size_t count, double mean_re, double mean_im, double gain_re, double gain_im, SimNoiseSourceRng rng)
	Add complex white Gaussian noise to an array in place.

void	sim_noise_source_temporal_params (double sigma, double tau, double alpha, double dt, double out_decay, double out_variance)
	Derive decay and innovation scale for temporal correlated noise.

void	sim_noise_source_apply_temporal_real (double dst, double noise_state, size_t count, double output_scale, double decay, double variance, SimNoiseSourceRng *rng)
	Advance real temporal-noise state and add it to a destination array.

void	sim_noise_source_apply_temporal_complex (SimComplexDouble dst, SimComplexDouble noise_state, size_t count, double output_scale, double decay, double variance, SimNoiseSourceRng *rng)
	Advance complex temporal-noise state and add it to a destination array.

void	sim_noise_source_apply_mean_reverting_real (double dst, size_t count, double mean, double decay, double variance, SimNoiseSourceRng rng)
	Apply a real mean-reverting update in place.

void	sim_noise_source_apply_mean_reverting_complex (SimComplexDouble dst, size_t count, double mean, double decay, double variance, SimNoiseSourceRng rng)
	Apply a complex mean-reverting update in place.

Detailed Description

Deterministic RNG streams and reusable noise update helpers.

This header exposes the shared stochastic primitives used by stimulus and noise operators. Streams are explicitly seeded, output buffers are caller-owned, and helper functions clamp non-finite parameters to deterministic fallbacks rather than propagating NaN through update loops.

Typedef Documentation

◆ SimNoiseSourceRng

typedef struct SimNoiseSourceRng SimNoiseSourceRng

Mutable deterministic RNG state with cached normal sample.

The state/inc pair implements the underlying uniform stream. The spare fields cache the second Box-Muller output so repeated scalar-normal calls consume the same sequence as paired normal generation.

Function Documentation

◆ sim_noise_source_apply_mean_reverting_complex()

void sim_noise_source_apply_mean_reverting_complex	(	SimComplexDouble *	dst,
		size_t	count,
		double	mean,
		double	decay,
		double	variance,
		SimNoiseSourceRng *	rng
	)

Apply a complex mean-reverting update in place.

The same real mean is applied to both real and imaginary channels, with independent Gaussian innovations when variance is nonzero.

Parameters

[in,out]	dst	Complex values to update in place.
	count	Number of entries in `dst`.
	mean	Reversion target for both channels.
	decay	Distance-from-mean multiplier.
	variance	Optional standard-normal innovation multiplier.
	rng	RNG state to advance when variance is nonzero.

◆ sim_noise_source_apply_mean_reverting_real()

void sim_noise_source_apply_mean_reverting_real	(	double *	dst,
		size_t	count,
		double	mean,
		double	decay,
		double	variance,
		SimNoiseSourceRng *	rng
	)

Apply a real mean-reverting update in place.

Each element becomes mean + decay * (x - mean) plus optional Gaussian innovation. Non-finite parameters fall back to mean=0, decay=1, variance=0.

Parameters

[in,out]	dst	Real values to update in place.
	count	Number of entries in `dst`.
	mean	Reversion target.
	decay	Distance-from-mean multiplier.
	variance	Optional standard-normal innovation multiplier.
	rng	RNG state to advance when variance is nonzero.

◆ sim_noise_source_apply_temporal_complex()

void sim_noise_source_apply_temporal_complex	(	SimComplexDouble *	dst,
		SimComplexDouble *	noise_state,
		size_t	count,
		double	output_scale,
		double	decay,
		double	variance,
		SimNoiseSourceRng *	rng
	)

Advance complex temporal-noise state and add it to a destination array.

Real and imaginary state channels use independent normal innovations.

Parameters

[in,out]	dst	Destination values incremented by output_scale * state.
[in,out]	noise_state	Persistent per-element complex noise state.
	count	Number of entries in both arrays.
	output_scale	Scale applied to updated channels before adding to dst.
	decay	Autoregressive decay factor.
	variance	Multiplier for fresh standard-normal innovations.
	rng	RNG state to advance.

◆ sim_noise_source_apply_temporal_real()

void sim_noise_source_apply_temporal_real	(	double *	dst,
		double *	noise_state,
		size_t	count,
		double	output_scale,
		double	decay,
		double	variance,
		SimNoiseSourceRng *	rng
	)

Advance real temporal-noise state and add it to a destination array.

Parameters

[in,out]	dst	Destination values incremented by output_scale * state.
[in,out]	noise_state	Persistent per-element real noise state.
	count	Number of entries in both arrays.
	output_scale	Scale applied to the updated state before adding to dst.
	decay	Autoregressive decay factor.
	variance	Multiplier for fresh standard-normal innovation.
	rng	RNG state to advance.

◆ sim_noise_source_apply_white_complex()

void sim_noise_source_apply_white_complex	(	SimComplexDouble *	dst,
		size_t	count,
		double	mean_re,
		double	mean_im,
		double	gain_re,
		double	gain_im,
		SimNoiseSourceRng *	rng
	)

Add complex white Gaussian noise to an array in place.

Real and imaginary channels draw independent standard-normal samples. Non- finite means or gains are treated as zero.

Parameters

[in,out]	dst	Complex destination values to increment.
	count	Number of entries in `dst`.
	mean_re	Real-channel deterministic offset.
	mean_im	Imaginary-channel deterministic offset.
	gain_re	Real-channel normal multiplier.
	gain_im	Imaginary-channel normal multiplier.
	rng	RNG state to advance.

◆ sim_noise_source_apply_white_real()

void sim_noise_source_apply_white_real	(	double *	dst,
		size_t	count,
		double	mean,
		double	gain,
		SimNoiseSourceRng *	rng
	)

Add real-valued white Gaussian noise to an array in place.

Non-finite mean and gain are treated as zero. The destination is unchanged when dst, rng, or count is empty.

Parameters

[in,out]	dst	Real destination values to increment.
	count	Number of entries in `dst`.
	mean	Deterministic offset added to each element.
	gain	Multiplier for independent N(0, 1) samples.
	rng	RNG state to advance.

◆ sim_noise_source_ensure_capacity()

SimResult sim_noise_source_ensure_capacity	(	double **	real_state,
		SimComplexDouble **	complex_state,
		size_t *	capacity,
		size_t	count,
		bool	is_complex
	)

Ensure reusable temporal-noise state storage has at least count entries.

The selected real or complex state array is allocated or grown with new slots zero-initialized. Passing count zero frees both arrays and resets capacity.

Parameters

[in,out]	real_state	Pointer to caller-owned real state storage.
[in,out]	complex_state	Pointer to caller-owned complex state storage.
[in,out]	capacity	Current and resulting number of allocated entries.
	count	Required element count; zero releases both arrays.
	is_complex	Selects which state array must be grown for nonzero count.

Returns: SIM_RESULT_OK, SIM_RESULT_INVALID_ARGUMENT, or SIM_RESULT_OUT_OF_MEMORY.

◆ sim_noise_source_gaussian_gain()

double sim_noise_source_gaussian_gain	(	double	sigma,
		double	dt,
		bool	scale_by_dt
	)

Compute the finite gain used by Gaussian white-noise updates.

Non-finite sigma or dt values are treated as zero. When scale_by_dt is true, the gain is multiplied by sqrt(abs(dt)).

Parameters

sigma	Noise amplitude.
dt	Simulation timestep.
scale_by_dt	Whether to apply sqrt(abs(dt)) scaling.

Returns: Finite gain value, or 0.0 if the computed gain is non-finite.

◆ sim_noise_source_normal()

double sim_noise_source_normal ( SimNoiseSourceRng * rng )

Draw one standard-normal variate.

Parameters

rng	RNG state to advance.

Returns: A cached or newly sampled N(0, 1) value, or 0.0 when rng is NULL.

◆ sim_noise_source_normal_pair()

void sim_noise_source_normal_pair	(	SimNoiseSourceRng *	rng,
		double *	n0,
		double *	n1
	)

Draw a pair of independent standard-normal variates.

Uses Box-Muller sampling with the first uniform clamped away from zero to avoid log(0). Output pointers may be NULL.

Parameters

	rng	RNG state to advance; NULL writes zeroes to non-NULL outputs.
[out]	n0	Receives the first N(0, 1) sample when non-NULL.
[out]	n1	Receives the second N(0, 1) sample when non-NULL.

◆ sim_noise_source_seed()

void sim_noise_source_seed	(	SimNoiseSourceRng *	rng,
		uint64_t	initstate,
		uint64_t	initseq
	)

Seed a deterministic RNG stream.

Parameters

rng	RNG state to initialize; NULL is ignored.
initstate	Initial generator state value.
initseq	Stream selector; converted to an odd increment internally.

◆ sim_noise_source_temporal_params()

void sim_noise_source_temporal_params	(	double	sigma,
		double	tau,
		double	alpha,
		double	dt,
		double *	out_decay,
		double *	out_variance
	)

Derive decay and innovation scale for temporal correlated noise.

The update convention is state = decay * state + variance * N(0, 1). Invalid dt disables innovation, invalid tau is clamped to a tiny positive value, and alpha is bounded below by 0.1.

Parameters

	sigma	Innovation amplitude before temporal normalization.
	tau	Positive correlation timescale.
	alpha	Positive stretch exponent, clamped to at least 0.1.
	dt	Simulation timestep.
[out]	out_decay	Receives decay factor when non-NULL.
[out]	out_variance	Receives normal multiplier when non-NULL.

◆ sim_noise_source_uniform()

double sim_noise_source_uniform ( SimNoiseSourceRng * rng )

Draw a uniform variate in [0, 1).

Parameters

rng	RNG state to advance.

Returns: Uniform double in [0, 1), or 0.0 when rng is NULL.

Classes

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SimNoiseSourceRng

Function Documentation

◆ sim_noise_source_apply_mean_reverting_complex()

◆ sim_noise_source_apply_mean_reverting_real()

◆ sim_noise_source_apply_temporal_complex()

◆ sim_noise_source_apply_temporal_real()

◆ sim_noise_source_apply_white_complex()

◆ sim_noise_source_apply_white_real()

◆ sim_noise_source_ensure_capacity()

◆ sim_noise_source_gaussian_gain()

◆ sim_noise_source_normal()

◆ sim_noise_source_normal_pair()

◆ sim_noise_source_seed()

◆ sim_noise_source_temporal_params()

◆ sim_noise_source_uniform()