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.

Setup#

Worked example: solvated benzamidine, with the ligand on AceFF and the rest of the system on AMBER. Download benzamidine_nnp_mm.zip for the structure + parameters.

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 and reference the file with nnp.file instead of nnp.name. To use ANI in place of AceFF, see Use ANI potentials.

Run#

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