API Reference¶

RootstockCalculator¶

The main interface to Rootstock is the RootstockCalculator class, an ASE-compatible calculator.

Basic Usage¶

from ase.build import bulk
from rootstock import RootstockCalculator

atoms = bulk("Cu", "fcc", a=3.6) * (5, 5, 5)

with RootstockCalculator(
    cluster="della",
    checkpoint="mace-mp-0-medium",
    device="cuda",
) as calc:
    atoms.calc = calc
    energy = atoms.get_potential_energy()
    forces = atoms.get_forces()
    stress = atoms.get_stress()

Parameters¶

*Either cluster or root must be provided, but not both.

Examples¶

# Using a known cluster
RootstockCalculator(cluster="della", checkpoint="mace-mp-0-medium")

# Perlmutter — install root and cache root come from the registry
RootstockCalculator(cluster="perlmutter", checkpoint="uma-s-1p1")

# Custom install root (cache_root defaults to the install root)
RootstockCalculator(root="/scratch/gpfs/specific/install/rootstock", checkpoint="mace-mp-0-medium")

# Explicit split between install root and cache root
RootstockCalculator(
    root="/global/cfs/cdirs/myproj/rootstock",
    cache_root="/pscratch/sd/u/me/rootstock-cache",
    checkpoint="uma-s-1p1",
    setup_kwargs={"task": "omol"},
)

Context Manager¶

RootstockCalculator should be used as a context manager to ensure proper cleanup of the worker subprocess:

with RootstockCalculator(...) as calc:
    # Use the calculator
    atoms.calc = calc
    energy = atoms.get_potential_energy()
# Worker process is automatically terminated when exiting the context

Available Models¶

Available models vary by cluster and change as new environments are added. See the Example Configs page for current deployments on each cluster.

Checkpoint Reference¶

Canonical checkpoint ids deployed by the bundled env files in sample_model_configurations/nvidia_configs/:

Checking Available Models¶

To see available models on your cluster, check the Example Configs page or run:

rootstock status

This command displays installed environments, their checkpoints, and cache sizes.

CLI Reference¶

The Rootstock CLI provides commands for both administrators (setting up clusters) and users (querying available environments).

User Commands¶

Commands users can run to explore available environments:

rootstock status¶

Display installation status, including all installed environments and cache usage.

rootstock status

rootstock list¶

List all registered environments in the shared environments directory.

rootstock list

rootstock resolve¶

Look up the root directory for a known cluster.

# Human-readable output
rootstock resolve --cluster della

# JSON output
rootstock resolve --cluster della --json

Administrator Commands¶

Commands for cluster administrators to set up and manage Rootstock installations:

rootstock init¶

Interactive setup wizard for creating a new Rootstock installation. Prompts for:

• Root directory path
• API credentials for dashboard integration (optional)
• Maintainer information

rootstock init

# Skip directory creation
rootstock init --skip-dirs

# Skip manifest initialization
rootstock init --skip-manifest

rootstock new-env¶

Create a new environment template file with the required PEP 723 structure.

# Create template in current directory
rootstock new-env mace

# Specify output path
rootstock new-env mace -o ./environments/mace.py

# Overwrite existing file
rootstock new-env mace --force

rootstock install¶

Build environment(s) from a file or directory. Builds the venv only — no model weights. Use rootstock add separately to download and verify checkpoints.

# Install from a single file
rootstock install ./mace.py

# Install all environments from a directory
rootstock install ./environments/

# Rebuild an existing environment
rootstock install mace --force

# Install without pushing manifest to backend
rootstock install mace.py --no-push

Options:

• --root <path>: Specify root directory (or use $ROOTSTOCK_ROOT)
• --force: Update registration and rebuild if environment exists
• --verbose, -v: Verbose output
• --no-push: Skip pushing manifest to backend

rootstock add¶

Download and verify a checkpoint by canonical id. The hosting env is resolved by walking the installed envs and matching the id against each env's CHECKPOINTS table. Idempotent — safe to re-run.

# Login node (CPU, has network): download only
rootstock add mace-mp-0-medium --no-verify

# GPU node (no network): skip download (already fetched), verify on GPU
rootstock add mace-mp-0-medium

# Forward extra kwargs to setup() — values are JSON-decoded, fall back to strings
rootstock add uma-s-1p1 --kwarg task=omat
rootstock add esen-md-direct-all-omol --kwarg charge=-1 --kwarg enabled=true

Options:

• --device <dev>: Device for verification (default: cuda)
• --no-verify: Skip the verify phase (login-node escape hatch)
• --kwarg KEY=VAL: Repeatable extra kwarg passed to setup(). Values are JSON-decoded first; on parse failure, fall back to a string
• --root <path>: Root directory
• --no-push: Skip pushing manifest to backend

rootstock smoke-test¶

Re-verify checkpoints already in the manifest. Never downloads. Suitable for nightly cron.

# Test all fetched checkpoints
rootstock smoke-test

# Filter
rootstock smoke-test --env mace
rootstock smoke-test --env mace --checkpoint mace-mp-0-medium

# JSON summary for cron
rootstock smoke-test --json

Exit code is 0 if all tested checkpoints passed, 1 otherwise.

rootstock serve¶

Start a worker process for an external i-PI server (advanced usage).

rootstock serve mace-mp-0-medium \
  --socket /tmp/ipi_socket \
  --device cuda

rootstock manifest¶

Manage the installation manifest that tracks environment state.

# Show current manifest
rootstock manifest show
rootstock manifest show --json

# Push manifest to dashboard
rootstock manifest push

# Initialize new manifest
rootstock manifest init --cluster della
rootstock manifest init --cluster della --force