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())

Propagation consumer API

External simulation packages can use the solver-neutral, versioned consumer boundary without importing a Channel solver or internal propagation contract:

from witwin.channel.propagation.consumer import (
    CONTRACT_VERSION,
    EndpointBatch,
    PropagationRequest,
    evaluate,
)

assert CONTRACT_VERSION == 4

The consumer publishes exact compact K rows with native-produced stable pair segmentation and scalar, Complex3, or complete source-basis-to-sink-basis Jones transport when advertised by its typed capabilities. It reuses the owning ADR-032 compact boundary; no adapter performs a second count observation or Torch/Python compaction. Unsupported component, response, frequency-offset, or AD combinations fail before a partial result is returned.

Contract version 1 supports LoS, reflection, transmission, and diffraction. Scattering is not advertised or accepted: its current enumerated rows are incoherent power-domain output and do not satisfy the consumer's coherent transport or canonical pair-major row contracts.

The consumer is intentionally propagation-only. It contains no Radar target, RCS, waveform, IQ, ADC, detection, or processing policy. See docs/dev/propagation-consumer-contract.md for the versioning, convention, zero-copy, and failure contracts.

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.

Complete signatures, parameter tables, tensor layouts, methods, exceptions, and usage patterns are collected in the docs/api-reference API Reference.

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 runtime-verified row. Release wheels must contain the repository-wide native SASS set, including SM87, and compute_120 PTX; SM87 runtime validation remains separate evidence.
• witwin==0.4.0 for the logical world contracts.
• 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.

_channel uses the versioned LibTorch/Python extension ABI. The Stage-I wheel is CPython 3.11 / Torch 2.10.0 only and is not advertised as a LibTorch Stable ABI binary. Linux release wheels are compiled inside a real manylinux_2_28 environment.

Installation

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

python -m pip install .\witwin_channel-0.5.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/witwin-platform/RayD"
python -m pip install . --no-build-isolation --no-deps

When RAYD_SOURCE_DIR is omitted, the build may use the unique locked rayd-torch 0.8.0 source bundle after validating its clean metadata, complete source manifest, RECORD ownership, and eight-header integration identity. 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.core import AntennaState, Scene
from witwin.channel.deterministic import Config, solve

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,
)

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

Logical scenes, structures, materials, stable IDs, endpoints, and snapshots are owned by witwin.core. Channel compiles them with witwin.channel.scene.compile(scene, reference_frequency_hz=...); the four solver entry points perform that same explicit compilation boundary. Use Core Mesh, PhysicalMaterial, MaterialLayer, and PhysicalMaterial.perfect_conductor(). Use Core ReceiverGrid for radiomap solves, or select witwin.channel.path when 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 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.