gpu3gppchan Python Bindings

Python interface to the GPU-accelerated gpu3gppchan C++/CUDA library through nanobind. The package provides 3GPP TR 38.901 system-level statistical channel models, TDL/CDL fading channels, OFDM modulation and demodulation, and GPU noise helpers.

Installation

python -m pip install gpu3gppchan

Pip selects the wheel matching your operating system, CPU architecture, and Python interpreter. Ordinary CPython 3.12–3.14 uses the cp312-abi3 wheel; free-threaded CPython 3.14 uses the separate cp314-cp314t wheel.

Verify the installation:

import gpu3gppchan as chan

print(chan.__version__)
config = chan.SimConfig(center_freq_hz=3.5e9, bandwidth_hz=100e6, run_mode=0)
print(config.center_freq_hz)

Prerequisites

CUDA runtime dependencies are installed through pip. A separate CUDA Toolkit installation is not required to use the wheels. HDF5 and yaml-cpp are bundled; no separate system installation of those libraries is required.

API Overview

System-Level Statistical Channels (SLS)

System-level models include UMa, UMi, and RMa scenarios, with topology, path loss, shadow fading, LOS/NLOS, small-scale fading, and user mobility. StatisticalChannel provides the high-level interface; StatisChanModel exposes the native engine and diagnostic exports.

SLS configuration can be supplied through YAML: Python reads it with PyYAML and passes the values into the bound configuration objects. Native C++ example applications also parse YAML with yaml-cpp. The repository includes complete SLS configurations and Python configuration-loading examples.

The following minimal example reads YAML settings, runs an SLS model with a generated topology, and dumps its results to HDF5 for debugging:

import yaml
import gpu3gppchan as chan
from gpu3gppchan.cuda_utils import CudaStream

# For a file, use yaml.safe_load() on an open text file instead.
settings = yaml.safe_load("""
simulation:
  center_freq_hz: 3500000000.0
  bandwidth_hz: 100000000.0
system_level:
  scenario: UMa
  n_site: 1
  n_sector_per_site: 1
  n_ut: 1
""")
sim = chan.SimConfig(**settings["simulation"], run_mode=0)
sim.internal_memory_mode = 1  # Retain channel data for inspection.
topology = dict(settings["system_level"])
topology["scenario"] = getattr(chan.Scenario, topology["scenario"])
system = chan.SystemLevelConfig(**topology)

stream = CudaStream()
model = chan.StatisChanModel(sim, system, 0, stream)
model.run(ref_time=0.0)
model.save_sls_chan_to_h5_file("_debug")
# Writes slsChanData_1sites_1uts_debug_seed0.h5 in the current directory.

The native HDF5 export is available through the Python binding. Use it to inspect channel results and diagnose simulations; h5py can read the generated files. dump_topology_to_yaml(filename) also exports the model topology.

Link-Level Fading Channels (TDL/CDL)

FadingChannel provides link-level TDL/CDL fading with OFDM and noise processing and manages GPU buffers through a CuPy array interface. TdlChannelConfig and CdlChannelConfig configure delay profiles, antenna counts, Doppler, and other link parameters. TdlChan and CdlChan expose the lower-level native engines.

TDL Example

The following example runs a single-cell, single-user channel on the GPU:

import cupy as cp
from gpu3gppchan import FadingChannel, TdlChannelConfig

config = TdlChannelConfig(
    delay_profile="A",
    delay_spread=30.0,
    n_bs_ant=1,
    n_ue_ant=1,
)
channel = FadingChannel(channel_config=config)

# Shape: (cells, users, transmit antennas, OFDM symbols, subcarriers).
tx = cp.ones((1, 1, 1, 14, 3276), dtype=cp.complex64)
rx = channel.run(freq_in=tx, tti_idx=0, snr_db=20.0)
print(rx.shape)  # (1, 1, 1, 14, 3276)
print(bool(cp.all(cp.isfinite(rx))))  # True

Other Signal Processing Helpers and Native Configuration

The lower-level API exposes the native engines and configuration objects for applications that manage their own GPU buffers and streams.

Configuration objects can be constructed without CuPy arrays. Channel execution requires a compatible GPU; low-level callers must synchronize their CUDA work and manage the lifetime of caller-owned buffers.

Dependencies

Pip installs the following runtime dependencies automatically:

• numpy, h5py, and pyyaml
• cuda-bindings
• nvidia-cuda-runtime>=13.0.88 and nvidia-curand>=10.4.0
• cupy-cuda13x (on Windows, cupy-cuda13x[ctk]>=14.2.0)

Native HDF5 handles C++ exports, while h5py supports Python-side HDF5 workflows. The package retains both native and Python YAML support. No .h5 or .hdf5 data files are included in the wheel.

Threading

Free-threaded Python getters for OFDM and fading output return owned GPU snapshots. Ordinary Python uses zero-copy views that may change on a later run(). Synchronize external CUDA work before passing buffers into a model, and do not modify them while the model uses them.

Testing and Source Builds

To install the optional test dependencies:

python -m pip install "gpu3gppchan[test]"

From a source checkout, run the installed-wheel smoke tests:

python -m pytest testBenches/gpu3GPPChan/python/tests/test_wheel_smoke.py -v

Import and configuration tests run without a GPU; GPU channel tests skip when no usable CUDA device is available. A successful import alone does not validate GPU execution.

The source is part of NVIDIA Aerial CUDA-Accelerated RAN. In a checkout, see testBenches/gpu3GPPChan/python/NOTES.md for native packaging, CMake presets, detailed tests, and threading semantics, and testBenches/gpu3GPPChan/tooling/README.md for Linux and Windows build workflows.

License

Aerial source is licensed under Apache-2.0. Bundled components retain their own license terms; the wheel includes notices under .dist-info/licenses/. Distribution metadata uses LicenseRef-gpu3gppchan-distribution for the combined terms described in the included THIRD_PARTY_NOTICES.txt.