Metadata-Version: 2.2
Name: witwin-channel
Version: 0.4.0
Summary: GPU-accelerated differentiable wireless propagation simulation for RF digital twins.
Requires-Python: <3.12,>=3.11
Requires-Dist: torch==2.10.0
Description-Content-Type: text/markdown

# 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:

```python
import witwin.channel as channel

print(channel.capabilities())
```

## Solver entry points

| Package | Use case | Primary result |
| --- | --- | --- |
| `witwin.channel.deterministic` | Repeatable coherent fields and radiomaps | Field, path gain, component maps, optional path table |
| `witwin.channel.path` | Explicit channel paths for point-to-point links | Complex coefficients, delays, angles, interactions, CIR/CFR |
| `witwin.channel.montecarlo.basic` | Incoherent sampled power and radiomaps | Path gain and component power/maps |
| `witwin.channel.montecarlo.bdpt` | Bidirectional Monte Carlo propagation | Path gain, component power, optional BDPT samples |

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`](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:

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

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

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

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

```powershell
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`](src/witwin/channel). Contributor rules and the
full native validation matrix are defined in [`AGENTS.md`](AGENTS.md).

## Citation

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

```bibtex
@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`](LICENSE) and the [Witwin licensing page](https://witwin.ai/license)
for the applicable terms.
