# Run an NNP/MM simulation

**You will learn:** how to set up and run a hybrid simulation in which one molecule is described by a neural-network potential and the rest of the system by a classical force field.

**Prerequisites:**

- ACEMD installed with NNP support (`pip install "acemd[nnp-cu13]" --extra-index-url https://download.pytorch.org/whl/cu130`, or the matching CUDA-12 variant).
- A classically built system (CHARMM or AMBER) covering **every** atom — including the molecule you plan to handle with the NNP.

For the concepts behind NNP/MM (where the boundary lives, how forces are combined), see [NNP and NNP/MM](../explanation/nnp-and-nnp-mm.md).

## Setup

Worked example: solvated benzamidine, with the ligand on AceFF and the rest of the system on AMBER. Download {download}`benzamidine_nnp_mm.zip <../benzamidine_nnp_mm.zip>` for the structure + parameters.

```{code-block} yaml
:caption: input.yaml

barostat: true
thermostat: true
thermostattemperature: 300
velocities: 300
structure: structure.prmtop
coordinates: structure.pdb
boxsize: [22.66, 25.397, 25.982]
minimize: 500
timestep: 2
run: 2ns
nnp:
  name: AceFF-2.0
  sel: "resname BEN"
  type: torch
```

The `nnp.sel` selection (`resname BEN`) defines which atoms are simulated by the NNP. Everything outside the selection follows the AMBER parameters in `structure.prmtop`. Non-bonded interactions between the selection and the rest of the system are computed classically.

On first use ACEMD pulls the AceFF-2.0 checkpoint from HuggingFace and caches it under `~/.cache/acemd/nnp/`. Subsequent runs reuse the cached copy with no network access. If you'd rather manage the file yourself (offline machines, pinning to a specific version), see [Obtain AceFF NNP models](obtain-aceff-models.md) and reference the file with `nnp.file` instead of `nnp.name`. To use ANI in place of AceFF, see [Use ANI potentials](use-ani-potentials.md).

## Run

```bash
acemd
```

## Why a timestep of 2 fs?

NNP forces are less numerically stable than classical force fields. A 2 fs timestep is the recommended ceiling for NNP and NNP/MM simulations; larger timesteps lead to drift and NaN crashes. The default 4 fs that ACEMD uses for pure-MM runs is **not** safe here.

## Parameters that matter

- **`nnp.sel`** — must cover the **whole** molecule of interest with no covalent bonds crossing the selection boundary. ACEMD doesn't currently support QM-MM style link atoms.
- **`nnp.name`** — picks the model. `"AceFF-2.0"` triggers the auto-download path; `"ANI-2x"` / `"ANI-1x"` / `"ANI-1ccx"` load the corresponding ANI variant; `"TorchMD-Net"` loads any checkpoint supplied via `nnp.file`.
- **`nnp.file`** — path to a TorchMD-Net checkpoint. Required only with `name: TorchMD-Net`; optional for the auto-handled AceFF and ANI names.
- **`nnp.type`** — currently always `"torch"`.

See [NNP options](../reference/nnp-options.md) for the full reference.

## Gotchas

- **AceFF 2.0 is trained on small molecules only.** Don't put protein, nucleic acid, or water atoms inside `nnp.sel` — those species are outside the training distribution. Keep `nnp.sel` restricted to a ligand, cofactor, or other small-molecule residue.
- **AceFF 2.0 supports total charges of -2 to +2.** Larger absolute charges are not described correctly; the model will run but produce wrong forces.
- **ANI cannot handle any non-zero total charge.** Prefer AceFF for charged species.
- **The `sel` must match the built topology.** If the atom names or residue names differ between the structure and what the NNP expects, the model will fail to load or produce nonsense.

## See also

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