Emitters

Scientific validation

The emitter backends have been scientifically validated against published references. See the per-backend reports:

Each report covers construct validity, mathematical correctness against cited equations, empirical comparison to published reference numbers, literature grounding, experimental methodology, operating envelope, and documented limitations.

An emitter creates the clean signal a transmitter would have produced before the scene places it in time, frequency, and space. The signal is complex baseband in-phase/quadrature (IQ): samples are centered at zero hertz in the emitter’s own frame, while carrier placement stays in metadata for later scene and channel stages.

Everything downstream consumes that output without depending on the waveform family. The shipped core example is an LFM chirp radar waveform; TorchSig and other optional emitters are selected through their explicit integration or backend boundary.

rfgen uses scipy.signal.chirp for its shipped core radar emitter. TorchSig, Sionna PHY, srsRAN, GNU Radio, RadarSimPy, and capture-oriented paths are separate optional or unavailable backend boundaries; consult the Library Landscape and Signal Catalog before selecting one.

The emitter contract is intentionally small: implement the waveform source, publish the supported labels and parameter schema, and return a Signal with SignalMetadata. Scenes, channels, labels, and storage handle placement, propagation, supervision, and persistence.

Add bounded waveform variety to an augmentation dataset

Use a waveform source when an augmentation experiment needs a particular baseband geometry or modulation primitive that is not supplied by the ordinary catalog. The source creates clean IQ; the scene composer then places it, the channel layer applies propagation and receiver effects, and the label layer derives supervision. Start with the waveform-source reference to select a source and its exact input label.

Three bounded sources are available for this task:

  • TorchSig target-constellation adapters provide 32psk and 128qam_cross clean-baseband geometries.

  • Fixed-profile APSK provides 16apsk, 32apsk, 64apsk, and 128apsk geometries from the selected DVB standards.

  • Generic OQPSK provides the half-sine, half-symbol-offset modulation primitive under oqpsk.

These labels are API inputs, not a statement that a generated example replays a capture, establishes corpus fidelity, or supplies a protocol frame, transmitter, or receiver model.

Minimal worked example

import torch
from rfgen.domains.radar.chirp_emitter import ChirpRadarEmitter

emitter = ChirpRadarEmitter(bandwidth_hz=1_000_000, pulse_duration_s=100e-6)
signal = emitter.generate(
    class_label="lfm_chirp",
    sample_rate=3_000_000,
    duration_s=0.001,
    f_offset_hz=0.0,
    rng=torch.Generator().manual_seed(0),
)
assert signal.metadata.family == "radar"
assert signal.metadata.bandwidth_hz == 1_000_000.0
assert signal.metadata.snr_db == float("inf")  # clean baseband; channel adds noise

For the browsable list of supported families with parameter ranges and example configs, see Signal Catalog.

Adjacent Concepts

Two emitter topics are important enough to have their own pages. Keeping them separate prevents this page from becoming a dependency catalog or a validation report.

Sub-concept

What it covers

See

Library landscape

Which mature tool or implementation strategy backs each family, and where optional dependencies are isolated.

Library Landscape

Coverage

What the catalog covers in practice, how coverage is measured, and where validation data is required.

Coverage

A reader writing a new emitter or scoping a sim2real study will want both. A reader trying to understand the emitter contract (this page) does not.

What an emitter does

An emitter (BaseEmitter subclass) returns a Signal wrapping the clean IQ and its SignalMetadata.

The metadata record stamps three things:

  • Identity: family, class_name, class_taxonomy, generator_name, and (when supplied) device_id. Tells downstream what was emitted, which implementation produced it, and which virtual TX device it belongs to.

  • Time-frequency extent: sample_rate_hz, bandwidth_hz, duration_samples. Tells downstream how the IQ sits on the time and frequency axes in the emitter’s own frame.

  • Clean-noise state: snr_db = +inf. Emitters never add propagation, receiver, or thermal noise; the channel layer is what makes SNR finite.

Source: the retained BaseEmitter contract and Reference / Contract Tests require emitter outputs to be baseband, metadata-bearing, deterministic, and clean; Concepts / Channels owns propagation, RX capture, RX hardware, and receiver noise.

Channels, the scene composer, and the labeler fill in the rest of the record: scene-relative placement, channel realizations, receiver outputs, and derived annotations. Full field-by-field reference belongs on the SignalMetadata API page.

The emitter also honors the RNG contract: random payloads, jitter, burst timing, and protocol choices are drawn from the supplied generator. Re-running the same emitter with the same resolved configuration, seed, dependency versions, and device determinism settings should reproduce the same clean IQ. Full normative contract on the BaseEmitter API page.

What an emitter does not do

  • Center-frequency placement in a wideband scene → handled by the scene composer.

  • Channel propagation (reflections from multiple paths, signal weakening with distance, motion-related Doppler shifts, receive (RX) capture, and RX hardware effects including low-noise amplifier (LNA) thermal noise) → handled by channels.

  • Time placement in a scene → scene composer.

  • Label generation → the label layer reads component_signals after the scene composer assembles the scene.

The emitter is a pure waveform source. Everything that depends on receiver geometry, propagation, or downstream supervision lives elsewhere.

Two cross-layer subtleties matter:

  1. Emitters own waveform-intrinsic frequency behavior. A frequency-sweeping waveform such as the shipped LFM chirp must not be reduced to “generate at direct current (DC), then blindly frequency-shift later” if that would break the waveform structure. The vocabulary for emitter-relative and scene-relative frequency lives in Coordinate Systems.

  2. Emitters can carry a device_id, which identifies transmitter hardware. The impairment math runs in the channel layer, but the identity travels with the emitted signal so scenes, channels, and labels can agree on the same virtual radio. See TX Impairments.

The Signal Catalog distinguishes the current runnable emitter surface from registered backend stubs. SciPy documents frequency-swept chirps in scipy.signal.chirp; the RF-frame handoff is defined in Coordinate Systems § Frame Transitions.

Adding a custom emitter

This section is a contract sketch for readers who need to recognize the shape of an emitter plugin. Step-by-step implementation instructions belong in Emitter API.

Subclass BaseEmitter, implement the waveform-generation and schema methods, and expose the implementation through the documented rfgen.emitters Python entry-point group.

The contract reference is on the emitters API page, and ChirpRadarEmitter is the canonical worked example.

See Also

Why ABC instead of duck-typed callables

The base class gives every emitter the same lifecycle: validate parameters, generate clean IQ, check metadata invariants, and expose a schema. That keeps family-specific synthesis local while scenes, channels, labels, and storage depend on one stable interface.

Why stateless?

Workers can instantiate emitters freely per shard, sample, or test without reset logic. State that should persist across samples, such as per-device fingerprint parameters, is keyed by device_id outside the emitter instance. Use the device-population service to resolve and persist that fixed device set before distributed scene generation.

What we deliberately do not model

  • Receiver-side hardware effects, including low-noise amplifier (LNA) noise and analog-to-digital converter (ADC) quantization; those live in the channel layer, after propagation.

  • Protocol-stack-level effects (medium access, retransmissions, carrier sensing) are outside scope; we model PHY only.

  • Power-amplifier modeling beyond Rapp / Saleh: fine for fingerprinting, coarse for power-amp characterization research.

  • Cellular base-station scheduling: LTE/NR emitters produce single-cell downlink (DL) waveforms; multi-cell coordination is left to scene composition.

Source: RX capture and RX hardware define LNA noise and ADC as channel transformations; TX impairments cites the Rapp and Saleh PA models used by the proposed PA slot; Sionna integration records the propagation boundary, while heterogeneous multi-emitter scene composition remains an rfgen responsibility.