> This page is for NVIDIA NIM for Batched Geometry Relaxation, 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-bgr/1.1.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/alchemi/alchemi-bgr/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-bgr/prerequisites) before you start.

For custom or alternative models, refer to [Custom Models](/nim/alchemi/alchemi-bgr/custom-models).
For advanced request workflows, refer to [Examples](/nim/alchemi/alchemi-bgr/examples).

## Pull the NIM Container

Run the following command to pull the container:

```bash
docker pull nvcr.io/nim/nvidia/alchemi-bgr: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.

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-bgr --gpus=all \
    -e NGC_API_KEY \
    -p 8000:8000 \
    --shm-size=8g \
    nvcr.io/nim/nvidia/alchemi-bgr:1.1.0
```


The output should display messages similar to the following:

```bash
INFO     | BGR:cuda:0 |  Starting BGR engine worker on cuda:0
INFO     | BGR:cuda:1 |  Starting BGR 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     | BGR:cuda:0 |  Starting BGR engine worker on cuda:0
INFO     | BGR:cuda:0 |  Atom count 192 took 12.90 ms, 67.17 μs/atom (3 runs)
INFO     | BGR:cuda:0 |  Atom count 504 took 14.06 ms, 27.89 μs/atom (3 runs)
...
INFO     | BGR:cuda:0 |  Estimated batch size: 4104, max: 38956
INFO     | BGR:cuda:0 |  Backend cuda:0 ready for inference
INFO     | BGR:cuda:0 |  Backend cuda:0 is ready (took 88.68s)
INFO     | BGR:cuda:0 |  Status server started on ipc:///tmp/nim_status_cuda_0.ipc
INFO     | BGR: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
INFO 2026-03-03 17:40:33.087 nimutils.py:79] I0303 17:40:33.087241 106 http_server.cc:4809] "Started HTTPService at 0.0.0.0:8000"
INFO 2026-03-03 17:40:33.130 nimutils.py:79] I0303 17:40:33.130584 106 http_server.cc:358] "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)
```

## Basic Inference Request

For the request format and required atomic data fields, refer to
[API Reference](/nim/alchemi/alchemi-bgr/api-reference#post-v1infer).

Install the Python library used in the code sample:

```bash
pip install requests
```

The following code sample demonstrates a simple inference request with a hydrogen
molecule in a periodic cell:

```python
import requests

server_url = "http://localhost:8000"

# Simple H2 molecule in a periodic box
package = {
    'atoms': [{
        'coord': [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
        'numbers': [1, 1],
        'cell': [10, 0, 0, 0, 10, 0, 0, 0, 10],
    }],
}

result = requests.post(f"{server_url}/v1/infer", json=package)
result.raise_for_status()
print(result.json())
```

## Configuration Options

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

## Stop the NIM Container

Run the following command to stop the running NIM container:

```bash
docker stop alchemi-bgr
```