> This page is for NVIDIA NIM for Batched Geometry Relaxation, version 1.1.0 (Latest) (default).
> 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 at container
startup, apply per-request overrides for geometry relaxation parameters, and
manage model and GPU settings.

## Startup Configuration

Configure the model, periodic boundary conditions, batch sizing, optimization
defaults, and DFT-D3(BJ) correction through environment variables when you
launch the container. Refer to [Environment Variables](/nim/alchemi/alchemi-bgr/environment-variables)
for the complete list, accepted values, and defaults.

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

```bash
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, every structure in a request must include `cell`. In
`false` mode, structures must omit `cell`. A container cannot accept a mixture
of 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 that 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 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 |

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

## Geometry Relaxation Configuration

The startup configuration establishes the default force tolerance,
cell-optimization setting, and pressure tolerance. An inference request can
override these defaults with `opttol`, `cellopt`, and `opttol_pressure`. The
maximum number of optimization steps and the optimizer preset apply to the
backend as a whole.

Refer to [API Reference](/nim/alchemi/alchemi-bgr/api-reference#post-v1infer) for the request schema
and to [Tuning Parameters](/nim/alchemi/alchemi-bgr/tuning-parameters#per-request-parameters) for an
override example.

## 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:

```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: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-bgr:1.1.0
```


For model sources and checkpoint-specific requirements, refer to
[Custom Models](/nim/alchemi/alchemi-bgr/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 requests.
- **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.