Configuration | NVIDIA Alchemi NIMs

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.