warp.experimental.build.add_builtin#

warp.experimental.build.add_builtin(
name,
input_types=None,
value_type=None,
*,
native_name=None,
is_differentiable=False,
adjoint_uses_forward_output=False,
doc='',
)[source]#

Register an external C++ function for use in Warp kernels.

Experimental: this API may change without deprecation in future releases.

The registered function is available in kernels as warp.<name> or through the returned function handle. Calling it directly from Python is not supported. Overloads must differ in their parameter types or the order of those types. Changing only parameter names, return types, or reference qualifiers does not distinguish overloads. Exact duplicate registrations return the existing handle.

External calls may run again during backward replay, even with is_differentiable=False. Stateful operations need replay-safe behavior; calls to external functions with mutable reference parameters (warp.ref[T]) require enable_backward=False or a wrapper with both warp.func_grad() and warp.func_replay().

See External Function Gradients for C++ adjoint signatures and custom gradient/replay examples.

Parameters:
  • name (str) – Name used to call the function from Warp kernels.

  • input_types (Mapping[str, type] | None) – Ordered mapping from parameter names to Warp types. Use warp.ref[T] for C++ T& parameters; callers must pass addressable storage, such as an array element or mutable local.

  • value_type (type | None) – Warp return type, or None for a function returning void.

  • native_name (str | None) – Exact qualified C++ function name. When omitted, wp::<name> is used.

  • is_differentiable (bool) – Whether the external header provides a C++ adjoint. Warp does not infer derivatives from C++ code. Reference inputs require a custom gradient/replay wrapper instead.

  • adjoint_uses_forward_output (bool) –

    Whether the C++ adjoint takes an extra argument containing the forward result, after the original inputs. Warp recomputes this result during backward execution. Requires is_differentiable=True and a non-void return type. For example:

    // False
    void adj_root(float x, float& adj_x, float adj_result);
    // True
    void adj_root(float x, float result, float& adj_x, float adj_result);
    

  • doc (str) – Description of the function.

Returns:

The canonical Warp function containing the registered overload.

Return type:

Function