Metadata-Version: 2.4
Name: gpu3gppchan
Version: 0.1.6
Summary: GPU-accelerated 3GPP channel models (TR 38.901)
License-Expression: LicenseRef-gpu3gppchan-distribution
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: licenses/CUTLASS-LICENSE.txt
License-File: licenses/HDF5-LICENSE.txt
License-File: licenses/NVIDIA-CCCL-NOTICES.txt
License-File: licenses/NVIDIA-CUDA-13.3-EULA.txt
License-File: licenses/NVIDIA-MathDx-LICENSE.txt
License-File: licenses/THIRD_PARTY_NOTICES.txt
License-File: licenses/gpu3gppchan-LICENSE.txt
License-File: licenses/nanobind-LICENSE.txt
License-File: licenses/robin-map-LICENSE.txt
License-File: licenses/yaml-cpp-LICENSE.txt
Requires-Dist: numpy
Requires-Dist: h5py
Requires-Dist: pyyaml
Requires-Dist: nvidia-cuda-runtime>=13.0.88
Requires-Dist: nvidia-curand>=10.4.0
Requires-Dist: cuda-bindings
Requires-Dist: cupy-cuda13x; sys_platform != "win32"
Requires-Dist: cupy-cuda13x[ctk]>=14.2.0; sys_platform == "win32"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: license-expression
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# 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

```bash
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:

```python
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

| Component | Requirement |
| --- | --- |
| Python | CPython 3.12–3.14, or free-threaded CPython 3.14 |
| GPU | NVIDIA Ampere (SM 8.0) or newer |
| Driver | NVIDIA driver supporting CUDA 13 |
| Linux | glibc 2.34 or newer; x86_64 or aarch64 |
| Windows | x86_64; Microsoft Visual C++ Redistributable |

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:

```python
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:

```python
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.

| Classes | Purpose |
| --- | --- |
| `SimConfig`, `SystemLevelConfig`, `LinkLevelConfig`, `ExternalConfig` | Simulation, topology, fading, and external geometry settings. |
| `TdlConfig` / `TdlChan`, `CdlConfig` / `CdlChan` | Native link-level channel configuration and engines. |
| `StatisChanModel` | Native system-level statistical channel engine. |
| `CarrierParams`, `OfdmModulate`, `OfdmDeModulate` | OFDM carrier configuration, modulation, and demodulation. |
| `GauNoiseAdder` | GPU additive Gaussian noise. |
| `CellParam`, `UtParamCfg`, `AntPanelConfig`, `Coordinate` | Cell, user, antenna, and position configuration. |
| `Scenario`, `UeType`, `SensingTargetType` | Scenario, user, and sensing-target enums. |
| `LinkParams`, `ClusterParams`, `UtMobilitySnapshot` | System-level link, cluster, and mobility snapshots. |

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:

```bash
python -m pip install "gpu3gppchan[test]"
```

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

```bash
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](https://github.com/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`.
