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 and NNP options.

Defaults at a glance#

# 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 build() handoff (see 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.

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

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.

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.

Integration#

ACEMD enables constraints and hydrogen-mass repartitioning automatically based on timestep — see Integrator and constraints 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 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 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).

`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.

`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.

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

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.
fbrefcoor — reference PDB for positional restraints. See External forces.
plumedfile — path to a PLUMED input file. See Run with PLUMED.
nnp — neural-network potential block. See NNP options.

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.
`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.

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

Input-file options#

Defaults at a glance#

System: structure and parameters#

structure#

parameters#

Initial conditions#

coordinates#

boxsize#

velocities#

restart#

Non-bonded interactions#

pme#

cutoff#

switching#

switchdistance#

Implicit solvent#

implicitsolvent#

igb#

Integration#

timestep#

hmr#

hydrogenmass#

hbondconstr#

rigidwater#