Python Waveform Generator API — Synth / PN¶

Waveform type. tone: complex sinusoid. noise: AWGN. pn: PN sequence (LFSR). bpsk/qpsk: PN-driven modulation. chirp: linear-FM sweep. bits: a caller's bit pattern, with selectable modulation. symbols: a caller's complex constellation stream. dsss: spread spectrum -- a two-code burst (repeated preamble + data-code-spread frame) by default, or a continuous asynchronous stream when symbol_rate is set. One of "tone", "noise", "pn", "bpsk", "qpsk", "chirp", "bits", "symbols", "dsss".

Carrier or offset frequency in Hz; for chirp, the sweep start. With fs = 1 it is in normalised cycles per sample.

Signal-to-noise ratio in dB, interpreted per snr_mode. 100 or more is clean: no AWGN is added.

How snr is interpreted. auto: Es/N0 for bpsk/qpsk/dsss, and relative to full scale for tone/noise/pn/chirp/bits/symbols -- bits included, because a bits frame has no symbol rate the engine can infer. fs: dB relative to full scale. ebno: Eb/N0, per bit. esno: Es/N0, per symbol; for a dsss burst the outer data symbol of len(data_code) chips x sps samples, for a continuous dsss stream the fs/symbol_rate samples the async symbol spans. One of "auto", "fs", "ebno", "esno".

PRNG and LFSR seed for the noise and PN streams. Deterministic: vary it for run-to-run change. For a PN-sourced type it starts the pn_length-bit register, masked: a seed whose low pn_length bits are zero starts the register at 1, as seed 0 does.

Samples per symbol (PSK) or per chip (PN): the oversampling factor. Unused by noise, which records it as 0.

PN LFSR register length in bits, 2 to 64 for the PN-bearing types; the sequence period is 2^pn_length - 1. Unused by noise, which records it as 0.

PN generator polynomial, in the Galois bit-vector convention; 0 selects a maximal-length (MLS) polynomial for pn_length. It must fit the pn_length-bit register: a bit at or above it is refused, not masked. A polynomial above 2^53 does not survive a JSON number, so a scene file needs 0 (auto) for such a register.

PN LFSR realisation. Both give the same period; fibonacci's chips are galois's in reverse order. One of "galois", "fibonacci".

Source power in dBFS (<= 0; 0 is unit power). Applies when summed in a Segment or Composer, as a gain of 10^(level/20); a standalone Synth.steps() ignores it.

Mark this source as part of the static background field (0/1). Plan.prepare() folds a contiguous leading run of background sources into ONE pre-summed cache entry instead of caching each separately, so a scene of many fixed emitters costs one buffer rather than hundreds. The composite is overridable as a unit: it takes a single slot in gains/phases/enable and counts as one in n_sources(), so scaling it trims the whole field while its members keep their relative levels. Background sources must come first in the segment (a non-prefix ordering is rejected by prepare, since the fold would no longer reproduce compose bit-for-bit). Ignored by compose() and by standalone Synth.steps().

Chirp end frequency in Hz; ignored by other types.

Chirp sweep length in samples: the frequency ramps from freq to f_end over this many samples, then holds at f_end. 0 means the enclosing Segment's num_samples. A standalone chirp (f_end != freq) must declare it, so step(), steps(N) and any chunking of reads produce the same waveform; generating one without it raises. Ignored by non-chirp types.

Clock Doppler in ppm: the received time base is rescaled by 1 + doppler*1e-6, so the symbol and chip rates move with the carrier and a timing loop sees the error a carrier-only freq offset hides. Accepts a (lo, hi) tuple drawn uniformly per repeat, like freq/snr. Zero doppler AND zero doppler_rate means no channel is built at all, so a source that does not ask for Doppler renders exactly as it always did.

Linear ramp on doppler, in ppm per second of elapsed stream time. The channel runs through a segment's gaps as well as its on-time -- an emitter does not stop moving because its burst ended -- so this is per second, not per second of on-time. Accepts a (lo, hi) tuple drawn uniformly per repeat.

RF carrier in Hz that the ppm figures are referred to. It gives the coherent carrier rotation that accompanies the time-base warp; 0 warps the clock alone, with no carrier rotation -- a legitimate scene, not an unset field. Independent of doppler/doppler_rate.

How long this source's Doppler channel lives. per_instance: the channel dies with each repeats instance, so the geometry restarts -- the repeated-trial shape, which composes with a ranged doppler re-drawn per instance. persist: one continuous pass carries across the segment's gaps and repeat instances, keyed by (segment, source) position -- the only lifetime under which doppler_rate accumulates across a multi-burst scene. compose(), stream() and Plan.prepare() all honour both. One of "per_instance", "persist".

Symbol mapping of a bits pattern. none: the pattern shaped and output as-is (NRZ). bpsk: +/-1 symbols. qpsk: Gray-coded symbols from pairs of bits. One of "none", "bpsk", "qpsk".

Pulse shape per symbol or chip, for pn/bpsk/qpsk/bits/symbols/dsss. rect: rectangular, no ISI filtering. rrc: root-raised cosine; see rrc_beta and rrc_span. One of "rect", "rrc".

RRC roll-off factor, in (0, 1], when pulse=rrc.

RRC filter support in symbols when pulse=rrc, ONE-SIDED: the filter has 2rrc_spansps + 1 taps, unit energy (sum of h^2 = 1).

For type=symbols: a complex constellation stream. Each element is the output point itself, oversampled by sps, cycled, and RRC-shaped with pulse=rrc, which generalises any modulation (pi/4-QPSK, QAM, ...).

The preamble code, sent acq_reps times at the head of the frame (a Field's *REPS on the command line and in a scene) -- the coherent pull-in target BurstDespreader.set_acq and BurstDemod.set_preamble lock to. For type=dsss it is unmodulated chips ahead of the spread frame; for type=bits it is the head of the bit pattern. Setting it is what makes a source FRAMED.

Preamble repetitions: periods of acq_code before the sync word. On the command line and in a scene it is acq_code's *REPS.

For type=dsss: the payload spreading code, a second code distinct from acq_code. Every frame bit (sync, payload, crc) is XOR-spread across its full length, so len(data_code) is the spreading factor.

RETIRED (doppler#1617): nothing reads it but the refusal. The frame-sync word is a field of the frame DESCRIPTION, so sync= is refused naming frame=; the CLI's --sync builds that description for you, and a scene refuses the "sync" key.

RETIRED (doppler#1617): nothing reads it but the refusal. A CRC is a stage of the frame DESCRIPTION, so crc= is refused naming frame=, whatever its value (crc="none" included); the CLI's --crc builds that description for you, and a scene refuses the "crc" key.

For type=dsss: > 0 selects CONTINUOUS asynchronous mode. The spreading code repeats endlessly and data rides on it at this symbol rate (Hz), independent of the code-epoch rate (chips/symbol = fs/sps/symbol_rate, non-integer). No preamble/sync/CRC frame; data comes from the payload when supplied, else a seeded PN a receiver regenerates. Absent/0 = burst.

Continuous dsss data source: 1 = code-only (the pure spreading code, no data modulation); 0 = data-modulated (the payload when supplied, else the seeded PN). Ignored for burst dsss and non-dsss types.

A frame DESCRIPTION, the whole frame: fields in wire order, and stages that each name the span they cover (crc16, rs, randomise, interleave, conv, or a kind of your own). It is the only way a source says anything but the common frame: a coding stage, a field of the caller's own bits at a position of their choosing, a stage covering a span they name. wfmgen --frame FILE, a scene's frame key and Python's frame= (a FrameDesc or a Frame) all land here. When it is set it IS the frame, and an unspread acq_code beside it is refused. NULL means the common frame, [preamble x reps | data], which dp_wfm_frame_fixed() builds from acq_code and the data source; a sync word or a CRC is a field or a stage of a description, never a flat field. A C caller's description is borrowed, exactly as wfm_seq_t is borrowed elsewhere here, so it must outlive the source. The composer and a Python source hold their own copy (dp_wfm_frame_copy()), so a later change to the FrameDesc does not reach them. On the Python face frame= is an input: read it back from the composer's JSON (its getter is jm's, pending removal: doppler#1694). KERNELS stay in C by design. A description names a stage's KIND; the code that runs it is a wfm_frame_ops_t entry, and a caller adding a genuinely new transform (convolutional interleaving, say) writes that kernel in C and hands it to dp_wfm_frame_assemble directly.

RETIRED (doppler#1718): nothing reads it but the refusal. A payload is drawn from a data source, so bits=, and its aliases payload= and pattern=, are refused naming data=; the CLI and a scene refuse --bits and "payload" the same way.

A frame's payload drawn from a data source: a Field on the command line and in a scene, a bit array in Python. The source is split into data_len-bit frames, one chunk per frame, and its last chunk is padded from fill. For type=bits, bpsk/qpsk/pn framed, a dsss burst (one burst per frame), and continuous dsss (one bit per data symbol, no frame); not with data_from_file.

Bits of the data source per frame: the data:LEN field of the common frame (preamble x reps, sync, data:LEN, crc). 0 takes a finite source whole, as one frame. A carried frame names its own data field, and this is then 0 or that field's LEN. Continuous dsss has no frame, and refuses it.

The bits that pad a data source's last frame when it does not divide into data_len-bit frames, tiled from their first bit; stdin on a framed source always needs them. Without them such a source is refused before the first sample. A Field on the command line and in a scene, a bit array in Python. Continuous dsss has no frame to pad, and refuses it.

Continuous dsss: pure-code symbols opening each frame of frame_symbols symbols. The data pauses through them and runs on across frames, so a searcher can integrate coherently over the window; once a payload ends, no window is sent. At most frame_symbols, and fewer when a data source is set; 0 with frame_symbols 0 = no window.

Continuous dsss: the frame, in symbols, that code_only_symbols opens; give it with code_only_symbols, or both 0 for no window. The frame runs on the stream's own symbol clock, so its edges land at any chip phase.

Sample rate in Hz, one per segment and shared by all its sources. At the default 1.0 every frequency is normalised (cycles per sample); state it whenever a scene is in real Hz.

Galois feedback tap polynomial (right-shift convention). The LSB is the tap at position 0 (always 1 for a primitive poly); bit k=1 means tap at position k. 0 (the default) selects the maximal-length polynomial for length. The Fibonacci taps are derived automatically so you only supply one value.

Initial LFSR register state; must be non-zero WITHIN the register, seed & pn_register_mask (length) -- the all-zero state is a fixed point, and a seed that masks to it (128 on 7 bits) is refused like 0.

Register width in bits, 1..64. The sequence period is 2^length - 1 for a primitive polynomial.

One of "galois", "fibonacci".

Register A feedback-tap mask; bit k set means stage k+1 is XORed into the feedback. Default 934 (stages 2,3,6,8,9,10 — the CCSDS-fixed Register A polynomial x^10+x^9+x^8+x^6+x^3+x^2+1).

Register A initial value; must be non-zero within the register (seed_a & pn_register_mask (length): a multiple of 2^length is refused like 0). Per CCSDS this is "User dependent" — each of the 2^length-1 nonzero values selects a different member of the family (1023 distinct codes at length=10, verified in test_gold_core.c). Default 350 is the worked example from CCSDS 415.0-G-1 Figure 5-2 (PN Code Library Table 1, Code Number 365).

Register B feedback-tap mask, same bit convention as taps_a. Default 567 (stages 1,2,3,5,6,10 — the CCSDS-fixed Register B polynomial).

Register B initial value; must be non-zero within the register, as seed_a. Default 73 (stages 1,4,7 — CCSDS's fixed Register B initial value 1001001000, unique per the standard, not user-selectable).

Register width in bits, 1..64. CCSDS command link uses 10 (period 1023). Default 10.

Initial segment list.

Loop the sequence after the last segment.

Never finish; execute always returns the requested count.

Waveform type. tone: complex sinusoid. noise: AWGN. pn: PN sequence (LFSR). bpsk/qpsk: PN-driven modulation. chirp: linear-FM sweep. bits: a caller's bit pattern, with selectable modulation. symbols: a caller's complex constellation stream. dsss: spread spectrum -- a two-code burst (repeated preamble + data-code-spread frame) by default, or a continuous asynchronous stream when symbol_rate is set. One of "tone", "noise", "pn", "bpsk", "qpsk", "chirp", "bits", "symbols", "dsss".

Carrier or offset frequency in Hz; for chirp, the sweep start. With fs = 1 it is in normalised cycles per sample.

Signal-to-noise ratio in dB, interpreted per snr_mode. 100 or more is clean: no AWGN is added.

How snr is interpreted. auto: Es/N0 for bpsk/qpsk/dsss, and relative to full scale for tone/noise/pn/chirp/bits/symbols -- bits included, because a bits frame has no symbol rate the engine can infer. fs: dB relative to full scale. ebno: Eb/N0, per bit. esno: Es/N0, per symbol; for a dsss burst the outer data symbol of len(data_code) chips x sps samples, for a continuous dsss stream the fs/symbol_rate samples the async symbol spans. One of "auto", "fs", "ebno", "esno".

PRNG and LFSR seed for the noise and PN streams. Deterministic: vary it for run-to-run change. For a PN-sourced type it starts the pn_length-bit register, masked: a seed whose low pn_length bits are zero starts the register at 1, as seed 0 does.

Samples per symbol (PSK) or per chip (PN): the oversampling factor. Unused by noise, which records it as 0.

PN LFSR register length in bits, 2 to 64 for the PN-bearing types; the sequence period is 2^pn_length - 1. Unused by noise, which records it as 0.

PN generator polynomial, in the Galois bit-vector convention; 0 selects a maximal-length (MLS) polynomial for pn_length. It must fit the pn_length-bit register: a bit at or above it is refused, not masked. A polynomial above 2^53 does not survive a JSON number, so a scene file needs 0 (auto) for such a register.

PN LFSR realisation. Both give the same period; fibonacci's chips are galois's in reverse order. One of "galois", "fibonacci".

Source power in dBFS (<= 0; 0 is unit power). Applies when summed in a Segment or Composer, as a gain of 10^(level/20); a standalone Synth.steps() ignores it.

Mark this source as part of the static background field (0/1). Plan.prepare() folds a contiguous leading run of background sources into ONE pre-summed cache entry instead of caching each separately, so a scene of many fixed emitters costs one buffer rather than hundreds. The composite is overridable as a unit: it takes a single slot in gains/phases/enable and counts as one in n_sources(), so scaling it trims the whole field while its members keep their relative levels. Background sources must come first in the segment (a non-prefix ordering is rejected by prepare, since the fold would no longer reproduce compose bit-for-bit). Ignored by compose() and by standalone Synth.steps().

Chirp end frequency in Hz; ignored by other types.

Chirp sweep length in samples: the frequency ramps from freq to f_end over this many samples, then holds at f_end. 0 means the enclosing Segment's num_samples. A standalone chirp (f_end != freq) must declare it, so step(), steps(N) and any chunking of reads produce the same waveform; generating one without it raises. Ignored by non-chirp types.

Clock Doppler in ppm: the received time base is rescaled by 1 + doppler*1e-6, so the symbol and chip rates move with the carrier and a timing loop sees the error a carrier-only freq offset hides. Accepts a (lo, hi) tuple drawn uniformly per repeat, like freq/snr. Zero doppler AND zero doppler_rate means no channel is built at all, so a source that does not ask for Doppler renders exactly as it always did.

Linear ramp on doppler, in ppm per second of elapsed stream time. The channel runs through a segment's gaps as well as its on-time -- an emitter does not stop moving because its burst ended -- so this is per second, not per second of on-time. Accepts a (lo, hi) tuple drawn uniformly per repeat.

RF carrier in Hz that the ppm figures are referred to. It gives the coherent carrier rotation that accompanies the time-base warp; 0 warps the clock alone, with no carrier rotation -- a legitimate scene, not an unset field. Independent of doppler/doppler_rate.

How long this source's Doppler channel lives. per_instance: the channel dies with each repeats instance, so the geometry restarts -- the repeated-trial shape, which composes with a ranged doppler re-drawn per instance. persist: one continuous pass carries across the segment's gaps and repeat instances, keyed by (segment, source) position -- the only lifetime under which doppler_rate accumulates across a multi-burst scene. compose(), stream() and Plan.prepare() all honour both. One of "per_instance", "persist".

Symbol mapping of a bits pattern. none: the pattern shaped and output as-is (NRZ). bpsk: +/-1 symbols. qpsk: Gray-coded symbols from pairs of bits. One of "none", "bpsk", "qpsk".

Pulse shape per symbol or chip, for pn/bpsk/qpsk/bits/symbols/dsss. rect: rectangular, no ISI filtering. rrc: root-raised cosine; see rrc_beta and rrc_span. One of "rect", "rrc".

RRC roll-off factor, in (0, 1], when pulse=rrc.

RRC filter support in symbols when pulse=rrc, ONE-SIDED: the filter has 2rrc_spansps + 1 taps, unit energy (sum of h^2 = 1).

For type=symbols: a complex constellation stream. Each element is the output point itself, oversampled by sps, cycled, and RRC-shaped with pulse=rrc, which generalises any modulation (pi/4-QPSK, QAM, ...).

The preamble code, sent acq_reps times at the head of the frame (a Field's *REPS on the command line and in a scene) -- the coherent pull-in target BurstDespreader.set_acq and BurstDemod.set_preamble lock to. For type=dsss it is unmodulated chips ahead of the spread frame; for type=bits it is the head of the bit pattern. Setting it is what makes a source FRAMED.

Preamble repetitions: periods of acq_code before the sync word. On the command line and in a scene it is acq_code's *REPS.

For type=dsss: the payload spreading code, a second code distinct from acq_code. Every frame bit (sync, payload, crc) is XOR-spread across its full length, so len(data_code) is the spreading factor.

RETIRED (doppler#1617): nothing reads it but the refusal. The frame-sync word is a field of the frame DESCRIPTION, so sync= is refused naming frame=; the CLI's --sync builds that description for you, and a scene refuses the "sync" key.

RETIRED (doppler#1617): nothing reads it but the refusal. A CRC is a stage of the frame DESCRIPTION, so crc= is refused naming frame=, whatever its value (crc="none" included); the CLI's --crc builds that description for you, and a scene refuses the "crc" key.

For type=dsss: > 0 selects CONTINUOUS asynchronous mode. The spreading code repeats endlessly and data rides on it at this symbol rate (Hz), independent of the code-epoch rate (chips/symbol = fs/sps/symbol_rate, non-integer). No preamble/sync/CRC frame; data comes from the payload when supplied, else a seeded PN a receiver regenerates. Absent/0 = burst.

Continuous dsss data source: 1 = code-only (the pure spreading code, no data modulation); 0 = data-modulated (the payload when supplied, else the seeded PN). Ignored for burst dsss and non-dsss types.

A frame DESCRIPTION, the whole frame: fields in wire order, and stages that each name the span they cover (crc16, rs, randomise, interleave, conv, or a kind of your own). It is the only way a source says anything but the common frame: a coding stage, a field of the caller's own bits at a position of their choosing, a stage covering a span they name. wfmgen --frame FILE, a scene's frame key and Python's frame= (a FrameDesc or a Frame) all land here. When it is set it IS the frame, and an unspread acq_code beside it is refused. NULL means the common frame, [preamble x reps | data], which dp_wfm_frame_fixed() builds from acq_code and the data source; a sync word or a CRC is a field or a stage of a description, never a flat field. A C caller's description is borrowed, exactly as wfm_seq_t is borrowed elsewhere here, so it must outlive the source. The composer and a Python source hold their own copy (dp_wfm_frame_copy()), so a later change to the FrameDesc does not reach them. On the Python face frame= is an input: read it back from the composer's JSON (its getter is jm's, pending removal: doppler#1694). KERNELS stay in C by design. A description names a stage's KIND; the code that runs it is a wfm_frame_ops_t entry, and a caller adding a genuinely new transform (convolutional interleaving, say) writes that kernel in C and hands it to dp_wfm_frame_assemble directly.

RETIRED (doppler#1718): nothing reads it but the refusal. A payload is drawn from a data source, so bits=, and its aliases payload= and pattern=, are refused naming data=; the CLI and a scene refuse --bits and "payload" the same way.

A frame's payload drawn from a data source: a Field on the command line and in a scene, a bit array in Python. The source is split into data_len-bit frames, one chunk per frame, and its last chunk is padded from fill. For type=bits, bpsk/qpsk/pn framed, a dsss burst (one burst per frame), and continuous dsss (one bit per data symbol, no frame); not with data_from_file.

Bits of the data source per frame: the data:LEN field of the common frame (preamble x reps, sync, data:LEN, crc). 0 takes a finite source whole, as one frame. A carried frame names its own data field, and this is then 0 or that field's LEN. Continuous dsss has no frame, and refuses it.

The bits that pad a data source's last frame when it does not divide into data_len-bit frames, tiled from their first bit; stdin on a framed source always needs them. Without them such a source is refused before the first sample. A Field on the command line and in a scene, a bit array in Python. Continuous dsss has no frame to pad, and refuses it.

Continuous dsss: pure-code symbols opening each frame of frame_symbols symbols. The data pauses through them and runs on across frames, so a searcher can integrate coherently over the window; once a payload ends, no window is sent. At most frame_symbols, and fewer when a data source is set; 0 with frame_symbols 0 = no window.

Continuous dsss: the frame, in symbols, that code_only_symbols opens; give it with code_only_symbols, or both 0 for no window. The frame runs on the stream's own symbol clock, so its edges land at any chip phase.

Sample rate in Hz, one per segment and shared by all its sources. At the default 1.0 every frequency is normalised (cycles per sample); state it whenever a scene is in real Hz.

Segment on-time in samples, before the trailing gap: 0 derives it from the sources, or 1024 when they set none. A finite data source sets its frames, a lone dsss burst one burst, and a stream runs to its end. A count beside a finite data source or a lone dsss burst is refused, since they set the length; give repeats for more.

Trailing gap after the on-time, in samples. It carries the noise floor or hard zeros, per gap_noise.

Play the segment this many times back-to-back (each instance = delay + on-time + trailing gap) before advancing. Ranged fields re-draw and the AWGN is fresh per instance; the signal (codes, payload, PN phase) stays fixed. 0 and 1 both mean one instance.

Leading gap before the on-time, in samples: the burst arrives after this delay, and the gap carries the noise floor like off_samples. Ranged like off_samples and re-drawn per repeats instance, so a (lo, hi) delay is per-burst arrival jitter. Use off_samples for inter-burst spacing, delay_samples for arrival jitter.

Gap policy for this segment's delay and trailing gap. auto: gaps carry the segment's noise floor -- the sources' AWGN keeps running while the signal stops (clean scenes still get exact-zero gaps). off: gaps are hard zeros. One of "auto", "off".

Endpoint, e.g. "nats://127.0.0.1:4222/iq".

The wire type. The integer types use full-scale +/-1.0. One of "cf32", "cf64", "ci32", "ci16", "ci8", "f32", "f64", "i32", "i16", "i8".

The scene to prepare — a :class:Composer (or any object with a to_json()) or a spec JSON string.