Quickstart Guide

Complete the Prerequisites before you start.

Pull the NIM Container

Run the following command to pull the container:

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.

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

export NGC_API_KEY=<Your NGC API Key>

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:

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:

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:

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

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:

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. Note the BMDAtomicData fields (atoms) and MDConfig fields (config) tables.

Install the Python library used in the following code sample:

pip install requests

Basic MD Simulation

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

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 and Environment Variables.

Stop the NIM Container

Run the following command to stop the running NIM container:

docker stop alchemi-bmd