wfmgen — User API: Surface, Target & Decisions¶

The model¶

doppler is C-first: every algorithm lives in C once, and everything else is a thin face. The waveform generator is four pieces over one core:

flowchart TB
    CLIB["<b>C lib</b> · wfm_* (libdoppler)<br/>every algorithm, once"]
    CCLI["<b>C CLI</b> · wfmgen<br/>the only true standalone"]
    PYLIB["<b>Python lib</b> · doppler.wfm<br/>Synth · Segment · Composer · …"]
    PYCLI["<b>Python console script</b> · wfmgen<br/>execs the C CLI"]

    CLIB -->|built into| CCLI
    CLIB -->|bound as glue| PYLIB
    CCLI -->|exposed as| PYCLI

    %% library use ← left column · CLI use ← right column

• C lib — the algorithms (wfm_synth engine + the wfm_* composer), once.
• Python lib (doppler.wfm) — just glue over the C lib.
• C CLI (wfmgen) — the one standalone executable (the composer superset).
• Python console script (wfmgen) — a tiny os.execv shim over the bundled C binary; no CLI logic in Python.

Naming: the wfm umbrella¶

One prefix ties the whole subsystem together — wfm (waveform). Each Python name mirrors its C backing at the same level.

Decisions¶

The composition verbs are settled and unchanged: Segment.sum() mixes sources at the same time (one noise floor); Segment.add() sequences segments in time. No +/- operators.

Current surface (baseline)¶

A · CLI flags (wavegen/wfmgen)¶

B · Python doppler.wfm¶

Target surface (0.11.0)¶

Same as the baseline, under the wfm umbrella (D0), with these deltas:

• One CLI wfmgen (the composer; all flags above, with --from-file etc. no longer "wfmgen-only").
• One waveform object Synth — config + .steps()/.step()/.reset() + usable directly in Segment.sum(Synth(...), …). Source removed; builders tone()/qpsk()/pn()/bpsk()/noise() return Synth. Synth becomes a thin Python object that lazily spins the C engine (so composing N synths does not allocate N engines), and the raw jm C type + its get_*/set_* go internal (D9).
• One import path (D7): from doppler.wfm import Synth, Segment, Timeline, Composer, Writer, StreamSink, Reader, tone, qpsk, ….
• Consistent params (D8): noise(level=), Segment.sum(num_samples=).

Target waveform usage:

from doppler.wfm import Synth, Segment, Composer, Writer, qpsk, tone

Synth(type="qpsk", snr=12).steps(4096)            # direct: generate now
scene = Segment.sum(                              # compose: same object
    qpsk(snr=15, level=-10),                      #   builders return Synth
    tone(freq=2e5),
    num_samples=65536,                            #   (was n=)
)
Composer(scene).compose()

Breaking changes / migration (pre-1.0, allowed)¶

Execution plan¶

Riskiest gate first (the jm drift gate), each step its own PR:

1. The wfm rename (D0/D10) — synth_* → wfm_synth_* (C); package doppler.wfm → doppler.wfm; reconcile objects/, just-makeit.toml (module name), and keep jm status --check green.
2. jm-app removal — delete the single-shot wavegen jm app + the Python CLI (doppler.wfm.cli) + wavegen.py; the C wfmgen composer binary becomes the one CLI.
3. Wheel-ship + shim (D2/D5) — package the wfmgen binary as data; the wfmgen console-script main() os.execvs it; wire cibuildwheel to build/bundle it across cp39–cp314 × {linux, macos}.
4. Synth unification (D4/D9) — fold Source into a thin Python Synth; builders return Synth; Segment.sum accepts Synth; hide accessors.
5. Import unification + param renames (D7/D8).
6. Docs — rewrite guide/gallery to the four-box model + one CLI; update the two diagrams; flip examples to the unified Synth + single import.
7. Cut 0.11.0 (the existing release checklist).

0.23.0 Status¶

The model and CLI/library surface above are as built. One capability has been added since this note that the original design did not anticipate: ranged numeric fields.

Every numeric segment/source field that the composer resolves per repeat — freq, f_end, snr, level, num_samples, off_samples — now accepts either a scalar (as before) or a [lo, hi] pair drawn uniformly on each segment repeat:

• JSON / --from-file / --record — the field value is either a number or a two-element [lo, hi] array. --record round-trips the range, not a realized draw.
• CLI — the corresponding flag accepts LO:HI in place of a scalar (--freq 11200:12800, --off 4000:5600, --snr 8:14, --level -12:-3); a bare number is unchanged.
• Python library — the generated Synth/Segment accept a tuple (lo, hi) wherever they accept a scalar, e.g. Synth(freq=(9000, 14000)) or Segment(freq=(11200, 12800), off_samples=(4000, 5600)). The getter returns a tuple when ranged, a scalar otherwise. This is generated glue (jm composer codegen), not a hand Python wrapper — consistent with the "Python is just glue" rule above.

Reproducibility is preserved without RNG state. Each draw is a splitmix64 hash of (seed, repeat index, segment index, source index, field), so a recorded spec replays the identical sequence of draws byte-for-byte; this is why --record stores the range rather than a sampled value. Ranges compose with the advancing-seed fresh-noise behaviour (the noise re-rolls and the parameters move) and with chirp (start/end can each be a range independently — a deterministic sweep whose endpoints jitter per burst).

This is what powers the realtime DSSS demo's per-burst Doppler offset and code phase: one looping burst segment with freq: [lo, hi] and a jittered off_samples: [lo, hi] trailing gap.

The original 0.11.0 decisions above remain accurate; ranged fields are purely additive (a scalar field is byte-identical to its pre-0.23.0 behaviour).