API Reference

OpenAPI Schema

The API Reference 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:

BMDAtomicData Fields (atoms):

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

When a unit cell is provided, its determinant must be positive and its volume must be greater than 1.0 ų.

Backend PBC mode is selected at container startup with ALCHEMI_NIM_PBC. The mode controls whether cell must be present; the nested pbc field controls which axes of that cell are periodic. To accept both cell-bearing and cell-free requests, run separate container instances with the corresponding backend modes.

MDConfig Fields (config):

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

Response:

The response contains the following fields:

BMDSnapshot Fields (trajectory items):

The following table lists the trajectory items (BMDSnapshot):

GET /v1/health/ready

Check if the NIM is ready to accept inference requests.

Response:

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

An HTTP 200 response reports "status":"ready" and includes both backend counts. If Triton is ready but no Alchemi backend worker responds, the endpoint returns HTTP 503 with "status":"no backends available", "backends_alive":0, and backends_total. Other HTTP 503 responses, such as Triton startup and health-check failures, contain only a status message.

GET /v1/health/live

Check if the Triton server is live.

Response:

{
  "status": "live"
}

The endpoint returns 503 with {"status":"not live"} when the Triton inference server is not live. This check does not report the health of the Alchemi backend workers.

GET /v1/status

Get detailed system status including worker metrics.

Response:

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

Example Validation Error (422):

The detail value is an array for request-schema errors, a string for the maximum-system-size check, or an object for service validation such as an invalid cell volume.

{
  "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) return 422 before inference.
• 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:

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:

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:

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:

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
    }
  }'