API reference

PyTorch compatibility layer for Tesseract.

Provides apply_tesseract(), which wraps any Tesseract as a differentiable PyTorch operation supporting both reverse-mode (.backward()) and forward-mode (torch.autograd.forward_ad) automatic differentiation.

tesseract_torch.apply_tesseract(tesseract, inputs, *, gpu_transport=None)[source]

Call a Tesseract as a differentiable PyTorch operation.

Infers which inputs/outputs are differentiable from the Tesseract’s schema. Torch tensors provided for differentiable fields participate in autograd; all other values are passed through as static inputs.

Supports both reverse-mode (.backward()) and forward-mode (torch.autograd.forward_ad) differentiation.

Parameters:

  • tesseract (Tesseract) – A Tesseract instance.

  • inputs (dict[str, Any]) – Nested dict matching the Tesseract’s input schema. Provide torch.Tensor for array fields you want gradients through, and plain Python / NumPy values for everything else.

  • gpu_transport (str | None) – Name of the on-device transport used to exchange CUDA tensors with the Tesseract instead of a host round-trip (currently "cuda_ipc"), so array data never leaves the device. Requires a served Tesseract (HTTPClient) started with the matching gpu_transport and GPU access (e.g. Tesseract.from_image(..., gpus=["all"], gpu_transport="cuda_ipc")); has no effect on CPU tensors, plain NumPy inputs, or a local (in-process) client, which already shares memory. For cuda_ipc both processes must share the CUDA IPC namespace (Docker’s --ipc=host). When None (default), CUDA tensors take the same host round-trip as CPU tensors. This is an experimental tesseract-core feature; see tesseract_core.runtime.cuda.ipc.

Return type:

dict[str, Any]

Returns:

Nested dict matching the Tesseract’s output schema, with differentiable array outputs as torch.Tensor (with grad_fn when inputs require grad) and non-differentiable outputs as-is (NumPy arrays or scalars).

Example:

# Flat schema
result = apply_tesseract(quadratic, {"x": x, "A": A, "b": b})
result["y"].sum().backward()

# Nested schema
result = apply_tesseract(meshstats, {
    "mesh": {"n_points": 3, ..., "points": points_tensor}
})
result["statistics"]["barycenter"].sum().backward()