# nvidia/aerial-cuda-accelerated-ran architecture

> Architecture diagram of the GitHub repository nvidia/aerial-cuda-accelerated-ran, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia/aerial-cuda-accelerated-ran
- Repository: https://github.com/nvidia/aerial-cuda-accelerated-ran

## Overview

#### Purpose and Top-Level Shape
NVIDIA Aerial CUDA-Accelerated RAN is a GPU-accelerated 5G NR RAN SDK spanning PHY, MAC scheduling, control-plane integration, reference simulation, and Python/ML APIs. It is a multi-language systems repository: CUDA/C++ runtime components, MATLAB reference models, and Python bindings/tools. Root build orchestration starts at `CMakeLists.txt`; deployment-oriented builds use `testBenches/phase4_test_scripts/build_aerial_sdk.sh`.

#### GPU PHY Library (cuPHY)
`cuPHY` is the L1 compute core: a CUDA library exposing reusable GPU primitives and channel implementations for coding, modulation, synchronization, channel estimation/equalization, and uplink/downlink processing. The public/API boundary is centered on `cuPHY/src/cuphy/cuphy_api.h` and implementation context/device management in `cuPHY/src/cuphy/cuphy_context.cpp`. Channel-level composition wraps primitives into operational PHY functions in `cuPHY/src/cuphy_channels/pusch_rx.cpp`, `cuPHY/src/cuphy_channels/pdsch_tx.cpp`, and peers.

Key data flow: host-side callers create/configure cuPHY contexts, submit tensors/buffers and per-channel descriptors, CUDA kernels execute on GPUs, and decoded/processed results return through host-visible buffers.

#### PHY Control Plane and Real-Time Execution
`cuPHY-CP/cuphydriver` schedules per-slot PHY work, owns cell state, buffers, workers, GPU devices, and aggregation of channel PDUs. Its DL/UL split is explicit in `cuPHY-CP/cuphydriver/src/downlink/slot_map_dl.cpp` and `cuPHY-CP/cuphydriver/src/uplink/slot_map_ul.cpp`; PHY channel aggregators bridge incoming slot commands to cuPHY execution, e.g. `cuPHY-CP/cuphydriver/src/uplink/phypusch_aggr.cpp`.

`cuPHY-CP/cuphycontroller/src/cuphydriver.cpp` configures and drives the PHY runtime from YAML-backed deployment profiles. This is the main control boundary between configuration/L2-facing applications and real-time GPU execution.

#### L2/MAC Scheduling and L2-to-PHY Boundary
`cuMAC` provides CUDA-accelerated L2 scheduling, with separate scheduling families for 4T4R and 64T64R/MU-MIMO. Representative allocation/scheduling engines are `cuMAC/src/4T4R/multiCellScheduler.cu` and `cuMAC/src/64T64R/multiCellMuUeGrp.cu`; its consumer-facing API is `cuMAC/src/api.h`.

L2-to-L1 messaging is handled by adapters rather than direct library coupling. The NVIDIA PHY adapter is in `cuPHY-CP/cuphyl2adapter/lib/nvPHY/nv_phy_driver_proxy.cpp`; the SCF 5G FAPI adapter translates MAC/FAPI messages and builds slot commands in `cuPHY-CP/scfl2adapter/lib/scf_5g_fapi/scf_5g_fapi_slot_commands.cpp`. Shared-memory/event-driven NVIPC is the process boundary for multi-process deployments.

#### Fronthaul, RU, and Operations
The O-RAN fronthaul path is implemented by `cuPHY-CP/aerial-fh-driver`, with packet/network/GPU-transfer coordination in `cuPHY-CP/aerial-fh-driver/lib/fronthaul.cpp` and `cuPHY-CP/aerial-fh-driver/lib/gpu_comm_doca.cu`. The RU emulator provides a software radio-endpoint for integration and test flows: `cuPHY-CP/ru-emulator/ru_emulator/main.cpp` and `cuPHY-CP/ru-emulator/ru_emulator/ru_emulator.cpp`.

Operational management is supplied through gRPC/protobuf OAM services in `cuPHY-CP/cuphyoam/src/cuphyoam.cpp` and `cuPHY-CP/cuphyoam/proto/scf_fapi_p9.proto`. Metrics support includes a Prometheus backend at `cuPHY-CP/gt_common_libs/aerial_metrics/src/prometheus_metrics_backend.cpp`.

#### Reference, Python, and Validation Ecosystem
`5GModel/nr_matlab/nrSimulator.m` and `5GModel/nr_matlab/runSim.m` form the MATLAB 3GPP-oriented reference simulation and waveform/test-vector generation path. These models produce validation artifacts, including HDF5, that can feed cuPHY examples and integration tests.

`pyaerial` exposes cuPHY through pybind11 (`pyaerial/pybind11/pycuphy_pybind.cpp`) and higher-level Python PHY APIs (`pyaerial/src/aerial/phy5g/api.py`). It also includes ML-to-TensorRT export support at `pyaerial/src/aerial/model_to_engine/exporters/tensorrt_exporter.py`.

Material runtime dependencies are NVIDIA CUDA GPUs and CUDA toolchain; deployment paths additionally target NVIDIA networking stacks through DOCA/DPDK/Rivermax, O-RAN fronthaul, gRPC, YAML configuration, HDF5 artifacts, and optionally TensorRT/ONNX for ML-enhanced PHY operations.

Main entry points: [`cuPHY-CP/cuphycontroller/src/cuphydriver.cpp`](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphycontroller/src/cuphydriver.cpp) (cuPHY controller), [`cuPHY/src/cuphy/cuphy_api.h`](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY/src/cuphy/cuphy_api.h) (cuPHY API), [`cuPHY/src/cuphy_channels/pusch_rx.cpp`](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY/src/cuphy_channels/pusch_rx.cpp) (PHY channels), [`cuPHY-CP/cuphyl2adapter/lib/nvPHY/nv_phy_driver_proxy.cpp`](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphyl2adapter/lib/nvPHY/nv_phy_driver_proxy.cpp) (NVIDIA PHY adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_phy["GPU PHY"]
  node_cuphy_api["cuPHY API<br/>CUDA/C++ API<br/>[cuphy_api.h]"]
  node_cuphy_context["cuPHY context<br/>CUDA runtime<br/>[cuphy_context.cpp]"]
  node_cuphy_channels["PHY channels<br/>CUDA channel pipeline<br/>[pusch_rx.cpp]"]
  node_gpu{{"CUDA GPUs<br/>hardware/runtime"}}
end

subgraph group_runtime["Real-Time RAN"]
  node_cumac_api["cuMAC API<br/>L2 scheduler API<br/>[api.h]"]
  node_cumac_4t4r["4T4R scheduler<br/>CUDA scheduler"]
  node_cumac_mumimo["64T64R MU-MIMO<br/>CUDA scheduler"]
  node_nvphy_adapter["NVIDIA PHY adapter<br/>L2-to-L1 adapter"]
  node_scf_adapter["SCF FAPI adapter"]
  node_nvipc["NVIPC<br/>IPC boundary"]
  node_controller["cuPHY controller<br/>PHY control plane<br/>[cuphydriver.cpp]"]
  node_dl_slot_map["DL slot map<br/>slot scheduler<br/>[slot_map_dl.cpp]"]
  node_ul_slot_map["UL slot map<br/>slot scheduler<br/>[slot_map_ul.cpp]"]
  node_pusch_aggregator["PUSCH aggregator<br/>PHY PDU aggregator<br/>[phypusch_aggr.cpp]"]
  node_fronthaul["O-RAN fronthaul<br/>fronthaul driver<br/>[fronthaul.cpp]"]
  node_ru_emulator["RU emulator<br/>radio endpoint<br/>[main.cpp]"]
  node_oam["OAM gRPC service<br/>operations service<br/>[cuphyoam.cpp]"]
  node_metrics["Prometheus metrics<br/>metrics backend"]
end

subgraph group_ecosystem["Reference and Python"]
  node_matlab_sim["MATLAB NR simulator<br/>reference simulator<br/>[nrSimulator.m]"]
  node_pyaerial["pyaerial PHY API<br/>Python API<br/>[api.py]"]
  node_tensorrt_export["TensorRT exporter<br/>ML export"]
end

node_build["Root build<br/>CMake build<br/>[CMakeLists.txt]"]

node_build -->|"builds"| node_cuphy_api
node_build -->|"builds"| node_controller
node_cuphy_api -->|"creates/configures"| node_cuphy_context
node_cuphy_context -->|"dispatches"| node_cuphy_channels
node_cuphy_channels -->|"executes kernels"| node_gpu
node_cumac_api -->|"selects"| node_cumac_4t4r
node_cumac_api -->|"selects"| node_cumac_mumimo
node_cumac_4t4r -->|"scheduling output"| node_nvphy_adapter
node_cumac_mumimo -->|"scheduling output"| node_nvphy_adapter
node_nvphy_adapter -->|"multi-process transport"| node_nvipc
node_scf_adapter -->|"slot commands"| node_nvipc
node_nvipc -->|"PHY requests"| node_controller
node_controller -->|"drives DL slots"| node_dl_slot_map
node_controller -->|"drives UL slots"| node_ul_slot_map
node_ul_slot_map -->|"UL PDUs"| node_pusch_aggregator
node_dl_slot_map -->|"DL descriptors/buffers"| node_cuphy_api
node_pusch_aggregator -->|"UL descriptors/buffers"| node_cuphy_api
node_fronthaul -->|"GPU transfer"| node_gpu
node_fronthaul -->|"O-RAN traffic"| node_ru_emulator
node_oam -->|"operations control"| node_controller
node_controller -->|"runtime metrics"| node_metrics
node_matlab_sim -.->|"waveforms and HDF5 artifacts"| node_cuphy_channels
node_pyaerial -->|"pybind11 binding"| node_cuphy_api
node_tensorrt_export -->|"ML engine export"| node_pyaerial

click node_build "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/CMakeLists.txt"
click node_cuphy_api "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY/src/cuphy/cuphy_api.h"
click node_cuphy_context "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY/src/cuphy/cuphy_context.cpp"
click node_cuphy_channels "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY/src/cuphy_channels/pusch_rx.cpp"
click node_cumac_api "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuMAC/src/api.h"
click node_cumac_4t4r "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuMAC/src/4T4R/multiCellScheduler.cu"
click node_cumac_mumimo "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuMAC/src/64T64R/multiCellMuUeGrp.cu"
click node_nvphy_adapter "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphyl2adapter/lib/nvPHY/nv_phy_driver_proxy.cpp"
click node_controller "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphycontroller/src/cuphydriver.cpp"
click node_dl_slot_map "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphydriver/src/downlink/slot_map_dl.cpp"
click node_ul_slot_map "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphydriver/src/uplink/slot_map_ul.cpp"
click node_pusch_aggregator "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphydriver/src/uplink/phypusch_aggr.cpp"
click node_fronthaul "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/aerial-fh-driver/lib/fronthaul.cpp"
click node_ru_emulator "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/ru-emulator/ru_emulator/main.cpp"
click node_oam "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphyoam/src/cuphyoam.cpp"
click node_metrics "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/gt_common_libs/aerial_metrics/src/prometheus_metrics_backend.cpp"
click node_matlab_sim "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/5GModel/nr_matlab/nrSimulator.m"
click node_pyaerial "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/pyaerial/src/aerial/phy5g/api.py"
click node_tensorrt_export "https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/pyaerial/src/aerial/model_to_engine/exporters/tensorrt_exporter.py"

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_cuphy_api,node_cuphy_context,node_cuphy_channels,node_gpu toneBlue
class node_cumac_api,node_cumac_4t4r,node_cumac_mumimo,node_nvphy_adapter,node_scf_adapter,node_nvipc,node_controller,node_dl_slot_map,node_ul_slot_map,node_pusch_aggregator,node_fronthaul,node_ru_emulator,node_oam,node_metrics toneAmber
class node_matlab_sim,node_pyaerial,node_tensorrt_export toneMint
class node_build toneNeutral
```

## Components

### GPU PHY

CUDA L1 library and channel processing.

- [cuPHY API](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY/src/cuphy/cuphy_api.h): CUDA/C++ API · Public host-side PHY context and submission boundary. · `cuPHY/src/cuphy/cuphy_api.h`
- [cuPHY context](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY/src/cuphy/cuphy_context.cpp): CUDA runtime · Manages device execution context and resources. · `cuPHY/src/cuphy/cuphy_context.cpp`
- [PHY channels](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY/src/cuphy_channels/pusch_rx.cpp): CUDA channel pipeline · Composes GPU primitives into operational UL and DL processing. · `cuPHY/src/cuphy_channels/pusch_rx.cpp`
- **CUDA GPUs**: hardware/runtime · Executes cuPHY and cuMAC CUDA kernels.

### Real-Time RAN

Slot execution, L2 adapters, fronthaul, and operations.

- [cuMAC API](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuMAC/src/api.h): L2 scheduler API · `cuMAC/src/api.h`
- [4T4R scheduler](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuMAC/src/4T4R/multiCellScheduler.cu): CUDA scheduler · `cuMAC/src/4T4R/multiCellScheduler.cu`
- [64T64R MU-MIMO](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuMAC/src/64T64R/multiCellMuUeGrp.cu): CUDA scheduler · `cuMAC/src/64T64R/multiCellMuUeGrp.cu`
- [NVIDIA PHY adapter](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphyl2adapter/lib/nvPHY/nv_phy_driver_proxy.cpp): L2-to-L1 adapter · Converts L2-facing calls into PHY driver requests. · `cuPHY-CP/cuphyl2adapter/lib/nvPHY/nv_phy_driver_proxy.cpp`
- **SCF FAPI adapter**: FAPI adapter · Translates FAPI messages into slot commands.
- **NVIPC**: IPC boundary · Shared-memory and event-driven multi-process boundary.
- [cuPHY controller](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphycontroller/src/cuphydriver.cpp): PHY control plane · Configures and drives the PHY runtime from deployment profiles. · `cuPHY-CP/cuphycontroller/src/cuphydriver.cpp`
- [DL slot map](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphydriver/src/downlink/slot_map_dl.cpp): slot scheduler · `cuPHY-CP/cuphydriver/src/downlink/slot_map_dl.cpp`
- [UL slot map](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphydriver/src/uplink/slot_map_ul.cpp): slot scheduler · `cuPHY-CP/cuphydriver/src/uplink/slot_map_ul.cpp`
- [PUSCH aggregator](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphydriver/src/uplink/phypusch_aggr.cpp): PHY PDU aggregator · Bridges uplink slot PDUs to cuPHY execution. · `cuPHY-CP/cuphydriver/src/uplink/phypusch_aggr.cpp`
- [O-RAN fronthaul](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/aerial-fh-driver/lib/fronthaul.cpp): fronthaul driver · Coordinates network packets and GPU transfer. · `cuPHY-CP/aerial-fh-driver/lib/fronthaul.cpp`
- [RU emulator](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/ru-emulator/ru_emulator/main.cpp): radio endpoint · Software radio endpoint for integration flows. · `cuPHY-CP/ru-emulator/ru_emulator/main.cpp`
- [OAM gRPC service](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/cuphyoam/src/cuphyoam.cpp): operations service · `cuPHY-CP/cuphyoam/src/cuphyoam.cpp`
- [Prometheus metrics](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/cuPHY-CP/gt_common_libs/aerial_metrics/src/prometheus_metrics_backend.cpp): metrics backend · `cuPHY-CP/gt_common_libs/aerial_metrics/src/prometheus_metrics_backend.cpp`

### Reference and Python

Validation models and Python/ML interfaces.

- [MATLAB NR simulator](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/5GModel/nr_matlab/nrSimulator.m): reference simulator · Generates reference waveforms and validation artifacts. · `5GModel/nr_matlab/nrSimulator.m`
- [pyaerial PHY API](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/pyaerial/src/aerial/phy5g/api.py): Python API · High-level Python interface backed by pybind11 cuPHY bindings. · `pyaerial/src/aerial/phy5g/api.py`
- [TensorRT exporter](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/pyaerial/src/aerial/model_to_engine/exporters/tensorrt_exporter.py): ML export · `pyaerial/src/aerial/model_to_engine/exporters/tensorrt_exporter.py`

### Other components

- [Root build](https://github.com/nvidia/aerial-cuda-accelerated-ran/blob/main/CMakeLists.txt): CMake build · `CMakeLists.txt`

## Connections

- Root build → cuPHY API: builds
- Root build → cuPHY controller: builds
- cuPHY API → cuPHY context: creates/configures
- cuPHY context → PHY channels: dispatches
- PHY channels → CUDA GPUs: executes kernels
- cuMAC API → 4T4R scheduler: selects
- cuMAC API → 64T64R MU-MIMO: selects
- 4T4R scheduler → NVIDIA PHY adapter: scheduling output
- 64T64R MU-MIMO → NVIDIA PHY adapter: scheduling output
- NVIDIA PHY adapter → NVIPC: multi-process transport
- SCF FAPI adapter → NVIPC: slot commands
- NVIPC → cuPHY controller: PHY requests
- cuPHY controller → DL slot map: drives DL slots
- cuPHY controller → UL slot map: drives UL slots
- UL slot map → PUSCH aggregator: UL PDUs
- DL slot map → cuPHY API: DL descriptors/buffers
- PUSCH aggregator → cuPHY API: UL descriptors/buffers
- O-RAN fronthaul → CUDA GPUs: GPU transfer
- O-RAN fronthaul → RU emulator: O-RAN traffic
- OAM gRPC service → cuPHY controller: operations control
- cuPHY controller → Prometheus metrics: runtime metrics
- MATLAB NR simulator → PHY channels: waveforms and HDF5 artifacts
- pyaerial PHY API → cuPHY API: pybind11 binding
- TensorRT exporter → pyaerial PHY API: ML engine export