How nvlabs/sionna works
1. Repository boundary
- This repo is the main Sionna 2.0 distribution, centered on Python packages for communication-system research.
- It contains two in-repo software layers, Sionna PHY and Sionna SYS, plus a separate Sionna RT ray-tracing package brought in as a submodule under ext/sionna-rt.
2. Top-level package structure
- The import root is src/sionna/.
- sionna.phy implements link-level signal processing and channel simulation.
- sionna.sys implements system-level simulation using physical-layer abstraction.
- sionna.rt is present as an integration point, but its code lives outside the main package tree.
3. Core architectural pattern in PHY
- PHY is organized as reusable processing blocks around a common base abstraction (phy/block.py, phy/object.py, phy/config.py).
- The main data path is: bits/labels → coding → mapping/modulation → MIMO/OFDM processing → channel → equalization/detection → decoded bits/metrics.
- Most modules are functional building blocks that can be composed into end-to-end transceiver graphs.
4. Channel simulation subsystem
- phy/channel/ is a major boundary and contains multiple channel families:
- abstract and utility layers (channel_model.py, discrete_channel.py, channel_utils)
- additive and fading models (awgn.py, flat_fading_channel.py, rayleigh_block_fading.py)
- time/frequency-domain OFDM channel generation and application
- optical channels (channel/optical)
- 3GPP TR 38.901 propagation models (channel/tr38901)
- This subsystem is data-heavy: it consumes transmitter waveforms or resource grids and outputs received samples, channel coefficients, or CIR-like representations.
5. 3GPP and realistic propagation assets
- The phy/channel/tr38901/models/*.json files encode standardized scenario parameters and are part of the simulation model, not just documentation.
- cir_dataset.py and related utilities support loading precomputed channels/datasets, which is another architectural input path distinct from on-the-fly channel synthesis.
6. FEC and coding stack
- phy/fec/ is a second major subsystem with layered coding components:
- generic coding utilities (coding.py, crc.py, interleaving.py, scrambling.py)
- convolutional, linear, LDPC, polar, and turbo code implementations
- code-specific parameter files under codes/
- The coding stack is designed as modular encoders/decoders that can be attached to different transceiver flows, especially PHY and NR.
7. Mapping, MIMO, and OFDM processing
- phy/mapping.py, phy/mimo/, and phy/ofdm/ form the modulation and spatial-processing middle layer.
- OFDM handles resource grids, pilot patterns, modulation/demodulation, channel estimation, equalization, and detection.
- MIMO handles stream management, precoding, equalization, and detection across spatial layers and antennas.
- These modules sit between coding and channel models and define the main waveform-level simulation boundary.
8. Signal processing utilities
- phy/signal/ contains lower-level DSP primitives such as filtering, up/downsampling, and windows.
- phy/utils/ provides shared numeric, linear algebra, metrics, random, tensor, and plotting helpers used across PHY.
- These are infrastructure dependencies for the higher-level communication blocks rather than standalone subsystems.
9. 5G NR transmitter/receiver stack
- phy/nr/ is a specialized application layer on top of PHY.
- It includes carrier, transport block, layer mapping, PUSCH configuration, DMRS/pilot generation, precoding, channel estimation, and full transmitter/receiver orchestration.
- This layer ties together coding, mapping, OFDM, and channel pieces into a standardized NR PUSCH pipeline.
10. System-level simulation layer
- sys/ is architecturally different from PHY: it operates on abstract link performance rather than full waveforms.
- Main concerns are topology.py, scheduling.py, power_control.py, link_adaptation.py, phy_abstraction.py, and effective_sinr.py.
- It uses lookup tables and abstraction parameters (bler_tables/, esm_params/) to convert physical conditions into packet-level outcomes such as throughput or BLER.
11. How SYS and PHY relate
- PHY provides detailed signal-level truth models.
- SYS consumes those results or abstractions of them to simulate larger networks more efficiently.
- In an architecture diagram, SYS should be shown as a higher-level consumer of PHY-derived metrics, not as a direct waveform-processing stack.
12. External runtime and technology boundaries
- The core packages require Python 3.11+ and PyTorch 2.9+; this strongly shapes the implementation style and GPU/CPU execution model.
- Sionna RT depends on Mitsuba 3 and Dr.Jit, with LLVM needed for CPU execution, so it is a distinct runtime boundary from the PyTorch-based PHY/SYS code.
13. Non-runtime repository content
- doc/ contains Sphinx documentation and API reference generation.
- tutorials/ contains executable notebooks demonstrating complete workflows across PHY, SYS, and RT.
- test/ contains unit tests plus extensive reference assets (.npy, .npz, .csv, .json) that validate numerical behavior and standardized models.
14. What to draw as the main architecture
- The clearest top-level diagram is: RT / environment generation → PHY link simulation → SYS abstraction/network simulation, with shared utility and model-data assets underneath.
- Within PHY, the key pipeline is source bits → FEC → mapping/MIMO/OFDM → channel → receiver → decoded bits/metrics.
- Around that, show separate supporting domains for 3GPP channel models, optical channels, NR PUSCH, and system-level control logic.
Main entry points: phy PHY · sys SYS · channel Channels · nr NR stack
Components 22
Core Packages
Main in-repo Python architecture: PHY, SYS, and RT integration.
PHY Stack
Waveform-level communication simulation components.
- PHY · Physical-layer signal processing and channel simulation.
src/sionna/phy - Base blocks · Common block/object/config foundation for composable PHY components.
src/sionna/phy/block.py - FEC stack · Modular encoders/decoders and coding utilities.
src/sionna/phy/fec - Mapping · Constellation mapping and demapping between bits and symbols.
src/sionna/phy/mapping.py - MIMO/OFDM · Spatial processing, resource grids, pilots, equalization, and detection.
src/sionna/phy/ofdm - Channels · AWGN, fading, OFDM/time-domain, optical, and dataset-backed channels.
src/sionna/phy/channel - 3GPP 38.901 · Standardized wireless channel scenarios and coefficients.
src/sionna/phy/channel/tr38901 - Optical · Optical propagation and amplification models.
src/sionna/phy/channel/optical - NR stack · 5G NR transmitter/receiver orchestration on top of PHY.
src/sionna/phy/nr - Signal DSP · Filtering, up/downsampling, and window functions.
src/sionna/phy/signal - PHY utils · Shared tensor, linear algebra, metrics, random, and plotting utilities.
src/sionna/phy/utils
SYS Stack
Network-level abstraction and control components.
- SYS · System-level simulation using physical-layer abstractions.
src/sionna/sys - Topology · Network layout and link geometry.
src/sionna/sys/topology.py - Control · Scheduling, power control, and link adaptation.
src/sionna/sys/scheduling.py - Abstraction · Effective SINR and PHY abstraction to packet-level outcomes.
src/sionna/sys/phy_abstraction.py
Models & Tables
Reusable scenario data, code parameters, and lookup assets.
- BLER tables · BLER and ESM parameter tables used by system abstraction.
src/sionna/sys/bler_tables
Connections 32
- sionna → PHY: contains · Main package exposes PHY as a primary subsystem.
- sionna → SYS: contains · Main package exposes SYS as a primary subsystem.
- sionna → Sionna RT: integrates · Import root includes an RT integration point.
- Sionna RT → RT code: submodule · Ray-tracing implementation lives in the external submodule.
- PHY → Base blocks: built on · PHY components share a common block/object/config base.
- PHY → FEC stack: uses · Bit-level payloads are encoded and decoded through FEC.
- PHY → Mapping: uses · Coded bits are mapped to and from symbols.
- PHY → MIMO/OFDM: uses · Waveform processing sits between mapping and the channel.
- PHY → Channels: uses · PHY injects signals into channel models and receives observations.
- Channels → 3GPP 38.901: includes · 3GPP scenarios are a major wireless channel family.
- Channels → Optical: includes · Optical propagation is modeled as a separate channel family.
- Channels → Signal DSP: depends on · Channel applications and generators rely on DSP primitives.
- Channels → PHY utils: depends on · Channel implementations share common numerical utilities.
- NR stack → FEC stack: orchestrates · NR transmitter/receiver uses the coding stack.
- NR stack → Mapping: orchestrates · NR layer mapping and symbol placement build on mapping.
- NR stack → MIMO/OFDM: orchestrates · NR PUSCH flows through MIMO and OFDM processing.
- NR stack → Channels: targets · NR pipelines are evaluated over PHY channels.
- SYS → Topology: contains · SYS begins with network topology and link geometry.
- SYS → Control: contains · Scheduling, power, and adaptation coordinate system behavior.
- SYS → Abstraction: contains · PHY abstraction converts link behavior into system metrics.
- Abstraction → BLER tables: reads · Abstraction relies on BLER and ESM lookup tables.
- SYS → PHY: consumes metrics from · SYS uses PHY-derived abstractions rather than waveform processing.
- Docs → PHY: documents · Documentation covers PHY APIs and tutorials.
- Docs → SYS: documents · Documentation covers SYS APIs and tutorials.
- Docs → Sionna RT: documents · Documentation also covers RT integration.
- Tutorials → PHY: demonstrates · Tutorials exercise link-level workflows.
- Tutorials → SYS: demonstrates · Tutorials exercise system-level workflows.
- Tutorials → Sionna RT: demonstrates · Tutorials include RT-based end-to-end examples.
- Tests → Channels: verifies · Tests cover channel model behavior and reference outputs.
- Tests → FEC stack: verifies · Tests validate coding algorithms and code assets.
- Tests → NR stack: verifies · Tests validate NR transmitter, receiver, and configs.
- Tests → SYS: verifies · Tests validate system abstraction and control logic.