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

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.

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:

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.