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()andwarp.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, meaningnscalar inputs, or a sequence of types, one per input:warp.float32,warp.vec2,warp.vec3,warp.quat,warp.mat22,warp.mat33,warp.mat32orwarp.mat23. A spring over two nodes is(warp.vec3, warp.vec3).dtype – Scalar type the jets are built on. Inferred from
slotswhen they are Warp types;warp.float32whenslotsis an integer or contains only Pythonfloat.width – Number of derivative directions each jet carries. Defaults to the total number of scalar components in
slots, in which caseseedseeds the unit directions and a jet carries the full gradient. A smaller width carries only the directions passed todirectional, 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’sgradfield (grad_type_scalar,grad_type_vec2, and so on throughgrad_type_mat23), the helpers that construct jets, includingexp_map, which maps avec3rotation-vector jet to a unit quaternion jet, andslots, the native type of each slot.
Jets are created inside a kernel or function with
seedordirectional. Withspring_energyan ordinary@warp.functhat 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 whenwidthequals the number of components; otherwise usedirectional.directional(*values, *directions)takes the same values, followed bywidth * len(slots)direction vectors ordered direction-major: directionqof slotsis argumentq * len(slots) + safter 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 alongdirection. Use it to seed in a loop, where the number of scalars is not a fixed argument list.jet_type(t)andgrad_type(t)look the types up by the Warp type of the value instead:J.grad_type(warp.vec2)isJ.grad_type_vec2. They are Python functions, so they work in annotations and host code, such aswarp.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, raisesTypeError.widthis fixed when the types are specialized, not when a kernel runs: it becomes the length ofgradand is unrolled into the generated code. Every intermediate value carries allwidthderivative 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
vec3nodes 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. Usewarp.Tapeorwarp.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 * bresolve on jets from any module. The effect is additive and lasts for the lifetime of the process.