NVIDIA ALCHEMI Toolkit
This skill helps you write and change code that uses nvalchemi, the Python
package of the NVIDIA ALCHEMI Toolkit. It scopes the request, checks the
installed version, and routes to one note per kind of task. The notes say which
component fits which need, how the components connect, which mistakes are
common, and how to check the result. They link to the docs and examples for
the full details.
Purpose and scope
Use it when the code imports nvalchemi, or when the user asks for a workflow
that the toolkit covers, including batched GPU simulation where nvalchemi
is installed or acceptable: AtomicData and Batch, Zarr storage, model
wrappers, relaxation and MD, reaction paths, enhanced sampling, training,
fine-tuning, distillation, generative sampling, or a custom hook, integrator,
loss, or reporter.
Do not use it when:
- The task is plain ASE, OpenMM, LAMMPS, GROMACS, or another package, and
the user did not ask for
nvalchemi. Solve it with that package and do not
import nvalchemi.
- The task is a Warp or CUDA kernel inside ALCHEMI Toolkit-Ops
(
nvalchemiops). That is a different package with its own rules.
- The question is general PyTorch with no atomistic workflow.
Prerequisites
- Python 3.11 to 3.13 with
nvalchemi-toolkit installed (pip or uv).
- PyTorch with the CUDA build that matches the host, or the CPU build.
- Optional model backends are extras:
mace, aimnet, uma-cu12/uma-cu13,
ase, pymatgen, tensorboard. UMA conflicts with MACE, so it lives in its
own environment.
Instructions
Work through these steps for every request.
Scope the request first
Before you write or run code, go through this checklist. Ask about unknown
scientific choices, hardware, workload, correctness checks, and permissions
(items 2, 7, 8, 9, 10). For items 1, 3, 4, 5, 6, state a one-line assumption
if needed. Check the installed software before execution.
- Intended result. What number, file, or model does the user want at the
end?
- Scientific choices. Model and checkpoint, ensemble (NVE, NVT, NPT),
temperature, pressure, timestep, convergence threshold, run length. Do not
pick these silently.
- Inputs. Structure files and their format, units, which fields they
carry (energies, forces, velocities, cells). Read the files first and ask
only for what they do not say.
- Deliverables. Script, data store, checkpoint, plot, or a short report.
- Reuse. Which shipped component already does this (see the reuse rule).
- Software environment. Installed
nvalchemi version and extras.
- Hardware. CPU only, one GPU, or several. Memory limits.
- Workload. Number of systems, atoms, and steps.
- Correctness check. How the result will be checked (see each note).
- Permissions. What you can write, download, or delete.
Limit exploratory runs to at most 3 systems and 100 steps, with a wall-time
limit under one minute. Do not start a production-length trajectory or a long
training run to "see what happens". Scale up only after the user agrees to the
settings.
Check the installed version
The notes describe the API of release 0.3.0. Their links point at the
v0.3.0 tag. Check what is installed before you apply any advice:
python - <<'EOF'
import importlib.util as u
for parts in ((), ("data",), ("dynamics",), ("models",), ("gen",),
("dynamics", "mep"), ("enhanced_sampling",),
("training", "distillation")):
m = ".".join(("nvalchemi", *parts))
try:
found = u.find_spec(m) is not None
except ModuleNotFoundError:
found = False
print(m, found)
if u.find_spec("nvalchemi") is not None:
import nvalchemi
print(nvalchemi.__version__, nvalchemi.__file__)
EOF
If the toolkit is not installed, say so. Write the code anyway, but stop
before running it. Do not fetch source or install packages to fill the gap.
For a version mismatch or missing module, tell the user what it affects:
- If version 0.2.0 or newer has the core modules nvalchemi.data,
nvalchemi.dynamics, and nvalchemi.models, proceed with the 0.3.0 patterns.
Flag each 0.3.0-only feature used. Check its API in the installed source
before execution. If it is absent, write the code but do not run it.
- If a core module is missing or the version is below the 0.2.0 floor, stop
execution and ask before any upgrade. Do not install or upgrade on your own.
The installed wheel ships no docs or examples. Read the installed package
source and the linked docs and example pages only. Each note names the
source module. Locate its file with Python's inspect.getfile, then read it in
site-packages. Links are for reading, never for downloading code to run.
If the network is unavailable, use installed source.
Run on the GPU
Pick the device once: use cuda when torch.cuda.is_available(), otherwise
cpu. Put the model, batch or dataset, and optimizer on that same device.
For dynamics, optimizer state comes from the batch. Pass
device_type=device.type to the engine. Given a model, structures, and the
agreed timestep and step budget:
import torch
from nvalchemi.data import Batch
from nvalchemi.dynamics import FIRE2, FusedStage
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = model.to(device)
batch = Batch.from_data_list(data_list).to(device)
opt = FIRE2(model=model, dt=dt, n_steps=step_budget, device_type=device.type)
dyn = FusedStage(sub_stages=[(0, opt)], device_type=device.type)
for hook in model.make_neighbor_hooks():
dyn.register_hook(hook)
Complete the pre-flight check below before dyn.run(batch). For training,
set Dataset(..., device=device) and TrainingStrategy(..., devices=[device]).
The strategy builds optimizers from the placed model (see the training note).
Keep the step loop on the GPU. Avoid .item(), .cpu(), .tolist(),
float(t), print(t), bool(t), a Python if on a tensor (including
if tensor.any()), and per-step host reads of batch.status. These wait for GPU
work before Python can continue. Host reads are fine at setup, at a
checkpoint, in a check every N steps (N > 1), and in the final report.
Prefer toolkit run() loops and hooks with a class-level frequency over a
hand-written step loop. Keep masks and reductions as device tensors.
A small CPU check is fine. The delivered code must still select cuda when a
GPU exists. Do not hard-code device="cpu" to make the check pass. This holds
for scratch test scripts too. Pass device_type=device.type there as well.
Build AtomicData only at setup, to validate input. In loops, work on
Batch tensors (see the data note, "Keep hot paths on Batch").
Batched dynamics pre-flight check
Before every run(), confirm both checks in one line. Do not run until both
are true. Details are in
dynamics-optimization.md.
- One batch, one engine or
FusedStage. Build one Batch with
Batch.from_data_list(...) for all independent systems. Do not run each
system in a Python loop. Use a FusedStage to retire each system on its
own when it converges.
- Neighbor hooks registered. Register every hook from
model.make_neighbor_hooks() on the engine or fused stage before the
first step. Models without a neighbor list return no hooks.
from nvalchemi.data import Batch
from nvalchemi.dynamics import FIRE2, ConvergenceHook, FusedStage
batch = Batch.from_data_list(data_list).to(device) # many systems, one batch
opt = FIRE2(model=model, dt=0.1, n_steps=100, device_type=device.type,
convergence_hook=ConvergenceHook.from_fmax(0.05))
dyn = FusedStage(sub_stages=[(0, opt)], device_type=device.type)
for hook in model.make_neighbor_hooks(): # BEFORE_COMPUTE hooks
dyn.register_hook(hook)
with dyn:
batch = dyn.run(batch)
Route to a note
Match the task to the routing table. If it spans notes, read each note named
in the matching rows before you write code.
| Task |
Note |
| Build, batch, convert, or inspect atomic systems, field names, ASE input |
data.md |
| Write, read, or stream Zarr stores, DataLoader throughput |
data.md |
| Load a pretrained model (MACE, AIMNet2, UMA, LJ, DFT-D3, Ewald, PME) |
models.md |
| Wrap a custom PyTorch model, combine models, outputs and embeddings |
models.md |
| Relax structures, run MD (NVE, NVT, NPT), chain stages, scans |
dynamics-optimization.md |
| Built-in hooks: freezing, safety, logging, snapshots, convergence, timing |
dynamics-optimization.md |
| Reaction paths and NEB, restraints and enhanced sampling |
dynamics-optimization.md |
| Train from scratch, losses, checkpoints, resume, DDP |
training.md |
| Fine-tune a pretrained model, distill a teacher into a student |
training.md |
| Sample structures with a generative model, generate then relax |
generative-workflows.md |
| Write a new hook, integrator, optimizer, loss, bias, or reporter |
composition-and-extension.md |
| Domain decomposition, dynamics stages on different GPUs, dashboards |
composition-and-extension.md |
| Custom NEB force equation or spring policy |
dynamics-optimization.md |
| Save and restore dynamics or sampling state, Hessians |
dynamics-optimization.md, models.md |
| Crystal structure prediction (the nvalchemi.csp package) |
generative-workflows.md |
Reuse first
- Reuse. Search the shipped components before you write anything. The
notes list them per area. Most needs (freezing atoms, NaN checks, drift
warnings, logging, snapshots, step budgets, restraints) already exist.
- Subclass for a small change. If a shipped class is close, subclass it
and override the one method that differs.
- Write new code only for missing behavior. Follow the protocol the toolkit
defines (for example the
Hook protocol or BaseDynamics), so it composes
with the rest.
Say which path you took and why, in one line, when you hand back the code.
Workspace rules
- Keep scratch files under the working folder you were given, for example in
a scratch subfolder. Do not write elsewhere unless the user asks.
- Do not delete files or folders with
rm -rf or rm -r, even for caches or
temporary folders. Leave __pycache__, Zarr scratch stores, and temporary
folders in place. If a single file must go, name it with rm -f <file> and
say why. Ask first if the user has not granted delete permission.
- Read only installed package source and linked docs and example pages.
Do not download source files, scripts, or wheels with
curl, wget, or
git. Do not download code to run by any other means.
- Do not print environment variables. Do not run
env or printenv, or
dump os.environ. These can expose secrets in tool output.
- Ask before you install, upgrade, or remove packages.
Report the result
In the final message, name any script you wrote and the toolkit components
you used. Report measured results with units only for work you ran. If you
did not execute the work, say "Not executed" and why. Do not invent numbers.
If the run failed or did not converge, say so and give the measured values.
Do not present a capped or failed run as a converged result.
Limitations
- The notes track release 0.3.0. Older installs miss generative sampling,
reaction paths, enhanced sampling, distillation, and other 0.3.0 APIs.
- Multi-GPU and multi-node runs need a launcher (
torchrun or Slurm). Write
the script and the launch command. Do not start multi-GPU jobs unasked.
- Model backends download checkpoints on first use. Offline machines need the
checkpoint file in advance.
Troubleshooting
| Symptom |
Likely cause |
Fix |
KeyError: 'neighbor_matrix' required or 'neighbor_list' |
No neighbor-list hook |
Register model.make_neighbor_hooks() |
AttributeError: ... no attribute 'masses' |
Field is atomic_masses |
Use batch.atomic_masses |
InvalidCxxCompiler or Inductor build error on CPU |
NeighborListHook is compiled, no C++ toolchain |
Run eagerly, see dynamics note |
AttributeError: 'Batch' has no attribute 'status' |
Plain dynamics does not create status |
Add a status column, see dynamics note |
FileExistsError: Zarr store already exists |
write() on an existing store |
Use append() or a new path |
ValueError: ... pattern ... did not match any parameter |
Wrong fine-tuning glob |
Print named_parameters() and fix the glob |
ValueError: ... has no trainable parameters with MACE |
MACEWrapper freezes weights by default since 0.3.0 |
Load with train=True, see the training note |
1---2name: nvalchemi-toolkit3description: >-4 Build and change NVIDIA ALCHEMI Toolkit (nvalchemi) workflows for atomistic5 simulation and machine-learned interatomic potentials (MLIPs). Use for6 batched structure relaxation, molecular dynamics, reaction paths, training7 or fine-tuning an MLIP, atomistic datasets in Zarr, generative structure8 workflows, model wrapping, and custom hooks or integrators, with the ALCHEMI9 Toolkit (nvalchemi), or when the user asks for batched GPU atomistic10 simulation and nvalchemi is installed or acceptable. Not for other11 simulation packages the user asked for (ASE-only, OpenMM, LAMMPS, GROMACS)12 when the request does not involve nvalchemi, ALCHEMI Toolkit-Ops13 (nvalchemiops) kernel work, or plain PyTorch questions.14license: Apache-2.015compatibility: >-16 Runs Python and shell commands to inspect the installed nvalchemi package17 and to run small checks. Reads linked docs and example pages over the18 network, never downloads code to run. No credentials needed.19metadata:20 source: https://skillmd.com/skills/nvidia/nvalchemi-toolkit21 author: NVIDIA <agent-skills@nvidia.com>22 tags: [nvalchemi, atomistic-simulation, mlip, molecular-dynamics, training]23---2425# NVIDIA ALCHEMI Toolkit2627This skill helps you write and change code that uses `nvalchemi`, the Python28package of the NVIDIA ALCHEMI Toolkit. It scopes the request, checks the29installed version, and routes to one note per kind of task. The notes say which30component fits which need, how the components connect, which mistakes are31common, and how to check the result. They link to the docs and examples for32the full details.3334## Purpose and scope3536Use it when the code imports `nvalchemi`, or when the user asks for a workflow37that the toolkit covers, including batched GPU simulation where `nvalchemi`38is installed or acceptable: `AtomicData` and `Batch`, Zarr storage, model39wrappers, relaxation and MD, reaction paths, enhanced sampling, training,40fine-tuning, distillation, generative sampling, or a custom hook, integrator,41loss, or reporter.4243Do not use it when:4445- The task is plain ASE, OpenMM, LAMMPS, GROMACS, or another package, and46 the user did not ask for `nvalchemi`. Solve it with that package and do not47 import `nvalchemi`.48- The task is a Warp or CUDA kernel inside ALCHEMI Toolkit-Ops49 (`nvalchemiops`). That is a different package with its own rules.50- The question is general PyTorch with no atomistic workflow.5152## Prerequisites5354- Python 3.11 to 3.13 with `nvalchemi-toolkit` installed (`pip` or `uv`).55- PyTorch with the CUDA build that matches the host, or the CPU build.56- Optional model backends are extras: `mace`, `aimnet`, `uma-cu12`/`uma-cu13`,57 `ase`, `pymatgen`, `tensorboard`. UMA conflicts with MACE, so it lives in its58 own environment.5960## Instructions6162Work through these steps for every request.6364### Scope the request first6566Before you write or run code, go through this checklist. Ask about unknown67scientific choices, hardware, workload, correctness checks, and permissions68(items 2, 7, 8, 9, 10). For items 1, 3, 4, 5, 6, state a one-line assumption69if needed. Check the installed software before execution.70711. **Intended result.** What number, file, or model does the user want at the72 end?732. **Scientific choices.** Model and checkpoint, ensemble (NVE, NVT, NPT),74 temperature, pressure, timestep, convergence threshold, run length. Do not75 pick these silently.763. **Inputs.** Structure files and their format, units, which fields they77 carry (energies, forces, velocities, cells). Read the files first and ask78 only for what they do not say.794. **Deliverables.** Script, data store, checkpoint, plot, or a short report.805. **Reuse.** Which shipped component already does this (see the reuse rule).816. **Software environment.** Installed `nvalchemi` version and extras.827. **Hardware.** CPU only, one GPU, or several. Memory limits.838. **Workload.** Number of systems, atoms, and steps.849. **Correctness check.** How the result will be checked (see each note).8510. **Permissions.** What you can write, download, or delete.8687Limit exploratory runs to at most 3 systems and 100 steps, with a wall-time88limit under one minute. Do not start a production-length trajectory or a long89training run to "see what happens". Scale up only after the user agrees to the90settings.9192### Check the installed version9394The notes describe the API of release 0.3.0. Their links point at the95v0.3.0 tag. Check what is installed before you apply any advice:9697```bash98python - <<'EOF'99import importlib.util as u100for parts in ((), ("data",), ("dynamics",), ("models",), ("gen",),101 ("dynamics", "mep"), ("enhanced_sampling",),102 ("training", "distillation")):103 m = ".".join(("nvalchemi", *parts))104 try:105 found = u.find_spec(m) is not None106 except ModuleNotFoundError:107 found = False108 print(m, found)109if u.find_spec("nvalchemi") is not None:110 import nvalchemi111 print(nvalchemi.__version__, nvalchemi.__file__)112EOF113```114115If the toolkit is not installed, say so. Write the code anyway, but stop116before running it. Do not fetch source or install packages to fill the gap.117118For a version mismatch or missing module, tell the user what it affects:119120- If version 0.2.0 or newer has the core modules nvalchemi.data,121 nvalchemi.dynamics, and nvalchemi.models, proceed with the 0.3.0 patterns.122 Flag each 0.3.0-only feature used. Check its API in the installed source123 before execution. If it is absent, write the code but do not run it.124- If a core module is missing or the version is below the 0.2.0 floor, stop125 execution and ask before any upgrade. Do not install or upgrade on your own.126127The installed wheel ships no docs or examples. Read the installed package128source and the linked docs and example pages only. Each note names the129source module. Locate its file with Python's inspect.getfile, then read it in130site-packages. Links are for reading, never for downloading code to run.131If the network is unavailable, use installed source.132133### Run on the GPU134135Pick the device once: use `cuda` when `torch.cuda.is_available()`, otherwise136`cpu`. Put the model, batch or dataset, and optimizer on that same device.137For dynamics, optimizer state comes from the batch. Pass138`device_type=device.type` to the engine. Given a model, structures, and the139agreed timestep and step budget:140141```python142import torch143from nvalchemi.data import Batch144from nvalchemi.dynamics import FIRE2, FusedStage145146device = torch.device("cuda" if torch.cuda.is_available() else "cpu")147model = model.to(device)148batch = Batch.from_data_list(data_list).to(device)149opt = FIRE2(model=model, dt=dt, n_steps=step_budget, device_type=device.type)150dyn = FusedStage(sub_stages=[(0, opt)], device_type=device.type)151for hook in model.make_neighbor_hooks():152 dyn.register_hook(hook)153```154155Complete the pre-flight check below before `dyn.run(batch)`. For training,156set `Dataset(..., device=device)` and `TrainingStrategy(..., devices=[device])`.157The strategy builds optimizers from the placed model (see the training note).158159Keep the step loop on the GPU. Avoid `.item()`, `.cpu()`, `.tolist()`,160`float(t)`, `print(t)`, `bool(t)`, a Python `if` on a tensor (including161`if tensor.any()`), and per-step host reads of batch.status. These wait for GPU162work before Python can continue. Host reads are fine at setup, at a163checkpoint, in a check every N steps (N > 1), and in the final report.164Prefer toolkit `run()` loops and hooks with a class-level `frequency` over a165hand-written step loop. Keep masks and reductions as device tensors.166167A small CPU check is fine. The delivered code must still select `cuda` when a168GPU exists. Do not hard-code `device="cpu"` to make the check pass. This holds169for scratch test scripts too. Pass `device_type=device.type` there as well.170171Build `AtomicData` only at setup, to validate input. In loops, work on172`Batch` tensors (see the data note, "Keep hot paths on `Batch`").173174### Batched dynamics pre-flight check175176Before every `run()`, confirm both checks in one line. Do not run until both177are true. Details are in178[dynamics-optimization.md](references/dynamics-optimization.md).1791801. **One batch, one engine or `FusedStage`.** Build one `Batch` with181 `Batch.from_data_list(...)` for all independent systems. Do not run each182 system in a Python loop. Use a `FusedStage` to retire each system on its183 own when it converges.1842. **Neighbor hooks registered.** Register every hook from185 `model.make_neighbor_hooks()` on the engine or fused stage before the186 first step. Models without a neighbor list return no hooks.187188```python189from nvalchemi.data import Batch190from nvalchemi.dynamics import FIRE2, ConvergenceHook, FusedStage191192batch = Batch.from_data_list(data_list).to(device) # many systems, one batch193opt = FIRE2(model=model, dt=0.1, n_steps=100, device_type=device.type,194 convergence_hook=ConvergenceHook.from_fmax(0.05))195dyn = FusedStage(sub_stages=[(0, opt)], device_type=device.type)196for hook in model.make_neighbor_hooks(): # BEFORE_COMPUTE hooks197 dyn.register_hook(hook)198with dyn:199 batch = dyn.run(batch)200```201202### Route to a note203204Match the task to the routing table. If it spans notes, read each note named205in the matching rows before you write code.206207| Task | Note |208| --- | --- |209| Build, batch, convert, or inspect atomic systems, field names, ASE input | [data.md](references/data.md) |210| Write, read, or stream Zarr stores, DataLoader throughput | [data.md](references/data.md) |211| Load a pretrained model (MACE, AIMNet2, UMA, LJ, DFT-D3, Ewald, PME) | [models.md](references/models.md) |212| Wrap a custom PyTorch model, combine models, outputs and embeddings | [models.md](references/models.md) |213| Relax structures, run MD (NVE, NVT, NPT), chain stages, scans | [dynamics-optimization.md](references/dynamics-optimization.md) |214| Built-in hooks: freezing, safety, logging, snapshots, convergence, timing | [dynamics-optimization.md](references/dynamics-optimization.md) |215| Reaction paths and NEB, restraints and enhanced sampling | [dynamics-optimization.md](references/dynamics-optimization.md) |216| Train from scratch, losses, checkpoints, resume, DDP | [training.md](references/training.md) |217| Fine-tune a pretrained model, distill a teacher into a student | [training.md](references/training.md) |218| Sample structures with a generative model, generate then relax | [generative-workflows.md](references/generative-workflows.md) |219| Write a new hook, integrator, optimizer, loss, bias, or reporter | [composition-and-extension.md](references/composition-and-extension.md) |220| Domain decomposition, dynamics stages on different GPUs, dashboards | [composition-and-extension.md](references/composition-and-extension.md) |221| Custom NEB force equation or spring policy | [dynamics-optimization.md](references/dynamics-optimization.md) |222| Save and restore dynamics or sampling state, Hessians | [dynamics-optimization.md](references/dynamics-optimization.md), [models.md](references/models.md) |223| Crystal structure prediction (the nvalchemi.csp package) | [generative-workflows.md](references/generative-workflows.md) |224225### Reuse first2262271. **Reuse.** Search the shipped components before you write anything. The228 notes list them per area. Most needs (freezing atoms, NaN checks, drift229 warnings, logging, snapshots, step budgets, restraints) already exist.2302. **Subclass for a small change.** If a shipped class is close, subclass it231 and override the one method that differs.2323. **Write new code only for missing behavior.** Follow the protocol the toolkit233 defines (for example the `Hook` protocol or `BaseDynamics`), so it composes234 with the rest.235236Say which path you took and why, in one line, when you hand back the code.237238### Workspace rules239240- Keep scratch files under the working folder you were given, for example in241 a scratch subfolder. Do not write elsewhere unless the user asks.242- Do not delete files or folders with `rm -rf` or `rm -r`, even for caches or243 temporary folders. Leave `__pycache__`, Zarr scratch stores, and temporary244 folders in place. If a single file must go, name it with `rm -f <file>` and245 say why. Ask first if the user has not granted delete permission.246- Read only installed package source and linked docs and example pages.247 Do not download source files, scripts, or wheels with `curl`, `wget`, or248 `git`. Do not download code to run by any other means.249- Do not print environment variables. Do not run `env` or `printenv`, or250 dump os.environ. These can expose secrets in tool output.251- Ask before you install, upgrade, or remove packages.252253### Report the result254255In the final message, name any script you wrote and the toolkit components256you used. Report measured results with units only for work you ran. If you257did not execute the work, say "Not executed" and why. Do not invent numbers.258If the run failed or did not converge, say so and give the measured values.259Do not present a capped or failed run as a converged result.260261## Limitations262263- The notes track release 0.3.0. Older installs miss generative sampling,264 reaction paths, enhanced sampling, distillation, and other 0.3.0 APIs.265- Multi-GPU and multi-node runs need a launcher (`torchrun` or Slurm). Write266 the script and the launch command. Do not start multi-GPU jobs unasked.267- Model backends download checkpoints on first use. Offline machines need the268 checkpoint file in advance.269270## Troubleshooting271272| Symptom | Likely cause | Fix |273| --- | --- | --- |274| `KeyError: 'neighbor_matrix' required` or `'neighbor_list'` | No neighbor-list hook | Register `model.make_neighbor_hooks()` |275| `AttributeError: ... no attribute 'masses'` | Field is `atomic_masses` | Use `batch.atomic_masses` |276| `InvalidCxxCompiler` or Inductor build error on CPU | `NeighborListHook` is compiled, no C++ toolchain | Run eagerly, see dynamics note |277| `AttributeError: 'Batch' has no attribute 'status'` | Plain dynamics does not create `status` | Add a `status` column, see dynamics note |278| `FileExistsError: Zarr store already exists` | `write()` on an existing store | Use `append()` or a new path |279| `ValueError: ... pattern ... did not match any parameter` | Wrong fine-tuning glob | Print `named_parameters()` and fix the glob |280| `ValueError: ... has no trainable parameters` with MACE | `MACEWrapper` freezes weights by default since 0.3.0 | Load with `train=True`, see the training note |