Witwin Channel

Witwin Channel is a GPU-accelerated, differentiable wireless propagation simulator for RF digital twins, coverage prediction, channel characterization, and inverse optimization. It models a declarative scene and exposes dedicated solvers for deterministic fields, explicit propagation paths, and Monte Carlo radiomaps through the witwin.channel Python package.

Project status Version 0.4 is a breaking replacement for the earlier 0.3 API. The supported runtime requires an NVIDIA GPU and the packaged native extension; APIs may continue to evolve before 1.0.

Capabilities

• Line-of-sight, multi-bounce specular reflection, first-order UTD diffraction, transmission through layered thin-sheet materials, and rough-surface Kirchhoff scattering.
• Point receivers and structured receiver grids for link-level and radiomap workflows.
• Complex fields, path gain, delay, departure/arrival angles, interaction geometry, CIR/CFR conversion, polarization, and antenna-array support where advertised by the selected solver.
• Fixed-topology JVP and VJP derivatives for deterministic, path, and Monte Carlo Basic solves. Supported inputs include material parameters, carrier frequency, endpoint positions, and mesh vertices.
• CUDA-resident scene, geometry, field, scattering, and derivative execution backed by the native Channel/RayD runtime.

The versioned capability manifest is available at runtime:

import witwin.channel as channel

print(channel.capabilities())

Solver entry points

Each solver owns its own Config, Result, and solve(scene, config) public contract. The exact stable exports are recorded in ci/public-api-snapshot.json.

Requirements

• CPython 3.11.
• PyTorch 2.10 with CUDA 12.8 runtime support.
• Windows x64 on an NVIDIA GPU with compute capability 12.0 for the currently verified release row. Other declared architectures and platforms require their own release evidence before publication.
• An ABI-compatible witwin-channel wheel, or a source build against the repository-locked RayD integration.

Channel has no production CPU compute backend. Missing CUDA, an unsupported GPU architecture, an incompatible extension, or a required native capability raises an error before returning a partial result.

Installation

Install an approved wheel into an environment that already contains the matching CUDA-enabled PyTorch build:

python -m pip install .\witwin_channel-0.4.0-cp311-cp311-win_amd64.whl --no-deps

For a source build, select the intended RayD checkout explicitly and keep the build in the same Python environment as PyTorch:

conda activate witwin2
$env:CMAKE_ARGS = "-DRAYD_SOURCE_DIR=E:/Code/RayD"
python -m pip install . --no-build-isolation --no-deps

When RAYD_SOURCE_DIR is omitted, the build may use a unique locked rayd-torch source bundle only when its package metadata reports a clean, matching source tree. The published rayd-torch 0.7.0 bundle does not satisfy that release guard, so Channel 0.4.0 source builds must set RAYD_SOURCE_DIR to the locked clean checkout. Discovery never scans a Conda prefix or loads an arbitrary global build.

Do not mix files from the 0.3 and 0.4 implementations in one environment.

Quick start

The following CUDA example evaluates a 10-metre free-space link with the deterministic solver:

import torch

from witwin.channel import ReceiverPoint, Scene, Transmitter
from witwin.channel.deterministic import Config, solve

scene = Scene(
    structures=[],
    transmitters=[
        Transmitter(
            position=torch.tensor([0.0, 0.0, 1.5]),
            power_w=1.0,
        )
    ],
    receivers=[
        ReceiverPoint(position=torch.tensor([10.0, 0.0, 1.5]))
    ],
    frequency=3.5e9,
)

result = solve(
    scene,
    Config(max_depth=0, components={"los"}),
)

print(result.path_gain)  # CUDA tensor with shape (1, 1)
print(result.field)      # complex64 coherent field

Structures use triangle meshes and material objects such as Dielectric, LossyDielectric, DispersiveMaterial, ITUMaterial, and PerfectConductor. Replace ReceiverPoint with ReceiverGrid for radiomap solves, or select witwin.channel.path when the individual path coefficients, delays, angles, and interactions are required.

Differentiation contract

path, deterministic, and montecarlo.basic accept ad_mode="none", "jvp", or "vjp". Derivatives are evaluated through the fixed topology selected by the primal solve. Visibility changes, path birth/death, and other discrete topology discontinuities are outside this contract. Unsupported solver/component/gradient combinations fail explicitly; BDPT currently supports primal evaluation only.

Runtime diagnostics

Use the public diagnostics instead of inspecting private extension modules:

import witwin.channel as channel

print(channel.runtime_diagnostics())
print(channel.build_info())

These records identify the package, CUDA architecture, native ABI, build fingerprint, and locked RayD source used by the running extension.

Development

Repository development and validation use the witwin2 Conda environment:

conda run -n witwin2 python ci/run_ci_tier.py quick
conda run -n witwin2 python ci/run_ci_tier.py cuda

Architecture and domain-owner documentation lives next to the implementation under src/witwin/channel. Contributor rules and the full native validation matrix are defined in AGENTS.md.

Citation

If you use Witwin Channel in academic research, please cite:

@inproceedings{chen2026rfdt,
  title     = {Physically Accurate Differentiable Inverse Rendering
               for Radio Frequency Digital Twin},
  author    = {Chen, Xingyu and Zhang, Xinyu and Zheng, Kai and
               Fang, Xinmin and Li, Tzu-Mao and Lu, Chris Xiaoxuan
               and Li, Zhengxiong},
  booktitle = {Proceedings of the 32nd Annual International Conference
               on Mobile Computing and Networking (MobiCom)},
  year      = {2026},
  doi       = {10.1145/3795866.3796686},
  publisher = {ACM},
  address   = {Austin, TX, USA},
}

License

Witwin Channel is available under a dual-license model for academic and non-commercial research use or for commercial and enterprise use. See LICENSE and the Witwin licensing page for the applicable terms.