# nvlabs/neural_rx architecture

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

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

## Overview

##### Project type and purpose
- This is a research‐driven machine‐learning pipeline and inference framework for 5G NR multiuser MIMO receivers.
- It consists of:
- A **training and evaluation pipeline** (scripts + configs + utils + Sionna/TF)
- A **model repository** (pretrained weights + ONNX/TensorRT export)
- **Notebooks** for tutorials and result visualization.
- **Results** and **weights** storage.

##### Break down the main components
a. Configuration Layer
- Directory: `config/`
- Purpose: parameterize experiments (channel models, modulation, MCS, site‐specific data).
b. Data & Channel Simulation
- Provided by NVIDIA Sionna (external library).
- Local channel‐realization datasets generated at runtime or from `data/` (ray‐tracing).
c. Model Definition & Utilities
- Directory: `utils/`
- Contains architecture building blocks: graph‐CNN modules, impairment models, baseline receivers, ONNX helpers.
d. Training & Evaluation Pipeline
- Directory: `scripts/`
- Scripts:
- `train_neural_rx.py` – loads config, builds model (utils), trains in TF.
- `evaluate.py` – runs test sets, computes BLER, outputs to `results/`.
- `export_onnx.py` – converts TF model to ONNX.
- `compute_cov_mat.py`, `export_onnx.py`, `evaluate.py` supporting tasks.
e. Storage
- `weights/` – pretrained model checkpoints for various configs.
- `results/` – precomputed BLER curves and sweeps.
- Generated at runtime:
- `logs/` – training logs, tensorboard.
- `onnx_models/` – exported ONNX files.
- `data/` – ray‐tracing channel sets.
f. Notebook Interface
- Directory: `notebooks/`
- Interactive demos: Jumpstart tutorial, model introspection, real‐time latency plots.
g. Deployment / Inference Runtime
- TensorRT engine loading ONNX for real‐time on GPU.
- Latency target: ≤1 ms on NVIDIA A100.

##### Relationships and data flows
- **Config → Training**: configs parameterize `train_neural_rx.py`.
- **Training → Weights**: trained TF model saved to `weights/`.
- **Weights → ONNX**: `export_onnx.py` loads weights → produces ONNX → stored in `onnx_models/`.
- **ONNX → TensorRT**: external step (not in repo) to build TRT engine.
- **Data (Sionna + ray tracing) → Training/Evaluation**: channel samples fed to model.
- **Evaluation → Results**: `evaluate.py` writes metrics to `results/`.
- **Notebooks** consume: configs, scripts, weights, results to display plots and latency figures.

##### Architectural patterns
- Modular ML pipeline: clear separation between **data**, **model logic**, **training**, **evaluation**, **export**.
- Two deployment paths:
- **Offline**: research via notebooks & scripts.
- **Real-time**: ONNX → TensorRT for low‐latency GPU inference.
- Use of external frameworks as “services”: Sionna (channel simulation), TensorFlow (training), ONNX/TensorRT (inference).

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "neural-rx Repository"
        direction TB

        subgraph "Configuration Layer"
            direction TB
            Config["config/"]:::core
        end

        subgraph "Model Definition & Utilities"
            direction TB
            Utils["utils/"]:::core
        end

        subgraph "Training & Evaluation Scripts"
            direction TB
            Train["train_neural_rx.py"]:::core
            Evaluate["evaluate.py"]:::core
            Export["export_onnx.py"]:::core
            ComputeCov["compute_cov_mat.py"]:::core
        end

        subgraph "Notebook Interface"
            direction TB
            Notebooks["notebooks/"]:::ui
        end

        subgraph "Storage"
            direction TB
            Weights["weights/"]:::storage
            Results["results/"]:::storage
            Logs["logs/"]:::storage
            ONNXModels["onnx_models/"]:::storage
        end
    end

    Sionna[(NVIDIA Sionna)]:::external
    TensorFlow[(TensorFlow)]:::external
    TensorRT[(TensorRT)]:::external

    Config -->|".cfg"| Train
    Sionna -->|"channel samples"| Train
    Train -->|"train()"| TensorFlow
    TensorFlow -->|"TF checkpoint"| Weights

    Weights -->|"load ckpt"| Export
    Export -->|".onnx"| ONNXModels
    ONNXModels -->|"build engine"| TensorRT

    Sionna -->|"channel samples"| Evaluate
    Evaluate -->|"BLER metrics"| Results

    Notebooks -->|"read"| Config
    Notebooks -->|"read"| Weights
    Notebooks -->|"read"| Results

    classDef core fill:#cce5ff,stroke:#0000cc,stroke-width:1px;
    classDef storage fill:#d4edda,stroke:#155724,stroke-width:1px;
    classDef external fill:#ffe5b4,stroke:#cc8400,stroke-width:1px;
    classDef ui fill:#fff3cd,stroke:#856404,stroke-width:1px;

    click Config "https://github.com/nvlabs/neural_rx/tree/main/config/"
    click Utils "https://github.com/nvlabs/neural_rx/tree/main/utils/"
    click Train "https://github.com/nvlabs/neural_rx/blob/main/scripts/train_neural_rx.py"
    click Evaluate "https://github.com/nvlabs/neural_rx/blob/main/scripts/evaluate.py"
    click Export "https://github.com/nvlabs/neural_rx/blob/main/scripts/export_onnx.py"
    click ComputeCov "https://github.com/nvlabs/neural_rx/blob/main/scripts/compute_cov_mat.py"
    click Notebooks "https://github.com/nvlabs/neural_rx/tree/main/notebooks/"
    click Weights "https://github.com/nvlabs/neural_rx/tree/main/weights/"
    click Results "https://github.com/nvlabs/neural_rx/tree/main/results/"
```
