warp.JetSpace#

warp.JetSpace(slots, dtype=None, *, width=None)[source]#

Return the jet types and helpers for a set of differentiated inputs.

Experimental

Forward-mode jets are experimental and subject to change without a formal deprecation cycle.

A jet is a value paired with its first derivatives along a fixed set of directions. Arithmetic on jets updates the derivatives alongside the value, so evaluating a function on jets computes its derivatives in the same pass. This is forward-mode automatic differentiation, in contrast to the reverse-mode differentiation of warp.grad() and warp.Tape. Jets are ordinary Warp types, so reverse mode can also differentiate through code that uses them.

The first call for a given width and scalar type generates the types and registers their arithmetic as overloads of Warp’s builtins; later calls return a namespace over the same types.

Parameters:
  • slots – The inputs differentiated with respect to. Either an integer n, meaning n scalar inputs, or a sequence of types, one per input: warp.float32, warp.vec2, warp.vec3, warp.quat, warp.mat22, warp.mat33, warp.mat32 or warp.mat23. A spring over two nodes is (warp.vec3, warp.vec3).

  • dtype – Scalar type the jets are built on. Inferred from slots when they are Warp types; warp.float32 when slots is an integer or contains only Python float.

  • width – Number of derivative directions each jet carries. Defaults to the total number of scalar components in slots, in which case seed seeds the unit directions and a jet carries the full gradient. A smaller width carries only the directions passed to directional, which is cheaper when only a few projections of the gradient are needed.

Returns:

A namespace holding the generated jet types (scalar, vec2, vec3, quat, mat22, mat33, mat32, mat23), the type of each one’s grad field (grad_type_scalar, grad_type_vec2, and so on through grad_type_mat23), the helpers that construct jets, including exp_map, which maps a vec3 rotation-vector jet to a unit quaternion jet, and slots, the native type of each slot.

Jets are created inside a kernel or function with seed or directional. With spring_energy an ordinary @warp.func that is generic over its argument types:

J = wp.JetSpace((wp.vec3, wp.vec3))  # two 3D points, width 6


@wp.func
def spring_gradient(x0: wp.vec3, x1: wp.vec3):
    # x0_jet and x1_jet are J.vec3: x0_jet carries directions 0-2, x1_jet 3-5.
    x0_jet, x1_jet = J.seed(x0, x1)
    return spring_energy(x0_jet, x1_jet).grad  # the 6-component gradient

seed(*values) takes one value per slot and returns one jet per slot, with the derivative directions numbered slot by slot in the order the components appear (row-major for matrices). With a single slot it takes and returns the bare value. It is available only when width equals the number of components; otherwise use directional.

directional(*values, *directions) takes the same values, followed by width * len(slots) direction vectors ordered direction-major: direction q of slot s is argument q * len(slots) + s after the values. For example, for a width-1 space the directions are one value per slot, and the jets carry the derivative along the combined direction:

J1 = wp.JetSpace((wp.vec3, wp.vec3), width=1)


@wp.func
def spring_directional_derivative(x0: wp.vec3, x1: wp.vec3, v0: wp.vec3, v1: wp.vec3):
    # Derivative along the combined direction (v0, v1).
    x0_jet, x1_jet = J1.directional(x0, x1, v0, v1)
    return spring_energy(x0_jet, x1_jet).grad[0]

variable(x, direction) is the underlying scalar primitive: a scalar jet with a unit derivative along direction. Use it to seed in a loop, where the number of scalars is not a fixed argument list.

jet_type(t) and grad_type(t) look the types up by the Warp type of the value instead: J.grad_type(warp.vec2) is J.grad_type_vec2. They are Python functions, so they work in annotations and host code, such as warp.array[J.grad_type(warp.vec2)], but cannot be called inside a kernel or @warp.func, where the attributes are needed. A type whose scalar type differs from the space’s, or that the space does not support, raises TypeError.

width is fixed when the types are specialized, not when a kernel runs: it becomes the length of grad and is unrolled into the generated code. Every intermediate value carries all width derivative components, so cost in registers and compile time scales with the width requested, regardless of how many components are read back. Different widths are independent specializations that may coexist in one process.

This makes jets suited to local derivatives of fixed arity – a spring over two vec3 nodes has width 6, a triangle 9, a tetrahedron 12 – where the layout is known where the kernel is written and the dense local gradient or Hessian block is scattered into a sparse global matrix. They are not suited to differentiating with respect to an unbounded or runtime number of variables: a problem-sized width cannot specialize a type, and even when it could, forward mode would cost one direction per variable against reverse mode’s single backward pass. Use warp.Tape or warp.grad() for that outer derivative, and jets for the fixed-arity term inside it.

Registering the arithmetic mutates Warp’s global builtin overload table, which is what lets a * b resolve on jets from any module. The effect is additive and lasts for the lifetime of the process.