Is this page helpful?

Custom Models#

The default launch flow downloads the MACE-MPA-0 medium checkpoint from Hugging Face at container startup. For the default setup, follow the Quickstart Guide.

For runtime tuning examples such as cell optimization and DFT-D3 dispersion, refer to Tuning Parameters.

Use Custom or Downloaded Models#

You can use the default MACE-MPA-0 checkpoint or provide a supported MACE, AIMNet2, or TensorNet model by downloading it and mounting the model file or directory into the container. Choose the model type below for download hints and the exact arguments to pass when launching the container.

MACE

MACE models are for periodic systems only (pbc: true). The default MACE-MPA-0 medium checkpoint is downloaded from Hugging Face at container startup. User-provided checkpoints from the MACE-MP model family are supported, including checkpoints trained from that model family. To use a different supported MACE checkpoint, do the following:

Downloading a MACE model

Refer to the MACE foundation model GitHub [releases](ACEsuit/mace-foundations) for download links. For example:

curl -LO https://github.com/ACEsuit/mace-foundations/releases/download/mace_mpa_0/mace-mpa-0-medium.model
export ALCHEMI_MODEL_PATH=mace-mpa-0-medium.model

Launching the container with MACE

Run the following commands to launch the container:

export ALCHEMI_MODEL_PATH=/path/to/mace.model
export NGC_API_KEY=<Your NGC API Key>
docker run --rm -ti --name alchemi-bgr --gpus=all \
    -e NGC_API_KEY \
    -p 8000:8000 --shm-size=8g \
    -v "${ALCHEMI_MODEL_PATH}:/opt/nim/.cache/mace.model:ro" \
    -e ALCHEMI_NIM_DISABLE_MODEL_DOWNLOAD=true \
    -e ALCHEMI_NIM_MODEL_TYPE="mace" \
    -e ALCHEMI_NIM_MODEL_PATH=/opt/nim/.cache/mace.model \
    nvcr.io/nim/nvidia/alchemi-bgr:1.1.0

AIMNet2

AIMNet2 models are not included in the container. Mount one v2-format .pt checkpoint file with format_version set to 2. You can download a compatible checkpoint or export a trained model as a v2-format checkpoint by following the AIMNetCentral model-format guide. AIMNet2 supports both periodic and non-periodic systems. The backend defaults to periodic mode (ALCHEMI_NIM_PBC=true); set ALCHEMI_NIM_PBC=false for non-periodic systems.

Downloading an AIMNet2 model

# Download and mount one v2-format .pt checkpoint file.
curl -OL https://storage.googleapis.com/aimnetcentral/aimnet2v2/AIMNet2/aimnet2_2025_b973c_d3_0.pt
export ALCHEMI_MODEL_PATH=./aimnet2_2025_b973c_d3_0.pt

Launching the container with AIMNet2

Run the following commands to launch the container:

export NGC_API_KEY=<Your NGC API Key>
docker run --rm -ti --name alchemi-bgr --gpus=all \
    -e NGC_API_KEY \
    -p 8000:8000 --shm-size=8g \
    -v "${ALCHEMI_MODEL_PATH}:/opt/nim/.cache/aimnet2.pt:ro" \
    -e ALCHEMI_NIM_DISABLE_MODEL_DOWNLOAD=true \
    -e ALCHEMI_NIM_MODEL_TYPE="aimnet2" \
    -e ALCHEMI_NIM_MODEL_PATH=/opt/nim/.cache/aimnet2.pt \
    -e ALCHEMI_NIM_PBC=true \
    nvcr.io/nim/nvidia/alchemi-bgr:1.1.0

TensorNet

TensorNet models are not included in the container; download and mount the model directory. The directory must contain model.json, model.pt, and state.pt. TensorNet models are available on Hugging Face. The easiest way to download the complete directory is to use Hugging Face Hub:

python -m pip install -U huggingface_hub

The following is an example:

Downloading a TensorNet model

# Download a TensorNet/MatPES model from materialyze on Hugging Face.

hf download materialyze/TensorNet-PES-MatPES-r2SCAN-2025.2 \
--repo-type model \
--local-dir ./TensorNet-PES-MatPES-r2SCAN-2025.2

export ALCHEMI_MODEL_PATH="$PWD/TensorNet-PES-MatPES-r2SCAN-2025.2"

Launching the container with TensorNet

Run the following commands to launch the container:

export NGC_API_KEY=<Your NGC API Key>
docker run --rm -ti --name alchemi-bgr --gpus=all \
    -e NGC_API_KEY \
    -p 8000:8000 --shm-size=8g \
    -v "${ALCHEMI_MODEL_PATH}:/opt/nim/.cache/TensorNet:ro" \
    -e ALCHEMI_NIM_DISABLE_MODEL_DOWNLOAD=true \
    -e ALCHEMI_NIM_MODEL_TYPE="tensornet" \
    -e ALCHEMI_NIM_MODEL_PATH="/opt/nim/.cache/TensorNet" \
    nvcr.io/nim/nvidia/alchemi-bgr:1.1.0

Example Configurations#

This section is a quick reference for common model configurations. For tuning-focused launch examples, refer to Tuning Parameters.

MACE for Periodic Materials (Default)#

Run the following commands:

export NGC_API_KEY=<Your NGC API Key>
docker run --rm -ti --name alchemi-bgr --gpus=all \
    -e NGC_API_KEY \
    -p 8000:8000 --shm-size=8g \
    nvcr.io/nim/nvidia/alchemi-bgr:1.1.0

AIMNet2 for Organic Molecular Systems#

Run the following commands:

export ALCHEMI_MODEL_PATH=/path/to/aimnet-model.pt
docker run --rm -ti --name alchemi-bgr --gpus=all \
    -e NGC_API_KEY \
    -p 8000:8000 --shm-size=8g \
    -v "${ALCHEMI_MODEL_PATH}:/opt/nim/.cache/aimnet.pt:ro" \
    -e ALCHEMI_NIM_DISABLE_MODEL_DOWNLOAD=true \
    -e ALCHEMI_NIM_MODEL_TYPE="aimnet2" \
    -e ALCHEMI_NIM_MODEL_PATH="/opt/nim/.cache/aimnet.pt" \
    -e ALCHEMI_NIM_PBC=false \
    nvcr.io/nim/nvidia/alchemi-bgr:1.1.0