Host requirements¶
Every env pins its own PyTorch (or TensorFlow) and CUDA build, so what your machine needs depends on which models you install.
In short¶
- Linux with an NVIDIA GPU. Installation counts as done only after the model computes energy and forces on the GPU.
- conda or mamba on
PATH. On every host,install.shruns its recipe and lock builds withCONDA_DEFAULT_CHANNELS=conda-forge(unless you set it), so conda's default Anaconda channels and their Terms-of-Service prompt are not used; the recipes listnodefaultsanyway. - An NVIDIA driver new enough for the env's CUDA build — see the table. Check
yours with
nvidia-smi(the CUDA version at the top right). - Disk: each env takes several GB, plus the model weights.
- Host RAM: 16 GB is enough for every model except
UMA-m-1p1-*, which needs 32 GB or more.
Per env¶
| Env | Python | Framework | CUDA | Driver | Notes |
|---|---|---|---|---|---|
| allegro | 3.11 | torch 2.8.0 | 12.8 | 570+ | compiled for your GPU at install (CuEquivariance) |
| alphanet | 3.11 | torch 2.1.2 | 12.1 | 525+ | |
| chgnet | 3.11 | torch 2.7.1 | 12.6 | 525+ | |
| deepmd | 3.11 | torch 2.8.0 | 12.8 | 570+ | |
| dpa4 | 3.11 | torch 2.11.0 | 13.0 | 580+ | |
| eqnorm | 3.11 | torch 2.6.0 | 11.8 | 450+ | |
| equflash | 3.12 | torch 2.9.1 | 12.6 | 525+ | |
| equiformer_v3 | 3.11 | torch 2.7.1 | 12.8 | 570+ | |
| fairchemv1 | 3.11 | torch 2.4.1 | 12.1 | 525+ | gated weights (eSEN) |
| grace | 3.11 | TensorFlow 2.16.2 | 12.3 | 525+ | |
| mace | 3.11 | torch 2.7.1 | 12.6 | 525+ | |
| matris | 3.11 | torch 2.12.1 | 13.0 | 580+ | |
| mattersim | 3.10 | torch 2.6.0 | 12.4 | 525+ | |
| nequip | 3.11 | torch 2.9.1 | 12.8 | 570+ | compiled for your GPU at install (OpenEquivariance) |
| nequix | 3.11 | torch 2.10.0 | 12.6 | 525+ | |
| orb | 3.11 | torch 2.7.1 | 12.6 | 525+ | |
| pet | 3.11 | torch 2.9.1 | 12.8 | 570+ | 2.8 GB checkpoint |
| sevennet | 3.11 | torch 2.7.1 | 12.6 | 525+ | OpenEquivariance kernels built at install |
| tace | 3.11 | torch 2.11.0 | 13.0 | 580+ | |
| uma | 3.11 | torch 2.8.0 | 12.8 | 570+ | gated weights; UMA-m-1p1-* needs 32 GB+ host RAM |
Versions come from the lock files in envs/locks/; driver floors are the
approximate Linux minimums for each CUDA build.
Blackwell GPUs (sm120)¶
A GPU of compute capability 12.0 needs CUDA 12.8 or newer builds: the CUDA 11.8 to
12.6 torch wheels in the table above carry no kernels for it, and fail at the
first calculation with CUDA error: no kernel image is available. On such a GPU
install.sh builds a different recipe where one exists:
- allegro and nequip (already CUDA 12.8, with
ninja) use their usual recipe; - uma, deepmd, equiformer_v3 and pet (CUDA 12.8) and dpa4, matris and tace
(CUDA 13.0) use a sibling (
envs/<env>.cu128.yml/envs/<env>.cu130.yml) with the same pins plus conda'sninjaand a pinned host compiler (gxx14.4 for CUDA 12.8, 15.3 for CUDA 13.0), so the D3 kernel builds there; - mace, sevennet, chgnet, orb, equflash and nequix use a sibling recipe
(
envs/<env>.cu128.yml) with the same torch release built for CUDA 12.8; - alphanet, fairchemv1, eqnorm and mattersim use a sibling recipe that raises torch to 2.7.1+cu128, because their pinned torch has no CUDA 12.8 build. This changes the numerical stack slightly; measured against the base stack (table below);
- grace uses a sibling on a TensorFlow nightly (
envs/grace.tfnightly.yml): the released TensorFlow wheels up to 2.21 do not run on sm120. It is markedcandidate(a nightly, and outside tensorpotential's declared TensorFlow range); see the recipe header; - for an env with no working recipe there,
install.shstops before downloading anything and prints the reason.
Raised-torch siblings against the base stack (its lock replayed, run on CPU, as the base wheels have no sm120 kernels), on a 38-atom Cu(111) slab with CO, rattled; sibling on an sm120 GPU. ΔE in meV/atom, largest force-component difference in meV/Å (measured 2026-11):
| Env | base torch | sibling torch | ΔE | max ΔF |
|---|---|---|---|---|
| alphanet | 2.1.2+cu121 | 2.7.1+cu128 | 0.0000 | 0.001 |
| eqnorm | 2.6.0+cu118 | 2.7.1+cu128 | 0.0000 | 0.002 |
| fairchemv1 | 2.4.1+cu121 | 2.7.1+cu128 | -0.0004 | 0.014 |
| mattersim | 2.6.0+cu124 | 2.7.1+cu128 | +0.0004 | 0.005 |
The sibling recipes also carry conda's gxx (14 for CUDA 12.x, 15 for CUDA 13.0)
and ninja: CUDA 12.x refuses a newer host gcc (Ubuntu 26.04 ships gcc 15), and
the D3 kernel and OpenEquivariance compile with them. install.sh (and
adopt_env.py) build the D3 kernel at install time with scripts/build_d3.py:
the env's bin/ first on PATH, its own nvcc as CUDA_HOME, its conda
compiler as CC/CXX, and TORCH_CUDA_ARCH_LIST with the GPU's arch added (as
env.sh does) and cut to what that nvcc compiles. Nothing then compiles at the
first D3 call, which runs through the bare interpreter with no env bin/ on
PATH.
envs/_arch_recipes.json is the list, Recipes shows each sibling's
pins, and the sm120 column of Supported models shows what
was verified on such a GPU. The driver must support CUDA 12.8 (570+). Older
GPUs keep the recipes in the table above; nothing changes for them.
Common problems¶
-
GRACE weights:
GRACE-2L-OAM(about 100 MB) comes from upstream's Hugging Face copy, checked against the recorded sha256, and an interrupted download resumes where it stopped. If Hugging Face is unreachable it falls back tograce_modelsand the upstream ICAMS share, which has served a few KiB/s (hours for the file) with no resume -- let that run finish undisturbed. -
Driver too old for a CUDA 13.0 env (dpa4, matris, tace):
torch.cuda.is_available()isFalse. Upgrade the driver, or use a host whose driver matches the build. A CPU run is not a general fallback here: these models' inference lines pin the GPU, and the hub refuses a CPU request rather than running on the GPU and reporting CPU. no kernel image is availableon a new GPU: the env was built from a recipe for older GPUs (for example copied from another machine, or built before the sibling recipes existed)../install.sh --status <env>says which recipe this GPU needs;./install.sh --rebuild <env>rebuilds it.- A different GPU than the one you installed on: NequIP and Allegro load a model compiled for a specific GPU architecture. See GPU-architecture compilation.
- Loading
UMA-m-1p1-*dies with no error message: the checkpoint (11.2 GB) is loaded into host RAM first, and the kernel's out-of-memory killer ends the process (exit code 137). Use a machine with 32 GB or more, or aUMA-s-*model. - GRACE fine-tuning on WSL crashes right after
Compiled cluster using XLA(segmentation fault, no Python traceback): rerun with--set jit_compile=false. Native Linux runs the default (jit_compile=true). - Gated models (UMA, eSEN) need your own Hugging Face login — see Hugging Face token.