Sionna stack

The framework’s preferred propagation backend is NVIDIA Sionna. This page describes Sionna’s full stack: what each module does, what it depends on, and how each piece maps onto the framework’s six layers. Read this when picking a backend, debugging propagation behavior, or planning Sionna upgrades.

What Sionna is

NVIDIA Sionna is an open-source wireless simulation library, Apache-2.0 licensed, with three modules. The framework consumes Sionna wherever it owns RF physics; rfgen owns the dataset orchestration around it.

Module	What it does	Backend dependency	Used by the framework
Sionna PHY	5G NR physical-layer primitives (LDPC, OFDM, channel coding) and statistical channel models (UMa, UMi, RMa, TDL, CDL from 3GPP TR 38.901)	PyTorch (CPU or GPU)	Yes (channels and NR emitters)
Sionna RT	Site-specific ray-traced propagation modeling on Mitsuba 3 + Dr.Jit	Mitsuba 3 (CUDA / OptiX or LLVM CPU)	Yes (channels)
Sionna SYS	System-level multi-cell, multi-user simulation (handover, scheduling, cross-cell interference)	PyTorch	No (out of scope)

pip install sionna pulls all three. The framework imports only the modules it uses and lazy-loads them so the dependency surface is exactly the modules in active use.

CPU support

All three Sionna modules run on CPU. Sionna PHY is PyTorch-backed and falls back to CPU when no GPU is available, just slower. Sionna RT runs on CPU through Dr.Jit’s LLVM backend; ray launching is several orders of magnitude slower than CUDA / OptiX, but functional. There is no separate “CPU-only” code path on either side; the same APIs work.

This means the framework does not need a parallel CPU-only fallback for any Sionna-backed feature. If a deployment lacks a GPU, the user gets slower behavior through the same backend and API, subject to the numeric determinism caveats documented in Reference / Determinism.

How Sionna maps to the framework’s layers

The framework has six swappable layers. Sionna replaces RF-domain implementation work in three of them: NR emitters, propagation channels, and ray-tracing scene geometry. It does not replace dataset composition, labels, annotations, or storage.

NVIDIA ownership boundary

Concern	Owner
5G NR PUSCH waveform physics	Sionna PHY
3GPP statistical propagation	Sionna PHY
Site-specific ray-traced propagation	Sionna RT
Antenna arrays and patterns consumed by Sionna channels	Sionna
Dataset scenario sampling	rfgen
Multi-emitter wideband composition	rfgen
Non-NR emitters and unverified NR signals	TorchSig / srsRAN / domain libraries behind rfgen wrappers, or unsupported until a mature backend is selected
Labels, annotations, storage, reproducibility metadata	rfgen

Channels (the primary mapping)

The channel layer is where the framework consumes Sionna most heavily. Sionna-backed implementations cover the propagation surface:

Sionna module	Framework class	Stage	What it provides
Sionna PHY	SionnaUMa	3	3GPP TR 38.901 Urban Macro scenario, including path loss and shadow fading
Sionna PHY	SionnaUMi	3	3GPP TR 38.901 Urban Micro / street-canyon scenario, including path loss and shadow fading
Sionna PHY	SionnaRMa	3	3GPP TR 38.901 Rural Macro scenario, including path loss and shadow fading
Sionna PHY	SionnaTDL	3	3GPP TR 38.901 TDL profiles A through E for profile-level studies
Sionna PHY	SionnaCDL	3	3GPP TR 38.901 CDL profiles A through E for profile-level MIMO studies
Sionna RT	SionnaRT	3	Site-specific ray-traced channel realizations from a Mitsuba 3 scene

The framework does not implement a core PathLoss backend. UMa / UMi / RMa large-scale attenuation and shadow fading come from Sionna PHY scenario classes. Site-specific attenuation comes from Sionna RT path gains. TDL / CDL remain available as lower-level profile wrappers, but they are not the default answer for complete deployment modeling.

TorchSigImpairments is a separate compatibility shim for reproducing RadioML / Sig53 benchmarks on existing TorchSig-trained baselines. It is not a propagation alternative; for any new study, use the Sionna stack.

See Concepts / Channels / Propagation for the full backend selection matrix and Reference / rfgen.channels for the proposed API surface.

Emitters (5G NR generators)

Sionna PHY’s sionna.phy.nr module is the framework’s preferred runtime backend for 5G NR emitters where Sionna exposes the needed transmitter block. The verified starting point is PUSCHTransmitter; users see an NRPUSCHEmitter wrapper rather than calling Sionna PHY directly.

Other NR signals are not assumed. PDSCH, SSB, PRACH, CSI-RS, and full downlink test models remain open until an implementation pass verifies upstream Sionna transmitter coverage or selects another mature backend.

LTE downlink does not come from Sionna (Sionna PHY is 5G NR only). The framework calls srsRAN_4G via ZMQ for that.

Scenes (geometry for ray tracing)

Sionna RT scenes are Mitsuba 3 XML files extended with radio-material plugin types. Sionna ships ten or more shipped scenes (Munich, San Francisco, Etoile, Florence, plus geometric test scenes). The framework consumes these directly; new scenes come from OSM ingestion via Blender, then export to Mitsuba XML.

The scene layer is the only place Mitsuba 3 surfaces. Mitsuba is a transitive dependency of Sionna RT; the framework does not depend on Mitsuba directly.

What Sionna does not provide

Four concerns the framework handles outside Sionna:

• TX hardware impairments (CFO, IQ imbalance, phase noise, PA nonlinearity, DAC quantization) live in the per-transformation ABCs of Group.TX (BaseDACQuantization, BasePANonlinearity, BaseTXPhaseNoise, BaseTXIQImbalance, BaseCFO). Sionna PHY ships a thin impairment library, but the framework needs SEI-grade hardware-fingerprinting impairments that are richer than what Sionna provides; see Concepts / Channels / TX impairments.

• Non-NR emitter families (LoRa, BLE, Wi-Fi, ADS-B, radar, drone controllers, LTE) are outside Sionna PHY’s NR-focused emitter surface. The framework uses TorchSig, srsRAN, and domain libraries behind the same emitter contract.

• Multi-emitter scene composition (density, time-frequency placement, SNR mix, multi-RX) lives in BaseSceneComposer. Sionna PHY targets single link-level studies; Sionna SYS targets cellular system-level work. Neither composes heterogeneous wideband scenes (Wi-Fi + BLE + ADS-B + LoRa + radar in one recording), so the framework’s composer is custom. See Concepts / Scenes / Composition § Why we don’t reuse TorchSig’s composer.

• Text annotations (inference-grounded captions, Q&A, reasoning chains) are entirely outside Sionna’s scope. They live in the annotation layer.

Versioning and upgrade path

Sionna releases on a roughly quarterly cadence. The framework pins to a specific Sionna version in requirements.txt and updates after a regression run. Major Sionna versions sometimes break API (e.g., the v0.x to v1.0 jump moved several modules); the framework absorbs those changes inside the wrapper classes (SionnaUMa, SionnaUMi, SionnaRMa, SionnaTDL, SionnaCDL, SionnaRT) so user configs do not need to change.

Sionna’s source is on GitHub at NVlabs/sionna; the framework’s wrapper classes cite specific source paths in their docstrings to make the upstream binding explicit.

See also

• Concepts / Channels / Propagation for the channel backend selection matrix.

• Concepts / Scenes / Geometry for Sionna RT scene format and shipped scenes.

• Concepts / Emitters / Library Landscape for Sionna PHY’s role in 5G NR generation.

• Background / Design Decisions for why Sionna is the preferred backend.

References

1. NVIDIA Sionna documentation. Top-level overview. https://nvlabs.github.io/sionna/

2. NVIDIA Sionna RT. Differentiable Ray Tracing for Radio Propagation. https://nvlabs.github.io/sionna/rt/

3. NVIDIA Sionna PHY. 5G NR PHY (sionna.phy.nr). https://nvlabs.github.io/sionna/api/nr.html

4. NVlabs / Sionna. Source repository. https://github.com/NVlabs/sionna

5. Mitsuba 3 documentation. Ray-tracing engine that Sionna RT consumes. https://mitsuba.readthedocs.io/