File wfm_plan.h¶

FileList > inc > wfm > wfm_plan.h

Go to the source code of this file

• #include <complex.h>
• #include <stddef.h>
• #include <stdint.h>

Public Types¶

Public Functions¶

Public Types Documentation¶

typedef wfm_plan_t¶

typedef struct wfm_plan wfm_plan_t;

Opaque prepared-plan state.

Public Functions Documentation¶

function wfm_plan_anchor_seed¶

The noise seed that reproduces a full compose.

uint64_t wfm_plan_anchor_seed (
    const wfm_plan_t * p
) 

The first noisy segment's default seed (its first source's seed field). Passing this as wfm_plan_at's seed (with the scene's base SNR) yields the byte-identical output of wfm_compose for a single-segment scene; for a multi-segment scene each segment still draws from its own default seed unless overridden. Varying the seed draws independent Monte-Carlo noise (and, for a ranged-gap scene, timing) realizations.

function wfm_plan_at¶

Scalar fast-path for the hot Monte-Carlo/SNR loop (no JSON parse).

size_t wfm_plan_at (
    const wfm_plan_t * p,
    double snr,
    uint64_t seed,
    float _Complex * out
) 

out = Σ gain_k·cache_k + gain(snr)·noise(seed) per segment/instance; writes up to wfm_plan_len(p) samples. Equivalent to render with only {"snr":snr,"seed":seed} — seed is always an explicit override here.

Returns:

Samples actually written for this draw (<= wfm_plan_len(p)).

function wfm_plan_destroy¶

Destroy a Plan and free its caches. NULL is a no-op.

void wfm_plan_destroy (
    wfm_plan_t * p
) 

function wfm_plan_dump¶

Save a Plan to a file ( wfm_plan_save() bytes atpath ).

int wfm_plan_dump (
    const wfm_plan_t * p,
    const char * path
) 

Returns:

0 on success, non-zero on an open/write error.

function wfm_plan_len¶

Worst-case materialized length in samples (every ranged gap at its hi bound) — the jm binding's out_len_fn / allocation capacity.

size_t wfm_plan_len (
    const wfm_plan_t * p
) 

function wfm_plan_load¶

Load a Plan from a file written by wfm_plan_dump() .

wfm_plan_t * wfm_plan_load (
    const char * path
) 

Same fingerprint semantics as wfm_plan_restore(): a matching build loads the cached buffers, a mismatch rebuilds from the embedded spec.

Returns:

Heap Plan (caller wfm_plan_destroy()s it), or NULL on an open/read error or a malformed/foreign-endian file.

function wfm_plan_n_sources¶

Number of cached signal sources across every segment (excludes noise floors); the length of the gains /phases /enable arrays.

size_t wfm_plan_n_sources (
    const wfm_plan_t * p
) 

function wfm_plan_prepare¶

Prepare a Plan from a composer spec JSON (Composer.to_json()).

wfm_plan_t * wfm_plan_prepare (
    const char * spec_json
) 

Parses + resolves the scene, validates scope per segment, then renders and caches each segment's clean signal ON-time at gain 1. Returns NULL on parse failure or an out-of-scope spec (continuous/repeat scene, a ranged on-time, a ranged per-source field, a non-trailing/multiple noise source within a segment, or a source carrying clock Doppler).

The last is a refusal rather than a limitation to work around. This cache holds one source's clean ON-time in isolation; a Doppler channel is a resampler with state that runs through the gaps too, so what a burst renders as depends on the leading delay and on the previous instance's gap, and the cache has nowhere to keep that. It also puts the AWGN outside the channel where compose() puts it inside. Both were measured against compose(), not assumed see the note in plan_build(). Refusing beats caching a render that differs from compose() invisibly; teaching the cache to carry a channel's history is gh-1109.

Parameters:

• spec_json A NUL-terminated composer spec JSON string.

Returns:

Heap Plan (caller wfm_plan_destroy()s it), or NULL.

function wfm_plan_render¶

General render: apply a JSON override spec, return a cf32 array.

size_t wfm_plan_render (
    const wfm_plan_t * p,
    const char * overrides_json,
    float _Complex * out
) 

overrides_json is a small JSON object, all keys optional: {"gains":[dB…], "phases":[rad…], "enable":[bool…], "snr":dB, "seed":u} (gains/phases/enable are per-source, flat and segment-major, length = wfm_plan_n_sources()). An empty object (or NULL) renders the baseline — bit-identical to Composer(scene).compose(). Writes up to wfm_plan_len(p) samples to out.

Returns:

Samples actually written for this draw (<= wfm_plan_len(p)).

function wfm_plan_restore¶

Reconstruct a Plan from a blob produced by wfm_plan_save() .

wfm_plan_t * wfm_plan_restore (
    const void * blob,
    size_t n
) 

If the blob's DSP fingerprint matches this build AND its structure matches the embedded spec, the cached buffers are loaded directly (no DSP). Otherwise the Plan is REBUILT from the embedded spec via the full DSP — same result, just paying prepare()'s cost. Returns NULL only on a malformed/foreign-endian blob or an unparseable/out-of-scope embedded spec (the same cases wfm_plan_prepare rejects), never on a mere fingerprint mismatch.

Parameters:

• blob Bytes from wfm_plan_save().
• n Length of blob in bytes.

Returns:

Heap Plan (caller wfm_plan_destroy()s it), or NULL.

function wfm_plan_save¶

Serialize a Plan into blob (wfm_plan_save_bytes(p) bytes).

size_t wfm_plan_save (
    const wfm_plan_t * p,
    void * blob
) 

Native-endian. The blob embeds the spec JSON, so a restore is self-contained. Returns the number of bytes written (== wfm_plan_save_bytes(p)) — the actual-length contract a variable-output binding needs, so save() -> bytes generates with no hand-written glue.

function wfm_plan_save_bytes¶

Serialized size of a Plan blob (envelope + spec + cached buffers).

size_t wfm_plan_save_bytes (
    const wfm_plan_t * p
) 

The number of bytes wfm_plan_save() writes: a small envelope with the DSP fingerprint, the embedded spec JSON, and every cached signal buffer. Dominated by the buffers (Σ per-source num_samples · 8 bytes) — multi-MB for a large scene, which is exactly why the spec-rebuild path is the default.

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