Dec 04 2025 Bringing Real-Time Ray-Tracing to ns-3: Integrating Sionna RT into ns-3

Online Integration of Sionna RT into ns-3

Why Sionna RT Inside ns-3?

Traditional channel models used in system-level simulations rely on analytic or stochastic approximations such as 3GPP TR 38.901. While efficient, they cannot accurately capture site-specific propagation, complex indoor/outdoor geometries, or interactions with dynamically placed objects. Sionna RT, on the other hand:

Computes deterministic multipath propagation via true 3D ray-tracing
Produces per-path delay, Doppler, and angle-of-arrival/angle-of-departure
Accepts arbitrary 3D scenes including buildings, cars, reflectors, and materials
Runs on GPU for exceptional performance

Good news!

We are excited to announce a new integration of NVIDIA Sionna RT, a real-time differentiable ray-tracing engine, into ns-3. This work enables high-fidelity, geometry-based wireless channel modelling directly inside ns-3 simulations—unlocking research capabilities that were previously either too slow, offline-only, or difficult to combine with full protocol-stack simulations.

The current ns-3 Sionna-RT merge request (still under development and testing) : MR2608

With this post, we’re excited to share preliminary results of these integration!

Online Integration of Sionna RT into ns-3

One of the core achievements of this work is the online integration of Sionna RT into the ns-3 simulation flow. Instead of relying on precomputed channel traces or offline ray-tracing files, ns-3 now communicates directly and dynamically with Sionna RT at runtime. This is enabled by a lightweight but powerful pybind11 interface, which allows C++ components in ns-3 to call Python functions inside Sionna with minimal overhead.

How Online Integration Works?

At each channel update event (e.g., user movement, beam change, mobility step), ns-3 requests a new channel solution from Sionna RT. Sionna RT computes all multipath components—delays, angles, Doppler, and path gains—using its GPU-accelerated ray-tracing engine. The results are returned as NumPy arrays and converted directly into ns-3’s internal ChannelMatrix format. No intermediate files, no manual preprocessing, and no user intervention are required. This creates a tight loop between the ray-tracing engine and the full NR protocol stack, enabling simulations that are both realistic and fully automated.

Performance Gains The online approach brings several important performance improvements:

Seamless Integration: The pybind11 interface ensures smooth communication between C++ and Python components, minimizing latency.
Reduced I/O Overhead: Eliminating file read/write operations significantly speeds up channel updates.
Dynamic Adaptation: Channels can be updated in real-time based on user mobility and environmental changes.
Scalability: The GPU-accelerated ray-tracing engine can handle large numbers of users and complex scenes efficiently.
Flexibility: Users can easily modify scenarios, antenna configurations, and mobility patterns without re-running offline ray-tracing.

Easy to Use

A major design goal of this integration was simplicity. Although the system internally connects C++, Python, GPU kernels, and ns-3’s channel pipeline, the user experience remains extremely straightforward. To run Sionna RT inside ns-3:

Create a Python virtual environment
Install the required Python packages (Sionna, Sionna-RT, and their dependencies)
Build ns-3 with pybind11
Run any of the provided examples

That’s all—no Python servers, no background daemons, no message passing, and no special scripts. All communication between ns-3 and Sionna happens inside the same process, through direct function calls using pybind11. This means:

No sockets or REST APIs
No RPC calls
No temporary files
No need to maintain a separate Python runtime during simulation

Users interact with this new channel model exactly like any existing ns-3 channel model: by setting a scenario name and running their simulation. Everything else—ray tracing, path extraction, Doppler computation, and channel-matrix assembly—happens automatically behind the scenes. This makes deterministic ray-tracing in ns-3 as easy to use as a standard 3GPP channel model, but with far greater realism and without any operational overhead.

Integration Architecture

The integration is implemented as a new channel model class in 5G-LENA that inherits from the existing MatrixBasedChannelModel in ns-3. This means:

Full reuse of the ns-3 MIMO processing pipeline, supporting multiple-antenna arrays as well as dual-polarized elements.”
Sionna RT delivers per-link channel matrices (H[u][s][n]) in the exact format similar to existing 3GPP channel model
Doppler, delay spread, angles are fully supported
The feature is backward compatible with the whole ns-3 PHY architecture

The C++ side interacts with Python only through clean APIs, keeping ns-3’s design principles intact.

Simulation Example

We have provided an example in the src/spectrum directory: sionna-rt-channel-example.cc . This example demonstrates a simple scenario where a mobile user moves through a 3D urban environment while communicating with a base station. . The example uses UPAs with multiple antennas and dual-polarization.

The example, included in the merge request, sets up: