# Input-file options

ACEMD reads a single YAML or JSON file describing the system, the integrator, and the output. Keywords are **case-insensitive**, but values can be case-sensitive (file names, atom selections).

The two large composite blocks — `extforces` and `nnp` — have their own pages: [External forces](external-forces.md) and [NNP options](nnp-options.md).

## Defaults at a glance

```yaml
# System
structure: null
parameters: null

# Initial conditions
coordinates: null
boxsize: null
velocities: 298.15
restart: false

# Non-bonded interactions
pme: true
cutoff: 9.0
switching: true
switchdistance: 7.5

# Implicit solvent
implicitsolvent: false
igb: 2

# Integration
timestep: 4.0
hmr: null
hydrogenmass: 4.032
hbondconstr: null
rigidwater: null

# Temperature
thermostat: false
thermostattemperature: 298.15
thermostatdamping: 1.0

# Pressure
barostat: false
barostatpressure: 1.0
barostatanisotropic: false
barostatconstratio: false
barostatconstxy: false

# Output
trajectoryfile: "output.xtc"
trajvelocityfile: null
trajforcefile: null
trajectoryperiod: 25000
stepzero: false

# Simulation length
run: 0
minimize: 0

# Small-molecule parameterisation (OpenMM XML only)
molecules: null
protonate: false

# Extras (see dedicated pages)
extforces: null
fbrefcoor: null
plumedfile: null
nnp: null
```

## System: structure and parameters

ACEMD supports CHARMM, AMBER, and OpenMM XML force fields.

- **CHARMM** — topology in `structure` (`.psf`), parameters in `parameters` (`.prm`/`.str`).
- **AMBER** — both topology and parameters in `structure` (`.prmtop`).
- **OpenMM XML** — structure as a `.pdb` or mmCIF (`.cif`/`.bcif`), parameters as one or more OpenMM ForceField `.xml` files (e.g. `amber14-all.xml`). The structure file supplies the topology (atoms, residues, and the bond graph); the XML files supply the force-field parameters, which ACEMD applies via `ForceField.createSystem`.

### `structure`

- **Type:** path to a PSF, PRMTOP, PDB, or mmCIF (`.cif`/`.bcif`) file.
- **Default:** none.

For the OpenMM XML route, an mmCIF (`.cif`) structure is preferred over PDB: it preserves the full bond graph — including inter-residue/external bonds such as disulfides — without PDB's 99,999-atom serial limit. mmCIF + XML is the format emitted by the HTMD {py:func}`~htmd.builder.openmm.build` handoff (see {py:func}`~acemd.protocols.setup_equilibration`).

### `parameters`

- **Type:** path or list of paths to `.prm`, `.str` (CHARMM), or OpenMM ForceField `.xml` files.
- **Default:** none.

OpenMM XML entries may be stock force-field names resolved by OpenMM (e.g. `amber14-all.xml`, `amber14/tip3pfb.xml`) and/or paths to local `.xml` fragments parameterising non-standard residues. Order is significant: earlier files take template precedence.

```yaml
structure: "structure.psf"
parameters: ["./par_all36m_prot.prm", "./par_water_ions.prm"]

structure: "structure-prepared.pdb"
parameters: ["amber14-all.xml", "amber14/tip3pfb.xml"]

# mmCIF preserves bonds; preferred for the openmm.build handoff
structure: "structure.cif"
parameters: ["amber14/protein.ff14SB.xml", "amber14/tip3p.xml", "ligand.xml"]
```

## Initial conditions

### `coordinates`

- **Type:** path to any coordinate file supported by [MoleculeKit](https://software.acellera.com/moleculekit/).
- **Default:** none.

Initial atomic positions. If unset and `structure` already carries coordinates, those are used.

### `boxsize`

- **Type:** list of numbers, list-of-lists, or filename.
- **Default:** none.

Periodic box. Units are Ångström and degrees. If unset, the box is read from `structure` when present.

Accepted forms:

- `[lx, ly, lz]` — orthogonal box, lengths only (angles default to 90°).
- `[lx, ly, lz, α, β, γ]` — triclinic box, lengths + angles.
- `[[ax,0,0],[bx,by,0],[cx,cy,cz]]` — explicit triclinic vectors. Must satisfy:
  1. `a_y = a_z = b_z = 0`
  2. `a_x, b_y, c_z > 0`
  3. `a_x/2 >= |b_x|`, `a_x/2 >= |c_x|`, `b_y/2 >= |c_y|`
- A file path (XSC, PDB, INPCRD, DCD, XTC) — vectors read from the file. Trajectory files take the last frame.

```yaml
boxsize: [10.0, 25.0, 30.0]
boxsize: [10.0, 25.0, 30.0, 90, 90, 90]
boxsize: [[7.15, 0.0, 0.0], [2.386, 6.74, 0.0], [-2.38, 3.37, 5.84]]   # truncated octahedron
boxsize: input.xsc
```

### `velocities`

- **Type:** a positive real number, **or** a path to a `.vel` (NAMD binary) or `.pdb` file.
- **Default:** `298.15`.

If a number is given, velocities are drawn from a Maxwell-Boltzmann distribution at that temperature (K). If a `.vel` (NAMD binary velocity) or `.pdb` file is given, velocities are read directly from it. No other file formats are accepted.

### `restart`

- **Type:** `true` / `false`.
- **Default:** `false`.

Continue from `restart.chk` if it exists. Overrides initial coordinates, velocities, box, and thermostat/barostat state. `restart.chk` is **always** written every `trajectoryperiod` steps regardless of this setting. Restart is only valid on the same GPU model that wrote the checkpoint. See [Restart a simulation](../how-to/restart-a-simulation.md).

## Non-bonded interactions

### `pme`

- **Type:** `true` / `false`.
- **Default:** `true`.

Enable Particle-Mesh Ewald for long-range electrostatics.

### `cutoff`

- **Type:** positive real number, Ångström.
- **Default:** `9.0`.

Cutoff for van der Waals interactions and short-range electrostatics.

### `switching`

- **Type:** `true` / `false`.
- **Default:** `true`.

Enable a switching function on the van der Waals interaction.

### `switchdistance`

- **Type:** positive real number, Ångström.
- **Default:** `7.5`.

Distance at which the switching function starts.

## Implicit solvent

### `implicitsolvent`

- **Type:** `true` / `false`.
- **Default:** `false`.

Enable GBSA-OBC implicit solvent. AMBER force field only.

### `igb`

- **Type:** one of `1`, `2`, `5`, `7`, `8`.
- **Default:** `2`.

Implicit-solvent model. See the [OpenMM AMBER implicit-solvent table](http://docs.openmm.org/latest/userguide/application/02_running_sims.html#amber-implicit-solvent).

## Integration

ACEMD enables constraints and hydrogen-mass repartitioning automatically based on `timestep` — see [Integrator and constraints](../explanation/integrator-and-constraints.md) for the why and the trade-offs.

### `timestep`

- **Type:** positive real number, fs.
- **Default:** `4.0`.

Integrator time step.

- `timestep > 0.5 fs` → H-bond constraints + rigid water are auto-enabled.
- `timestep > 2.0 fs` → all bond constraints + HMR are auto-enabled.

Each of these can be overridden manually via `hmr`, `hbondconstr`, `rigidwater`.

### `hmr`

- **Type:** `true` / `false` / `null`.
- **Default:** `null` (auto-enabled at `timestep > 2.0 fs`).

Hydrogen-mass repartitioning.

### `hydrogenmass`

- **Type:** positive real number, amu.
- **Default:** `4.032`.

Mass assigned to hydrogen atoms when HMR is on. The mass is removed from the bonded heavy atom.

### `hbondconstr`

- **Type:** `true` / `false` / `null`.
- **Default:** `null` (auto-enabled at `timestep > 0.5 fs`).

H-bond constraints (SHAKE/SETTLE).

### `rigidwater`

- **Type:** `true` / `false` / `null`.
- **Default:** `null` (auto-enabled at `timestep > 0.5 fs`).

Constrain water geometry.

## Temperature control

### `thermostat`

- **Type:** `true` / `false`.
- **Default:** `false`.

Enable the Langevin thermostat.

### `thermostattemperature`

- **Type:** non-negative real number, K.
- **Default:** `298.15`.

Target temperature.

### `thermostatdamping`

- **Type:** non-negative real number, ps⁻¹.
- **Default:** `1.0`.

Damping (friction) coefficient. OpenMM's recommended value.

## Pressure control

### `barostat`

- **Type:** `true` / `false`.
- **Default:** `false`.

Enable the Monte Carlo barostat. Requires `thermostat: true`.

### `barostatpressure`

- **Type:** real number, bar.
- **Default:** `1.0`.

Target pressure.

### `barostatanisotropic`

- **Type:** `true` / `false`.
- **Default:** `false`.

Allow `x`, `y`, `z` axes to scale independently.

### `barostatconstratio`

- **Type:** `true` / `false`.
- **Default:** `false`.

Keep `x/y` ratio constant; `z` varies independently. Useful for bilayers.

### `barostatconstxy`

- **Type:** `true` / `false`.
- **Default:** `false`.

Keep `x` and `y` fixed; only `z` varies.

## Output

The final positions, velocities, and box are always written to `output.coor`, `output.vel`, and `output.xsc`. A `restart.chk` checkpoint and an `output.csv` log are also written every `trajectoryperiod` steps (see [Output files](#output-files) below).

### `trajectoryfile`

- **Type:** file name with `.dcd` or `.xtc` extension.
- **Default:** `"output.xtc"`.

Trajectory file for atomic positions. Format follows the extension. Positions are in Ångström. Frames are **not** wrapped — use {py:meth}`~moleculekit.molecule.Molecule.wrap` to wrap them.

### `trajvelocityfile`

- **Type:** file name with `.xtc` or `.dcd` extension.
- **Default:** none.

Trajectory of atomic velocities. Format follows the extension (`.xtc` or `.dcd`). Velocities are in arbitrary units; multiply by `20.45482706` for Å/ps (the [NAMD DCD convention](https://www.ks.uiuc.edu/Research/namd/2.14/ug/node11.html)).

### `trajforcefile`

- **Type:** file name with `.xtc` or `.dcd` extension.
- **Default:** none.

Trajectory of atomic forces in kcal/mol/Å. Format follows the extension (`.xtc` or `.dcd`). Useful for debugging crashes — see [Debug a simulation crash](../how-to/debug-a-simulation-crash.md).

### `trajectoryperiod`

- **Type:** non-negative integer (simulation steps).
- **Default:** `25000`.

Period at which trajectory, log, and restart files are written.

### `stepzero`

- **Type:** `true` / `false`.
- **Default:** `false`.

Also write a frame at step 0. Mostly used for debugging the initial state.

## Simulation length

### `run`

- **Type:** non-negative integer + optional time suffix.
- **Default:** `0`.

Length of the production phase. Suffixes: `fs`, `ps`, `ns`, `us`. Without a suffix the value is interpreted as a step count.

### `minimize`

- **Type:** non-negative integer (steps).
- **Default:** `0`.

Energy-minimization steps performed before the production phase. Skipped on restart.

```yaml
minimize: 500
run: 100ns
```

## Small-molecule parameterisation (OpenMM XML only)

These options apply when the system uses an OpenMM XML force field (`parameters: ["amber14-all.xml", ...]`) and contains residues that the force field doesn't cover — typically small-molecule ligands. They are ignored for CHARMM / AMBER builds, where parameterisation happens upstream in the builder.

### `molecules`

- **Type:** dict, or `null`.
- **Default:** `null`.

Generate force-field parameters on the fly for one or more residues, using their SMILES. Keys inside the dict:

- **`smiles`** (required) — dict mapping residue name → SMILES string.
- **`charge_model`** — partial-charge method. Default `"am1bcc"`. Also accepts `"gasteiger"` and the other [openff-toolkit](https://docs.openforcefield.org) methods.
- **`forcefield`** — force-field path or name. Default `"gaff-2.2.20"`.
- **`forcefield_type`** — one of `"gaff"`, `"openff"`, `"espaloma"`. Auto-detected from the `forcefield` prefix (e.g. `gaff-2.2.20` → `gaff`); only set explicitly when the name doesn't follow that convention.

```yaml
molecules:
  smiles:
    BEN: "[NH2+]=C(N)c1ccccc1"
  charge_model: am1bcc
  forcefield: gaff-2.2.20
```

### `protonate`

- **Type:** `false` / `true` / a pH value (float).
- **Default:** `false`.

When set, ACEMD runs OpenMM's `Modeller.addHydrogens(forcefield, pH=...)` after building the system from the PDB, using the residue templates from the XML force field. Useful when the input PDB has no hydrogens. Only applies to OpenMM XML setups.

- `protonate: false` (default) — no hydrogens added.
- `protonate: true` — add hydrogens at **pH 7.4**.
- `protonate: 6.5` (any float) — add hydrogens at the given pH.

## Composite blocks

- **`extforces`** — list of restraints / biases. See [External forces](external-forces.md).
- **`fbrefcoor`** — reference PDB for positional restraints. See [External forces](external-forces.md).
- **`plumedfile`** — path to a PLUMED input file. See [Run with PLUMED](../how-to/run-with-plumed.md).
- **`nnp`** — neural-network potential block. See [NNP options](nnp-options.md).

(output-files)=

## Output files

Beyond the trajectory file(s), every run writes the following to the run directory:

| File | Written | Contents |
|------|---------|----------|
| `output.coor` | at the end of the run | final positions (NAMD binary coordinates). |
| `output.vel` | at the end of the run | final velocities (NAMD binary velocities). |
| `output.xsc` | at the end of the run | final periodic box (NAMD extended-system file). |
| `restart.chk` | every `trajectoryperiod` steps | OpenMM checkpoint used by `restart`. |
| `output.csv` | every `trajectoryperiod` steps | per-report log (see below). |

### `output.csv` columns

`output.csv` is a comma-separated log with one header row and one row appended per report (every `trajectoryperiod` steps). The columns are, in order:

| Column | Units | Meaning |
|--------|-------|---------|
| `Step` | steps | Simulation step number. |
| `Time (ns)` | ns | Elapsed simulated time. |
| `Progress (%)` | % | Fraction of the requested run completed. |
| `Mean speed (ns/day)` | ns/day | Average throughput since the start of the run. |
| `Current speed (ns/day)` | ns/day | Throughput over the most recent interval. |
| `Remaining time` | H:MM:SS | Estimated wall-clock time to completion (ETA). |
| `Completion date` | DD/MM HH:MM:SS | Estimated wall-clock date/time of completion. |
| `Temperature (K)` | K | Instantaneous system temperature. |
| `Pressure (bar)` | bar | Instantaneous pressure. **Only present when a barostat is enabled.** (The console log prints a smoothed `Avg Pressure (bar)` instead; the CSV stores the instantaneous value.) |
| `Volume (A^3)` | ų | Periodic-box volume. |
| `Density (g/cm^3)` | g/cm³ | System mass density. |
| *energy terms* | kcal/mol | One column per active energy component (see below). |
| `k0`, `k1`, … | kcal/mol/Ų | Force constant of each external restraint, in declaration order. **Only present when `extforces` are defined**, one `k`-column per restraint. |

The energy-term columns are emitted only for force types actually present in the system, so the exact set varies by setup. Possible terms are:

`Bond`, `Angle`, `Dihedral`, `Improper`, `CMAP`, `Non-bonded`, `Implicit` (implicit-solvent / GB), `External` (positional/external restraints), `NNP`, `PLUMED`, followed always by `Potential`, `Kinetic`, and `Total`. All energies are in kcal/mol.

## Migrating from ACEMD 3 / deprecated options

Several legacy option names from earlier ACEMD versions are still recognised but deprecated. When you use the modern YAML/JSON input format, a deprecated key is treated as a **hard error**; with the old plain-text input format it is accepted with a warning and rewritten. Update your inputs to the new names:

| Deprecated option | Use instead | Notes |
|-------------------|-------------|-------|
| `bincoordinates` | `coordinates` | |
| `temperature` | `velocities` | `velocities` accepts a temperature (K) to seed Maxwell-Boltzmann velocities. |
| `binvelocities` | `velocities` | `velocities` also accepts a `.vel` file path. |
| `parmfile` | `structure` | If both are given, `parmfile` is ignored. |
| `celldimension` | `boxsize` | |
| `extendedsystem` | `boxsize` | `boxsize` accepts a NAMD XSC file path or a list of box lengths. |
| `thermostattemp` | `thermostattemperature` | |
| `switchdist` | `switchdistance` | |
| `trajectoryfreq` | `trajectoryperiod` | |
| `implicit` | `implicitsolvent` | |
| `atomrestraint` | `extforces` | Old string-format restraints are no longer accepted in YAML/JSON — convert them to the `extforces` list of `positionalRestraint` dicts. See [External forces](external-forces.md). |
| `grouprestraint` | `extforces` | As above. |

```{note}
In the YAML/JSON format, ACEMD raises an error if it encounters an old-style string restraint inside `extforces` — only the new dict form (`type: positionalRestraint`, …) is supported. See [Use positional restraints](../how-to/use-positional-restraints.md).
```

## Other options

A few additional options exist for backwards compatibility or advanced/Python use:

- **`slowperiod`** — *deprecated, no-op.* Historically the multi-timestep integrator period. The multistep integrator is not available in this ACEMD version; any value greater than `1` is ignored with a warning and treated as `1`.
- **`deterministic`** — Python-API keyword of {py:func}`~acemd.acemd.setup_acemd` only (default `False`). When set, ACEMD enables OpenMM's `DeterministicForces` for bit-reproducible runs; it is rejected on the CPU platform and on single-precision CUDA. There is **no** `--deterministic` command-line flag (it was removed); set it from Python if you need it.
- **`rfdielectric`** — Python-API keyword of {py:func}`~acemd.acemd.setup_acemd` only (default `78.5`). Reaction-field dielectric constant used when running without PME. Not exposed as an input-file key or CLI flag.