Metadata-Version: 2.4
Name: rayd-torch
Version: 0.6.0
Summary: Torch-native RayD geometry and multipath primitives.
Author-Email: Xingyu Chen <xic063@ucsd.edu>
License-Expression: BSD-3-Clause
Requires-Python: <3.15,>=3.10
Requires-Dist: torch<2.11,>=2.10
Description-Content-Type: text/markdown

# RayD Torch

RayD Torch is a Torch-native CUDA/OptiX package for RayD geometry primitives and
RayD-style multipath/diffraction kernels.

```python
import rayd.torch as rt
```

Install the `rayd-torch` distribution. It owns only `rayd/torch/**` and can
coexist with the independently installed `rayd-drjit` backend.

## Tensor ABI

RayD Torch APIs accept CUDA `torch.float32` tensors for vector data and CUDA `torch.int32` tensors for index data. Vector tensors are row-major `(N, 3)` unless otherwise documented, masks are `torch.bool`, and tensors should be contiguous. Outputs and AD tapes are Torch-owned tensors.

## Gradient Contract

Intersection, edge, reflection, EPC, and diffraction operators use a fixed-winner gradient contract where explicit native kernels exist. The discrete primitive, edge, visibility, or path decision selected in the forward pass is treated as non-differentiable; VJP and JVP propagate through the continuous values recomputed from the saved winner and live Torch tensors.

## Autograd

The native operators support Torch reverse-mode VJP and forward-mode JVP for the supported continuous inputs where explicit kernels have been implemented. CUDA work is launched on the current Torch CUDA stream.

## Current Status

RayD Torch now builds separate native scene, edge, reflection, and diffraction
Torch extension bindings. The native build includes OptiX PTX pipelines for
scene intersection, edge queries, reflection tracing/EPC/visibility/
accumulation, and diffraction path/accumulation/coherent direct execution.

Current opt-in RayD parity tests cover forward cases for scene intersection,
multi-mesh global ids, nearest-edge, visibility, reflection tracing,
diffraction paths, direct/Keller/suffix diffraction accumulation, order-2 and
order-3 diffraction chains, and coherent direct accumulation. Torch VJP/JVP
coverage exists for geometry, edge, reflection trace, EPC, and diffraction
accumulation under the fixed-winner contract.

On the recorded same-script benchmark shape (grid 64, 4,096 queries, warm
caches), RayD Torch currently measures faster than RayD for scene build,
intersect, nearest edge, reflection trace, diffraction paths, and direct
diffraction accumulation. Far-from-surface nearest-edge queries use a tiled
exact fallback scan instead of the scene-diagonal OptiX tier. Release-size and
Nsight-counter-backed runs remain the broader performance gate. See
`docs/torch_gap_analysis.md` and `docs/torch_performance.md`.

## Dependencies

RayD Torch depends on PyTorch, CUDA, and OptiX for native execution. The RayD Torch package path has no Dr.Jit dependency.
