Is this page helpful?

Custom Models#

The default launch flow uses the bundled MACE-MP-0b2-Large model. 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#

The bundled MACE model (auto-downloaded with an NGC API key) can be used, or you can provide MACE, AIMNet2, or TensorNet models by downloading them 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 models are for periodic systems only (pbc: true). The default MACE-MP-0b2-Large model is bundled and auto-downloaded when NGC_API_KEY is set. To use a different MACE model (for example, a custom-trained model), 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 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:${__container_version}

AIMNet2 models are not bundled with the container; download or train a model and mount the model file. For trained models, a selection of checkpoints are available for download from AIMNetCentral, whose links can be used as follows:

Downloading an AIMNet2 model

# Download a model from AIMNet Central (or another source). Mount the contents of the model directory.
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 NIM_DISABLE_MODEL_DOWNLOAD=true \
    -e ALCHEMI_NIM_MODEL_TYPE="aimnet2" \
    -e ALCHEMI_NIM_MODEL_PATH=/opt/nim/.cache/aimnet2.pt \
    nvcr.io/nim/nvidia/alchemi-bgr:${__container_version}

TensorNet models are not bundled; download the model and mount it. TensorNet models are available on matgl. The easiest way to download a particular model directory (the entire directory, not just the .pt checkpoint file, is necessary) is to do the following:

curl -L https://codeload.github.com/materialsvirtuallab/matgl/tar.gz/main | tar -xz --strip=2 matgl-main/pretrained_models/<model-directory>

The following is an example:

Downloading a TensorNet model

# Download a TensorNet/MatPES model (for example, from materialyzeai/matgl or the model provider).
curl -L https://codeload.github.com/materialsvirtuallab/matgl/tar.gz/main | tar -xz --strip=2 matgl-main/pretrained_models/TensorNet-MatPES-PBE-v2025.1-PES
export ALCHEMI_MODEL_PATH=./TensorNet-MatPES-PBE-v2025.1-PES

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_MODEL_TYPE="tensornet" \
    -e ALCHEMI_NIM_MODEL_PATH="/opt/nim/.cache/TensorNet" \
    nvcr.io/nim/nvidia/alchemi-bgr:${__container_version}

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:${__container_version}

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 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:${__container_version}