# NNP options

The `nnp` block of the input file activates a neural-network potential. ACEMD supports two modes:

- **NNP/MM (hybrid)** — `sel` defines the atoms simulated with the NNP; the rest of the system is described by the classical force field. Non-bonded interactions across the boundary are computed classically.
- **Pure NNP** — `sel` is omitted; the whole system is simulated with the NNP. Requires a non-classical structure file (PDB, CIF, BCIF, SDF, MOL2).

```yaml
nnp:
  file: null
  name: null
  sel: null
  type: null
  max_num_neighbors: 128
```

## `name`

- **Type:** string.
- **Default:** none.

Model identifier. ACEMD handles the weights for any of the named models below — no `file` is needed. The only difference is where the weights come from. Names are matched case-insensitively and dashes are ignored (e.g. `ANI-2x` and `ani2x` are equivalent).

- `"AceFF-2.0"` — Acellera's TensorNet v2 model. Downloaded from HuggingFace on first use and cached under `~/.cache/acemd/nnp/`.
- `"ANI-2x"`, `"ANI-1x"`, `"ANI-1ccx"` — ANI models from `torchani`. Downloaded by the `torchani` package on first use and cached for later runs.
- `"ANI-2xr"`, `"ANI-2dr"`, `"snnANI-2xr"` — additional `torchani` ANI variants. The `r` / `dr` suffix denotes repulsion / dispersion+repulsion corrections (a smoother potential-energy surface for MD); these are **not** reactive models — they are still bonded-only models trained on the ANI-2x element set. Note that NNPOps acceleration only applies to the classic `ANI-2x` architecture; these variants fall back to the slower pure-PyTorch path.
- `"TorchMD-Net"` — load a TorchMD-Net checkpoint from the path given in `file`. Use this when supplying a checkpoint manually (offline machine, version pinning, or any non-AceFF TorchMD-Net model).

## `file`

- **Type:** path to an NNP checkpoint.
- **Default:** none.

Required when `name` is `"TorchMD-Net"`. Not needed for the named AceFF or ANI variants — ACEMD handles their weights automatically. If you do set `file` alongside a named AceFF model, the given path is used in place of the cached download (still benefitting from the model's known charge range for validation).

## `sel`

- **Type:** atom selection ([VMD-style](https://www.ks.uiuc.edu/Research/vmd/current/ug/node89.html)).
- **Default:** none.

Atoms simulated with the NNP. Must cover the full molecule(s) of interest — covalent bonds across the selection boundary are not supported.

Omit `sel` for a **pure NNP** simulation.

## `type`

- **Values:** `torch`.
- **Default:** none.

NNP runtime. Currently only PyTorch (`torch`) is supported.

## `max_num_neighbors`

- **Type:** positive integer.
- **Default:** `128`.

Maximum number of neighbours per atom used when building the NNP neighbour list. Only used for **file-based** models (TorchMD-Net / AceFF loaded from a `file`); it has no effect on the named `torchani` ANI models. The effective value is capped at the number of atoms in the NNP selection. Increase it only if you see neighbour-list overflow warnings for dense selections.

## Examples

### NNP/MM with AceFF (auto-download)

```yaml
nnp:
  name: AceFF-2.0
  sel: "resname BEN"
  type: torch
```

### NNP/MM with ANI-2x

```yaml
nnp:
  name: ANI-2x
  sel: "resname BEN"
  type: torch
```

### NNP/MM with a manually managed checkpoint

```yaml
nnp:
  file: aceff_v2.0.ckpt
  name: TorchMD-Net
  sel: "resname BEN"
  type: torch
```

### Pure NNP

```yaml
nnp:
  name: AceFF-2.0
  type: torch
```

## Recommendations

- Use `timestep: 2` fs for NNP and NNP/MM. NNPs are less numerically stable than classical force fields and larger time steps lead to drift or NaNs.
- Prefer AceFF over ANI for systems with charged molecules. ANI cannot correctly describe molecules with non-zero total charge; AceFF 2.0 supports total charges of -2 to +2.

## See also

- [Run an NNP/MM simulation](../how-to/run-an-nnp-mm-simulation.md)
- [Run a pure NNP simulation](../how-to/run-a-pure-nnp-simulation.md)
- [Obtain AceFF NNP models](../how-to/obtain-aceff-models.md)
- [Use ANI potentials](../how-to/use-ani-potentials.md)
- [NNP and NNP/MM concepts](../explanation/nnp-and-nnp-mm.md)