Differentiation

RayD differentiates the continuous quantities of a query while it holds the discrete choices of the forward pass fixed. This page explains that contract, how you turn AD on in each backend, and which operations support reverse mode (VJP) and forward mode (JVP).

The fixed-winner contract#

Every ray query makes discrete decisions: which triangle a ray hits, which edge is nearest, whether a segment is blocked, which reflectors form a path. RayD makes those decisions in a detached forward pass, then recomputes the continuous result on the winning primitive with the AD-tracked inputs.

• Discrete, no gradient: primitive ids, edge ids, visibility masks, path selection, bounce counts.
• Continuous, differentiable: hit distance t, hit position, normals, UVs, barycentrics, edge distances and closest points, reflection points and image sources, supported field quantities.
• Inputs that receive gradients: vertex positions, mesh and instance transforms, ray origins and directions, query points, SDF values and placement, surfel fields, and material parameters where the operation supports them.

The derivative is therefore the derivative of the result while the same primitive stays the winner. It does not include the change caused by a ray switching to a different triangle, or a silhouette moving across a pixel. Those boundary terms need edge sampling, which you build on top of RayD's edge queries; see Edges and edge sampling.

Turning AD on#

dr.enable_grad(vertices)
mesh.vertex_positions = vertices
# ... build the scene ...
hit = scene.intersect(rd.RayAD(origins, directions))
dr.backward(dr.sum(hit.t))      # reverse mode (VJP)
grad = dr.grad(vertices)

Support by operation#

The table shows the 0.8.0 status from api_manifest()["derivatives"], written as VJP / JVP. "Supported" means implemented and tested for that input; "unsupported" means the derivative exists mathematically but RayD does not provide it on that path; "n/a" means the output has no derivative (it is a mask).

In the Torch backend, an operation marked "forward only" raises RuntimeError when any of its inputs requires a gradient or carries a forward-AD tangent. It never returns a silently detached result. Detach the inputs yourself if you want the primal value only.

Read the status at run time instead of hard-coding it:

status = rt.api_manifest()["derivatives"]["reflection_accumulation"]["accumulate_reflections"]
print(status["input_domains"]["geometry"])   # {'vjp': 'unsupported', 'jvp': 'unsupported'}
print(status["note"])                         # why, in one sentence

Practical consequences#

• Mask invalid lanes before you reduce. A missed ray has t = inf; sum dr.select(hit.is_valid(), hit.t, 0) (or torch.where) instead of hit.t.
• Gradients are exact for the frozen winner, so finite differences agree only while the perturbation keeps the same primitive. Use small steps when you check gradients.
• Visibility results are masks. If your objective depends on occlusion, it is piecewise constant in RayD, and you need an edge-sampling estimator for its gradient.