Getting started¶

This page walks you from a clean machine to a running 6G NTN simulation in under 30 minutes.

Prerequisites¶

Requirement	Version	Notes
Linux	Ubuntu 22.04 / Debian 12	macOS works for most modules; Windows via WSL2
C++ compiler	g++ 11+ or clang 14+	C++20 features
CMake	≥ 3.20	required by ns-3.43
Python	3.10–3.13	for `ntn-constellation`, `ns3-ai-ntn`, `ntn-digital-twin`
Docker	optional, ≥ 24.0	for FlexRIC bridge + observability stack
NVIDIA GPU	optional	for `ntn-sionna` GPU ray tracing

Option 1 - Docker (fastest)¶

docker pull uzairdocker69/ns3-ntn-toolkit:latest
docker run --rm -it -p 8000:8000 -p 3000:3000 uzairdocker69/ns3-ntn-toolkit:latest

This gives you a shell inside a pre-built image with ns-3.43, all 13 contrib modules, and Python utilities ready. Port 8000 exposes the digital-twin FastAPI; port 3000 exposes Grafana.

Option 2 - Build from source¶

1. Clone¶

git clone https://github.com/Muhammaduazir69/ns3-ntn-toolkit.git
cd ns3-ntn-toolkit/ns-3-dev

2. Install build dependencies (Ubuntu / Debian)¶

sudo apt update
sudo apt install -y \
  build-essential cmake ninja-build pkg-config \
  python3 python3-venv python3-pip \
  libgsl-dev libxml2-dev libsqlite3-dev \
  libboost-all-dev libpcap-dev \
  qtbase5-dev qttools5-dev qttools5-dev-tools \
  git ca-certificates

3. Configure & build ns-3¶

./ns3 configure --enable-examples --enable-tests
./ns3 build

First build is ~20-40 minutes depending on cores. Subsequent incremental builds are seconds.

4. Install Python utilities¶

python3 -m venv .venv
source .venv/bin/activate

# Each module is its own pip-installable package:
pip install -e contrib/ntn-constellation
pip install -e contrib/ntn-digital-twin
pip install -e contrib/ns3-ai-ntn/python_utils

Or install everything via the metapackage once it lands on PyPI:

pip install ns3-ntn-toolkit

Verify the install¶

Run the test suites¶

./test.py --suite=ntn-rrc        # 16 unit tests
./test.py --suite=ntn-sagin      # 6 unit tests
./test.py --suite=ntn-slice      # 7 unit tests
./test.py --suite=ntn-v2x        # 5 unit tests

# Python tests
pytest contrib/ntn-constellation/tests
pytest contrib/ns3-ai-ntn/python_utils/tests

Run the live-Starlink demo¶

.venv/bin/ntn-fetch starlink --out data/starlink-now \
    --max-sats 200 --czml --czml-duration-min 120 -v

This fetches today's Starlink TLEs from CelesTrak, propagates a 200-sat sample for 2 hours, and emits both an SNS3 scenario directory and a CesiumJS CZML file you can drop into a viewer.

Bring up the observability stack¶

cd contrib/ntn-observability/docker
docker compose up -d
# Grafana on http://localhost:3000  (admin / admin)
# InfluxDB on http://localhost:8086

Bring up the digital-twin API¶

ntn-twin-api &
curl http://localhost:8000/health
curl http://localhost:8000/constellation/state

Common issues¶

ns-3 build fails on c++20 features

Update g++ to ≥11 or clang to ≥14. apt install g++-11 if on Ubuntu 22.04.

./ns3 configure reports modules missing

Make sure all contrib subdirectories have CMakeLists.txt. Run git status in contrib/ to confirm no files are missing.

pip install -e contrib/ntn-constellation fails on sgp4

pip install --upgrade pip setuptools wheel first; the older defaults can struggle with the C extension.

FlexRIC docker build hangs on ASN.1 toolchain

The first docker compose build for FlexRIC compiles asn1c from source - allow 15-20 minutes.

Sionna RT example reports CUDA errors

ntn-sionna requires a CUDA-capable GPU and TensorFlow 2.20 GPU. The toolkit works without it; just skip the W9 examples.

What next¶

Architecture - high-level data flow across the 13 modules
Modules - per-module deep dives
Papers - published work using this toolkit