Skip to content

thz-ntn - 100 GHz – 1 THz physics for NTN

EKF beam tracking holding a sub-THz link through a LEO pass
EKF beam tracking holding a sub-THz link through a LEO pass
RIS phase sweep across the 100 GHz–1 THz band
RIS phase sweep across the 100 GHz–1 THz band
thz-ntn module architecture
thz-ntn module architecture

thz-ntn is the ns3-ntn-toolkit module that provides a physics-grounded 100 GHz to 1 THz (D-band and sub-THz) PHY layer for non-terrestrial links, cascading free-space path loss, HITRAN-2020-baseline molecular absorption, ITU-R weather and scintillation, alpha-mu fading, pointing error, and hardware impairments into a single composite channel. On top of that channel it adds ultra-massive MIMO arrays, reconfigurable intelligent surfaces, an ISAC sensing subsystem, and an EKF beam tracker, and re-homes the atmospheric loss as a real ns-3 PropagationLossModel so it attenuates actual packets on a live mmwave NR NTN spectrum channel and shows up in measured SINR / TBLER / goodput.

Why it matters. Terahertz and sub-THz NTN links live or die on molecular absorption, beam squint, and pointing stability, effects that closed-form path-loss models simply omit. thz-ntn is a physics-grounded sub-THz module for open ns-3: its channel is cross-validated against ITU-R P.676-13, P.618-13, and S. Paine's am atmospheric model, its scaling laws (radar range^4 SNR, RIS 20·log10(N) gain, UM-MIMO 10·log10(N) gain with 1/sqrt(N) beamwidth narrowing) are verified numerically correct, and its atmospheric loss is a chainable channel plug-in that attenuates real packets rather than a standalone spreadsheet.

What it simulates

  • Composite THz channel cascade. Free-space path loss (ThzNtnFreeSpaceLoss) with correct frequency/distance scaling; HITRAN line-by-line molecular absorption (ThzNtnMolecularAbsorption, 14 H2O + 9 O2 rotational lines from the HITRAN-2020 release) over an ITU-R P.835 stratified atmosphere; weather attenuation (rain/fog/snow) per ITU-R P.838 / P.840; ITU-R P.618 scintillation (amplitude and phase, AR(1) time series); alpha-mu small-scale fading; composite pointing error (vibration, J2 perturbation, atmospheric refraction, tracking latency); and hardware impairments (PA, phase noise, ADC SQNR, I/Q imbalance).
  • Real channel plug-in. ThzNtnPropagationLossModel re-homes the gaseous-absorption and weather calculators as an ns-3 PropagationLossModel, chained onto a real mmwave NR NTN spectrum channel via NtnRealStackHelper::AddExtraPropagationLoss, so the atmospheric loss attenuates actual packets carried by NtnOranApplication QoS flows and measured at NtnOranSink.
  • Atmospheric transmission windows. ThzNtnSpectrum classifies THz bands and exposes standard windows (140 / 220 / 340 / 410 / 460 GHz); peakTransmittance and maxZenithAttenuation_dB are distinct multiplicative inputs to ComputeTransmittance, not inverses of each other.
  • Ultra-massive MIMO. ThzNtnAntennaArray / ThzNtnBeamforming build UPA / UCA / Cassegrain arrays (up to 128×128) with DFT codebooks and wideband beam-squint analysis (ComputeBeamSquintLoss_dB).
  • RIS. ThzNtnRis / ThzNtnRisController model space / aerial / ground reconfigurable intelligent surfaces with N^2 scaling and phase-quantisation loss, plus an O-RAN-style ThzNtnRisServiceModel and ThzNtnRisXapp for closed-loop control.
  • ISAC. ThzNtnIsac / ThzNtnIsacProcessor / ThzNtnIsacScheduler provide integrated sensing and communication for space-debris CRLB ranging, with comm/sense sub-band scheduling.
  • Beam tracking. ThzNtnBeamTracking offers EKF and position-based satellite-ephemeris beam tracking; in the measured-radio path the EKF prediction error maps through the array 3-dB beamwidth to a pointing loss applied as a live channel reconfiguration.
  • ISL and waveforms. ThzNtnIslChannel / ThzNtnIslLink inter-satellite link channel and link budget; ThzNtnWaveform selects among 5 candidates (OFDM / DFT-s-OFDM / OTFS / AFDM / SC-FDE). NYUSIM-140 calibration is provided by ThzNtnNyusimReference / ThzNtnNyusimCalibrator.
  • Real-radio examples. Run a full mmwave NR NTN cell (SpectrumPhy + MAC + HARQ + RLC/PDCP + RRC + EPC) with SGP4/Walker satellite mobility and TR 38.811 ground terminals; the carrier is capped at 100 GHz (sub-THz / W-band) by the 3GPP spectrum model, with higher-band studies kept in the analytic link-budget examples. Each writes an honest sim_health.csv and enables the toolkit AI flow monitor.

Standards & references

  • HITRAN. HITRAN-2020 line-by-line absorption baseline (Gordon et al. 2022, CFA Harvard); the bundled HitranLut lookup table is tagged HITRAN-2024 but generated from the same 23-line HITRAN-2020 model (per-line 2020-to-2024 deltas under 0.5%).
  • ITU-R. P.676 (oxygen + water vapour gaseous attenuation), P.618 (rain attenuation and scintillation), P.835 (reference standard atmosphere), P.838 (rain specific attenuation), P.840 (fog/cloud), and P.681 (land mobile satellite). The channel is cross-validated against ITU-R P.676-13 and P.618-13.
  • Reference models. S. Paine's am atmospheric model (SAO) and the NYUSIM-140 GHz channel as a calibration reference.
  • 3GPP. TR 38.811 ground-terminal mobility and the 3GPP NR spectrum model (100 GHz carrier cap) on the measured-radio path; NtnOranApplication flows carry in-band 5QI / S-NSSAI headers.
  • O-RAN. A RIS service model and xApp enabling O-RAN-style closed-loop RIS control over the toolkit's E2/KPM path.

Use cases

  • Molecular-absorption-gated downlink. Quantify how HITRAN gaseous absorption plus rain degrade a measured sub-THz downlink, toggling rain mid-run to watch the link respond (thz-ntn-real-stack, thz-ntn-weather-traffic).
  • RIS link recovery. Recover a blocked THz link mid-simulation by engaging a RIS relay as a live channel event on the real cell (thz-ntn-ris-relay-traffic).
  • EKF beam tracking through a pass. Hold a sub-THz link across a real SGP4 pass and compare EKF against position-based tracking on the measured link (thz-ntn-beam-tracking).
  • ISAC coexistence. Study comm/sense coexistence as the ISAC scheduler partitions the sub-band grid from COMM_ONLY to SENSING_ONLY and gates measured goodput (thz-ntn-isac-coexist-traffic).
  • Inter-satellite links. Evaluate a real mmwave NR ISL between cross-plane SGP4 satellites of a Starlink-class shell alongside the analytic ISL budget (thz-ntn-isl-traffic).
  • Closed-loop thz-ntn × oran-ntn. Drive a ground RIS from an xApp reacting to KPM read off the measured DL SINR, recovering goodput after an urban-canyon blockage (thz-ntn-ric-controlled-traffic).
  • UM-MIMO and RIS scaling laws. Sweep array size and RIS element count to read worst-case beam-squint loss and N^2 RIS gain (thz-ntn-um-mimo, thz-ntn-ris-assisted).

Run it

# Flagship channel-plugin demo: HITRAN absorption + rain on the real mmwave channel
./ns3 run "thz-ntn-real-stack --duration=16 --freqGhz=100 --rainMmH=25"

# EKF vs position-based beam tracking, closed over the real radio
./ns3 run "thz-ntn-beam-tracking --trackingMode=EKF --updateRate=10"

# Closed-loop RIS recovery driven by an O-RAN xApp on measured SINR
./ns3 run "thz-ntn-ric-controlled-traffic --simSeconds=40 --xapp=1"

Test suite: ./test.py --suite=thz-ntn (38 unit tests, including ITU-R reference cross-validation and the verified scaling laws).

Reference paper

Muhammad Uzair. Sub-THz Non-Terrestrial Networks: Physics, RIS, and ISAC. IEEE Transactions on Terahertz Science and Technology (under review).

See Papers for the arXiv preprint.

Source