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 for the complete list, accepted values, and defaults.

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

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

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

For detailed information on DFT-D3(BJ) dispersion corrections, refer to the ALCHEMI Toolkit-Ops documentation.

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:

Temperature Control (NVT)

Use the following parameters to control temperature:

Pressure Control (NPT)

Use the following parameters to control pressure:

External Fields (AIMNet2 only)

Use the following parameter to control external fields in AIMNet2:

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:

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.

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.