> This page is for NVIDIA NIM for Batched Geometry Relaxation, 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-bgr/1.1.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/alchemi/alchemi-bgr/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 BGR using environment
variables during container launch, apply per-request overrides for geometry
relaxation parameters, and manage model and GPU settings.

## Environment Variables

Pass environment variables when you launch the container. For example:

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

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

| Environment Variable | Type | Default | Description |
|---|---|---|---|
| `ALCHEMI_NIM_MODEL_TYPE` | string | `"mace"` | Model type: `mace`, `aimnet2`, or `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 mode. |
| `ALCHEMI_NIM_BATCH_SIZE` | int | null | Fixed batch size. If `null`, the NIM estimates the batch size automatically at startup. |
| `ALCHEMI_NIM_BGR_OPTTOL` | float | 0.005 | Force tolerance (eV/Å). You can override this per request. |
| `ALCHEMI_NIM_BGR_MAX_STEPS` | int | 2000 | Maximum optimization steps. You can override this per request. |
| `ALCHEMI_NIM_BGR_CELLOPT` | bool | false | Enable cell optimization. You can override this per request. |
| `ALCHEMI_NIM_BGR_OPTTOL_PRESSURE` | float | 0.5 | Pressure tolerance (kBar) for cell optimization. You can override this per request. |
| `ALCHEMI_NIM_BGR_OPTIMIZER_PRESET` | string | `"materials"` | Optimizer preset: `materials` or `molecules`. |
| `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-bgr/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 the C6 term |
| `s8` | float | null | Scaling factor for the C8 term |
| `cutoff` | float | 15.0 | Cutoff distance (Å) |
| `smoothing_fraction` | float | 0.2 | Fraction of the cutoff used for the smoothing region |

## Model Configuration

For supported models and sourcing details, refer to
[Supported Models](/nim/alchemi/alchemi-bgr/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-bgr/1.0.0/custom-models).

For non-bundled models (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-bgr --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-bgr: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-bgr/1.0.0/custom-models).

## GPU and Memory Configuration

Configure memory allocation and GPU utilization to manage hardware resources.

- **Shared memory**: Use `--shm-size=8g` to support large requests.
- **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.