Compatibility and known limitations#
Platforms and toolchain#
There is one artifact per GPU architecture unless
GRID_RBD_CUDA_ARCHSnames several and the build is a fat binary. A robot.sois otherwise compiled for thesm_XXof the GPU that registers it (orcuda_arch=); loading it on a different architecture is refused at context creation with a clear error. The model, the API and the generated code carry over between machines; the binary does not.The 0.7.0 primary GPU test receipt and the release timing ran on Linux x86-64 with CUDA toolkit 13.2 and one RTX 5090 (sm_120). A secondary receipt of the same 2056 tests at the same commit ran on a Jetson AGX Orin (sm_87, aarch64, CUDA toolkit 13.2); the table below lists both environments. CUDA 12 toolkits and other GPUs are untested. The Xavier (sm_72) ran the header-only example and has no receipt.
The host compiler standard is C++17 for the code generator, benchmarks and a numpy-only build. With the
[torch]extra the wrapper reads the standard that torch’s ATen header guard demands and compiles with it. The torch we run (2.12.0, cu128) compiles with C++17. A torch that demands C++20 needs an nvcc and host compiler accepting C++20; that path ran under the Orin receipt below (torch 2.14.0+cu130).GRID_RBD_CXX_STDforces the standard.The
[jax]/[torch]extras pin the CPU packages; install the CUDA wheel yourself. We runjax[cuda12](jax-cuda12-plugin0.10.0) and a cu128 torch wheel;jax[cuda13]and other torch wheels are untested. A CPU-only jax is refused at handle construction with that hint. See Installation for the PyPI install and its extras.
What we ran#
The RTX 5090 produced the primary evidence for 0.7.0: the full test
receipt (gpu-proof.json, verified by CI), the release timing on the
release measurements page, and the
installed-wheel check of the release playbook. The Jetson AGX Orin recorded
the secondary receipt receipts/gpu-proof-sm87.json, the same collection
at the same commit, which make verify-all checks against its own
expected-skips baseline. Everything validated ran in
fp32, the default compute precision; the fp64 tier (dtype="float64") is
an alpha feature outside the receipt.
The table below records that historical qualification, not a qualification of changed 0.7.1 code. The 0.7.1 candidate has additional local correctness and installed-artifact gates; its fresh full primary receipt is a separate release gate. The Orin receipt remains tied to the 0.7.0 source and does not attest the new armature, allocation or free-body repairs. No new Orin qualification is claimed. Strict verification of a historical receipt against changed inputs may fail; preserve that evidence and verify it at its recorded source revision, rather than weakening policy or relabeling it as current.
GPU architecture |
GPU |
CUDA toolkit (nvcc) |
Driver |
Python |
torch wheel |
jax plugin |
OS |
What ran |
Date |
|---|---|---|---|---|---|---|---|---|---|
sm_120 (compute capability 12.0) |
NVIDIA GeForce RTX 5090, 32 GB |
13.2 (V13.2.86) |
615.71.09 |
CPython 3.12.3 |
2.12.0.dev20260408+cu128 (CUDA 12.8 runtime) |
jax 0.10.0 with jax-cuda12-plugin 0.10.0 |
Ubuntu 24.04.5, Linux 7.0.0-38, x86-64 |
full receipt; release timing; install check (a fresh venv with torch 2.11.0+cu128 and jax 0.11.2 from PyPI) |
receipt 2026-11-01; timing 2026-09-27 to 2026-10-07; install check 2026-10-15 |
sm_87 (compute capability 8.7) |
NVIDIA Jetson AGX Orin, 64 GB |
13.2 (V13.2.78) |
L4T R39.2 (JetPack; driver 595.78) |
CPython 3.12.3 |
2.14.0+cu130 (NVIDIA Jetson build) |
jax 0.11.1 with jax-cuda13-plugin 0.11.1 (NVIDIA Jetson build) |
Ubuntu 24.04.4, Linux 6.8.12-1021-tegra, aarch64 |
secondary receipt |
receipt 2026-11-01 to 2026-11-02 |
sm_72 (compute capability 7.2) |
NVIDIA Jetson AGX Xavier, 32 GB |
11.4 (V11.4.315) |
L4T R35.3.1 (JetPack 5) |
CPython 3.8.10 and 3.9 only; grid-rbd needs 3.10 |
not applicable |
not applicable |
Ubuntu 20.04, Linux 5.10.104-tegra, aarch64 |
header-only CUDA: the fused control step example, built against an iiwa14 header generated on the x86-64 machine, compiled with nvcc 11.4 for sm_72 and validated fused against layered; the generator, the bindings and the test suite do not install on this Python |
2026-10-16 |
The toolkit and the framework wheels are separate things. nvcc 13.2
compiles the generated kernels and the per-robot .so. The torch wheel
carries its own CUDA 12.8 runtime libraries for torch’s kernels, and the
jax-cuda12-plugin carries CUDA 12 runtime libraries for XLA; neither uses
nvcc. The driver has to satisfy every runtime in the process, and
615.71.09 does. On x86-64, a jax[cuda13] plugin, a torch wheel other
than cu128, a CUDA 12 toolkit and CPython 3.10, 3.11 or 3.13 on a GPU are
untested; the CI wheel builds for CPython 3.10, 3.11 and 3.13 and the CPU test
lane on 3.10 and 3.13 run on CPU only. The Orin receipt is the one run of
jax-cuda13-plugin and a cu130 torch wheel, on aarch64. The Orin row is a
secondary receipt, recorded through the per-architecture table in
test/gpu-proof-receipts.yaml and verified by make verify-all; it
documents the architecture and does not gate CI. The Xavier stays header-only
because JetPack 5 ships CUDA 11.4 and Python 3.8, below the floors of the
generator and the bindings.
Runtime contexts#
Every native call resolves a runtime context by id; handle.context()
opens an isolated one (own arena, tables, streams, launch overrides) and a
handle is the one owner of its context. Runtime-parameter mutations give the
context a new model_version, and torch/JAX backwards refuse a forward that
ran under a different version. Concurrent asynchronous calls on one context
share its scratch buffers, so each context carries one ordered pipeline; use a
context per pipeline, as execution is not fully asynchronous. Ownership,
workspace_slots, versioning and the synchronisation points are specified in
Runtime contexts.
Captured CUDA graphs (torch)#
handle.capture(...)replays only on its context at the captured model epoch: a replay after a mutation is refused (recapture) and a replay after the context was closed is refused (never a launch into freed memory). Replays of one graph are serialized;static_outis overwritten by the next replay.Capturing a backward is unsupported. Do not mix graph replay and concurrent eager calls on the same context.
Operands#
One rule set per operand class is enforced natively on all three surfaces
(1 <= B <= max_batch, exact last dim, every operand carrying the leading
batch). Configuration inputs have width nq; velocities, accelerations and
generalized forces have width nv, and floating and spherical quaternions
make these widths different. What each surface coerces, refuses or elides is
specified in Operand validation; layouts are in
Input / Output ABI (h_q_qd_u).
Native interface stability#
Public generated surfaces are the ones documented on the API reference pages and the CUDA tutorials: the kernel and
*_deviceentry points named in CUDA Support Status, thegrid::modelmetadata and transform helpers of Model coordinates and named frames, the configuration primitives of Integration, derivatives and model primitives and thegrid_plantworkspace views of Composing generated workspaces. Neither an underscore nor aninlinespelling decides this: a generated function absent from those pages is an implementation detail that a later release may rename or remove. (init_gridData_checkedgained an optional trailing allocator-pool argument; the pool-less allocator spellings remain.)Release policy during 0.x: any release may change a documented public contract, and a release that does so says so in the changelog with the migration step, as Migrating from 0.6 to 0.7 does for this one. Correctness fixes name the affected operations, the numerical change and any rebuild they require. The version number records what shipped; it does not promise which kind of change a release may carry, a deprecation period, a support window or a response time. What is promised is that a public contract never changes silently.
Source compatibility, descriptor schema compatibility, compiled-artifact reuse and tested numerical support are separate promises. A call that still compiles does not imply that an old prepared artifact loads: artifact reuse is decided by the content, toolchain and descriptor checks described on the model-coordinates page, and a schema change requires one rebuild.
The per-robot wrapper
.so’sextern "C" grid_rbd_*symbols are private to the package: they are consumed only by the pybind core of the same content-keyed build and gained a leadingctx_idin 0.5.0, the first packaged release. Do not link against them directly.The two joint-transform helpers in
grid::modelare CUDA device functions; host code reads the same placements through the constexprjointandframerecord accessors.
Differentiation#
First-order autograd (torch
backward,jax.grad/vjp) runs the analytic gradient kernels; higher-order differentiation through those kernels is not provided.*_wrt_paramsis the local sensitivity of the compiled model to its inertial parameters (a parameters argument does not install a new runtime model).Second-order tensors are values (
idsva_so/fdsva_so), not autograd-composable operators. Per-method and per-joint-type restrictions are collected on Python backend interfaces.
Build cost#
A full-feature humanoid build is expensive (see the cold/warm table on the fast-robot-setup page); subset builds (
algorithm_list=,enable_mujoco_kernels=False) are the practical path when compile time or memory matters. Generated-source portability is not binary portability.
Sanitizer diagnostics with JAX#
Running a process that initializes the JAX CUDA backend under NVIDIA Compute Sanitizer reports one CUDA API warning during JAX’s device-allocator query (
cuDeviceGetAttribute: fabric handle support requires IMEX channels) and, for a standalone JAX reduction, a selective device-code recompilation notice. Both come from JAX 0.11 and the CUDA 13 toolchain and reproduce in a process that imports no GRiD; the numerical results are correct and the NumPy and PyTorch surfaces pass the same sanitizer with zero errors. The first is the driver’s own behaviour:cuDeviceGetAttributereports fabric-handle support on a machine that has no IMEX channel node (the driver creates one only withNVreg_CreateImexChannel0), so XLA’s allocator probe takes the fabric path and the API call it makes is refused; the allocator then falls back and runs correctly. Nothing in GRiD selects a handle type. We record this as an accepted limitation of the combined sanitizer invocation rather than a defect of the wrapper: the sanitizer exit code of a JAX-initialized process is nonzero, and the release checks state it so instead of suppressing the warning.