cu3GPPChan Python Bindings

Python interface to the GPU-accelerated cu3gppchan C++/CUDA library via nanobind.

Prerequisites

The wheel build invokes the repo CMake project and packages both _cu3gppchan*.so and libchanModels.so into the wheel. The target machine must still provide the CUDA driver/runtime and system libraries such as HDF5.

Build a Wheel

# From the repository root:
bash scripts/build_wheel.sh --clean

# Install the generated wheel
python3 -m pip install dist/cu3gppchan-*.whl

# Verify import and basic config construction
python3 scripts/use_python_wheel.py

Set CUDA architectures with:

CU3GPPCHAN_CUDA_ARCHS="80;90" bash scripts/build_wheel.sh --clean

For editable development:

bash scripts/build.sh --python
python3 -m pip install -e python/

Verify:

import cu3gppchan
print(cu3gppchan.__version__)  # 0.1.1

Wheel smoke tests

The build smoke-tests each wheel with python/tests/test_wheel_smoke.py:

• Tier 1 (import + config construction) runs everywhere.
• Tier 2 (FadingChannel / StatisticalChannel GPU runs) auto-skips when no cupy/CUDA device is present.

Run manually against an installed wheel:

pip install "cu3gppchan[test]"
pytest python/tests/test_wheel_smoke.py -v

Package Structure

python/
  pyproject.toml
  src/cu3gppchan/
    __init__.py              Public API re-exports
    _cu3gppchan*.so          nanobind C++ extension (built by CMake)
    libchanModels.so         bundled runtime library used by the extension
    statistical_channel.py   StatisticalChannel — system-level SLS wrapper
    fading_channel.py        FadingChannel — link-level TDL/CDL wrapper
    channel_config.py        TdlChannelConfig / CdlChannelConfig
    channel_api_ref.py       3GPP TR 38.901 reference data
    cuda_utils.py            CUDA stream and array helpers

API Overview

Low-Level Bindings (no CuPy needed)

These are direct nanobind wrappers of C++ classes. Use when you manage GPU memory yourself or only need configuration objects.

High-Level Wrappers (require CuPy)

These provide a Pythonic interface with CuPy array I/O and automatic GPU memory management.

StatisticalChannel — System-Level Channel

from cu3gppchan import (
    StatisticalChannel, SimConfig, SystemLevelConfig,
    LinkLevelConfig, ExternalConfig, Scenario,
)

sim_cfg = SimConfig(center_freq_hz=3.5e9, bandwidth_hz=100e6, run_mode=1)
sys_cfg = SystemLevelConfig(scenario=Scenario.UMa, n_site=1, n_ut=10)
link_cfg = LinkLevelConfig(fast_fading_type=2)  # CDL
ext_cfg = ExternalConfig()

chan = StatisticalChannel(sim_cfg, sys_cfg, link_cfg, ext_cfg)

# Run one TTI
chan.run(ref_time=0.0)

FadingChannel — Link-Level TDL / CDL

from cu3gppchan import FadingChannel, TdlChannelConfig

config = TdlChannelConfig(
    n_cell=1, n_ue=1,
    n_bs_ant=4, n_ue_ant=4,
    delay_profile='A',
    delay_spread_ns=30,
    max_doppler_hz=5,
    sc_spacing_hz=30e3,
)

chan = FadingChannel(config)
rx_signal = chan.run(tx_signal, ref_time=0.0, snr_db=20.0)

Configuration Classes

Enums

Running Tests

# Static analysis (flake8 / pylint / mypy)
bash tests/run_static_tests.sh

# Python unit tests
bash tests/run_unit_tests.sh --python_only

Dependencies

Required (installed automatically by pip install):

• numpy
• h5py
• pyyaml

Optional:

• cupy-cuda13x — for StatisticalChannel, FadingChannel, and GPU array wrappers

License

Apache-2.0. See file headers for details.