> 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.

# Quickstart Guide

Complete the [Prerequisites](/nim/alchemi/alchemi-bmd/prerequisites) before you start.

## Pull the NIM Container

Run the following command to pull the container:

```bash
docker pull nvcr.io/nim/nvidia/alchemi-bmd:1.1.0
```


## Run the NIM Container

**Default model:** The default configuration downloads the **MACE-MPA-0**
medium checkpoint from
[Hugging Face](https://huggingface.co/mace-foundations/mace-mpa-0) when the
container starts. No manual model download or mount is required for the default
use case.

For custom or alternative models (other MACE checkpoints, AIMNet2, or
TensorNet), refer to [Custom Models](/nim/alchemi/alchemi-bmd/custom-models).

Run the following command to start the NIM container and expose port 8000 for
interaction:

```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
```


The output should display messages similar to the following:

```bash
INFO     | BMD:cuda:0 |  Starting BMD engine worker on cuda:0
INFO     | BMD:cuda:1 |  Starting BMD engine worker on cuda:1
```

At this point, the server might perform automatic batch size estimation (unless
you set `ALCHEMI_NIM_BATCH_SIZE`), which produces output similar to the
following:

```bash
INFO     | BMD:cuda:0 |  Starting BMD engine worker on cuda:0
INFO     | BMD:cuda:0 |  Atom count 192 took 12.90 ms, 67.17 μs/atom (3 runs)
INFO     | BMD:cuda:0 |  Atom count 504 took 14.06 ms, 27.89 μs/atom (3 runs)
...
INFO     | BMD:cuda:0 |  Estimated batch size: 4104, max: 38956
INFO     | BMD:cuda:0 |  Backend cuda:0 ready for inference
INFO     | BMD:cuda:0 |  Backend cuda:0 is ready (took 88.68s)
INFO     | BMD:cuda:0 |  Status server started on ipc:///tmp/nim_status_cuda_0.ipc
INFO     | BMD:cuda:0 |  Initialization complete on cuda:0
```

After initialization is complete, the Triton server starts and is ready when
the following logging statements appear:

```bash
... "Started HTTPService at 0.0.0.0:8000"
... "Started Metrics Service at 0.0.0.0:8002"
```

## Check the Health of the NIM

Open a new terminal, leaving the current terminal open with the launched
service.

In the new terminal, run the following command to query the health check:

```bash
curl -X 'GET' \
    'http://localhost:8000/v1/health/ready' \
    -H 'accept: application/json'
```

Wait until the health check endpoint returns HTTP 200 with `"status":"ready"`
before you proceed. The successful response also includes `backends_alive` and
`backends_total`. During startup or a health failure, a 503 response might
contain only a `status` message. This can take a couple of minutes while the NIM
estimates optimal batch sizes for the GPU.

To check the NIM's status using Python, use the `requests` module:

```python
import requests

url = "http://localhost:8000/v1/health/ready"

headers = {
    "content-type": "application/json"
}
try:
    response = requests.get(url, headers=headers)
    if response.ok:
        print("Request succeeded:", response.json())
    else:
        print("Request failed:", response.status_code, response.text)
except Exception as E:
    print("Request failed:", E)
```

## Example Usage

For the request format and required atomic data fields, refer to
[API Reference](/nim/alchemi/alchemi-bmd/api-reference#post-v1infer). Note the **BMDAtomicData
fields (atoms)** and **MDConfig fields (config)** tables.

Install the Python library used in the following code sample:

```bash
pip install requests
```

### Basic MD Simulation

The following code sample demonstrates a simple NVT molecular dynamics
simulation:

```python
import requests

server_url = "http://localhost:8000"

# Define atomic structure and MD configuration
request = {
    "atoms": {
        "coord": [0.0, 0.0, 0.0, 1.5, 0.0, 0.0],  # Two carbon atoms
        "numbers": [6, 6],
        "cell": [10.0, 0.0, 0.0, 0.0, 10.0, 0.0, 0.0, 0.0, 10.0],
        "pbc": [True, True, True]
    },
    "config": {
        "temperature": 300.0,    # K
        "dt": 1.0,               # fs
        "md_time_max": 1.0,      # ps (total simulation time)
        "nvt": True,             # Use NVT ensemble
        "save_interval": 10      # Save every 10 steps
    }
}

response = requests.post(f"{server_url}/v1/infer", json=request)
response.raise_for_status()
result = response.json()

print(f"Status: {result['status']}")
print(f"Number of snapshots: {len(result['trajectory'])}")

# Access trajectory data
for snapshot in result["trajectory"]:
    print(f"Step {snapshot['istep']}: E = {snapshot['energy']:.4f} eV, "
          f"time = {snapshot['md_time']:.4f} ps")
```

## Configuration Options

For the complete configuration reference and all environment variables, refer to
[Configuration](/nim/alchemi/alchemi-bmd/configuration) and
[Environment Variables](/nim/alchemi/alchemi-bmd/environment-variables).

## Stop the NIM Container

Run the following command to stop the running NIM container:

```bash
docker stop alchemi-bmd
```