Is this page helpful?

API Reference#

OpenAPI Schema#

The OpenAPI specification 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]	Conditional	Unit cell (9 elements, row-major) in Angstrom. Required when backend PBC mode is enabled and forbidden when it is disabled.
`pbc`	array[bool]	No	Periodic axes for the supplied cell in [x,y,z] order, default [true,true,true]. This field does not override backend PBC mode.
`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)

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):

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
`mass`	array[float]	Atomic masses in amu
`cell`	array[float]	Unit cell (if periodic)
`stress`	array[float]	Stress tensor in eV/Å³ (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:

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

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 or a cell volume of 1.0 Å³ or less).
500	Internal Server Error	Unexpected server failure or GPU out-of-memory (OOM) error.
503	Service Unavailable	NIM not ready, backend unavailable, or engine recovery in progress. Retry the request after the readiness check succeeds.

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