Check the runtime
Diagnose a Channel install with runtime_diagnostics and build_info, and fix CPU-only PyTorch, a missing native extension and memory budget errors.
Channel fails loudly: when something is wrong it raises an error instead of returning a degraded result. This page shows how to find the cause.
Step 1: run the diagnostics#
import witwin.channel as channel
diagnostics = channel.runtime_diagnostics()
print("package:", diagnostics["package_version"], "python:", diagnostics["python"], "torch:", diagnostics.get("torch"))
print("cuda:", diagnostics.get("cuda_available"), diagnostics.get("cuda_runtime"))
print("device:", diagnostics.get("device"))
print("errors:", diagnostics["errors"])On a working installation (RTX 5080):
package: 0.5.0 python: 3.11.14 torch: 2.10.0
cuda: True 12.8
device: {'name': 'NVIDIA GeForce RTX 5080', 'sm': 120, 'total_memory_bytes': 17066033152, 'declared_supported': True, 'runtime_verified': True, 'status': 'runtime_verified', ...}
errors: []runtime_diagnostics() never raises, so it works even when importing the solvers fails. Then run the Friis check from Installation; it exercises the full native path.
Step 2: match the symptom#
| Symptom | Cause | Fix |
|---|---|---|
cuda: False, cuda_runtime: None | PyTorch is a CPU build, or no NVIDIA driver | Reinstall PyTorch from the CUDA 12.8 index: pip install torch==2.10.0 --index-url https://download.pytorch.org/whl/cu128. Check nvidia-smi. |
errors contains native extension import failed; install a matching Channel wheel ... | The _channel extension could not load: wrong Python version, a different torch version, or a missing CUDA runtime DLL | Use CPython 3.11 and exactly torch==2.10.0. Reinstall witwin-channel in a fresh environment. |
pip finds no matching distribution | Python is not 3.11, or the platform is not Windows x64 or Linux x86_64 | Create a Python 3.11 environment. Other platforms need a source build. |
device shows declared_unverified | Your GPU architecture is built into the wheel but was not in the release test matrix | Channel still runs. Validate results with the Friis check and the quickstart. |
Import errors mention witwin.channel.core or RadioMapResult | Code or files from Channel 0.3 | Port to the 0.4+ API on these pages, in a fresh environment. |
Step 3: read the error#
Errors name the rule they enforce. Some you will meet while setting up solves:
| Error | Meaning |
|---|---|
RuntimeError: deterministic reflection/transmission currently support max_depth <= 5 | Lower max_depth. |
RuntimeError: max_diffraction_order above 1 is not supported yet | Only first-order diffraction exists. |
RuntimeError: coupled reflection-diffraction paths require max_depth >= 2 | Raise max_depth or set coupled_paths=False. |
ValueError: components must be a non-empty subset of [...] | A misspelled component name. |
ValueError: path max_paths_scope must be 'per_pair' | The path solver only limits paths per pair. |
ValueError: Antenna IDs must be unique within a Scene. | Two endpoints share an antenna_id. |
MemoryBudgetError: workspace for Monte Carlo basic exceeds the GPU memory budget before launch ... | samples times endpoints needs more than workspace_limit_bytes. Lower samples or raise the budget. |
ValueError saying spacing must contain two positive values (from ReceiverGrid) | Use positive spacing; flip x_axis or y_axis to step in the negative direction. |
ValueError: Geometry tensor device cpu conflicts with resolved device cuda:0. | A Mesh got vertices and faces on different devices. |
NotImplementedError from backward() mentioning scattering | Scattering is not differentiable; see Differentiability. |
Passing one solver's Config to another solver also fails (for example, deterministic.solve with a path.Config raises AttributeError).
Step 4: report a problem#
If the diagnostics are clean and a solve still fails, open an issue on witwin-ai/witwin-channel with:
- the output of
channel.build_info()(it identifies the exact native build); runtime_diagnostics();- the smallest script that reproduces the error, and the full traceback.