# nvlabs/sionna architecture

> Architecture diagram of the GitHub repository nvlabs/sionna, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvlabs/sionna
- Repository: https://github.com/nvlabs/sionna

## Overview

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: [`src/sionna/phy`](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy) (PHY), [`src/sionna/sys`](https://github.com/nvlabs/sionna/tree/main/src/sionna/sys) (SYS), [`src/sionna/phy/channel`](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/channel) (Channels), [`src/sionna/phy/nr`](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/nr) (NR stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Packages"]
  node_src_sionna["sionna<br/>import root"]
  node_rt_ext["Sionna RT<br/>ray tracing submodule"]
  node_ext_rt["RT code<br/>external package"]
end

subgraph group_phy["PHY Stack"]
  node_sionna_phy["PHY<br/>link-level sim"]
  node_phy_base["Base blocks<br/>abstractions<br/>[block.py]"]
  node_phy_coding["FEC stack<br/>coding"]
  node_phy_mapping["Mapping<br/>modulation<br/>[mapping.py]"]
  node_phy_mimo_ofdm["MIMO/OFDM<br/>waveform processing"]
  node_phy_channel["Channels<br/>channel models"]
  node_phy_tr38901["3GPP 38.901<br/>propagation models"]
  node_phy_optical["Optical<br/>fiber channel"]
  node_phy_nr["NR stack<br/>5G PUSCH"]
  node_phy_signal["Signal DSP<br/>dsp primitives"]
  node_phy_utils["PHY utils<br/>numerics/helpers"]
end

subgraph group_sys["SYS Stack"]
  node_sionna_sys["SYS<br/>network-level sim"]
  node_sys_topology["Topology<br/>network model<br/>[topology.py]"]
  node_sys_control["Control<br/>adaptation<br/>[scheduling.py]"]
  node_sys_abstraction["Abstraction<br/>phy→sys bridge<br/>[phy_abstraction.py]"]
end

subgraph group_assets["Models & Tables"]
  node_sys_tables[("BLER tables<br/>lookup assets")]
end

subgraph group_support["Support"]
  node_doc["Docs"]
  node_tutorials["Tutorials<br/>notebooks"]
  node_tests["Tests<br/>verification assets"]
end

node_src_sionna -->|"contains"| node_sionna_phy
node_src_sionna -->|"contains"| node_sionna_sys
node_src_sionna -->|"integrates"| node_rt_ext
node_rt_ext -.->|"submodule"| node_ext_rt
node_sionna_phy -->|"built on"| node_phy_base
node_sionna_phy -->|"uses"| node_phy_coding
node_sionna_phy -->|"uses"| node_phy_mapping
node_sionna_phy -->|"uses"| node_phy_mimo_ofdm
node_sionna_phy -->|"uses"| node_phy_channel
node_phy_channel -->|"includes"| node_phy_tr38901
node_phy_channel -->|"includes"| node_phy_optical
node_phy_channel -.->|"depends on"| node_phy_signal
node_phy_channel -.->|"depends on"| node_phy_utils
node_phy_nr -->|"orchestrates"| node_phy_coding
node_phy_nr -->|"orchestrates"| node_phy_mapping
node_phy_nr -->|"orchestrates"| node_phy_mimo_ofdm
node_phy_nr -->|"targets"| node_phy_channel
node_sionna_sys -->|"contains"| node_sys_topology
node_sionna_sys -->|"contains"| node_sys_control
node_sionna_sys -->|"contains"| node_sys_abstraction
node_sys_abstraction -->|"reads"| node_sys_tables
node_sionna_sys -.->|"consumes metrics from"| node_sionna_phy
node_doc -.->|"documents"| node_sionna_phy
node_doc -.->|"documents"| node_sionna_sys
node_doc -.->|"documents"| node_rt_ext
node_tutorials -.->|"demonstrates"| node_sionna_phy
node_tutorials -.->|"demonstrates"| node_sionna_sys
node_tutorials -.->|"demonstrates"| node_rt_ext
node_tests -.->|"verifies"| node_phy_channel
node_tests -.->|"verifies"| node_phy_coding
node_tests -.->|"verifies"| node_phy_nr
node_tests -.->|"verifies"| node_sionna_sys

click node_src_sionna "https://github.com/nvlabs/sionna/tree/main/src/sionna"
click node_sionna_phy "https://github.com/nvlabs/sionna/tree/main/src/sionna/phy"
click node_phy_base "https://github.com/nvlabs/sionna/blob/main/src/sionna/phy/block.py"
click node_phy_coding "https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/fec"
click node_phy_mapping "https://github.com/nvlabs/sionna/blob/main/src/sionna/phy/mapping.py"
click node_phy_mimo_ofdm "https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/ofdm"
click node_phy_channel "https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/channel"
click node_phy_tr38901 "https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/channel/tr38901"
click node_phy_optical "https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/channel/optical"
click node_phy_nr "https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/nr"
click node_phy_signal "https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/signal"
click node_phy_utils "https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/utils"
click node_sionna_sys "https://github.com/nvlabs/sionna/tree/main/src/sionna/sys"
click node_sys_topology "https://github.com/nvlabs/sionna/blob/main/src/sionna/sys/topology.py"
click node_sys_control "https://github.com/nvlabs/sionna/blob/main/src/sionna/sys/scheduling.py"
click node_sys_abstraction "https://github.com/nvlabs/sionna/blob/main/src/sionna/sys/phy_abstraction.py"
click node_sys_tables "https://github.com/nvlabs/sionna/tree/main/src/sionna/sys/bler_tables"
click node_rt_ext "https://github.com/nvlabs/sionna/tree/main/src/sionna/rt"
click node_ext_rt "https://github.com/nvlabs/sionna/tree/main/ext/sionna-rt"
click node_doc "https://github.com/nvlabs/sionna/tree/main/doc"
click node_tutorials "https://github.com/nvlabs/sionna/tree/main/tutorials"
click node_tests "https://github.com/nvlabs/sionna/tree/main/test"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_sionna,node_rt_ext,node_ext_rt toneBlue
class node_sionna_phy,node_phy_base,node_phy_coding,node_phy_mapping,node_phy_mimo_ofdm,node_phy_channel,node_phy_tr38901,node_phy_optical,node_phy_nr,node_phy_signal,node_phy_utils toneAmber
class node_sionna_sys,node_sys_topology,node_sys_control,node_sys_abstraction toneMint
class node_sys_tables toneRose
class node_doc,node_tutorials,node_tests toneIndigo
```

## Components

### Core Packages

Main in-repo Python architecture: PHY, SYS, and RT integration.

- [sionna](https://github.com/nvlabs/sionna/tree/main/src/sionna): import root · Top-level Python package entry point. · `src/sionna`
- [Sionna RT](https://github.com/nvlabs/sionna/tree/main/src/sionna/rt): ray tracing submodule · External ray-tracing runtime integrated through a submodule boundary. · `src/sionna/rt`
- [RT code](https://github.com/nvlabs/sionna/tree/main/ext/sionna-rt): external package · Ray-tracing implementation stored outside the main package tree. · `ext/sionna-rt`

### PHY Stack

Waveform-level communication simulation components.

- [PHY](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy): link-level sim · Physical-layer signal processing and channel simulation. · `src/sionna/phy`
- [Base blocks](https://github.com/nvlabs/sionna/blob/main/src/sionna/phy/block.py): abstractions · Common block/object/config foundation for composable PHY components. · `src/sionna/phy/block.py`
- [FEC stack](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/fec): coding · Modular encoders/decoders and coding utilities. · `src/sionna/phy/fec`
- [Mapping](https://github.com/nvlabs/sionna/blob/main/src/sionna/phy/mapping.py): modulation · Constellation mapping and demapping between bits and symbols. · `src/sionna/phy/mapping.py`
- [MIMO/OFDM](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/ofdm): waveform processing · Spatial processing, resource grids, pilots, equalization, and detection. · `src/sionna/phy/ofdm`
- [Channels](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/channel): channel models · AWGN, fading, OFDM/time-domain, optical, and dataset-backed channels. · `src/sionna/phy/channel`
- [3GPP 38.901](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/channel/tr38901): propagation models · Standardized wireless channel scenarios and coefficients. · `src/sionna/phy/channel/tr38901`
- [Optical](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/channel/optical): fiber channel · Optical propagation and amplification models. · `src/sionna/phy/channel/optical`
- [NR stack](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/nr): 5G PUSCH · 5G NR transmitter/receiver orchestration on top of PHY. · `src/sionna/phy/nr`
- [Signal DSP](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/signal): dsp primitives · Filtering, up/downsampling, and window functions. · `src/sionna/phy/signal`
- [PHY utils](https://github.com/nvlabs/sionna/tree/main/src/sionna/phy/utils): numerics/helpers · Shared tensor, linear algebra, metrics, random, and plotting utilities. · `src/sionna/phy/utils`

### SYS Stack

Network-level abstraction and control components.

- [SYS](https://github.com/nvlabs/sionna/tree/main/src/sionna/sys): network-level sim · System-level simulation using physical-layer abstractions. · `src/sionna/sys`
- [Topology](https://github.com/nvlabs/sionna/blob/main/src/sionna/sys/topology.py): network model · Network layout and link geometry. · `src/sionna/sys/topology.py`
- [Control](https://github.com/nvlabs/sionna/blob/main/src/sionna/sys/scheduling.py): adaptation · Scheduling, power control, and link adaptation. · `src/sionna/sys/scheduling.py`
- [Abstraction](https://github.com/nvlabs/sionna/blob/main/src/sionna/sys/phy_abstraction.py): phy→sys bridge · 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](https://github.com/nvlabs/sionna/tree/main/src/sionna/sys/bler_tables): lookup assets · BLER and ESM parameter tables used by system abstraction. · `src/sionna/sys/bler_tables`

### Support

Documentation, tutorials, and test scaffolding.

- [Docs](https://github.com/nvlabs/sionna/tree/main/doc): sphinx docs · API reference, developer docs, and rendered tutorials. · `doc`
- [Tutorials](https://github.com/nvlabs/sionna/tree/main/tutorials): notebooks · Executable end-to-end examples across PHY, SYS, and RT. · `tutorials`
- [Tests](https://github.com/nvlabs/sionna/tree/main/test): verification assets · Unit tests and numerical reference data for core modules. · `test`

## Connections

- 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.