rayd 0.1.0__tar.gz

rayd-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,179 @@
+name: Build And Publish PyPI Wheels
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+jobs:
+  build_linux_wheels:
+    name: linux / manylinux_2_28
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build Linux wheels
+        uses: pypa/cibuildwheel@v3.3.0
+        env:
+          CIBW_BUILD: "cp310-manylinux_x86_64 cp311-manylinux_x86_64 cp312-manylinux_x86_64 cp313-manylinux_x86_64"
+          CIBW_SKIP: "*-musllinux_*"
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+          CIBW_BEFORE_ALL_LINUX: >-
+            dnf install -y dnf-plugins-core gcc-toolset-13 &&
+            rpm --import https://developer.download.nvidia.com/compute/cuda/repos/rhel8/x86_64/D42D0685.pub &&
+            dnf config-manager --add-repo https://developer.download.nvidia.com/compute/cuda/repos/rhel8/x86_64/cuda-rhel8.repo &&
+            dnf clean expire-cache &&
+            dnf install -y cuda-toolkit-12-5 &&
+            ln -sfn /usr/local/cuda-12.5 /usr/local/cuda &&
+            /usr/local/cuda/bin/nvcc --version
+          CIBW_ENVIRONMENT_LINUX: >-
+            CUDA_HOME=/usr/local/cuda
+            CUDA_PATH=/usr/local/cuda
+            CUDA_ROOT=/usr/local/cuda
+            CUDA_BIN_PATH=/usr/local/cuda
+            CUDACXX=/usr/local/cuda/bin/nvcc
+            CC=/opt/rh/gcc-toolset-13/root/usr/bin/gcc
+            CXX=/opt/rh/gcc-toolset-13/root/usr/bin/g++
+            CUDAHOSTCXX=/opt/rh/gcc-toolset-13/root/usr/bin/g++
+            PATH=/usr/local/cuda/bin:$PATH
+            LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
+          CIBW_REPAIR_WHEEL_COMMAND_LINUX: >-
+            auditwheel repair
+            --exclude libcuda.so.1
+            --exclude libnvoptix.so.1
+            --exclude libdrjit-core.so
+            --exclude libdrjit-extra.so
+            --exclude libnanothread.so
+            -w {dest_dir} {wheel}
+        with:
+          output-dir: dist
+
+      - name: Upload Linux wheel artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux
+          path: dist/*.whl
+          if-no-files-found: error
+
+  build_windows_wheels:
+    name: windows / py${{ matrix.python_version }}
+    runs-on: windows-2022
+    strategy:
+      fail-fast: false
+      matrix:
+        python_version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python_version }}
+
+      - name: Install CUDA Toolkit
+        uses: Jimver/cuda-toolkit@v0.2.29
+        with:
+          cuda: "12.5.0"
+          method: local
+          log-file-suffix: "windows-py${{ matrix.python_version }}.log"
+
+      - name: Show toolchain
+        shell: bash
+        run: |
+          python --version
+          cmake --version || true
+          nvcc --version
+
+      - name: Install build frontend
+        run: python -m pip install --upgrade pip build cmake ninja
+
+      - name: Build wheel
+        env:
+          CMAKE_BUILD_PARALLEL_LEVEL: "4"
+        run: python -m build --wheel
+
+      - name: Upload Windows wheel artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-windows-py${{ matrix.python_version }}
+          path: dist/*.whl
+          if-no-files-found: error
+
+  build_sdist:
+    name: sdist
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build frontend
+        run: python -m pip install --upgrade pip build
+
+      - name: Build source distribution
+        run: python -m build --sdist
+
+      - name: Upload sdist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    name: Publish To PyPI
+    if: github.event_name == 'release' && github.event.action == 'published'
+    needs:
+      - build_linux_wheels
+      - build_windows_wheels
+      - build_sdist
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/rayd
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download wheel artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          pattern: wheels-*
+          merge-multiple: true
+
+      - name: Download sdist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Remove non-package files
+        shell: bash
+        run: find dist -maxdepth 1 -type f ! \( -name '*.whl' -o -name '*.tar.gz' \) -delete
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          verbose: true

rayd-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+*.o
+*.so
+*.log
+*.exe
+__pycache__
+build/
+ext_win64/
+local/
+scripts/
+AGENTS.md
+claude.md
+dev_notes.md
+dist/
+tmp/
+**/*.log
+unit_test/*.exr
+unit_test/inv_test/
+unit_test/result/
+.ipynb_checkpoints
+.vscode/
+.claude

rayd-0.1.0/CMakeLists.txt

@@ -0,0 +1,217 @@
+cmake_minimum_required(VERSION 3.15...3.22)
+if(POLICY CMP0146)
+    cmake_policy(SET CMP0146 OLD)
+endif()
+
+project(${SKBUILD_PROJECT_NAME} VERSION ${SKBUILD_PROJECT_VERSION})
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+option(RAYD_OPTIX_PRODUCTION_CONFIG "Use OptiX production module settings (LEVEL_3 + no exceptions)." ON)
+option(RAYD_NANOBIND_NOMINSIZE "Disable nanobind's size-oriented optimization flags in optimized configs." ON)
+option(RAYD_ENABLE_LTO "Enable nanobind/C++ link-time optimization." OFF)
+
+find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
+execute_process(
+    COMMAND "${Python_EXECUTABLE}" -c "import importlib.util, pathlib, sys; spec = importlib.util.find_spec('drjit'); sys.stdout.write(str(pathlib.Path(next(iter(spec.submodule_search_locations))).resolve() / 'cmake')) if spec and spec.submodule_search_locations else sys.exit(1)"
+    RESULT_VARIABLE DRJIT_CMAKE_DIR_RESULT
+    OUTPUT_VARIABLE DRJIT_CMAKE_DIR
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+if(NOT DRJIT_CMAKE_DIR_RESULT EQUAL 0)
+    message(FATAL_ERROR "Could not locate the installed Dr.Jit CMake package. Ensure drjit>=1.3.0 is installed in the build environment.")
+endif()
+
+execute_process(
+    COMMAND "${Python_EXECUTABLE}" -c "import importlib.util, pathlib, sys; spec = importlib.util.find_spec('nanobind'); sys.stdout.write(str(pathlib.Path(next(iter(spec.submodule_search_locations))).resolve() / 'cmake')) if spec and spec.submodule_search_locations else sys.exit(1)"
+    RESULT_VARIABLE NANOBIND_CMAKE_DIR_RESULT
+    OUTPUT_VARIABLE NANOBIND_CMAKE_DIR
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+if(NOT NANOBIND_CMAKE_DIR_RESULT EQUAL 0)
+    message(FATAL_ERROR "Could not locate the installed nanobind CMake package.")
+endif()
+
+list(PREPEND CMAKE_PREFIX_PATH "${DRJIT_CMAKE_DIR}" "${NANOBIND_CMAKE_DIR}")
+find_package(drjit CONFIG REQUIRED)
+find_package(nanobind CONFIG REQUIRED)
+
+if(WIN32)
+    add_definitions(-D_USE_MATH_DEFINES -D_CRT_SECURE_NO_WARNINGS)
+else()
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wno-reorder -Wno-sign-compare -fPIC")
+    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3 -DNDEBUG")
+    set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -O3 -DNDEBUG")
+endif()
+
+option(BUILD_SHARED_LIBS "Build shared libraries" ON)
+
+if(RAYD_OPTIX_PRODUCTION_CONFIG)
+    set(RAYD_OPTIX_MODULE_OPT_LEVEL 0x2343)
+    set(RAYD_OPTIX_EXCEPTION_FLAGS 0)
+else()
+    set(RAYD_OPTIX_MODULE_OPT_LEVEL 0x2340)
+    set(RAYD_OPTIX_EXCEPTION_FLAGS 11)
+endif()
+
+find_package(CUDA 11.0 REQUIRED)
+set(CUDA_PROPAGATE_HOST_FLAGS OFF)
+mark_as_advanced(CLEAR CUDA_64_BIT_DEVICE_CODE)
+
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+
+include_directories(
+    include/
+    ${CMAKE_CURRENT_SOURCE_DIR}
+    ${CMAKE_CURRENT_BINARY_DIR}
+    ${CUDA_INCLUDE_DIRS}
+)
+
+set(RAYD_INCLUDE_DIR include/rayd)
+set(RAYD_SOURCE_DIR src)
+set(RAYD_CORE_SOURCE_FILES
+    ${RAYD_INCLUDE_DIR}/rayd.h
+    ${RAYD_INCLUDE_DIR}/constants.h
+    ${RAYD_INCLUDE_DIR}/fwd.h
+    ${RAYD_INCLUDE_DIR}/types.h
+    ${RAYD_INCLUDE_DIR}/utils.h
+
+    ${RAYD_INCLUDE_DIR}/ray.h
+    ${RAYD_INCLUDE_DIR}/intersection.h
+    ${RAYD_INCLUDE_DIR}/transform.h
+
+    ${RAYD_INCLUDE_DIR}/edge.h
+
+    ${RAYD_INCLUDE_DIR}/mesh.h
+    ${RAYD_SOURCE_DIR}/mesh.cpp
+
+    ${RAYD_INCLUDE_DIR}/optix.h
+
+    ${RAYD_INCLUDE_DIR}/camera.h
+    ${RAYD_SOURCE_DIR}/camera.cpp
+
+    ${RAYD_INCLUDE_DIR}/scene/scene_optix.h
+    ${RAYD_SOURCE_DIR}/scene/scene_optix.cpp
+    ${RAYD_INCLUDE_DIR}/scene/scene_edge.h
+    ${RAYD_SOURCE_DIR}/scene/scene_edge.cpp
+    ${RAYD_SOURCE_DIR}/scene/edge_bvh.h
+
+    ${RAYD_INCLUDE_DIR}/scene/scene.h
+    ${RAYD_SOURCE_DIR}/scene/scene.cpp
+
+    ${RAYD_SOURCE_DIR}/optix.cpp
+)
+if(WIN32)
+    set(RAYD_CUDA_OBJECT "${CMAKE_CURRENT_BINARY_DIR}/edge_bvh.obj")
+    set(RAYD_VSDEVCMD "${CMAKE_GENERATOR_INSTANCE}/Common7/Tools/VsDevCmd.bat")
+    set(RAYD_CUDA_BUILD_SCRIPT "${CMAKE_CURRENT_BINARY_DIR}/build_edge_bvh.bat")
+    file(GENERATE OUTPUT "${RAYD_CUDA_BUILD_SCRIPT}" CONTENT
+"@echo off\r\n\
+call \"${RAYD_VSDEVCMD}\" -arch=x64\r\n\
+if errorlevel 1 exit /b %errorlevel%\r\n\
+\"${CUDA_NVCC_EXECUTABLE}\" --extended-lambda -std=c++17 -c \"${CMAKE_CURRENT_SOURCE_DIR}/${RAYD_SOURCE_DIR}/scene/edge_bvh.cu\" -I\"${CMAKE_CURRENT_SOURCE_DIR}/include\" -I\"${CMAKE_CURRENT_SOURCE_DIR}\" -Xcompiler \"/MD /O2 /EHsc /wd4819\" -o \"${RAYD_CUDA_OBJECT}\"\r\n\
+")
+    add_custom_command(
+        OUTPUT "${RAYD_CUDA_OBJECT}"
+        COMMAND "${RAYD_CUDA_BUILD_SCRIPT}"
+        DEPENDS
+            "${RAYD_CUDA_BUILD_SCRIPT}"
+            "${CMAKE_CURRENT_SOURCE_DIR}/${RAYD_SOURCE_DIR}/scene/edge_bvh.cu"
+            "${CMAKE_CURRENT_SOURCE_DIR}/${RAYD_SOURCE_DIR}/scene/edge_bvh.h"
+        VERBATIM
+    )
+else()
+    set(RAYD_CUDA_OBJECT "${CMAKE_CURRENT_BINARY_DIR}/edge_bvh.o")
+    add_custom_command(
+        OUTPUT "${RAYD_CUDA_OBJECT}"
+        COMMAND "${CUDA_NVCC_EXECUTABLE}" -ccbin "${CMAKE_CXX_COMPILER}" -std=c++17 -Xcompiler=-fPIC -c
+                "${CMAKE_CURRENT_SOURCE_DIR}/${RAYD_SOURCE_DIR}/scene/edge_bvh.cu"
+                -I"${CMAKE_CURRENT_SOURCE_DIR}/include"
+                -I"${CMAKE_CURRENT_SOURCE_DIR}"
+                -o "${RAYD_CUDA_OBJECT}"
+        DEPENDS
+            "${CMAKE_CURRENT_SOURCE_DIR}/${RAYD_SOURCE_DIR}/scene/edge_bvh.cu"
+            "${CMAKE_CURRENT_SOURCE_DIR}/${RAYD_SOURCE_DIR}/scene/edge_bvh.h"
+        VERBATIM
+    )
+endif()
+set_source_files_properties("${RAYD_CUDA_OBJECT}" PROPERTIES EXTERNAL_OBJECT TRUE GENERATED TRUE)
+list(APPEND RAYD_CORE_SOURCE_FILES "${RAYD_CUDA_OBJECT}")
+
+set(RAYD_NANOBIND_ARGS NB_DOMAIN drjit)
+if(RAYD_NANOBIND_NOMINSIZE)
+    list(APPEND RAYD_NANOBIND_ARGS NOMINSIZE)
+endif()
+if(RAYD_ENABLE_LTO)
+    list(APPEND RAYD_NANOBIND_ARGS LTO)
+endif()
+
+add_library(rayd_core STATIC ${RAYD_CORE_SOURCE_FILES})
+target_include_directories(rayd_core PUBLIC
+    ${CMAKE_CURRENT_SOURCE_DIR}/include
+    ${CMAKE_CURRENT_SOURCE_DIR}
+    ${CMAKE_CURRENT_BINARY_DIR}
+    ${CUDA_INCLUDE_DIRS}
+)
+target_compile_definitions(rayd_core PRIVATE
+    RAYD_OPTIX_MODULE_OPT_LEVEL=${RAYD_OPTIX_MODULE_OPT_LEVEL}
+    RAYD_OPTIX_EXCEPTION_FLAGS=${RAYD_OPTIX_EXCEPTION_FLAGS}
+)
+
+if(WIN32)
+    target_compile_options(rayd_core PRIVATE
+        $<$<COMPILE_LANGUAGE:CXX>:/wd4251>
+        $<$<COMPILE_LANGUAGE:CXX>:/MP>
+        $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:Release>>:/O2>
+        $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:RelWithDebInfo>>:/O2>
+        $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:MinSizeRel>>:/O2>
+    )
+endif()
+
+set(PYRAYD_LIBRARIES drjit drjit-core drjit-extra nanothread)
+if(WIN32)
+    list(APPEND PYRAYD_LIBRARIES version)
+endif()
+target_link_libraries(rayd_core PUBLIC ${PYRAYD_LIBRARIES} ${CUDA_LIBRARIES})
+set_property(TARGET rayd_core PROPERTY CXX_STANDARD 17)
+set_target_properties(rayd_core PROPERTIES
+    POSITION_INDEPENDENT_CODE ON
+)
+
+nanobind_add_module(rayd ${RAYD_NANOBIND_ARGS} ${RAYD_SOURCE_DIR}/rayd.cpp)
+target_link_libraries(rayd PRIVATE rayd_core)
+if(WIN32)
+    target_compile_options(rayd PRIVATE
+        $<$<COMPILE_LANGUAGE:CXX>:/wd4251>
+        $<$<COMPILE_LANGUAGE:CXX>:/MP>
+        $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:Release>>:/O2>
+        $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:RelWithDebInfo>>:/O2>
+        $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:MinSizeRel>>:/O2>
+    )
+endif()
+
+install(TARGETS rayd DESTINATION rayd)
+install(TARGETS rayd_core
+    ARCHIVE DESTINATION rayd/lib
+    LIBRARY DESTINATION rayd/lib
+    RUNTIME DESTINATION rayd/bin
+)
+install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/rayd
+    DESTINATION .
+    FILES_MATCHING
+        PATTERN "*.h"
+        PATTERN "*.slang"
+)
+
+set_target_properties(rayd PROPERTIES
+    SKIP_BUILD_RPATH FALSE
+    BUILD_WITH_INSTALL_RPATH FALSE
+    INSTALL_RPATH "$ORIGIN"
+    INSTALL_RPATH_USE_LINK_PATH TRUE
+)
+set_property(TARGET rayd PROPERTY CXX_STANDARD 17)
+set_target_properties(rayd PROPERTIES PREFIX "")
+

rayd-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.2
+Name: rayd
+Version: 0.1.0
+Summary: RayD: minimalist differentiable ray tracing package wrapping Dr.Jit and OptiX.
+Author: Xingyu Chen
+Requires-Python: >=3.10
+Requires-Dist: drjit>=1.3.0
+Provides-Extra: torch
+Requires-Dist: torch; extra == "torch"
+Description-Content-Type: text/markdown
+
+# RayD
+
+RayD is a minimalist differentiable ray tracing package built on top of Dr.Jit and OptiX.
+
+```bash
+pip install rayd
+```
+
+RayD is not a full renderer. It is a thin wrapper around Dr.Jit and OptiX for building your own renderers and simulators.
+
+The goal is simple: expose differentiable ray-mesh intersection on the GPU without bringing in a full graphics framework.
+
+## Why RayD?
+
+RayD is for users who want OptiX acceleration and autodiff, but do not want a full renderer.
+
+Why not `Mitsuba`? `Mitsuba` is excellent for graphics rendering, but often too high-level for RF, acoustics, sonar, or custom wave simulation. In those settings, direct access to ray-scene queries and geometry gradients is usually more useful than a full material-light-integrator stack.
+
+RayD keeps only the geometric core:
+
+- differentiable ray-mesh intersection
+- scene-level GPU acceleration through OptiX
+- edge acceleration structures for nearest-edge queries
+- primary-edge sampling support for edge-based gradient terms
+
+For intersection workloads, RayD targets Mitsuba-level performance and matching results with a much smaller API surface.
+
+## What RayD Provides
+
+- `Mesh`: triangle geometry, transforms, UVs, and edge topology
+- `Scene`: a container of meshes plus OptiX acceleration
+- `scene.intersect(ray)`: differentiable ray-mesh intersection
+- `scene.nearest_edge(query)`: nearest-edge queries for points and rays
+- edge acceleration data that is useful for edge sampling and edge diffraction methods
+
+## PyTorch Wrapper
+
+RayD also provides an optional `rayd.torch` module implemented at the Python package layer.
+
+`rayd.torch` mirrors the core `rayd` API:
+
+- `rayd.torch.Mesh`
+- `rayd.torch.Scene`
+- `rayd.torch.Camera`
+- `rayd.torch.Ray` / `rayd.torch.RayDetached`
+- the same intersection and nearest-edge result types
+
+Key conventions:
+
+- array inputs and outputs use CUDA `torch.Tensor`
+- vectors use shape `(N, 3)` or `(N, 2)`; `(3,)` and `(2,)` are accepted as batch size `1`
+- index tensors use shape `(F, 3)`
+- images use shape `(H, W)`
+- transforms use shape `(4, 4)`
+- CPU tensors are rejected; `rayd.torch` does not do implicit device transfers
+
+The original `rayd` Dr.Jit API remains unchanged and does not depend on PyTorch.
+
+## Quick Examples
+
+If you only want to see the package in action, start here:
+
+- [`examples/basics/ray_mesh_intersection.py`](examples/basics/ray_mesh_intersection.py): custom rays against a mesh
+- [`examples/basics/nearest_edge_query.py`](examples/basics/nearest_edge_query.py): nearest-edge queries
+- [`examples/basics/camera_edge_sampling_gradient.py`](examples/basics/camera_edge_sampling_gradient.py): camera-driven edge-sampling gradients
+- [`docs/slang_interop.md`](docs/slang_interop.md): Slang `cpp` target interop for host-side RayD scene queries
+
+Build meshes, put them in a scene, launch rays, define a loss, and backpropagate through geometry.
+
+## Minimal Differentiable Ray Tracing Example
+
+The example below traces a single ray against one triangle and backpropagates the hit distance to the vertex positions.
+
+```python
+import rayd as rd
+import drjit as dr
+import drjit.cuda as cuda
+import drjit.cuda.ad as ad
+
+
+mesh = rd.Mesh(
+    cuda.Array3f([0.0, 1.0, 0.0],
+                 [0.0, 0.0, 1.0],
+                 [0.0, 0.0, 0.0]),
+    cuda.Array3i([0], [1], [2]),
+)
+
+verts = ad.Array3f(
+    [0.0, 1.0, 0.0],
+    [0.0, 0.0, 1.0],
+    [0.0, 0.0, 0.0],
+)
+dr.enable_grad(verts)
+
+mesh.vertex_positions = verts
+
+scene = rd.Scene()
+scene.add_mesh(mesh)
+scene.configure()
+
+ray = rd.Ray(
+    ad.Array3f([0.25], [0.25], [-1.0]),
+    ad.Array3f([0.0], [0.0], [1.0]),
+)
+
+its = scene.intersect(ray)
+loss = dr.sum(its.t)
+dr.backward(loss)
+
+print("t =", its.t)
+print("grad z =", dr.grad(verts)[2])
+```
+
+This is the core RayD workflow. Replace the single ray with your own batched rays, RF paths, acoustic paths, or edge-based objectives.
+
+## Edge Acceleration Structure
+
+RayD also provides a scene-level edge acceleration structure.
+
+This is useful for:
+
+- edge sampling
+- nearest-edge queries
+- visibility-boundary terms
+- geometric edge diffraction models
+
+In other words, RayD is not limited to triangle hits. It also gives you direct access to edge-level geometry queries, which are important in many non-graphics simulators.
+
+## Compiling Locally
+
+RayD is a Python package with a C++/CUDA extension.
+
+You need Python `>=3.10`, CUDA Toolkit `>=11.0`, CMake, a C++17 compiler, `drjit>=1.3.0`, `nanobind==2.11.0`, and `scikit-build-core`.
+
+On Windows, use Visual Studio 2022 with Desktop C++ tools. On Linux, use GCC or Clang with C++17 support.
+
+### Recommended environment
+
+```powershell
+conda create -n myenv python=3.10 -y
+conda activate myenv
+python -m pip install -U pip setuptools wheel
+python -m pip install cmake scikit-build-core nanobind==2.11.0
+python -m pip install "drjit>=1.3.0"
+```
+
+### Install
+
+```powershell
+conda activate myenv
+python -m pip install .
+```
+
+## Dependencies
+
+RayD depends on:
+
+- Python `3.10+`
+- Dr.Jit `1.3.0+`
+- OptiX `8+`
+
+RayD does not include:
+
+- BSDFs
+- emitters
+- integrators
+- scene loaders
+- image I/O
+- path tracing infrastructure
+
+That is by design.
+
+## Repository Layout
+
+- [`include/rayd/`](include/rayd): public C++ headers
+- [`src/`](src): C++ and CUDA implementation
+- [`src/rayd.cpp`](src/rayd.cpp): Python bindings
+- [`include/rayd/slang/interop.h`](include/rayd/slang/interop.h): C++ POD/handle bridge for Slang
+- [`include/rayd/slang/rayd.slang`](include/rayd/slang/rayd.slang): Slang declarations for the C++ interop layer
+- [`examples/`](examples): basic and renderer-side examples
+- [`tests/test_geometry.py`](tests/test_geometry.py): geometry regression tests
+- [`docs/api_reference.md`](docs/api_reference.md): Python API reference
+- [`docs/slang_interop.md`](docs/slang_interop.md): Slang interop notes and examples
+
+## Testing
+
+```powershell
+python -m unittest tests.test_geometry -v
+```
+
+Optional PyTorch wrapper tests:
+
+```powershell
+python -m unittest tests.test_torch_geometry -v
+```
+
+## Credits
+
+RayD is developed with reference to:
+
+- [psdr-jit](https://github.com/andyyankai/psdr-jit)
+- [redner](https://github.com/BachiLi/redner)
+- [mitsuba3](https://github.com/mitsuba-renderer/mitsuba3)
+
+## Citation
+
+```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
+
+MIT