> This page is for NVIDIA NIM for Batched Molecular Dynamics, 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-bmd/1.1.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/alchemi/alchemi-bmd/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.

# Configuration

This page explains how to configure NIM for BMD at container
startup, apply per-request molecular dynamics settings, and manage model and GPU
settings.

## Startup Configuration

Configure the model, periodic boundary conditions, batch sizing, and DFT-D3(BJ)
correction through environment variables when you launch the container. Refer
to [Environment Variables](/nim/alchemi/alchemi-bmd/environment-variables) for the complete list,
accepted values, and defaults.

For example, set the model architecture when launching the container:

```bash
docker run ... -e ALCHEMI_NIM_MODEL_TYPE="mace" ...
```

### Periodic Boundary Conditions

`ALCHEMI_NIM_PBC` selects the backend PBC mode when the container starts. In
the default `true` mode, the request structure must include `cell`. In `false`
mode, it must omit `cell`. A container cannot switch between these two request
forms; use separate containers when serving both periodic and non-periodic
workloads.

The nested `atoms.pbc` field has a different purpose. It selects the periodic
axes for the structure's supplied cell, in `[x, y, z]` order, and defaults to
`[true, true, true]`. It does not change the backend PBC mode or relax the
backend's requirement that `cell` be present or absent.

## DFT-D3 Parameters

When `ALCHEMI_NIM_DFTD3_ENABLED` is `true`, you can provide custom damping
parameters using the `ALCHEMI_NIM_DFTD3_PARAM` environment variable. The value
must be a JSON string (for example, `'{"s8": 0.3908, "a1": 0.5660, "a2":
3.1280}'`).

DFT-D3(BJ) can be combined with MACE, AIMNet2, or TensorNet. When
`ALCHEMI_NIM_MODEL_PATH` is not set, `ALCHEMI_NIM_MODEL_TYPE` selects the
following functional preset:

**Default DFT-D3(BJ) Parameters by Model Type**

| Model type | Functional | `a1` | `a2` (Bohr) | `s6` | `s8` |
|---|---|---:|---:|---:|---:|
| `mace` | PBE | 0.4289 | 4.4407 | 1.0 | 0.7875 |
| `aimnet2` | wB97M | 0.5660 | 3.1280 | 1.0 | 0.3908 |
| `tensornet` | PBE | 0.4289 | 4.4407 | 1.0 | 0.7875 |

By default, DFT-D3(BJ) uses a 15 Å cutoff and smoothly switches the correction
off from 12 Å to 15 Å.

When `ALCHEMI_NIM_MODEL_PATH` selects a user-provided checkpoint, the DFT-D3
configuration must specify `a1`, `a2`, and `s8`.

The JSON object supplied through `ALCHEMI_NIM_DFTD3_PARAM` accepts the following
fields:

**`ALCHEMI_NIM_DFTD3_PARAM` JSON Object Fields**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `a1` | float | null | BJ damping parameter a1 |
| `a2` | float | null | BJ damping parameter a2 (Bohr) |
| `s6` | float | null | Scaling factor for C6 term |
| `s8` | float | null | Scaling factor for C8 term |
| `cutoff` | float | 15.0 | Cutoff distance (Å) |
| `smoothing_fraction` | float | 0.2 | Fraction of cutoff for smoothing region |

For detailed information on DFT-D3(BJ) dispersion corrections, refer to the
[ALCHEMI Toolkit-Ops documentation](https://nvidia.github.io/nvalchemi-toolkit-ops/index.html).

## Per-Request MD Configuration

The `config` field in requests accepts the following parameters to override defaults for a specific request.

### Time and Integration

Use the following parameters to set time and integration:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `dt` | float | 1.0 | Timestep in femtoseconds |
| `md_time` | float | 0.0 | Starting simulation time in ps (for restart) |
| `md_time_max` | float | 10.0 | Maximum simulation time in ps |
| `save_interval` | int | 100 | Save trajectory every N steps |
| `istep` | int | 0 | Starting step number (for restart) |

### Temperature Control (NVT)

Use the following parameters to control temperature:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `temperature` | float | 300.0 | Target temperature in Kelvin |
| `nvt` | bool | true | Enable NVT ensemble (Langevin thermostat) |
| `friction` | float | 1.0 | Langevin friction coefficient in ps^-1 |

### Pressure Control (NPT)

Use the following parameters to control pressure:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `npt` | bool | false | Enable NPT ensemble (MC barostat) |
| `pressure` | float | 0.0 | Target pressure in kBar |
| `barostat_anisotropic` | bool | false | Enable anisotropic cell changes |
| `barostat_every` | int | 25 | Barostat update frequency in steps |
| `barostat_prob_shear` | float | 0.5 | Probability of shear move (anisotropic) |
| `barostat_shear_max` | float | 0.01 | Maximum shear move magnitude |
| `barostat_diag_max` | float | 0.01 | Maximum diagonal cell change |
| `barostat_log_scale_max` | float | 0.001 | Maximum log-scale volumetric move |

### External Fields (AIMNet2 only)

Use the following parameter to control external fields in AIMNet2:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `efield` | array[float] | [0,0,0] | External electric field [Ex, Ey, Ez] in μV/Å |

## Model Configuration

`ALCHEMI_NIM_MODEL_TYPE` selects the model architecture: MACE, AIMNet2, or
TensorNet. `ALCHEMI_NIM_MODEL_PATH` points to the checkpoint that the selected
architecture loads.

To load a checkpoint from the host, mount its model file or directory into the
container and set `ALCHEMI_NIM_MODEL_PATH` to the mounted path. MACE and
AIMNet2 use a single model file. TensorNet uses a directory containing
`model.json`, `model.pt`, and `state.pt`.

For example, mount a TensorNet directory as follows:

```bash
docker run --rm -ti --name alchemi-bmd --gpus=all \
    -e NGC_API_KEY \
    -p 8000:8000 --shm-size=8g \
    -v /path/to/model-dir:/opt/nim/.cache/model-dir:ro \
    -e ALCHEMI_NIM_DISABLE_MODEL_DOWNLOAD=true \
    -e ALCHEMI_NIM_MODEL_TYPE="tensornet" \
    -e ALCHEMI_NIM_MODEL_PATH="/opt/nim/.cache/model-dir" \
    nvcr.io/nim/nvidia/alchemi-bmd:1.1.0
```


For model sources and checkpoint-specific requirements, refer to
[Custom Models](/nim/alchemi/alchemi-bmd/custom-models).

## GPU and Memory Configuration

Configure memory allocation and GPU utilization when you launch the container:

- **Shared memory**: Use `--shm-size=8g` to support large simulations.
- **Batch size**: The NIM estimates the optimal and maximum batch size for
  available GPU memory at startup. Set `ALCHEMI_NIM_BATCH_SIZE` to use a fixed
  batch size.
- **Multi-GPU**: The NIM automatically uses all available GPUs. Each GPU runs an
  independent worker.