Architecture¶

The organising idea¶

Five layers sit on two vendored upstream stacks, which sit on an unmodified ns-3.43 core. Nothing in the core is patched, which is what makes the toolkit trackable against upstream ns-3 releases rather than a permanent fork.

The layering is not decorative. Each layer only knows about the one below it, so a scenario can replace a layer without the ones above noticing. The orbital layer does not know a radio exists. The radio does not know a RIC exists. The RIC gets its measurements through E2SM-KPM rather than by reaching into the PHY. This is what lets oran-ntn run over either radio backend, and what lets ntn-sionna substitute a ray-traced channel for a closed-form one without touching a scenario.

The single most important property¶

The decision plane and the measurement plane are the same plane.

That sentence is doing real work. In a simulation, it is easy and common for a control decision to be evaluated against numbers that the decision could not have affected: a handover trigger that fires while a counter increments beside an unrelated SINR series. The result looks like a closed loop and is not one, and no amount of running it longer will reveal the gap.

Here, a trigger that fires calls into the RRC, which moves the terminal onto a different cell, whose SINR is then measured off the spectrum PHY by the same accumulator that fed the trigger. When that property fails somewhere, the toolkit says so in sim_health.csv rather than leaving it to be inferred.

The five layers¶

Orbital and mobility¶

ntn-constellation propagates the shell, from two-line elements or from orbital elements, and owns the contact graph over inter-satellite links including limb clearance. ntn-sagin adds the air and ground layers, UAV and HAPS, with a TR 36.777 channel. ntn-v2x puts vehicles under the shell with NR sidelink.

Everything above consumes one ephemeris, which is the reason coordinate frames agree: there is only one source of position.

Protocol, L1 to L3¶

ntn-traffic is the spine. NtnRealStackHelper assembles a genuine NR cell, mmWave FR2 or 5G-LENA nr at FR1, under that ephemeris: SpectrumPhy, LDPC error model, HARQ, RLC, PDCP, RRC, EPC and GTP, with TR 38.811 NTN physics chained onto the channel and timers relaxed to the slant round trip.

ntn-cho decides when to hand over, ntn-rrc carries the SIB19 timing that makes uplink work over a round trip the terrestrial standard never anticipated, ntn-fapi exposes the MAC-PHY boundary, and ntn-slice differentiates the traffic across it.

Physical layer¶

thz-ntn and ntn-sionna both replace or augment the propagation chain rather than sitting beside it: a THz atmospheric term or a ray-traced channel impulse response attenuates real packets and shows up in the measured SINR.

Control and learning¶

oran-ntn closes the loop. E2SM-KPM indications carry measurements up, E2SM-RC control actions and A1 policies come back down, and the E2 latency between them is taken from live slant geometry, which is what makes the RIC placement question answerable. ns3-ai-ntn exposes the same loop to a Gymnasium agent.

Operations¶

ntn-observability records the scene once and exports it four ways. ntn-digital-twin runs the prediction outside the simulation and pushes the decision back in.

One run, end to end¶

flowchart TD
    A["CelesTrak / Space-Track<br/>two-line elements"] --> B["ntn-constellation<br/>SGP4, ISL contact graph, presets"]
    B --> C["contrib/satellite (SNS3)<br/>SatSGP4MobilityModel"]
    C --> D["ntn-traffic · NtnRealStackHelper<br/>NR SpectrumPhy, HARQ, RLC, PDCP, RRC, EPC"]
    D --> P["thz-ntn / ntn-sionna<br/>atmospheric and ray-traced channel"]
    P --> D
    D --> E["ntn-rrc<br/>SIB19, K_offset, timing advance, DRX"]
    E --> F["ntn-cho<br/>time-to-exit conditional handover"]
    F -->|"RRC reconfiguration with sync"| D
    D --> G["oran-ntn<br/>E2SM-KPM indications"]
    G --> H["Near-RT RIC and xApps<br/>on-board · gateway · cloud"]
    H -->|"E2SM-RC action, A1 policy"| D
    H --> I["ns3-ai-ntn<br/>Gymnasium environments"]
    I --> H
    D --> J["ntn-slice<br/>per-5QI bearers, SLA percentiles"]
    D --> K["ntn-observability<br/>sim_health.csv, KPM series, CZML, InfluxDB"]
    K --> L["ntn-digital-twin<br/>FastAPI prediction"]
    L -->|"actuated handover"| F

The two loops that matter are the ones drawn back into ntn-traffic: the handover path and the RIC path. Both terminate at the radio, which is why their effect is measurable.

Layer by layer¶

Layer	Modules	Responsibility
Orbital and mobility	`ntn-constellation`, `ntn-sagin`, `ntn-v2x`	One ephemeris for the whole run; contact graph; air, ground and vehicular layers
Protocol, L1 to L3	`ntn-traffic`, `ntn-cho`, `ntn-rrc`, `ntn-fapi`, `ntn-slice`	The measured NR data plane and the control that shapes it
Physical layer	`thz-ntn`, `ntn-sionna`	Channel models chained onto the real propagation path
Control and learning	`oran-ntn`, `ns3-ai-ntn`	E2 and A1 loops, RIC placement, RL environments
Operations	`ntn-observability`, `ntn-digital-twin`	Export, visualization, and closed-loop prediction
Vendored upstream	`satellite` (SNS3), `mmwave`, `nr` (5G-LENA), `netsimulyzer`	SGP4 mobility and antenna corpus; the NR PHY and MAC; 3D playback
Simulation core	ns-3.43, unmodified	Events, channels, helpers, the attribute system

Where the boundaries are¶

An architecture page that only lists what is present is half a document. The toolkit's boundaries are stated in SCOPE_AND_LIMITATIONS.md, and the ones most likely to affect an experiment design are:

The air interface carries no propagation delay in the shipped runs; the NTN slant delay rides the transport leg, and the health record says so per row.
The multi-tap TR 38.811 NTN-TDL is not implemented; the measured channel carries large-scale loss with the spectrum model's own fading.
The in-simulation E2 transport is an ns-3 header, not ASN.1 APER over SCTP; the wire-level path is the FlexRIC bridge.
Release 19 AI/ML lifecycle management is absent entirely.

Next¶

Getting started to build and run
Modules for what each one does
Papers for the work built on it