File awgn_core.h¶

FileList > awgn > awgn_core.h

Go to the source code of this file

Additive White Gaussian Noise generator. More...

• #include "clib_common.h"
• #include "dp_state.h"
• #include "jm_perf.h"

Classes¶

Public Functions¶

Macros¶

Detailed Description¶

Generates complex CF32 samples where real and imaginary parts are independent zero-mean Gaussians, each with standard deviation amplitude. Total complex power = 2 * amplitude².

Algorithm¶

RNG: xoshiro256++ — four 64-bit state words, seeded via SplitMix64 from the user-supplied uint64 seed. Period 2^256 − 1.

Transform: Box-Muller. Each call to awgn_generate() consumes two 64-bit RNG outputs per complex output sample:

u1 ∈ (0, 1] (top 24 bits of first 64-bit word, +1 offset, /2^24) u2 ∈ [0, 1) (top 24 bits of second 64-bit word, /2^24) r = amplitude * sqrt(−2 · ln u1) θ = 2π · u2 out = r·cos θ + j·r·sin θ

Usage¶

awgn_state_t *g = awgn_create(42, 1.0f);
float complex out[1024];
awgn_generate(g, 1024, out);
awgn_destroy(g);

Public Functions Documentation¶

function awgn¶

One-shot AWGN generation — no persistent state required.

int awgn (
    uint64_t seed,
    float amplitude,
    size_t n,
    float complex * out
) 

Creates a temporary generator, fills out, then frees it. Equivalent to:

awgn_state_t *g = awgn_create(seed, amplitude);
awgn_generate(g, n, out);
awgn_destroy(g);

Parameters:

• seed RNG seed.
• amplitude Per-component (Re, Im) standard deviation.
• n Number of samples to generate.
• out Output buffer, capacity ≥ n.

Returns:

DP_OK on success, DP_ERR_MEMORY on allocation failure.

function awgn_create¶

Create an AWGN generator. Allocates state, seeds the xoshiro256++ RNG via SplitMix64, and sets up both the scalar and the AVX2 parallel streams. The initial seed is stored so awgn_reset() can reproduce the exact same stream.

awgn_state_t * awgn_create (
    uint64_t seed,
    float amplitude
) 

Parameters:

• seed 64-bit RNG seed. Two generators with different seeds produce statistically independent noise streams.
• amplitude Per-component (Re, Im) standard deviation. Must be ≥ 0; total complex power = 2 × amplitude².

Returns:

Heap-allocated state, or NULL on allocation failure.

>>> from doppler.source import AWGN
>>> gen = AWGN(seed=0, amplitude=1.0)
>>> gen.amplitude
1.0

function awgn_destroy¶

void awgn_destroy (
    awgn_state_t * state
) 

Free all resources. NULL is a no-op.

function awgn_generate¶

Generate n complex CF32 AWGN samples. Uses Box-Muller with xoshiro256++ to fill out with independent complex Gaussians: Re and Im each have zero mean and standard deviationamplitude . Total complex power = 2 × amplitude². The AVX2 path processes 8 samples in parallel when available.

size_t awgn_generate (
    awgn_state_t * state,
    size_t n,
    float complex * out
) 

Parameters:

• state Generator state returned by awgn_create().
• n Number of samples to generate.
• out Output buffer; must hold at least n float complex values.

Returns:

n (always).

>>> import numpy as np
>>> from doppler.source import AWGN
>>> gen = AWGN(seed=0, amplitude=1.0)
>>> out = gen.generate(1024)
>>> out.dtype
dtype('complex64')
>>> out.shape
(1024,)
>>> round(float(np.var(out.real)), 1)
1.0
>>> round(float(np.var(out.imag)), 1)
1.0

function awgn_generate_max_out¶

Conservative upper bound on generate() output size.

size_t awgn_generate_max_out (
    awgn_state_t * state
) 

Returns 65536. The Python extension uses this for the initial buffer allocation; the buffer grows on demand if n > 65536.

function awgn_get_amplitude¶

Return the current amplitude (per-component std dev).

float awgn_get_amplitude (
    const awgn_state_t * state
) 

>>> from doppler.source import AWGN
>>> gen = AWGN(seed=0, amplitude=1.0)
>>> gen.amplitude
1.0
>>> gen.amplitude = 2.0
>>> gen.amplitude
2.0

function awgn_get_state¶

Serialize the RNG state (scalar + AVX2 streams) into blob .

void awgn_get_state (
    const awgn_state_t * state,
    void * blob
) 

function awgn_reseed¶

Reseed the RNG and reset all xoshiro256++ state. Equivalent to calling awgn_destroy() and awgn_create(seed, amplitude) but reuses the existing allocation. amplitude is unchanged.

void awgn_reseed (
    awgn_state_t * state,
    uint64_t seed
) 

Parameters:

• state Generator state returned by awgn_create().
• seed New 64-bit RNG seed.

  >>> import numpy as np
  >>> from doppler.source import AWGN
  >>> gen = AWGN(seed=0, amplitude=1.0)
  >>> gen.reseed(42)
  >>> out1 = gen.generate(4)
  >>> gen2 = AWGN(seed=42, amplitude=1.0)
  >>> out2 = gen2.generate(4)
  >>> bool(np.all(out1 == out2))
  True
  

function awgn_reset¶

Reset RNG to the seed supplied at create time. Re-runs the SplitMix64 seeding procedure with the original seed so the next awgn_generate() call produces exactly the same samples as the first call afterawgn_create() . amplitude is not changed.

void awgn_reset (
    awgn_state_t * state
) 

>>> import numpy as np
>>> from doppler.source import AWGN
>>> gen = AWGN(seed=0, amplitude=1.0)
>>> first = gen.generate(4)
>>> gen.reset()
>>> second = gen.generate(4)
>>> bool(np.all(first == second))
True

function awgn_set_amplitude¶

void awgn_set_amplitude (
    awgn_state_t * state,
    float val
) 

Set amplitude without disturbing RNG state.

function awgn_set_state¶

Restore RNG state; DP_OK, or DP_ERR_INVALID if rejected.

int awgn_set_state (
    awgn_state_t * state,
    const void * blob
) 

function awgn_state_bytes¶

Serialized-state byte size.

size_t awgn_state_bytes (
    const awgn_state_t * state
) 

Macro Definition Documentation¶

define AWGN_STATE_MAGIC¶

#define AWGN_STATE_MAGIC `DP_FOURCC ('A', 'W', 'G', 'N')`

define AWGN_STATE_VERSION¶

#define AWGN_STATE_VERSION `1u`

The documentation for this class was generated from the following file native/inc/awgn/awgn_core.h