Transmit (TX) Impairments

Note

Layer 3 shipped, Pass-1. The Layer 3 implementation (emitters, device-fingerprint, tx-impairments, propagation, rx-frontend) landed on branch rfgen-impl-2026-06-25-105955 (PR #94). The class names, Pydantic schemas, and Transformation enum members referenced below match the shipped surface; Pass-1 stubs (GNU Radio OOT emitters, cellular emitters, Sionna propagation backends) construct cleanly and raise an EmitterError or ChannelError tagged with stage="pass1_stub" until backend wiring lands. See Reference / rfgen.emitters and Reference / rfgen.channels for the shipped class roster.

Scientific validation

The TX impairment models have been scientifically validated against published references. See the per-component reports:

• TX power-amplifier nonlinearity (Rapp, Saleh): validated with documented limitations.

• TX phase noise (Leeson): validated with documented limitations.

• TX IQ imbalance, DAC quantization, CFO: validated.

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.

Transmit (TX) impairments are Group 1 of the four-group channel pipeline. They apply transmitter-side hardware effects to each emitter component before propagation. They run at the emitter’s native sample rate, R_emitter, and operate on clean baseband in-phase/quadrature (IQ) samples from the emitter plugin. The output is degraded baseband IQ that carries the physical signature of the transmit chain.

Overview

The five transformations model a simple transmitter chain. The digital-to-analog converter (DAC) turns digital samples into finite hardware levels. The power amplifier (PA) can compress large amplitudes near saturation. The local oscillator contributes phase noise and carrier frequency offset. The quadrature mixer can make the I and Q paths slightly different in gain or phase.

The table covers T1 through T5 in Group.TX. Each ABC is the pluggable interface for one transmitter effect; the transformation enum records that effect’s position in the ordered ChannelPipeline.

Name	Transformation	ABC	Default backend
DAC quantization	DAC_QUANTIZATION	BaseDACQuantization	Uniform mid-tread quantizer that rounds sample amplitudes to the nearest allowed hardware level
PA nonlinearity	PA_NONLINEARITY	BasePANonlinearity	Rapp model for soft compression near saturation; Saleh model optional
TX phase noise	TX_PHASE_NOISE	BaseTXPhaseNoise	Leeson oscillator noise model
TX IQ imbalance	TX_IQ_IMBALANCE	BaseTXIQImbalance	Gain and phase mismatch between I and Q paths
Carrier frequency offset (CFO)	CFO	BaseCFO	Constant deterministic offset in hertz

rfgen treats transmitter hardware effects as channel-pipeline transformations. All five are BaseChannel subclasses and compose with ChannelPipeline.

Sample Rate and Carrier Frame

TX impairments operate at R_emitter throughout. No resampling occurs in this group.

Baseband IQ means the complex samples are centered at 0 Hz, also called direct current (DC) in this representation. The emitter does not shift samples to realized_carrier_hz in the sample domain. That absolute carrier frequency lives in metadata, is passed to Sionna during Group 2 propagation, and is later used by the receiver (RX) mixer in RX capture.

Default Implementations

DAC quantization

Models finite word length in the transmit DAC. A uniform mid-tread quantizer clamps the IQ samples to [-1, 1] and rounds to 2^bits levels. Higher bit depths preserve smaller amplitude differences; fewer bits create stronger quantization error. Typical values are 12 to 16 bits for commercial off-the-shelf (COTS) software-defined radios (SDRs), and 6 to 8 bits for constrained hardware studies.

Source: IEEE Std 1241-2010 defines converter terminology and nominally uniform quantization framing; Analog Devices’ MT-001 tutorial derives ideal N-bit quantization-noise behavior, and Reference / Fingerprint parameter priors records the cited bit-depth ranges.

PA nonlinearity

Models compression near the amplifier’s saturation point. AM/AM means amplitude-to-amplitude distortion, where output amplitude stops growing linearly with input amplitude. AM/PM means amplitude-to-phase distortion, where large amplitudes also rotate the signal phase. Two models are supported:

• Rapp: soft-limiter envelope model with knee smoothness parameter p. Suitable for general PA compression studies.

• Saleh: polynomial AM/AM and AM/PM model with four parameters. More accurate for traveling-wave tube amplifiers.

The Rapp model is the default. Output back-off (OBO) and input back-off (IBO) can be set directly on the config.

Source: Rapp’s HPA nonlinearity paper records the soft-limiter model for OFDM/DPSK transmitter studies (NASA ADS record); Saleh’s IEEE paper defines the TWT amplifier AM/AM and AM/PM model (DOI 10.1109/TCOM.1981.1094911). See Reference / Fingerprint math for the proposed rfgen equations.

TX phase noise

Models random phase fluctuations from the local oscillator using a Leeson-style phase-noise profile. The profile defines the single-sideband phase-noise power spectral density (SSB PSD), a curve of oscillator noise power versus offset frequency from the carrier, in dBc/Hz. Phase noise is applied as a multiplicative complex exponential.

Source: Leeson’s oscillator phase-noise model grounds the PSD profile (DOI 10.1109/PROC.1966.4682); see Reference / RF frontend models for the shared RX/TX equation.

TX IQ imbalance

Models the gain and phase mismatch between the in-phase and quadrature paths of the transmit mixer. The effect is parameterized by gain_imbalance_db and phase_imbalance_deg. The IQ imbalance matrix is:

\[ y = \frac{1}{2}\bigl[(1+\alpha)x + (1-\alpha)e^{j\phi}\bar{x}\bigr] \]

where \(\alpha\) is the amplitude imbalance ratio and \(\phi\) is the phase imbalance in radians.

Source: Razavi, RF Microelectronics, 2nd ed., Pearson, 2011, ISBN 978-0137134731, covers quadrature mixer mismatch; MathWorks’ iqimbal documents the gain/phase imbalance equation used as a validation oracle, and Analog Devices’ AN-2557 ties gain and phase mismatch to image rejection.

CFO

Models a deterministic constant carrier frequency offset. The caller supplies f_offset_hz directly, and the transform applies that fixed offset as a linear phase ramp across the sample axis:

\[ y[n] = x[n] \cdot e^{j 2\pi (f_\text{cfo} / R_\text{emitter}) n} \]

The contract is fixed-in-hertz for the full emitter component, matching LinearCFO(f_offset_hz=...) in the shipped examples and API. Workflows that start from oscillator tolerances in parts per million must convert those offsets to hertz before constructing LinearCFO(f_offset_hz=...).

Source: Razavi, RF Microelectronics, 2nd ed., Pearson, 2011, ISBN 978-0137134731, covers oscillator drift in RF transceivers; GNU Radio’s carrier frequency offset model documents the same mixer local-oscillator drift abstraction. See Reference / Fingerprint math for the rfgen phase-ramp equation.

Plugin Slots

Each transformation is a plugin slot. Swap any of the five ABCs to customize the impairment model:

from rfgen.channel_pipeline import ChannelPipeline
from rfgen.tx_impairments import (
    LeesonTXPhaseNoise,
    LinearCFO,
    LinearDACQuantizer,
    RappPA,
    TorchSigTXIQImbalance,
)

tx_chain = ChannelPipeline([
    LinearDACQuantizer(enob_bits=12),
    RappPA(),                    # Rapp default
    LeesonTXPhaseNoise(),        # Leeson default
    TorchSigTXIQImbalance(amplitude_imbalance_db=0.5, phase_imbalance_rad=0.05),
    LinearCFO(f_offset_hz=250.0),
])

To disable a specific impairment for an ablation study, omit it from the list or replace it with an identity pass-through. Ordering validation still applies to the remaining entries: the constructor accepts sparse TX chains, but whatever you keep must stay in canonical T1 through T5 order. There is no strict=False escape hatch on the shipped ChannelPipeline API:

tx_chain = ChannelPipeline([
    LeesonTXPhaseNoise(),
    LinearCFO(f_offset_hz=250.0),
])

Minimal Example

This pipeline runs separately on each emitter component before receiver-side summing. An emitter component is one emitter’s generated IQ plus its metadata; the scene composer applies the same pre-sum chain once per component.

from rfgen.channel_pipeline import ChannelPipeline
from rfgen.propagation import SionnaUMi
from rfgen.tx_impairments import (
    LeesonTXPhaseNoise,
    LinearCFO,
    LinearDACQuantizer,
    RappPA,
    TorchSigTXIQImbalance,
)

# Group 1 TX impairments applied per emitter, followed by Group 2 propagation.
pre_sum = ChannelPipeline([
    LinearDACQuantizer(enob_bits=14),
    RappPA(),
    LeesonTXPhaseNoise(),
    TorchSigTXIQImbalance(),
    LinearCFO(f_offset_hz=250.0),
    # Sionna Urban Micro (UMi) propagation. The backend reads carrier and
    # topology from scene config and ChannelContext; individual emitters
    # still carry realized carrier metadata for per-emitter offsets.
    SionnaUMi(),
])

The ChannelPipeline above covers TX impairments and channel propagation. See Channels overview for the full pipeline including RX capture and RX hardware.

See Also

• Channels overview: semantic channel groups and transformation table.

• Channel propagation: propagation slot that follows TX impairments.

• Reference / rfgen.channels: full ABC contracts and parameter surfaces.

• Reference / Fingerprint math: full derivations and per-device parameter ranges for TX impairments.

• Reference / RF frontend models: IQ imbalance, phase-noise, and quantization equations shared with RX hardware.

• Background / Sionna stack: Sionna handles propagation; TX impairments are analytic.

• Background / Design Decisions § Channel pipeline for the rationale behind splitting TX into five explicit transformations rather than one coarse TX-hardware stage.

References

The five TX transformations follow standard transmitter impairment models. The math is collected in Reference / Fingerprint math; the citations below are the primary sources.

1. Rapp, C. Effects of HPA-Nonlinearity on a 4-DPSK/OFDM-Signal for a Digital Sound Broadcasting System, Proc. 2nd European Conf. on Satellite Communications, 1991. https://ui.adsabs.harvard.edu/abs/1991ESASP.332..179R/abstract (Rapp model)

2. Saleh, A. A. M. Frequency-Independent and Frequency-Dependent Nonlinear Models of TWT Amplifiers, IEEE Trans. Comm., 1981. https://doi.org/10.1109/TCOM.1981.1094911 (Saleh model)

3. Leeson, D. B. A Simple Model of Feedback Oscillator Noise Spectrum, Proc. IEEE, 1966. https://doi.org/10.1109/PROC.1966.4682 (phase-noise PSD)

4. IEEE Std 1241-2010 IEEE Standard for Terminology and Test Methods for Analog-to-Digital Converters. https://ieeexplore.ieee.org/document/5692956 (quantization, ENOB framing)

5. Kester, W. MT-001: Taking the Mystery out of the Infamous Formula, “SNR = 6.02N + 1.76 dB,” and Why You Should Care, Analog Devices. https://www.analog.com/media/en/training-seminars/tutorials/MT-001.pdf (ideal N-bit quantization noise)

6. Razavi, B. RF Microelectronics, 2nd ed., Pearson, 2011, ISBN 978-0137134731. (IQ imbalance, oscillator drift / CFO)

7. MathWorks. iqimbal. https://www.mathworks.com/help/comm/ref/iqimbal.html (I/Q gain and phase imbalance equation)

8. Analog Devices. Quadrature Error Correction for Wideband Zero-IF Signals, AN-2557. https://www.analog.com/en/resources/app-notes/an-2557.html (gain/phase mismatch and image rejection)

9. GNU Radio. gnuradio.channels carrier frequency offset model. https://www.gnuradio.org/doc/sphinx-v3.7.13.4/channels_blocks.html (local-oscillator drift abstraction)

10. Sankhe, K. et al. ORACLE: Optimized Radio classifier for Attacking cellular networks, INFOCOM 2019, arXiv:1812.01124. (per-device fingerprint-chain ordering)