Skip to main content

RayD Torch

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

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.

Published complete wheels are built for and require PyTorch 2.10 (torch>=2.10,<2.11) because _legacy_ops uses the non-Stable-ABI LibTorch C++ surface. The separately audited _stable_ops library remains validated across PyTorch 2.10 through 2.13.

Published wheels contain both native backends and do not require an OptiX SDK at runtime. Building this dual-backend distribution from source does require the OptiX SDK headers, even when the target machine will select CUDA at runtime; an SDK-less CUDA-only source-build mode is not currently provided. Native source builds require CUDA Toolkit 11.3 or newer so the CUDA runtime can resolve driver entry points lazily without making the wheel depend directly on the platform CUDA driver library.

Ray-tracing backend selection

Scene() selects OptiX when the current CUDA device and driver expose it and otherwise selects RayD's pure-CUDA triangle and edge BVHs. The resolved choices are available through scene.trace_backend and scene.edge_bvh_backend after build():

scene = rt.Scene()  # trace_backend="auto", edge_bvh_backend="auto"
scene.add_mesh(mesh)
scene.build()
print(scene.trace_backend, scene.edge_bvh_backend)

Pass trace_backend="optix" or "cuda" and edge_bvh_backend="optix" or "cuda" to require a backend. An explicit OptiX request fails if OptiX is unavailable; runtime pipeline, allocation, and CUDA errors are never converted into a fallback. RAYD_DISABLE_OPTIX=1 is the deployment and test kill switch. Both backends use Torch-owned tensors and the current Torch CUDA stream.

The separately governed ADR-0029 exact four-sample axial-edge primitive and ADR-0033 segment-penetration family remain OptiX-only by contract. Requesting either from a CUDA scene raises an explicit unsupported-backend error; RayD does not substitute a numerically different implementation.

SDF Grid Intersection

rt.SdfGrid and rt.sdf_intersect sphere-trace a caller-owned dense signed distance field. The grid holds vertex-centred float32 samples of shape [Nx, Ny, Nz] in world-metric distance with the negative-inside sign convention, placed by an oriented box given as a world centre, a scalar-first quaternion, and full side lengths:

result = rt.sdf_intersect(
    rt.SdfGrid(values, position=position, rotation=rotation, scale=scale),
    origins,
    directions,
    tmax=10.0,
)
result.t.sum().backward()

The march is relaxed, recovers from overshoot by bisecting the bracketing sign change, and clips the traced interval to the ray/box overlap, so an origin inside the box is a supported case. t, position, and normal carry gradients and tangents to the grid values, the box transform, and the rays under the frozen-winner implicit function theorem; hit_mask and steps carry none. Missed lanes report t = +inf and are bitwise inert: zero outputs, zero derivatives, and no atomic contribution. The operation performs no device-to-host copy and no stream synchronization, including for its resolution-derived eps_hit default.

The primitive is standalone and Torch-only: no OptiX, no Scene membership, no mixing with triangle geometry, and no silhouette gradients in v1. See docs/adr/0037-differentiable-sdf-intersection.md.

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.

Native Source Integration

Native downstream projects built in the same CMake/LibTorch graph use the versioned typed C++ surface in rayd/integration.h; they do not load a second RayD Python extension or use a dynamic symbol registry. Solver-neutral transmission and scattering device math is exposed through src/transmission_device.cuh and rayd/scattering_table.cuh. Torch-specific cross-concept field AD helpers live at src/field_transport_ad.cuh.

The rayd-torch wheel also carries a relocatable source bundle at rayd/torch/_source. rayd-source.json records the distribution version, source commit and repository, integration ABI identity, the complete eight-header integration API set and its aggregate SHA-256, the separately bundled path_exchange.h contract, and the SHA-256 of a complete per-file manifest. The bundle contains the canonical include, source, and build inputs needed for a same-graph native build. Downstreams locate this passive resource through importlib.metadata; they must not import rayd.torch, scan an environment prefix, or trust the metadata without pinning and recomputing the full source manifest. An explicit source checkout remains a higher-priority developer input and keeps its Git identity checks. See docs/adr/0034-validated-package-source-discovery.md.

The accepted transmission surface consists of complete primal/backward/JVP families for resident CSR layer-stack evaluation and complete-row Jones field transport. These operations preserve precise-math compilation, row fusion, atomic layer-gradient order, and the no-persistent-tape contract. Inputs are validated before launch, work runs on the caller's current Torch CUDA stream, and invalid shape/dtype/device/ABI state or CUDA failure raises immediately; there is no CPU, Torch-expression, finite-difference, or legacy-dispatch fallback.

RayD owns the numerical primitives and typed native operations, not a downstream application's material encoding, topology selection, solver estimator policy, RNG/MIS, accumulation, metadata, or result schema. A newly merged transmission implementation may remain a dormant candidate until the consumer pins it, switches all callers, proves parity, and deletes its local implementation. See docs/adr/0002-shared-rf-transmission-ownership.md.

The accepted diffraction surface will place the complete fixed-winner pure-wedge field primal/backward/JVP family behind the typed integration header once the dormant RayD candidate is implemented and direct-tested. Channel remains the production numerical owner until it pins, validates, activates, and deletes its local CUDA implementation. The future typed family must preserve optional winner vertices, three separate native entry launches, current-stream execution, output schemas, and the family-local --use_fast_math contract required for order-1 exporter parity. Monte Carlo Sionna accumulation, coupled RD/DD operations, and BDPT estimator policy remain downstream-owned. See docs/adr/0025-diffraction-family-ownership.md.

The accepted generic-scattering surface consists of exactly seventeen typed operations in six complete families: resident table evaluation AD, resident table sampling/PDF, single-bounce ensemble, phase-screen patch integral, chain ensemble, and chain realization. RayD evaluates caller-owned resident CUDA tensors but does not own table construction, cache/version policy, phase-screen seed/lifecycle, topology, estimator, RNG/MIS, accumulation, or result policy. A high-level BSDF/material framework remains out of scope; solver-neutral RF scattering primitives are in scope.

The migration preserves the existing AD asymmetry: chain-ensemble continuous geometry supports JVP but reverse-mode requests fail loudly, while chain-realization supports its existing continuous-geometry VJP and JVP. Complete row fusion, launch count, recomputation/tape lifetime, backward atomics, output schemas, and the source-TU compile split are frozen: table primal/sample/PDF uses default CUDA flags, while the audited table-AD, ensemble, patch, and chain lockstep TUs retain --fmad=false. A merged RayD implementation remains dormant until Channel pins it, switches a complete family with parity evidence, and deletes the local implementation. See docs/adr/0026-generic-scattering-runtime-ownership.md.

The stable source-level boundary is named rayd/integration.h, its exact identity is rayd.torch.integration, and its numeric API version is 7. No integration_v2 forwarding header, CMake target alias, or alternate identity is supported. See docs/adr/0028-stable-typed-integration-naming.md.

API version 3 makes row validity explicit for pure-wedge diffraction, transmission sequences, and all generic scattering requests. The required device boolean tensor is checked before any row payload or ID is read; invalid primal/JVP rows and supported row gradients are bitwise zero and cannot contribute shared-gradient atomics. AD companions inherit the mask from their nested primal request. See docs/adr/0030-typed-capacity-row-validity.md.

API version 4 additionally makes DiffractionPathConfig.active required for order-1 path export. It is a contiguous CUDA boolean tensor with exact shape [state_limit]; an empty state set carries a defined empty mask. The Python Scene.trace_dfr_paths(...) entry requires the keyword, and neither the typed API nor dispatcher accepts omitted, None, broadcast, or strided validity. Diffraction accumulation and coherent-accumulation contracts are unchanged. See docs/adr/0031-required-diffraction-path-validity.md.

The typed boundary also carries a dormant axial-edge visibility candidate for device-resident diffraction state selection. It consumes broadcast TX and contiguous AoS edge tensors, evaluates the four exact binary32 fractions in one separate OptiX launch on the caller's current CUDA stream, and returns a resident boolean state mask. Its traversal inherits the legacy OptiX compile policy while inline PTX locks only point construction to non-FTZ, non-FMA round-to-nearest operations. The legacy visibility dispatcher is unchanged and cannot select this entry. The operation adds no synchronization beyond the existing common launch-parameter staging path; removing that staging path's host event wait is a separate optimization. See docs/adr/0029-typed-axial-edge-visibility.md.

API version 5 adds an explicit DiffractionPathLayout to the typed order-1 exporter. Existing callers retain Compact; same-graph consumers may request SourceLane, where the fixed row is ((tx * rx_count + rx) * state_limit) + state. Rejected lanes remain inert and the CUDA count remains actual-count metadata rather than a storage ordinal. Both layouts use the same traversal and UTD implementation. See docs/adr/0032-source-lane-diffraction-path-layout.md.

API version 6 adds the dormant complete batched segment-penetration family. Each non-empty structurally active forward call submits one OptiX launch and performs its ordered D+1 capacity probe in raygen; an explicit structurally all-inactive call uses only a same-stream CUDA mask consistency check. Results and tapes use fixed [N,D] storage and the caller's shared device failure transaction. Backward/JVP use frozen winners and never retrace. RayD exposes no Python dispatcher for this family, and Channel retains material and wall-product policy. See docs/adr/0033-batched-segment-penetration.md.

RayD Torch carries all seventeen typed operations. Channel has activated the Phase 10A table, sampling, single-bounce ensemble, and patch-integral entries. The six Phase 10B chain entries are source-linked into the native core and direct-tested but remain dormant: no RayD Python binding dispatches them, and Channel remains their production numerical owner until its atomic pin/switch/delete commit.

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 torch_gap_analysis.md and

Dependencies

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

rayd_torch-0.8.0-cp314-cp314-win_amd64.whl (18.6 MB view details)

Uploaded CPython 3.14Windows x86-64

rayd_torch-0.8.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (19.0 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

rayd_torch-0.8.0-cp313-cp313-win_amd64.whl (18.7 MB view details)

Uploaded CPython 3.13Windows x86-64

rayd_torch-0.8.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (19.0 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

rayd_torch-0.8.0-cp312-cp312-win_amd64.whl (18.7 MB view details)

Uploaded CPython 3.12Windows x86-64

rayd_torch-0.8.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (19.0 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

rayd_torch-0.8.0-cp311-cp311-win_amd64.whl (18.7 MB view details)

Uploaded CPython 3.11Windows x86-64

rayd_torch-0.8.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (19.0 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

rayd_torch-0.8.0-cp310-cp310-win_amd64.whl (18.7 MB view details)

Uploaded CPython 3.10Windows x86-64

rayd_torch-0.8.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (19.0 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

File details

Details for the file rayd_torch-0.8.0-cp314-cp314-win_amd64.whl.

File metadata

  • Download URL: rayd_torch-0.8.0-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 18.6 MB
  • Tags: CPython 3.14, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for rayd_torch-0.8.0-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 9142345327c3614025a0f4d9fec76de126922ac0dbb957b98cb377b65542645d
MD5 4d5f58f905cc2f2e0fc17d5cea50dc5a
BLAKE2b-256 7145cb1a5f96454e33665c7615b7362caee7e4fc3702f69343115b499e64ed67

See more details on using hashes here.

Provenance

The following attestation bundles were made for rayd_torch-0.8.0-cp314-cp314-win_amd64.whl:

Publisher: pypi.yml on Asixa/RayD

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rayd_torch-0.8.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rayd_torch-0.8.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b5457bbe2d560a4457d4adb2fe163b433515f5b98384a11622d8a67cd87425b4
MD5 743e3bb7ae828ca5a3c42371fb5a4a77
BLAKE2b-256 338c1693444d1068413ba9de6d6c3237844187af04df51ffac64de79991db687

See more details on using hashes here.

Provenance

The following attestation bundles were made for rayd_torch-0.8.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: pypi.yml on Asixa/RayD

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rayd_torch-0.8.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: rayd_torch-0.8.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 18.7 MB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for rayd_torch-0.8.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 244e6d6c22040f3c1a8868b710fc64488ff8c02b875471c2ff9b827f0ace1b5f
MD5 319c2a29629488b87137df30bf14ad46
BLAKE2b-256 f2904299221004ef7f91fe751a67fe296b543d785038d3e0c7d6434379a127b4

See more details on using hashes here.

Provenance

The following attestation bundles were made for rayd_torch-0.8.0-cp313-cp313-win_amd64.whl:

Publisher: pypi.yml on Asixa/RayD

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rayd_torch-0.8.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rayd_torch-0.8.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 bc09d6c4cb68de3c7dc39690581635ec6545118cc8e2478b58618fc3b8683a98
MD5 89e36cd03cad4d7727f8cfa255e523e6
BLAKE2b-256 2c7f766b709a3ffed5388a75ded000c637adcab5402c640390c881ab528b469a

See more details on using hashes here.

Provenance

The following attestation bundles were made for rayd_torch-0.8.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: pypi.yml on Asixa/RayD

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rayd_torch-0.8.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: rayd_torch-0.8.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 18.7 MB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for rayd_torch-0.8.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 af848c81d46f4aace48ea04757aae344b0d0c6aa68f3789757d8919508eb9f3a
MD5 6a6ca36b341f0d15b322a100accf7375
BLAKE2b-256 059c39516314d361bfdd6a79ed7f1612304966aaf3a0b7ed372d866497cfb93a

See more details on using hashes here.

Provenance

The following attestation bundles were made for rayd_torch-0.8.0-cp312-cp312-win_amd64.whl:

Publisher: pypi.yml on Asixa/RayD

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rayd_torch-0.8.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rayd_torch-0.8.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 353046e022e6041e4b5e890dd6e19e32f44257ac07e89bb859cfdd89eadf205b
MD5 487f0b54de3ce47ca5f5c97bd0b1d003
BLAKE2b-256 7a147a6d86985cb7135ee699a0ffc5722159f4ff9c678a07842bdc7c70dcbba5

See more details on using hashes here.

Provenance

The following attestation bundles were made for rayd_torch-0.8.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: pypi.yml on Asixa/RayD

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rayd_torch-0.8.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: rayd_torch-0.8.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 18.7 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for rayd_torch-0.8.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 c477d476895aaf12ae2ea0c6c6135e9b46cfb6e790d46396331b390822f8639d
MD5 507a14e496b4fcf60b0f539848aa8505
BLAKE2b-256 b440690b698dc5e3c121dda0d532ee6d38f533d6d5f349b34854e523cbc1192d

See more details on using hashes here.

Provenance

The following attestation bundles were made for rayd_torch-0.8.0-cp311-cp311-win_amd64.whl:

Publisher: pypi.yml on Asixa/RayD

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rayd_torch-0.8.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rayd_torch-0.8.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 24704293c3c72ca3252178f7a94718429936bdae1466252bfc550c36ed427d16
MD5 1718dcdbeb358dd2cf8c72a0d9ffc499
BLAKE2b-256 1750745468aec5a8b5cf89350aaa29738b4008750b04cc6a03f728bd6027f4af

See more details on using hashes here.

Provenance

The following attestation bundles were made for rayd_torch-0.8.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: pypi.yml on Asixa/RayD

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rayd_torch-0.8.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: rayd_torch-0.8.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 18.7 MB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for rayd_torch-0.8.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 6e98bccaddc45c56333696ce5c08f76b8fb942132bf1c126145ce77f7d9abc75
MD5 0f0161861a99f1d614d140ba09144fb9
BLAKE2b-256 0a58b538f7019cf468ce3f8d328caed2b3b633711263194a2b4156237a7abb4f

See more details on using hashes here.

Provenance

The following attestation bundles were made for rayd_torch-0.8.0-cp310-cp310-win_amd64.whl:

Publisher: pypi.yml on Asixa/RayD

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rayd_torch-0.8.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rayd_torch-0.8.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5b389b2b9382470aa95ba43077f7830a3090523641125ff6265ca208babdde35
MD5 f64c0751c2aef9c7d0c82838c6e8694f
BLAKE2b-256 1f87a33dd930b79771193c6683d8b120f8457e85a43cc3864008f90145468149

See more details on using hashes here.

Provenance

The following attestation bundles were made for rayd_torch-0.8.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: pypi.yml on Asixa/RayD

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.8.0 This release

10 files

0.7.0

10 files

0.6.0

10 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page