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

# Quickstart Guide

Complete the [Prerequisites](/nim/alchemi/alchemi-bmd/1.0.0/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.0.0
```


## Run the NIM Container

**Pre-bundled model:** The default configuration uses the **MACE-MPA-0**
model, which is bundled and auto-downloaded when you provide an NGC API key. 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/1.0.0/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.0.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 `{"status":"ready"}` before you
proceed. 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/1.0.0/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/1.0.0/configuration) and
[Environment Variables](/nim/alchemi/alchemi-bmd/1.0.0/environment-variables).

## Stop the NIM Container

Run the following command to stop the running NIM container:

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