Installation#

GRiD is a single repository with its peer products (GLASS, RBDReference, URDFParser) vendored as git submodules under external/. Clone with --recursive so those populate, then run the install script — a single pip install -e . installs the codegen toolkit and the grid_rbd Python wrapper together (see the GRiD documentation quick-start for the extras).

git clone --recursive https://github.com/A2R-Lab/GRiD.git
cd GRiD

If you already cloned without --recursive, populate the submodules with git submodule update --init --recursive.

Source installation#

An editable install from a Git checkout uses that checkout’s generator, peer submodules, wrapper template and launch profiles, so keep it in place. main is the branch documented here. Distribution wheels instead contain their own pinned resources and do not need Git or a retained checkout.

Installing a distribution artifact#

Release wheels and the source distribution are published on PyPI as grid-rbd (Linux x86-64, CPython 3.10–3.12):

python -m pip install grid-rbd

This does not compile robot CUDA code or access a GPU. On a platform without a matching wheel pip builds the source distribution, whose small Python extension requires a C++17 compiler. The source installation above remains available for development. GRiD is alpha software: APIs may change between minor versions (see the repository CHANGELOG.md).

One distribution contains the NumPy, JAX and PyTorch adapters. The base install requires NumPy; jax, torch and all extras select optional framework dependencies. Install a GPU-enabled framework build suitable for your hardware before registering a robot. Neither these extras nor GRiD install the system NVIDIA driver or CUDA Toolkit.

Registration is explicit and can take substantial time for large robots:

import grid_rbd
robot = grid_rbd.register_robot(
    "my_robot", urdf_path="robot.urdf",
    algorithm_list=["inverse_dynamics", "inverse_dynamics_gradient"],
    backend="numpy")

Use backend="jax" or backend="torch" for the other interfaces. The adapters share the content-addressed registration cache. A subsequent registration with unchanged inputs reuses its compiled library; changed model, generator, toolkit or framework ABI inputs can require a new build. See Fast Robot Setup for cache loading and subset selection.

Bundled provenance#

Wheels and source distributions bundle URDFParser and RBDReference Python sources from GRiD’s exact submodule commits, plus GLASS headers and launch profiles. They do not resolve newer peer versions during installation. Inspect the commit IDs, source hashes and resource hashes with:

from grid_codegen.resources import bundled_provenance
print(bundled_provenance())

Third-party licenses are included under grid_codegen/_data/licenses. User URDF files and referenced meshes remain user-supplied. The checkout’s example robot collection and optional foam checkout are not bundled.

Runtime requirements#

What each activity needs:

Activity	Requirements
Import `grid_codegen` / generate `grid.cuh`	Python ≥ 3.10; populated submodules for an editable install, or the bundled distribution resources. No GPU, no `nvcc`.
`grid_rbd.register_robot` / `warm_robot` (first call per robot)	the CUDA Toolkit’s `nvcc` on `PATH` (the toolkit that matches your driver), a host C++ compiler, and an NVIDIA GPU present (the compute capability is read from `nvidia-smi` unless you pass `cuda_arch=`).
Warm loads and every numeric method	a GPU with the arch the `.so` was built for; no `nvcc`.
`backend="jax"` / `backend="torch"`	the `[jax]` / `[torch]` extra plus a CUDA build of that framework matching your GPU arch (the extras pin the CPU packages only; the CUDA wheel is your choice, e.g. `pip install "jax[cuda12]"` or `"jax[cuda13]"`, and a `cu1xx` torch wheel — see the bindings README). A missing framework, or a CPU-only jax, is reported at `register_robot` time, not deep inside a call.
Equivalence tests / the Pinocchio oracle / docs	`install/developer_install.sh` (apt build deps, `pin`, robot-description fixtures, the Pinocchio second-order extension).

Platform: Linux x86_64 with CUDA 12.x/13.x is what is built and tested (the committed GPU-proof receipt names the exact GPU and toolkit). Windows and macOS are not supported. The submodules must be populated before the first generation (not before the editable install itself): install/base_install.sh runs pip install -e . and then git submodule update --init --recursive; a bare editable install on a non-recursive clone succeeds and then fails at first generation with a “GLASS submodule is missing” error naming the fix.

Install Python Dependencies#

The simplest path is to use the provided install scripts, which create a local .venv and register the grid-generate CLI.

For end-user installs (just the runtime + CLI):

bash install/base_install.sh
source .venv/bin/activate

For developer installs (adds Pinocchio, robot-description fixtures, documentation tooling, and the Pinocchio second-order pybind11 extension used as the golden oracle in the equivalence tests):

bash install/developer_install.sh

The developer script will, on Debian/Ubuntu, install the system build deps needed by the Pinocchio pybind11 extension via apt-get: pkg-config, g++, libeigen3-dev, liburdfdom-headers-dev. The pin wheel ships its own pinocchio.pc inside the venv via cmeel, and install/developer_install.sh computes the right PKG_CONFIG_PATH automatically for the extension build — no manual configuration is required.

You can also install manually with:

pip3 install -e .

Install CUDA Dependencies#

sudo apt-get update
sudo apt-get -y install xorg xorg-dev linux-headers-$(uname -r) apt-transport-https

Download and Install CUDA#

Note: the commands below are for Ubuntu 24.04 (ubuntu2404) — substitute your release in the repo URL, and see https://developer.nvidia.com/cuda-downloads for other distros. NVIDIA’s repos now use the cuda-keyring package (the old apt-key method was removed in Ubuntu 22.04+):

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get -y install cuda-toolkit

Add the following to `~/.bashrc`#

export PATH="/usr/local/cuda/bin:$PATH"
export LD_LIBRARY_PATH="/usr/local/cuda/lib64:$LD_LIBRARY_PATH"
export PATH="/opt/nvidia/nsight-compute/:$PATH"

Note

GRiD requires a C++17-capable host compiler (e.g. g++ >= 7 or clang++ >= 5). The benchmark and codegen runtime compile with -std=c++17, needed for inline variables in the bench common header. With the [torch] extra the per-robot .so is compiled with whatever standard the installed torch’s ATen headers demand (-std=c++20 from torch 2.14 on, detected from the header guard), so a torch-enabled build needs an nvcc and host compiler that accept C++20 (CUDA 12+, g++ >= 10). GRID_RBD_CXX_STD forces the standard.