Skip to content

Architecture

The toolkit is organised as 13 ns-3 contrib modules that together cover the full 6G non-terrestrial network stack. Each module owns a single concern; they compose along a well-defined data flow from live ephemerides at the top to dashboards and digital-twin feedback at the bottom.

Pipeline overview

flowchart TD
    A[CelesTrak / Space-Track<br/>live TLEs] --> B[W1 ntn-constellation<br/>SGP4 + ISL graph + presets]
    B --> C[contrib/satellite SNS3<br/>SatSGP4MobilityModel]
    C --> D[W2 ntn-rrc<br/>TA pre-comp · SIB19 · GNSS · NTN-DRX]
    D --> E[contrib/mmwave + lte<br/>NR PHY/MAC/RRC]
    E --> F[ntn-cho<br/>TTE-aware CHO]
    F --> G[oran-ntn + FlexRIC<br/>13 xApps · A1/E2]
    G --> H1[W4 RL/GNN xApps]
    G --> H2[W6 slices: eMBB / URLLC / mMTC]
    H2 --> I[W5 SAGIN<br/>HAPS / UAV cross-layer routing]
    I --> J[W7 V2X<br/>SUMO TraCI vehicular nodes]
    J --> K[W3 metrics<br/>InfluxDB + Grafana + NetSimulyzer]
    B --> L[CZML feed]
    K --> M[W10 digital twin<br/>FastAPI + CesiumJS live viewer]
    L --> M
    H1 --> G

Layer-by-layer

Layer Module(s) Responsibility
Ephemeris W1 ntn-constellation Live TLE fetch, SGP4 propagation, ISL topology, SNS3 + CZML export
Mobility satellite (SNS3) SatSGP4MobilityModel reads positions, handles GS/UT propagation
RRC W2 ntn-rrc 3GPP Rel-17/18/19 NTN procedures: TA pre-comp, SIB19, GNSS-assisted timing, NTN-extended DRX, regenerative vs transparent payload
PHY/MAC mmwave, lte (upstream) NR PHY/MAC waveforms
Channel thz-ntn, ntn-sionna TR 38.811 (default) · 100 GHz – 1 THz with HITRAN-2020 (sub-THz scenarios) · NVIDIA Sionna RT (opt-in GPU ray tracing)
Mobility (CHO) ntn-cho TTE-aware Conditional Handover with 4-state automaton
RIC / xApps W8 oran-ntn + FlexRIC Near-RT RIC, 13 xApps, A1 policies, real ASN.1-compiled E2AP/KPM/RC over SCTP
AI/ML W4 ns3-ai-ntn Gymnasium envs, Stable-Baselines3, PyTorch Geometric GAT, MAPPO/MASAC
Slicing W6 ntn-slice SST/SD slice association, slice orchestrator xApp, isolation monitor
SAGIN W5 ntn-sagin HAPS station-keeping, UAV mobility, TR 36.777 A2G channel, multi-layer routing
V2X W7 ntn-v2x SUMO TraCI bridge, vehicle-to-LEO direct + relay, maritime scenarios
Observability W3 ntn-observability InfluxDB line-protocol sink, NetSimulyzer JSON, 4 pre-built Grafana dashboards
Digital twin W10 ntn-digital-twin Live TLE refresh loop, FastAPI prediction service, CesiumJS live mode

Standards alignment

Standard Modules implementing
3GPP TR 38.811 (NTN channel) satellite, thz-ntn (sub-THz extension), ntn-sionna
3GPP TS 38.213/331/321 (NR L1/L2 procedures) mmwave, lte, ntn-rrc
3GPP TR 38.821 (NTN scenarios) ntn-rrc, ntn-cho
3GPP TR 36.777 (A2G channel) ntn-sagin
3GPP TS 22.261 / 23.501 (slicing) ntn-slice
O-RAN E2AP v2.03, E2SM-KPM v3, E2SM-RC v1.03 oran-ntn, flexric-bridge
ITU-R P.676/618/838 (atmospheric attenuation) thz-ntn
HITRAN-2020 (molecular absorption) thz-ntn

Validation gates

Every workstream ships with a three-layer validation gate:

flowchart LR
    U[Unit tests<br/>per-function assertions] --> I[Integration tests<br/>2+ workstreams cooperate] --> E[End-to-end smoke<br/>full pipeline exit 0]

Repository layout

ns3-ntn-toolkit/
├── ns-3-dev/
│   ├── contrib/
│   │   ├── ntn-constellation/   # W1
│   │   ├── ntn-rrc/             # W2
│   │   ├── ntn-observability/   # W3
│   │   ├── ns3-ai-ntn/          # W4
│   │   ├── ntn-sagin/           # W5
│   │   ├── ntn-slice/           # W6
│   │   ├── ntn-v2x/             # W7
│   │   ├── oran-ntn/            # W8 (+ flexric-bridge/)
│   │   ├── ntn-sionna/          # W9
│   │   ├── ntn-digital-twin/    # W10
│   │   ├── ntn-cho/             # TTE-aware CHO
│   │   ├── thz-ntn/             # sub-THz physics
│   │   └── satellite/           # SNS3 (upstream)
│   └── ROADMAP_EXECUTION.md
├── docs/                        # this site (MkDocs Material)
├── distribution/                # PyPI metapackage + Dockerfile
├── hf-space/                    # Hugging Face Space Gradio demo
├── papers/                      # 4 papers + figures
└── SCALING_PLAN.md              # 24-month commercialization plan

Where to next