> This page is for NVIDIA NIM for Batched Molecular Dynamics, version 1.0.0.
> For other versions, use one of these documentation indexes:
> - 1.1.0 (Latest) (default): https://docs.nvidia.com/nim/alchemi/alchemi-bmd/1.1.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/alchemi/alchemi-bmd/1.0.0/llms.txt
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/alchemi/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/alchemi/_mcp/server.
# Custom Models
The default quickstart uses the bundled **MACE-MPA-0** model. For the
default setup, follow the [Quickstart Guide](/nim/alchemi/alchemi-bmd/1.0.0/quickstart-guide).
## Use Custom or Downloaded Models
The bundled MACE model (auto-downloaded with an NGC API key) can be used. You
can also provide MACE, AIMNet2, or TensorNet models by downloading them and
mounting the model file or directory into the container. Choose the model type
from the following tabs 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-MPA-0 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](https://github.com/ACEsuit/mace-foundations/releases) for download links. For example:
```bash
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:
```bash
export ALCHEMI_MODEL_PATH=/path/to/mace.model
export NGC_API_KEY=
```
```bash
docker run --rm -ti --name alchemi-bmd --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-bmd:1.0.0
```
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](https://isayevlab.github.io/aimnetcentral/models/guide/#direct-model-downloads), whose links can be used as follows:
**Downloading an AIMNet2 model**
```bash
# 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:
```bash
export NGC_API_KEY=
```
```bash
docker run --rm -ti --name alchemi-bmd --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-bmd:1.0.0
```
TensorNet models are not bundled; download the model and mount it.
TensorNet models are available on
[matgl](https://github.com/materialyzeai/matgl/tree/main/pretrained_models). 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:
```bash
curl -L https://codeload.github.com/materialsvirtuallab/matgl/tar.gz/main | tar -xz --strip=2 matgl-main/pretrained_models/
```
The following is an example:
**Downloading a TensorNet model**
```bash
# 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:
```bash
export NGC_API_KEY=
```
```bash
docker run --rm -ti --name alchemi-bmd --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-bmd:1.0.0
```
## Example Configurations
This section is a quick reference for common configurations. For download steps
and model-type-specific launch details, refer to
[Use Custom or Downloaded Models](#use-custom-or-downloaded-models).
### MACE for Periodic Systems (Default)
Run the following commands:
```bash
export NGC_API_KEY=
```
```bash
docker run --rm -ti --name alchemi-bmd --gpus=all \
-e NGC_API_KEY \
-p 8000:8000 \
--shm-size=8g \
nvcr.io/nim/nvidia/alchemi-bmd:1.0.0
```
### AIMNet2 for Organic Molecular Systems
Run the following commands:
```bash
export ALCHEMI_MODEL_PATH=/path/to/aimnet-model.pt
```
```bash
docker run --rm -ti --name alchemi-bmd --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" \
-e ALCHEMI_NIM_PBC=false \
nvcr.io/nim/nvidia/alchemi-bmd:1.0.0
```
### TensorNet for Periodic Materials
Run the following commands:
```bash
export ALCHEMI_MODEL_PATH=/path/to/model-dir
```
```bash
docker run --rm -ti --name alchemi-bmd --gpus=all \
-p 8000:8000 --shm-size=8g \
-v "${ALCHEMI_MODEL_PATH}:/opt/nim/.cache/TensorNet:ro" \
-e 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-bmd:1.0.0
```