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:

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

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. For step-by-step download hints and container launch arguments for each model type (MACE, AIMNet2, TensorNet), refer to 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:

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.

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.