> This page is for NVIDIA NIM for Batched Molecular Dynamics, version 1.1.0 (Latest) (default).
> 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 downloads the **MACE-MPA-0** medium checkpoint from
Hugging Face at container startup. For the default setup, follow the
[Quickstart Guide](/nim/alchemi/alchemi-bmd/quickstart-guide).

## 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
from the following tabs for download hints and the exact arguments to pass when
launching the container.

<Tabs>
  <Tab title="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](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=<Your 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 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-bmd:1.1.0
```


  </Tab>
  <Tab title="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](https://isayevlab.github.io/aimnetcentral/model_format/).
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**

```bash
# 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:

```bash
export NGC_API_KEY=<Your 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 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-bmd:1.1.0
```


  </Tab>
  <Tab title="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](https://huggingface.co/materialyze). The easiest way to
download the complete directory is to use Hugging Face Hub:

```bash
python -m pip install -U huggingface_hub
```

The following is an example:

**Downloading a TensorNet model**

```bash
# 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:

```bash
export NGC_API_KEY=<Your 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_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.1.0
```


  </Tab>
</Tabs>

## 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=<Your 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.1.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 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=false \
    nvcr.io/nim/nvidia/alchemi-bmd:1.1.0
```


### TensorNet for Periodic Materials

Run the following commands:

```bash
export ALCHEMI_MODEL_PATH=/path/to/model-dir
export NGC_API_KEY=<Your 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_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.1.0
```