Calibrated RF Chain API¶

rfgen.rf_chain is the sealed, profile-bound processor for a single complex-baseband vector. It compiles immutable calibration data and ordered stage configurations into a deterministic execution object. It is not a plugin boundary: applications select the documented stage configuration and provide calibration assets rather than subclassing the processor.

Public surface¶

Group	Public symbols	Contract
Calibration	`Curve1DV1`, `HardwareProfileV1`, `IQImbalanceProfileV1`, `ConverterProfileV1`, `AGCProfileV1`, `ToleranceV1`, `TouchstoneRefV1`	Frozen, extra-forbidden Pydantic v2 profile data.
Compilation	`DACStageConfigV1`, `PAStageConfigV1`, `PhaseNoiseStageConfigV1`, `IQImbalanceStageConfigV1`, `CFOStageConfigV1`, `PropagationStageConfigV1`, `RXMixerStageConfigV1`, `IFFilterStageConfigV1`, `ResamplerStageConfigV1`, `LNAStageConfigV1`, `ADCStageConfigV1`, `AGCStageConfigV1`, `RFCompiledStageV1`, `RFChainDescriptorV1`	Ordered stage declarations and their hash-bound compiled form.
Stateful execution	`StatefulRFChain`, `RFChainStateV1`, `RFChainResultV1`, `RFChainReportV1`, `RFStageReportV1`	Process, snapshot, and restore one rank-one complex64 stream.
Constructors	`build_hardware_profile`, `build_compiled_stage`, `build_chain_descriptor`, `compile`	Build self-hashing models without manually calculating their hashes.
Errors	`RFChainInputError`, `RFProfileIntegrityError`, `CalibrationRangeError`, `RFCompileError`, `RFChainStateError`, `RFChainReportError`	`ValueError` subclasses with a stable uppercase `code`.

Interpolation has LINEAR and PCHIP; Extrapolation has only ERROR. RFMetric names gain, noise figure, IP3, P1dB, phase, frequency, and PSD tolerance rows. RFWarning reports NEAR_CLIP, AGC_LIMIT, or CALIBRATION_EDGE in lexical enum order.

Input and profile contracts¶

ComplexTensor accepts only a finite, contiguous, strided, rank-one torch.complex64 tensor on CPU or CUDA. validate_complex_tensor(value) returns that tensor without casting; every other representation raises RFChainInputError(code="IQ"). The chain therefore never silently narrows complex128, accepts nonfinite samples, or changes input layout.

Curve1DV1 stores equal-length, finite frequency_hz and value tuples. It requires at least two strictly increasing positive frequencies, a nonempty unit, and explicit interpolation. Curve evaluation outside the declared calibration interval raises CalibrationRangeError; there is no extrapolation mode.

HardwareProfileV1 carries UTC calibration provenance, all carrier-indexed curves, converter and AGC settings, Touchstone references, and one sorted ToleranceV1 row per RFMetric. Its curves must cover [frequency_low_hz, frequency_high_hz], noise-figure values must be nonnegative, and Touchstone reference impedance must equal z0_ohm. profile_sha256 is SHA-256 over RFC 8785 canonical JSON after excluding the hash field. Use build_hardware_profile(**fields) to derive it.

TouchstoneRefV1 is provenance and integrity metadata, not a URI fetch mechanism: it records uri, SHA-256, positive port count, and reference impedance. process verifies only locally available Touchstone references when the profile supplies them; the package does not download laboratory assets at runtime.

Compilation contract¶

Every stage config is frozen and extra-forbidden, and its stage literal selects exactly one Transformation. RFCompiledConfigV1 is the union of the twelve public config models. The required configuration fields are:

Stage	Required stage-specific fields
DAC / ADC	positive `bits`, `dither`
PA	positive `memory_depth`, positive `polynomial_order`, P1dB curve digest
TX or RX phase noise	positive `filter_order`, PSD curve digest
TX or RX IQ imbalance	gain and phase curve digests
CFO	finite `offset_hz`
propagation	nonempty backend selector and resolved-config digest
RX mixer	`filter_taps >= 2`, finite `lo_hz`
IF filter	`filter_taps >= 2`, coefficient digest
resampler	positive numerator/denominator, taps, and coefficient digest; numerator no larger than taps
LNA noise	noise-figure curve digest
AGC	finite positive target/attack/decay and `min_gain_db <= max_gain_db`

build_compiled_stage(config, implementation_id) derives the stage, expected state-vector shape, and a SHA-256 RFC 8785 hash of the config. A PA has memory_depth - 1 state samples; phase-noise, RX-mixer, IF-filter, and resampler stages have their documented finite filter delay; stateless stages have no state vector.

build_chain_descriptor(profile, stage_configs, *, sample_rate_hz, carrier_hz) requires positive rates, unique Transformation values in enum order, and binds the descriptor to profile.profile_sha256. Its chain_sha256 hashes the descriptor payload excluding itself. compile(...) performs that construction and returns StatefulRFChain; it raises RFCompileError(code="STAGE_CONFIG") for duplicate or unordered stages.

The propagation config is intentionally not an identity fallback. Calling process with it raises RFCompileError(code="BACKEND") until the declared resolved propagation backend is supplied at the appropriate pipeline boundary.

`StatefulRFChain` lifecycle¶

chain = compile(profile, (CFOStageConfigV1(stage=Transformation.CFO,
                                           offset_hz=125.0),),
                sample_rate_hz=1_000_000.0, carrier_hz=915_000_000.0)
state = chain.reset(seed=7)
result = chain.process(torch.ones(1024, dtype=torch.complex64), state)
saved = chain.snapshot(result.state)
resumed = chain.process(torch.ones(32, dtype=torch.complex64), chain.restore(saved))

reset(seed: int) -> RFChainStateV1 starts a deterministic state for this descriptor and profile. process(iq, state=None) -> RFChainResultV1 advances the supplied state; None means reset(0). It preserves the validated input device and returns contiguous complex64 IQ, the next state, and a report. It rejects an incompatible profile or descriptor state, malformed state self-hash, and RNG-counter overflow with RFChainStateError.

snapshot(state) -> bytes produces canonical CBOR. restore(raw) -> RFChainStateV1 accepts only that canonical state envelope, bounded to 64 MiB, and revalidates its self-hash. The snapshot includes processed sample count, filter and resampler delay, CFO/RX-mixer phase, AGC envelope, state vectors, and the uint64 stochastic counter. Equal profile, descriptor, seed, and input partitioning produce a restart-compatible stream within the validation envelope, not an assertion of physical receiver equivalence.

Result and report contract¶

RFChainStateV1 self-hashes canonical CBOR excluding state_sha256; RFChainReportV1 self-hashes RFC 8785 JSON excluding report_sha256. RFStateEnvelopeV1, encode_state, restore_state, and snapshot_state are the corresponding strict serialization helpers. State profiles and chain hashes must match the object that consumes them.

Each RFStageReportV1 records finite input/output power in W, gain in dB, added noise power in W, clipping count, optional converter width, and the post-stage state hash. RFChainReportV1 requires stages in unique enum order, reconciled adjacent powers within 1e-6 relative tolerance, paired endpoint powers, and ordered unique warnings. RFChainResultV1 bundles that report with output IQ and next state.

Scope and validation boundary¶

The PA is a P1dB-bound Rapp AM/AM proxy with an equal-weight causal drive average. It is not a coefficient-identified memory polynomial and makes no calibrated AM/PM, EVM, or spectral-regrowth claim without measured assets. Phase noise is a finite SciPy firwin2 spectral approximation. LNA evidence covers the one-stage added-noise term, not source-temperature or a receiver noise cascade. See Calibrated stateful RF validation for equations, experiments, thresholds, and the tested operating envelope.