nvalchemi-toolkit: Instructions file for Codex

AGENTS.md - NVIDIA ALCHEMI Toolkit

Guidelines for AI coding agents operating in this repository.

Project Overview

nvalchemi-toolkit provides the nvalchemi Python package: a GPU-first framework for AI atomic simulation workflows. It covers graph-structured atomic data, model wrappers for machine-learned interatomic potentials, batched dynamics, hooks/reporting, and training/finetuning workflows.

• Python support: >=3.11,<3.14; CI and setup examples use Python 3.12.
• Package manager: uv; build backend: hatchling.
• Core dependencies: PyTorch, Pydantic v2, jaxtyping, TensorDict, Zarr, Rich, PhysicsNeMo, and nvalchemi-toolkit-ops.
• The project is in public beta. Public PRs may not be accepted immediately, but bug reports, feature requests, and scoped implementation discussions are welcome.

Repository Practices

• Commits need DCO sign-off and Conventional Commits-style messages: git commit -s -m "fix: describe change". Pre-commit hooks are required; PRs that skip them are not expected to be reviewed. See CONTRIBUTING.md for DCO details, hook setup, and CI stages.
• The PR template expects a short description, testing notes, changelog updates, docstring/docs updates where applicable, and the relevant type-of-change box.
• Keep work tightly scoped; read docs/userguide/about/ before broad changes.

CUDA And Environment Setup

First check CUDA availability:

nvidia-smi

• If nvidia-smi is missing or reports no usable device, use default uv commands without CUDA extras where possible.
• If it reports CUDA 12.x, pass --extra cu12 to uv commands and CUDA_EXTRA=cu12 to make targets.
• If it reports CUDA 13.x, cu13 is the default Makefile extra; explicit commands can still use --extra cu13 or CUDA_EXTRA=cu13.
• Do not use uv sync --all-extras: the CUDA variants and some model extras are mutually exclusive.

Common setup commands:

# Default development environment; Makefile currently defaults CUDA_EXTRA=cu13.
make install

# CUDA 12 development environment.
make install CUDA_EXTRA=cu12

# Add CUDA-aligned optional extras, for example MACE.
make install CUDA_EXTRA=cu12 OPTIONAL_EXTRAS=mace

# Direct uv equivalents.
uv sync --extra cu13
uv sync --extra cu12 --extra mace

# Include documentation dependencies when needed.
uv sync --extra cu13 --group docs