Installation

Channel ships as prebuilt wheels on PyPI. A wheel contains the compiled CUDA/OptiX extension, so most users only need pip and a CUDA build of PyTorch. Build from source only when you change the native code or need a platform without a wheel.

Requirements#

Channel has no CPU backend. Every solve runs on CUDA. If CUDA, a supported GPU or the native extension is missing, Channel raises an error before it returns any result. See GPU and native runtime for the architecture list and the failure behavior.

Install from PyPI#

Install the CUDA 12.8 build of PyTorch first, then Channel. Installing PyTorch first matters on Windows, where the default PyPI torch wheel is CPU-only.

python -m pip install torch==2.10.0 --index-url https://download.pytorch.org/whl/cu128
python -m pip install witwin-channel==0.5.0

witwin-channel pins torch==2.10.0 and witwin==0.4.0. pip keeps the CUDA torch you installed because the version matches. The 0.5.0 release publishes two wheels: cp311-win_amd64 and cp311-manylinux_2_28_x86_64. Each contains native code (SASS) for SM70, SM75, SM80, SM86, SM87, SM89, SM90, SM100, SM101 and SM120, plus compute_120 PTX that newer GPUs compile at load time.

Verify the installation#

Run this check. It prints the build identity, runs a 10 m free-space link and compares it with the Friis formula.

import math
 
import torch
 
import witwin.channel as channel
from witwin.core import AntennaState, Scene
from witwin.channel.deterministic import Config, solve
 
info = channel.build_info()
print(info["backend"], info["cuda_available"], info["optix_available"])
 
diagnostics = channel.runtime_diagnostics()
print("errors:", diagnostics["errors"])
 
scene = Scene(
    structures=[],
    endpoints=[
        AntennaState(1, "tx", torch.tensor([0.0, 0.0, 1.5]), power_w=1.0),
        AntennaState(2, "rx", torch.tensor([10.0, 0.0, 1.5])),
    ],
)
result = solve(scene, Config(max_depth=0, components={"los"}), reference_frequency_hz=3.5e9)
wavelength = 299_792_458.0 / 3.5e9
print(float(result.path_gain), (wavelength / (4 * math.pi * 10.0)) ** 2)

Expected output on a working installation:

channel True True
errors: []
4.6460672820103355e-07 4.646068291545675e-07

The two numbers agree to float32 precision. If errors is not empty, or the solve raises, see Check the runtime.

Build from source#

A source build compiles the _channel CUDA extension with scikit-build-core and CMake, and links RayD from source at the commit pinned in dependencies/rayd.lock.json. Use it when you develop Channel itself.

You need:

• the Python environment you will run Channel in, with torch==2.10.0 (CUDA 12.8) and witwin==0.4.0 already installed;
• the CUDA Toolkit 12.8 (nvcc, cudart, cuBLAS, cuSPARSE and cuSOLVER development files);
• a C++ compiler: MSVC x64 (Visual Studio 2022 Build Tools) on Windows, GCC 12 on Linux;
• the OptiX 8.1 SDK headers, for example a checkout of https://github.com/NVIDIA/optix-dev at tag v8.1.0;
• cmake>=4.3,<4.4, ninja>=1.13,<1.14 and scikit-build-core>=0.12,<0.13, installed in the same environment because the build runs without isolation;
• RayD 0.8.0 source: either a clean checkout of https://github.com/Asixa/RayD at commit c7a99979d0fdcc67b2ec8a12246a7df597603409, or the rayd-torch==0.8.0 package installed in the environment, which carries the locked source bundle.

1. Get the sources

   git clone https://github.com/witwin-ai/witwin-channel.git
   git clone https://github.com/Asixa/RayD.git
   git -C RayD checkout c7a99979d0fdcc67b2ec8a12246a7df597603409
   git clone --branch v8.1.0 https://github.com/NVIDIA/optix-dev.git

2. Install the build tools

   python -m pip install "cmake>=4.3,<4.4" "ninja>=1.13,<1.14" "scikit-build-core>=0.12,<0.13"

3. Point CMake at RayD and OptiX

   Pass the paths through CMAKE_ARGS. On Windows (PowerShell):

   $env:CMAKE_ARGS = "-DRAYD_SOURCE_DIR=C:/src/RayD -DOPTIX_INCLUDE_DIR=C:/src/optix-dev/include"

   On Linux:

   export CMAKE_ARGS="-DRAYD_SOURCE_DIR=$HOME/src/RayD -DOPTIX_INCLUDE_DIR=$HOME/src/optix-dev/include"

   Optional: add -DCMAKE_CUDA_ARCHITECTURES=120-real to compile only for your GPU and shorten the build. The default set is 75-real;80-real;86-real;89-real;120-real;120-virtual.

4. Build and install

   cd witwin-channel
   python -m pip install . --no-build-isolation --no-deps

The build validates the RayD source before it compiles anything. It checks that the checkout is at the locked commit and origin URL, and that the eight RayD integration headers match the hashes in the lock file. A dirty RayD checkout still builds, with the CMake warning RayD checkout is dirty; this developer build is not publishable. If you omit RAYD_SOURCE_DIR, the build looks for exactly one lock-valid rayd-torch source bundle in the active Python environment and fails if it finds none. It never scans a Conda prefix or loads another global build. If CMake cannot find OptiX, it stops with Could not locate OptiX SDK include directory. Set OPTIX_INCLUDE_DIR or OPTIX_PATH.

Run the verification script above after the build.