> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/alchemi/alchemi-bmd/1.0.0/api-reference/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/alchemi/_mcp/server.

# API Reference

## OpenAPI Schema

The [API Reference](https://docs.nvidia.com/nim/alchemi/alchemi-bgr/1.1.0/api-reference/process-request-v-1-infer-post) tab details the following endpoints:

- `/v1/infer` Inference endpoint for molecular dynamics simulations
- `/v1/health/live` Health liveliness endpoint
- `/v1/health/ready` Health readiness endpoint
- `/v1/status` System status monitoring endpoint

## Endpoints

### POST /v1/infer

Run a molecular dynamics simulation on a single atomic structure.

**Request Body:**

The request body contains the following fields:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `atoms` | object | Yes | Atomic structure for the simulation |
| `config` | object | No | MD simulation configuration (uses defaults if not provided) |
| `info` | string | No | Optional metadata to echo back |

**BMDAtomicData Fields (`atoms`):**

The following table lists the `atoms` field parameters (`BMDAtomicData`):

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `coord` | array[float] | Yes | Flattened coordinates [x1,y1,z1,x2,y2,z2,...] in Angstrom |
| `numbers` | array[int] | Yes | Atomic numbers |
| `cell` | array[float] | No | Unit cell (9 elements, row-major) in Angstrom |
| `pbc` | array[bool] | No | Periodic boundary conditions [x,y,z], default [true,true,true] |
| `charge` | int | No | System charge, default 0 |
| `mult` | int | No | Spin multiplicity (2S+1), default 1 |
| `mass` | array[float] | No | Atomic masses in amu (uses standard if not provided) |
| `velocity` | array[float] | No | Initial velocities [vx1,vy1,vz1,...] in Å/fs (Maxwell-Boltzmann if not provided) |

**MDConfig Fields (`config`):**

The following table lists the `config` field parameters (`MDConfig`):

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `temperature` | float | 300.0 | Target temperature in K |
| `dt` | float | 1.0 | Timestep in fs |
| `nvt` | bool | true | Enable NVT ensemble |
| `friction` | float | 1.0 | Langevin friction in ps^-1 |
| `npt` | bool | false | Enable NPT ensemble |
| `pressure` | float | 0.0 | Target pressure in kBar |
| `barostat_anisotropic` | bool | false | Enable anisotropic barostat |
| `barostat_every` | int | 25 | Barostat update frequency |
| `barostat_prob_shear` | float | 0.5 | Shear move probability |
| `barostat_shear_max` | float | 0.01 | Max shear magnitude |
| `barostat_diag_max` | float | 0.01 | Max diagonal change |
| `barostat_log_scale_max` | float | 0.001 | Max log-scale move |
| `md_time` | float | 0.0 | Starting time in ps (for restart) |
| `md_time_max` | float | 10.0 | Max simulation time in ps |
| `save_interval` | int | 100 | Save every N steps |
| `istep` | int | 0 | Starting step (for restart) |
| `efield` | array[float] | [0,0,0] | Electric field [Ex,Ey,Ez] in μV/Å |

**Response:**

The response contains the following fields:

| Field | Type | Description |
|-------|------|-------------|
| `trajectory` | array | List of trajectory snapshots |
| `config` | object | Final MDConfig state (updated istep/md_time) |
| `status` | string | Status message ("Success" or error) |
| `info` | string | Echoed metadata from request |

**BMDSnapshot Fields (`trajectory` items):**

The following table lists the `trajectory` items (`BMDSnapshot`):

| Field | Type | Description |
|-------|------|-------------|
| `coord` | array[float] | Atomic coordinates in Angstrom |
| `velocity` | array[float] | Atomic velocities in Å/fs |
| `energy` | float | Potential energy in eV |
| `cell` | array[float] | Unit cell (if periodic) |
| `stress` | array[float] | Stress tensor in kBar (if periodic) |
| `charges` | array[float] | Partial charges (if available) |
| `istep` | int | Step number |
| `md_time` | float | Simulation time in ps |

### GET /v1/health/ready

Check if the NIM is ready to accept inference requests.

**Response:**

```json
{
  "status": "ready",
  "backends_alive": 2,
  "backends_total": 2
}
```

### GET /v1/health/live

Check if the Triton server is live.

**Response:**

```json
{
  "status": "live"
}
```

### GET /v1/status

Get detailed system status including worker metrics.

**Response:**

```json
{
  "total": {
    "tasks_received": 100,
    "tasks_completed": 95,
    "queue_size_atoms": 1024,
    "queue_size_tasks": 5,
    "requests_received": 50,
    "requests_completed": 48,
    "requests_in_progress": 2,
    "max_system_size": 36876
  },
  "workers": [
    {
      "device": "cuda:0",
      "tasks_received": 50,
      "tasks_completed": 48,
      "queue_size_atoms": 512,
      "queue_size_tasks": 2,
      "batch_size": 36876,
      "max_batch_size": 47136,
      "gpu_model": "NVIDIA H100 80GB HBM3"
    }
  ]
}
```

## Error Responses

The API returns the following error responses:

| HTTP Status | Meaning | When |
|-------------|---------|------|
| 200 | Success | Request completed. Check `status` field for simulation outcome. |
| 400 | Bad Request | Malformed JSON or missing required fields. |
| 422 | Validation Error | Invalid field types or values (for example, mismatched `coord` and `numbers` lengths). |
| 500 | Internal Server Error | Unexpected server failure or GPU out-of-memory (OOM) error. |
| 503 | Service Unavailable | NIM not ready (still estimating batch sizes at startup). |

**Error Response Schema (422):**

```json
{
  "detail": [
    {
      "loc": ["body", "atoms", "coord"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

### Timeout and Memory Behavior

- Requests with systems exceeding `max_system_size` (check by using `GET /v1/status`) might return 500 with an OOM error.
- There is no built-in server-side request timeout. Use client-side timeouts for long simulations.
- Long trajectories (large `md_time_max`) increase response time proportionally. Consider breaking long simulations into restart chunks.

## Example Requests

The following sections show how to use the API to start a simulation.

### Basic NVT Simulation

Start this simulation by running the following command:

```bash
curl -X 'POST' \
  'http://localhost:8000/v1/infer' \
  -H 'Content-Type: application/json' \
  -d '{
    "atoms": {
      "coord": [0.0, 0.0, 0.0, 0.0, 0.0, 1.5],
      "numbers": [1, 1],
      "cell": [10, 0, 0, 0, 10, 0, 0, 0, 10],
      "pbc": [true, true, true]
    },
    "config": {
      "temperature": 300.0,
      "dt": 1.0,
      "md_time_max": 0.1,
      "nvt": true,
      "save_interval": 10
    }
  }'
```

### NPT Simulation With Pressure Control

Start this simulation by running the following command:

```bash
curl -X 'POST' \
  'http://localhost:8000/v1/infer' \
  -H 'Content-Type: application/json' \
  -d '{
    "atoms": {
      "coord": [0.0, 0.0, 0.0, 0.0, 0.0, 1.5],
      "numbers": [1, 1],
      "cell": [10, 0, 0, 0, 10, 0, 0, 0, 10],
      "pbc": [true, true, true]
    },
    "config": {
      "temperature": 300.0,
      "dt": 1.0,
      "md_time_max": 1.0,
      "nvt": true,
      "npt": true,
      "pressure": 1.0,
      "barostat_every": 25,
      "save_interval": 100
    }
  }'
```

### NVE Simulation (Constant Energy)

Start this simulation by running the following command:

```bash
curl -X 'POST' \
  'http://localhost:8000/v1/infer' \
  -H 'Content-Type: application/json' \
  -d '{
    "atoms": {
      "coord": [0.0, 0.0, 0.0, 0.0, 0.0, 1.5],
      "numbers": [1, 1],
      "cell": [10, 0, 0, 0, 10, 0, 0, 0, 10],
      "pbc": [true, true, true],
      "velocity": [0.0, 0.0, 0.01, 0.0, 0.0, -0.01]
    },
    "config": {
      "nvt": false,
      "npt": false,
      "dt": 0.5,
      "md_time_max": 1.0,
      "save_interval": 10
    }
  }'
```

### Restart From a Previous State

Start this simulation by running the following command:

```bash
curl -X 'POST' \
  'http://localhost:8000/v1/infer' \
  -H 'Content-Type: application/json' \
  -d '{
    "atoms": {
      "coord": [0.0, 0.0, 0.0, 0.0, 0.0, 1.52],
      "numbers": [1, 1],
      "cell": [10, 0, 0, 0, 10, 0, 0, 0, 10],
      "pbc": [true, true, true],
      "velocity": [0.001, 0.002, 0.003, -0.001, -0.002, -0.003]
    },
    "config": {
      "temperature": 300.0,
      "nvt": true,
      "dt": 1.0,
      "istep": 100,
      "md_time": 0.1,
      "md_time_max": 0.2,
      "save_interval": 10
    }
  }'
```