> This page is for NVIDIA NIM for Batched Molecular Dynamics, version 1.0.0.
> 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 using environment variables during container launch, apply per-request overrides for molecular dynamics parameters, and manage model and GPU settings.

## Environment Variables

Pass environment variables when you launch the container:

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

Use the environment variables in the following table to configure NIM for BMD:

| Environment Variable                   | Type          | Default    | Description                                                                                                                                            |
| -------------------------------------- | ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ALCHEMI_NIM_MODEL_TYPE`               | string        | `"mace"`   | Model type: mace, aimnet2, tensornet                                                                                                                   |
| `ALCHEMI_NIM_MODEL_PATH`               | string        | null       | Path to the model file or directory inside the container                                                                                               |
| `ALCHEMI_NIM_PBC`                      | bool          | true       | Periodic boundary conditions. If true, requests must include `cell`. If false, requests must not include `cell`.                                       |
| `ALCHEMI_NIM_BATCH_SIZE`               | int           | 0          | Batch size in atoms (0 = auto-estimate at startup)                                                                                                     |
| `ALCHEMI_NIM_BATCH_SIZE_ESTIMATE_DATA` | string        | `"omat24"` | Dataset used for auto-estimation: **omat24** (bulk materials), **omol25** (molecules), **omc25** (molecular crystals). Options: omat24, omol25, omc25. |
| `ALCHEMI_NIM_DFT3_ENABLED`             | bool          | false      | Enable DFT-D3(BJ) dispersion correction                                                                                                                |
| `ALCHEMI_NIM_DFT3_PARAM`               | string (JSON) | null       | JSON-encoded object for custom DFT-D3(BJ) parameters (for example, `{"s8": 0.3908, "a1": 0.5660, "a2": 3.1280}`).                                      |

Refer to [Environment Variables](/nim/alchemi/alchemi-bmd/1.0.0/environment-variables) for a complete reference of all environment variables and their defaults.

### DFT-D3 Parameters

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

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

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

## 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

For supported models and sourcing details, refer to [Supported Models](/nim/alchemi/alchemi-bmd/1.0.0/overview#supported-models). For step-by-step download hints and container launch arguments for each model type (MACE, AIMNet2, TensorNet), refer to [Custom Models](/nim/alchemi/alchemi-bmd/1.0.0/custom-models).

For non-bundled models (such as TensorNet and AIMNet2), mount the **content of the model directory** into the container and set `ALCHEMI_NIM_MODEL_PATH` to the mounted path inside the container:

```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 \
    -e ALCHEMI_NIM_MODEL_TYPE="tensornet" \
    -e ALCHEMI_NIM_MODEL_PATH="/opt/nim/.cache/model-dir" \
    nvcr.io/nim/nvidia/alchemi-bmd:1.0.0
```


The mounted directory should contain the model files as downloaded from the model repository. For specific model requirements, refer to [Custom Models](/nim/alchemi/alchemi-bmd/1.0.0/custom-models).

## GPU and Memory Configuration

- **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. Override this behavior by setting `ALCHEMI_NIM_BATCH_SIZE`.
- **Multi-GPU**: The NIM automatically uses all available GPUs. Each GPU runs an independent worker.