# Integrator and constraints

ACEMD's default behaviour around timestep, constraints, and hydrogen-mass repartitioning is set up so that a user who simply writes `run: 100ns` gets a stable, accurate trajectory at the highest safe throughput. The rules look magical until you know what they are; this page explains them.

## The default timestep is 4 fs — here's why that works

A standard MD integrator is stable up to roughly half the period of the fastest motion in the system. The fastest motions in a biomolecular system are bond stretches involving hydrogens (~10 fs period). With nothing else done, you'd need a timestep of about 1 fs.

ACEMD's default `timestep: 4.0` fs is safe because of two automatic mitigations:

1. **Bond constraints.** Removing the bond-stretch degree of freedom (SHAKE/SETTLE) lets you push past 1 fs. With H-bonds constrained, ~2 fs is the safe ceiling. With **all** bonds constrained, ~3 fs.
2. **Hydrogen-mass repartitioning (HMR).** Reassigning mass from heavy atoms to bonded hydrogens slows the remaining fast motions. With HMR on top of bond constraints, 4 fs is stable.

The defaults are tuned so that whatever `timestep` you pick, the constraints needed to make it stable are enabled automatically.

## The auto-enable rules

| `timestep`          | `rigidwater` | `hbondconstr` | `hmr`       |
|--------------------:|--------------|---------------|-------------|
| ≤ 0.5 fs            | off          | off           | off         |
| > 0.5 fs, ≤ 2.0 fs  | **on**       | **on**        | off         |
| > 2.0 fs            | **on**       | **on**        | **on**      |

You can override any of these manually — `hmr: false`, `hbondconstr: false`, `rigidwater: false` — but if you reduce constraints while keeping a long timestep, expect crashes. Conversely, leaving constraints on at a short timestep is harmless (just slightly slower).

```{note}
**NNP runs are a special case.** When an `nnp` block is present, HMR is force-enabled regardless of `timestep` — the code sets `hmr = timestep > 2 or nnp is not None`. So an NNP/MM or pure-NNP run at the recommended 2 fs already has HMR on. This is the "Massive speed-up for AceFF NNP simulations using CUDA graphs" path the 4.0.9 changelog refers to.
```

## What HMR actually does

HMR replaces each hydrogen's mass (1.008 amu) with `hydrogenmass` (default 4.032 amu) and subtracts the difference from the bonded heavy atom. Total mass is conserved. The slower hydrogens let the integrator stay stable at larger timesteps without affecting thermodynamic averages.

HMR is **not** applied to:

- Water molecules (they're already rigid via `rigidwater`).
- Atoms that participate in virtual sites.

This is why "no more HMR on rigid water" appeared as an improvement in 4.0.9 — applying HMR redundantly on rigid waters was needlessly heavy.

## When you'd want to deviate from the defaults

- **NNP and NNP/MM simulations** — drop `timestep` to 2 fs. NNPs are less numerically stable than classical force fields; the default 4 fs is unsafe. The constraint settings auto-adjust.
- **Diagnosing a crash** — set `timestep` to 1 fs (and remove HMR). If the simulation now runs, the original timestep was too aggressive for your system; if it still crashes, the issue isn't integration stability.
- **Energy-conserving NVE** — drop `timestep` and disable constraints involving the atoms whose dynamics you care about, accepting the throughput hit.

## See also

- [`timestep`, `hmr`, `hbondconstr`, `rigidwater`, `hydrogenmass`](../reference/input-options.md)
- [Debug a simulation crash](../how-to/debug-a-simulation-crash.md)