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='',
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]) requireenable_backward=Falseor a wrapper with bothwarp.func_grad()andwarp.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¶meters; callers must pass addressable storage, such as an array element or mutable local.value_type (type | None) – Warp return type, or
Nonefor a function returningvoid.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=Trueand 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: