Scientific validation: TorchSig FSK emitter

Validated with documented limitations.

1. The component

TorchSigFSKEmitter is a PyTorch-fronted generator that produces clean baseband in-phase/quadrature (IQ) tensors for 16 continuous-phase frequency-shift keying (FSK: a family of digital modulations that encodes information by shifting the carrier between discrete frequency tones rather than discrete amplitude or phase points) class labels. The component wraps TorchSig’s fsk_modulator builder and exposes the 16 labels through the rfgen BaseEmitter interface.

class TorchSigFSKEmitter(BaseEmitter):
    family: ClassVar[EmitterFamily] = EmitterFamily.COMMS
    supported_classes: ClassVar[tuple[str, ...]] = (
        "2fsk",  "2gfsk",  "2msk",  "2gmsk",
        "4fsk",  "4gfsk",  "4msk",  "4gmsk",
        "8fsk",  "8gfsk",  "8msk",  "8gmsk",
        "16fsk", "16gfsk", "16msk", "16gmsk",
    )

    def __init__(self) -> None: ...

    def schema(self) -> type[BaseModel]: ...

    def generate(
        self,
        *,
        class_label: str,
        sample_rate: float,
        duration_s: float,
        f_offset_hz: float,
        rng: torch.Generator,
        device_id: str | None = None,
        params: BaseModel | None = None,
    ) -> Signal: ...


class TorchSigFSKParams(BaseModel):
    bandwidth_hz: float = Field(default=200_000.0, gt=0)

Parameter	Type	Units	Default	Purpose
class_label	str	n/a	required	One of 16 labels encoding <order><fsk_type>, e.g. "2fsk" or "4gmsk". The order is the number of discrete frequency tones; the fsk_type selects the pulse shape.
sample_rate	float	Hz	required	Samples per second on the output tensor.
duration_s	float	s	required	Output duration. Total sample count N = round(sample_rate * duration_s).
f_offset_hz	float	Hz	required	Baseband frequency shift applied after synthesis. May be negative or zero. Must satisfy bandwidth_hz + 2 * &#124;f_offset_hz&#124; < sample_rate.
rng	torch.Generator	n/a	required	Seeds the NumPy generator used internally. A given seed always produces the same IQ.
device_id	str or None	n/a	None	Optional label echoed into Signal.metadata. Never affects IQ.
params.bandwidth_hz	float	Hz	200_000.0	TorchSig resampler-target bandwidth. This is not the realized 3 dB occupied bandwidth; see §3.3.

Worked example.

import torch
from rfgen.emitters.torchsig_fsk import TorchSigFSKEmitter, TorchSigFSKParams

emitter = TorchSigFSKEmitter()
signal = emitter.generate(
    class_label="4gfsk",
    sample_rate=2_000_000.0,   # 2 MHz
    duration_s=0.05,            # 100 000 samples
    f_offset_hz=0.0,
    rng=torch.Generator().manual_seed(42),
    params=TorchSigFSKParams(bandwidth_hz=200_000.0),
)
print(signal.iq.shape)   # torch.Size([2, 100000])
print(signal.iq.dtype)   # torch.float32
print(signal.metadata.extras["realized_h"])    # e.g. 0.274
print(signal.metadata.extras["realized_bt"])   # e.g. 0.388 (Gaussian variants only)

Taxonomy. The 16 labels arise from the Cartesian product of constellation orders {2, 4, 8, 16} and pulse-shape families {fsk, gfsk, msk, gmsk}. MSK (Minimum Shift Keying: FSK with modulation index h = 0.5, the smallest h that yields orthogonal tones) and GMSK (Gaussian MSK: MSK with a Gaussian pre-filter applied to the symbol stream to limit spectral spreading) are widely deployed in cellular (GSM uses GMSK) and Bluetooth radios. GFSK (Gaussian FSK: FSK with a Gaussian filter on the symbols but h not fixed to 0.5) is the Bluetooth Basic Rate physical layer. The fsk variant is standard non-Gaussian FSK. All four are CPM (continuous-phase modulation: the phase trajectory is continuous across symbol boundaries, which gives them their constant-envelope property). The emitter sits at the modulation-order level: no protocol framing, no preamble, no payload, no burst envelope.

2. What we validated

This validation establishes 8 load-bearing claims. Each is restated and supported by evidence in §3.

1. Output shape, dtype, and metadata (§3.1): all 16 labels produce (2, N) float32 tensors with correct metadata fields.

2. DC balance (§3.2): the explicit DC subtraction brings the channel mean to the float32 noise floor.

3. Bandwidth knob scales PSD (§3.3): doubling bandwidth_hz doubles the empirical 3 dB bandwidth with ~15% tolerance.

4. Family bandwidth ordering (§3.4): at fixed bandwidth_hz, empirical 3 dB bandwidth follows fsk > msk > gfsk.

5. Constant-envelope (low PAPR) (§3.5): envelope coefficient of variation stays below 0.05 in the steady-state interior.

6. Phase continuity (§3.6): per-sample phase step stays below π/4 rad for all CPM variants.

7. Realized-parameter capture (§3.7): h, BT, and m are recorded in metadata without perturbing the IQ output.

8. Unit mean power (§3.8): mean(|cz|²) = 1 ± 1e-4 after the rfgen-layer normalization.

Limits and scope-bounded items appear in §4; full citations are in §5.

3. Evidence per claim

3.1 Output shape, dtype, and metadata

Claim. Every one of the 16 supported class labels generates without error, produces a tensor of shape (2, round(sample_rate * duration_s)) with dtype float32, and populates SignalMetadata with class_taxonomy = ("comms", "fsk", class_label), family = "comms", snr_db = +inf, and an extras map containing fsk_type, constellation_size, realized_h, and power_normalization_scale (plus realized_bt and realized_gaussian_half_span_m for Gaussian variants).

Test. tests/validation/emitters/torchsig_fsk/test_experiment_contract.py::test_shape_and_dtype[<label>] (16 parametrized cases), test_metadata_fields. Setting: sample_rate = 2 MHz, duration_s = 0.05, seed 42.

Result. All 16 labels pass. Shape is (2, 100_000), dtype is float32, all metadata fields present and correctly typed.

Unsupported labels. test_experiment_contract.py::test_unsupported_label_raises confirms that "32fsk" (order outside {2,4,8,16}) and "2bfsk" (unrecognized fsk_type suffix) both raise EmitterError.

3.2 DC balance

Claim. After the explicit DC subtraction at line 297 of torchsig_fsk.py, the channel mean satisfies |mean(channel)| < 1e-4 × peak(|cz|) for all 16 labels. This is approximately −80 dBc suppression relative to peak power.

Justification of tolerance. FSK is constant-envelope, so even without DC subtraction the residual would be small. The 1e-4 gate is tighter than the chance-only standard error at N = 100,000 (which is 0.28 / sqrt(100000) ≈ 9e-4). Passing therefore confirms the active subtraction is working, not sampling luck.

Test. test_experiment_contract.py::test_dc_balance[<label>] (16 parametrized cases). N = 100,000 per call.

Result. Residual ≈ 1e-8 across all 16 labels (float32 noise floor).

3.3 Bandwidth knob scales PSD

Claim. Doubling bandwidth_hz from B₀ to 2 × B₀ doubles the empirical −3 dB bandwidth within a 15% tolerance. The PSD shape (power spectral density: the distribution of signal energy across frequency, estimated here using Welch’s method) moves linearly with the bandwidth_hz knob.

Design. Welch PSD (the Welch method averages overlapping windowed FFT segments to reduce spectral variance) with nperseg = 4096, sample_rate = 2 MHz, duration_s = 0.2 (N = 400,000, ~194 averaged segments, frequency resolution ≈ 488 Hz). The −3 dB bandwidth is the width of the spectral region within 3 dB of the peak power. Tested for {2fsk, 4fsk} × {50, 100, 200} kHz.

Tolerance. 1.7 ≤ ratio ≤ 2.3 (15% margin around the expected factor of 2).

Test. test_experiment_psd_bandwidth.py::test_bandwidth_scaling[<label>-<B0>] (6 parametrized cases).

Result. Empirical doubling ratios 1.96–2.00 across all 6 cases, within tolerance.

Figure 1 shows the measured −3 dB bandwidth vs. bandwidth_hz for {2fsk, 4fsk} × {50, 100, 200} kHz.

Important note on bandwidth_hz semantics. The realized −3 dB occupied bandwidth is not equal to bandwidth_hz. The knob is the TorchSig polyphase resampler’s target rate; the actual 3 dB bandwidth depends on the randomized modulation index h and time-bandwidth product BT. Empirical realized ratios (3 dB BW / bandwidth_hz) at default settings: 2fsk ≈ 0.50, 2msk ≈ 0.27, 2gfsk ≈ 0.10. See §3.4 and §4.

3.4 Family bandwidth ordering

Claim. At fixed bandwidth_hz, the median empirical −3 dB bandwidth across 5 seeds satisfies BW(2fsk) > BW(2msk) > BW(2gfsk). This ordering follows the modulation-index hierarchy: standard FSK draws h ~ U(0.7, 1.01) or h = 1.0 (orthogonal), MSK fixes h = 0.5, and GFSK draws h ~ U(0.1, 0.5). Higher h means wider frequency deviation per symbol, hence wider occupied bandwidth.

Modulation index h is the ratio of the peak frequency deviation to the symbol rate; h = 0.5 (MSK) is the minimum value that keeps adjacent symbols orthogonal (non-overlapping in a correlation sense).

Test. test_experiment_psd_bandwidth.py::test_family_hierarchy. Also test_iter1_high_fixes.py::test_realized_3db_bw_ratio_per_class locks in the absolute ratios: 2fsk ≈ 0.50, 2msk ≈ 0.27, 2gfsk ≈ 0.10 of bandwidth_hz, within factor-of-2 tolerance.

Result. bw_fsk (103 kHz) > bw_msk (54 kHz) > bw_gfsk (20 kHz) at bandwidth_hz = 200 kHz. Ordering confirmed.

Figure 2 shows the Welch PSD for the four binary FSK family variants at fixed bandwidth_hz = 200 kHz, illustrating the class-dependent bandwidth ratios.

3.5 Constant-envelope property (low PAPR)

Claim. All 16 FSK class labels exhibit a near-constant envelope (standard deviation of |cz| below 5% of the mean) in the steady-state interior of the waveform. PAPR (peak-to-average power ratio: ratio of peak instantaneous power to mean power, expressed in dB; 0 dB means perfectly constant power) for binary CPM variants stays below 1.5 dB. This is the defining property of CPM modulations and distinguishes them from PSK/QAM, which have PAPR of 3–7 dB under SRRC (square-root raised-cosine: a widely used pulse-shaping filter that concentrates symbol energy while limiting inter-symbol interference) pulse shaping.

CV (coefficient of variation) is std(|cz|) / mean(|cz|), a unit-free measure of envelope fluctuation.

Test. test_empirical_known_results.py::test_constant_envelope_interior[<label>] asserts CV < 0.05 with 10% edge trim (6 labels); test_experiment_contract.py::test_approx_constant_envelope[<label>] asserts CV < 0.10 with 5% edge trim (all 16 labels). test_empirical_known_results.py::test_papr_below_psk_baseline asserts median PAPR < 1.5 dB for {2fsk, 2msk, 2gmsk, 4fsk} × 5 seeds.

Result. Median CV 0.01–0.05 across all 16 labels. Median PAPR 0.7 dB for the binary CPM subset. The 10% edge trim is necessary: for N < 1000, the polyphase resampler’s head/tail padding dominates and CV exceeds the 0.05 bound (see §4).

Figure 3 shows IQ scatter plots and envelope histograms for the four binary CPM variants, confirming the near-circular IQ trajectory and narrow |IQ| distribution.

Figure 4 shows PAPR distributions across all 16 FSK class labels.

3.6 Phase continuity

Claim. The per-sample phase step |dφ/sample| stays below π/4 rad for all CPM variants. Phase continuity is the defining property of CPM: the modulator accumulates phase via φ(t) = 2π h ∫ f(τ) dτ (Proakis & Salehi, Digital Communications, 5th ed., 2008, §4.3), so phase is a continuous function of time with no instantaneous jumps. TorchSig implements this via np.cumsum on the instantaneous-frequency array.

MSK reference. For MSK (h = 0.5), the per-symbol phase excursion is exactly ±π/2 = ±1.5708 rad. The test measures the standard deviation of per-symbol phase increments across seeds and asserts it lands in [0.8, 2.0] rad (tolerance accommodates pulse-shape smear and symbol-rate alignment slack). 3GPP TS 45.005 mandates h = 0.5 and continuous phase for GMSK in GSM.

Test. test_empirical_known_results.py::test_phase_continuity[<label>] (5 labels: 2fsk, 2gfsk, 2msk, 2gmsk, 8fsk). test_empirical_known_results.py::test_msk_modulation_index checks per-symbol phase std in [0.8, 2.0] rad.

Result. Max per-sample phase step 0.07–0.35 rad across tested labels, well below the π/4 = 0.785 bound. Per-symbol phase std 1.0–1.4 rad for 2msk (consistent with theoretical π/2 = 1.5708 rad).

Figure 5 shows the unwrapped phase trajectory and instantaneous frequency for the four binary CPM variants.

3.7 Realized-parameter capture does not perturb IQ

Claim. The wrapper replicates TorchSig’s internal RNG draw sequence for h, BT, and m on a copy.deepcopy of the NumPy generator, captures the realized values, then passes the un-advanced original generator to TorchSig. The IQ output is byte-identical to what TorchSig would produce without the capture step. Realized values are stored in metadata.extras: realized_h for all variants; additionally realized_bt and realized_gaussian_half_span_m for Gaussian variants (gfsk, gmsk); absent for fsk and msk.

Reference values. TorchSig’s get_fsk_mod_index (TorchSig 2.1.1, torchsig/signals/builders/fsk.py) draws: for fsk, h = 1.0 with probability 0.5 or h ~ U(0.7, 1.01) otherwise; for msk and gmsk, h = 0.5 exactly; for gfsk, h ~ U(0.1, 0.5). For Gaussian variants, BT ~ U(0.1, 0.5) and m ~ randint(1, 5).

Tests. test_iter1_high_fixes.py::test_capture_does_not_perturb_iq asserts np.array_equal between two independent calls with the same seed. test_iter1_high_fixes.py::test_realized_h_recorded_for_fsk[<label>] checks fsk-type labels. test_realized_h_msk_is_half[<label>] checks MSK/GMSK labels. test_realized_h_gfsk_in_bluetooth_range_support[<label>] checks GFSK range. test_realized_bt_and_m_for_gaussian_variants[<label>] checks BT and m ranges. test_bt_absent_for_non_gaussian_variants[<label>] checks absence.

Result. All 16 labels pass. Captured values match expected distributions. IQ is bit-identical with and without the capture step.

3.8 Unit mean power

Claim. After DC subtraction, the rfgen layer applies iq ← iq / sqrt(mean(|cz|²)) so that mean(|cz|²) = 1 to within 1e-4. TorchSig’s fsk_modulator outputs amplitude scaled by 1 / resample_rate_ideal (constant-envelope amplitude ≈ 0.4 at default settings, mean power ≈ 0.16), which is a library convention. The rfgen normalization gives downstream channel layers a known reference power level. The applied scale factor is recorded in metadata.extras["power_normalization_scale"].

Test. test_iter1_high_fixes.py::test_unit_mean_power[<label>] (16 parametrized cases) asserts |mean(|cz|²) - 1| < 1e-4. test_power_normalization_scale_recorded[<label>] confirms the scale factor is present, finite, positive, and in the expected range (1.0, 6.0).

Result. |mean(|cz|²) - 1| ≈ 1e-7 (float32 noise floor) for all 16 labels. Typical scale factor ≈ 2.5 (consistent with 1 / sqrt(0.16) ≈ 2.5).

4. Limits and what’s not validated

Resampler-padding regime (N < ~1000). The polyphase resampler in TorchSig pads the head and tail of short records. Below N ≈ 1000 these padding regions dominate the envelope, and the CV bound of 0.05 no longer holds. test_robustness_envelope.py::test_r2_small_n_envelope_cv_degrades documents the fall-off: CV ≈ 0.32 at N = 64, declining to < 0.10 at N = 100,000. The 10% edge trim applied in the steady-state tests excludes this regime.

Higher-order labels not in CPM-specific tests. Phase-continuity and PAPR tests cover binary CPM variants and selected higher-order cases. The 8gfsk, 8gmsk, 16gfsk, 16gmsk, and similar labels are not separately probed for phase-continuity: the property follows from TorchSig’s np.cumsum construction regardless of order, but it is not directly asserted for every label.

bandwidth_hz is not the realized 3 dB occupied bandwidth. The knob is the TorchSig resampler target. Empirical realized ratios (3 dB BW / bandwidth_hz) at default settings: 2fsk ≈ 0.50, 2msk ≈ 0.27, 2gfsk ≈ 0.10. A downstream config builder that interprets bandwidth_hz as occupied bandwidth will be miscalibrated. The locked-in regression in test_iter1_high_fixes.py::test_realized_3db_bw_ratio_per_class asserts these ratios within factor-of-2.

No OTA (over-the-air) capture comparison. The 16 class labels are protocol-agnostic (no preamble, payload, or burst envelope). A comparison against a Bluetooth or GSM capture would conflate the modulation construct with the protocol framing. Standards-derived parametric reference values are the appropriate benchmark for this level.

TorchSig GFSK modulation index is wider than Bluetooth BR. TorchSig draws h ~ U(0.1, 0.5) for GFSK; the Bluetooth Basic Rate specification (Bluetooth Core Specification v5.3, Vol 6 Part A) requires h ∈ [0.28, 0.35]. The TorchSig support is wider. A downstream consumer that requires Bluetooth-spec conformance should filter by the recorded metadata.extras["realized_h"] field.

No closed-form test of Gaussian pulse coefficients. The gaussian_taps function inside TorchSig is exercised only indirectly through phase-continuity and bandwidth tests. No direct numerical comparison of filter coefficients against the exp(-2π²BT²t²/ln2) formula (Proakis & Salehi §9.2.5) is included.

5. References

Published works

Item	Full citation
Continuous-phase FSK theory	Proakis, J.G. and Salehi, M. Digital Communications, 5th edition. McGraw-Hill (2008). ISBN 978-0072957167. §4.3 (CPM definition and phase integral), §9.2.5 (Gaussian pulse filter).
GMSK / GSM specification	3GPP TS 45.005, “GSM/EDGE Radio transmission and reception,” Release 17 (2022). §4.6 specifies GMSK with h = 0.5 and BT = 0.3.
Bluetooth GFSK specification	Bluetooth Core Specification v5.3, Vol 6 Part A “Radio Specification.” Bluetooth SIG (2021). Specifies Basic Rate GFSK modulation index h ∈ [0.28, 0.35].
TorchSig paper	Boegner, A. et al. “Large Scale Radio Frequency Signal Classification.” arXiv:2207.09918 (2022). Describes TorchSig’s signal taxonomy and FSK builder design.
RadioML 2018.01a benchmark	O’Shea, T.J., Roy, T., Clancy, T.C. “Over the Air Deep Learning Based Radio Signal Classification.” IEEE Journal of Selected Topics in Signal Processing, vol. 12, no. 1, pp. 168–179 (2018). DOI: 10.1109/JSTSP.2018.2797022. FSK subset used as context for the modulation taxonomy.

Libraries

PyPI dist	Installed version	Docs URL	Role in this validation
torchsig	2.1.1	https://github.com/TorchDSP/torchsig	FSK signal synthesis (fsk_modulator, fsk_modulator_baseband); all RF math delegated to this library
torch	2.12.1	https://pytorch.org/docs/stable/	torch.Generator seeding; IQ tensor output type
numpy	2.4.6	https://numpy.org/doc/stable/	Complex arithmetic, phase unwrapping, DC subtraction, power normalization
scipy	1.18.0	https://docs.scipy.org/doc/scipy/	scipy.signal.welch Welch PSD estimator used in bandwidth validation tests
matplotlib	3.11.0	https://matplotlib.org/stable/	Figure generation in generate_figures.py