Ctrl+K

Manual#

Command line arguments#

Syntax:

acemd [--platform <platform>]
      [--ncpus <n> | --ngpus <n> | --device <d1>[,<d2>,...]]
      [--help]
      <input>
--platform

  • Valid values: CPU, CUDA, OpenCL

  • Default: CUDA

Platform to use for a simulation. CUDA is for the GPUs from NVIDIA, while OpenCL is for the rest GPUs.

--ncpus

  • Valid values: positive integer

  • Default: all available CPUs

Number of CPUs to use for a simulation. This is only relevant for --platform CPU.

--ngpus

  • Valid values: positive integer

  • Default: 1

Number of GPUs to use for a simulation. This is only relevant for --platform CUDA or --platform OpenCL.

--device

  • Valid values: list of GPU indices

  • Default: none

List of GPU device indices to use for a simulation. The indices are separated by comma, but without spaces. If --device is set, it overrides --ngpus.

Run nvidia-smi to get the available device indices.

Example:

acemd --device 0,2
--precision

  • Valid values: single, mixed, double

  • Default: mixed

Set the precision mode on GPU devices.

--license

  • Valid values: none

Print the ACEMD license.

--help

  • Valid values: none

Show help message.

<input>

  • Valid values: filename of a YAML or JSON input file

  • Default: input.yaml

Input file (see input options).

Input file options#

Input files are written in YAML or JSON format. The keywords are case-insensitive, but their arguments may be case-sensitive (e.g. filenames).

Here you can find a list of all the available options with their default values. All options are explained in more details below. For the External forces and NNP options, see External Forces and Neural Network Potentials for more details.

# ACEMD Configuration File Documentation
# Here we show the default values used if the option is not specified

#--- System Structure and Parameters ---
structure: null           # Path to structure file (.psf or .prmtop)
parameters: null          # Path to parameter file(s) (.prm or .str for CHARMM)

#--- Initial Conditions ---
coordinates: null            # Path to coordinate file (.pdb, .coor)
boxsize: null                # Box dimensions [x y z] in Angstroms or NAMD XSC file path
velocities: 298.15           # Path to velocity file (.vel or .pdb) or
                             # temperature for initial velocity assignment (K)
restart: false               # Restart from checkpoint if available

#--- Non-bonded Interactions ---
pme: true               # Use Particle Mesh Ewald for electrostatics
cutoff: 9.0             # Non-bonded cutoff distance (Angstroms)
switching: true         # Use switching function for non-bonded interactions
switchdistance: 7.5     # Distance at which switching function starts (Angstroms)

#--- Implicit Solvent ---
implicitsolvent: false  # Use implicit solvent
igb: 2                  # Implicit solvent model

#--- Integration ---
timestep: 4.0          # Integration timestep (fs)
hmr: null              # Override default HMR setting
hydrogenmass: 4.032    # Hydrogen mass for HMR (amu)
hbondconstr: null      # Override default H-bond constraints setting
rigidwater: null       # Override default rigid water setting

#--- Temperature Control ---
thermostat: false              # Enable Langevin thermostat
thermostattemperature: 298.15  # Target temperature (K)
thermostatdamping: 1.0         # Thermostat damping (1/ps)

#--- Pressure Control ---
barostat: false               # Enable barostat
barostatpressure: 1.0         # Target pressure (bar)
barostatanisotropic: false    # Allow anisotropic xyz box scaling
barostatconstratio: false     # Keep xy ratio constant
barostatconstxy: false        # Keep xy dimensions constant

#--- External Forces ---
extforces: null       # List of restraint specifications
fbrefcoor: null       # Reference coordinates for fixed/moving restraints

#--- PLUMED ---
plumedfile: null       # PLUMED input file

#--- Output Control ---
trajectoryfile: "output.xtc"  # Output trajectory file name
trajvelocityfile: null        # Output velocity trajectory file name
trajforcefile: null           # Output force trajectory file name
trajectoryperiod: 25000       # Steps between trajectory frames
stepzero: false               # Output frame at step 0. Mostly used for debugging

#--- Simulation Length ---
run: 0                 # Simulation length (steps or time unit: fs/ps/ns/us)
minimize: 0            # Number of minimization steps (0 = no minimization)

#--- Neural Network Potentials ---
nnp: null             # Neural network potential configuration

System Structure and Parameters#

AMBER and CHARMM force fields are supported:

  • For AMBER, both parameters and system topology are specified with structure.

  • For CHARMM, system topology is specified with structure and parameters are specified with parameters.

structure

  • Valid values: filename of a PSF or PRMTOP file

  • Default: none

parameters

  • Valid values: path to a PRM file or a list of PRM files

  • Default: none

CHARMM force field parameters. Can also be a list of prm files.

Initial conditions#

coordinates

  • Valid values: filename of any coordinate file supported by MoleculeKit

  • Default: none

Initial system coordinates.

boxSize

  • Valid values: 3 positive real numbers or filename of a NAMD XSC file

  • Default: none

Initial size of the simulation box. If a list of 3 numbers is given, it is used as the size of the box. If a filename of a NAMD XSC file is given, the box size is read directly from the file. Note that the simulation box has to be rectangular.

Examples

boxSize: [10.0, 25.0, 30.0]  # 10.0 x 25.0 x 30.0 Angstrom box
boxSize: input.xsc           # Read from NAMD XSC file
velocities

  • Valid values: filename of PDB file or NAMD BINCOOR file or positive real number

  • Default: 298.15

Initial system velocities. If a filename is given, the velocities are read from the file. If a number is given, the velocities are generated from a Maxwell-Boltzmann distribution with the given number used as temperature (K)

restart

  • Valid values: true, false

  • Default: false

Enable the restart of simulation from restart.chk file. The restart overrides the initial system coordinates, velocities, and box size. Also, the states of thermostat and barostart are overridden, if they are used. Note that restart.chk is always written every trajectoryPeriod steps irrespective of this option. Note that restart.chk can only be used to restart on the same hardware (i.e. a GPU has be of the same model).

Non-bonded Interactions#

PME

  • Valid values: true, false

  • Default: true

Enable the particle-mesh Ewald summation for electrostatic interactions.

cutoff

  • Valid values: positive real number

  • Default: 9.0

  • Units: Angstrom

Cutoff distance for van der Waals interactions and real-space electrostatic interactions.

switching

  • Valid values: true, false

  • Default: true

Enable a switching function for van der Waals interactions.

switchDistance

  • Valid values: positive real number

  • Default: 7.5

  • Units: Angstrom

Cutoff of the switching function.

Implicit Solvent#

implicitSolvent

  • Valid values: true, false

  • Default: false

Enable the implicit solvent (GBSA-OBC). Valid only for AMBER force field.

igb

  • Valid values: 1, 2, 5, 7, 8

  • Default: 2

Implicit solvent model. For more details see the table here: http://docs.openmm.org/latest/userguide/application/02_running_sims.html#amber-implicit-solvent

Integration#

timeStep

  • Valid values: positive real number

  • Default: 4.0

  • Units: fs

Time step of an integrator. Note that the constraints and hydrogen mass repartitioning is enabled automatically:

  • If timeStep > 0.5 fs, enable hydrogen bond constraints and make water molecules rigid.

  • If timeStep > 2.0 fs, enable all bond constraints and repartition hydrogen mass.

hmr

  • Valid values: true, false

  • Default: null

Enable hydrogen mass repartitioning. By default, HMR is enabled if timeStep > 2.0 fs.

hydrogenMass

  • Valid values: positive real number

  • Default: 4.032

  • Units: amu

Mass of a hydrogen atom for the mass repartitioning.

hbondConstr

  • Valid values: true, false

  • Default: null

Enable H-bond constraints. By default, H-bond constraints are enabled if timeStep > 0.5 fs.

rigidWater

  • Valid values: true, false

  • Default: null

Enable rigid water. By default, rigid water is enabled if timeStep > 0.5 fs.

Temperature Control#

thermostat

  • Valid values: true, false

  • Default: false

Enable Langevin thermostat.

thermostatTemperature

  • Valid values: non-negative real number

  • Default: 298.15

  • Units: Kelvin

Target temperature for the thermostat

thermostatDamping

  • Valid values: non-negative real number

  • Default: 0.1

  • Units: ps^-1

Damping constant of the thermostat.

Pressure Control#

barostat

  • Valid values: true, false

  • Default: false

Enable Monte Carlo barostat.

barostatPressure

  • Valid values: real number

  • Default: 1.0

  • Units: bar

Target pressure of the barostat.

barostatAnisotropic

  • Valid values: true, false

  • Default: false

Enable the axes (x, y, z) of the simulation box to vary independently.

barostatConstRatio

  • Valid values: true, false

  • Default: false

Enable a constraint of x / y, while z varies independently.

barostatConstXY

  • Valid values: true, false

  • Default: false

Enable a constraint of x and y, while z varies independently.

External Forces#

ACEMD supports a variety of external forces applying to the system. Forces are specified in the yaml file as a list under the extforces keyword.

Positional restraints#

Each positional restraint can be specified with the following options:

extforces:
  - type: positionalRestraint # Type of restraint (required)
    sel: null                 # Atoms to which the force is applied (required)
    axes: "xyz"               # Axes on which the force is applied
    fbWidth: [0, 0, 0]        # Width of the flat-bottom potential in Å
    fbCenter: null            # Center of the flat-bottom potential
    fbCenterOffset: [0, 0, 0] # Offset for the center of the flat-bottom potential
    setPoints:                # List of force constant setpoints (required)
      - k@time                # Force constant value at a given time
sel

  • Valid values: atom selection in VMD format

  • Default: none

Atom selection which defines the atoms on which to apply the restraining force. Take special care to not include hydrogens in the selection if using timestep larger than 2 fs, as the hydrogens are constrained to their corresponding heavy atoms and can cause NaN coordinates during the simulation. You can use the noh keyword to exclude hydrogens from a selection, see examples below.

axes

  • Valid values: x, y, z, +x, -x, +y, -y, +z, -z or any string concatenation of them

  • Default: xyz

Axes defines on which axes the restraint will be applied. By default it will be applied along all axes. If an axis has a + or - prefix, the restraint will be applied only to the specified direction of the axis leaving the other direction unrestrained.

fbWidth

  • Valid values: list of 3 positive real numbers

  • Default: [0, 0, 0]

Width of the flat-bottom potential. If just a single number is given, it is used for all defined axes. By default the width is 0, which means that no flat-bottom potential is applied and the restraint applies directly a harmonic potential to the atom positions. If the width is not 0, each atom is restrained to its original position by a flat-bottom potential with the given width. If fbCenter is defined, the width is used to define the size of the single box within which all atoms of sel are restrained.

fbCenter

  • Valid values: atomselection string or list of 3 real numbers

  • Default: none

If an atomselection string is passed, it defines a single moving center for the flat-bottom potential. The center of mass of the selected atoms in fbCenter is used as the center of the flat-bottom potential. All atoms in sel are restrained inside a box centered at the moving center with the given fbWidth.

If a list of 3 real numbers is given, it defines a single fixed-position center for the flat-bottom potential. All atoms in sel are restrained inside a box centered at the given absolute xyz coordinates.

fbCenterOffset

  • Valid values: list of 3 real numbers

  • Default: [0, 0, 0]

Offset of the center of the flat-bottom potential from the center defined in fbCenter. This can be useful for example to define a flat-bottom potential that is not centered directly on the center of mass of the selected atoms but 10 Å away from it in the z direction (e.g. fbCenterOffset: [0, 0, 10]).

setPoints

  • Valid values: list of k@time strings

  • Default: []

The setpoints define the force constant of the restraint (in kcal/mol/Ų) as a function of time. The force constant is linearly interpolated between the setpoints if there is more than one. If no setpoint is set for time 0, the restraint at time 0 will be 0 kcal/mol/Ų and will be interpolated to the specified next setpoint. If no setpoint is specified for the last step of the simulation, the last defined force constant will be used for the remaining simulation time.

Time units can be specified as:

  • us: microseconds

  • ns: nanoseconds

  • ps: picoseconds

  • fs: femtoseconds

  • or as number of timesteps if no suffix is specified

Example#

extforces:
  # Keep the CA atoms restrained in place during the first 100ns with 1 kcal/mol/Ų
  - type: positionalRestraint
    sel: "protein and name CA"
    axes: "xyz"
    setpoints:
      - 1@0ns
      - 0@100ns

  # Restrain molecules named MOL within 10 Å of COM of the protein
  - type: positionalRestraint
    sel: "resname MOL"
    axes: "xyz"
    fbwidth: 10
    fbcenter: "protein and name CA"
    setpoints:
      - 0.5@0

  # Restrain molecules named MOL which are located above the membrane to stay within 20 Å
  # of the membrane by defining a box with a center +10 Å in the z direction from the
  # center of mass of the membrane and width 20 Å
  - type: positionalRestraint
    sel: "resname MOL and noh"
    axes: "z"
    fbwidth: 20
    fbcenter: "(lipid or resname AR CHL DHA LAL MY OL PA PC PE PGR PGS PS SA SPM ST) and noh"
    fbcenteroffset: [0, 0, 10]
    setpoints:
      - 0.5@0

  # Restrain the center of mass of the protein to [21, 13.5, -5] position
  - type: positionalRestraint
    sel: "protein and noh"
    axes: "xyz"
    fbwidth: 0
    fbcenter: [21, 13.5, -5]
    setpoints:
      - 1@0
fbRefCoor

  • Valid values: filename of a PDB file

  • Default: none

Reference coordinates for positionalRestraint restraints. The reference coordinates in fbRefCoor are used to calculate the reference atom positions to which the atoms are restrained.

PLUMED#

plumedFile

  • Valid values: filename of a PLUMED input file

  • Default: none

Enables PLUMED. It can be used to perform enhanced sampling simulations (i.e. metadynamics, steered MD, etc.) or apply complex restraints. For more details, see our PLUMED tutorial and the PLUMED documentation.

Output Control#

The final atomic positions, velocities, and sizes of the simulation box are always written to output.coor, output.vel and output.xsc, respectively.

trajectoryFile

  • Valid values: filename with a dcd or xtc extension

  • Default: output.xtc

Name of a trajectory file for atomic positions. The trajectory is written in DCD or XTC format depending on the file extension. The positions are in Ångstrom. By default, the atomic positions are not wrapped. The atomic positions can be wrapped with moleculekit.

trajVelocityFile

  • Valid values: filename with a dcd extension

  • Default: none

Name of a trajectory file for atomic velocities. The trajectory is written in DCD format only. The velocities are in arbitrary units, which can be converted to Å/ps by multiplying by 20.45482706 (the standard of DCD).

trajForceFile

  • Valid values: filename with a dcd extension

  • Default: none

Name of a trajectory file for atomic forces. The trajectory is written in DCD format only. The forces are in kcal/mol/Å.

trajectoryPeriod

  • Valid values: non-negative integer

  • Default: 25000

  • Units: simulation steps

Period of the trajectory files. Note that the log and restart files are written at the same period.

stepZero

  • Valid values: true, false

  • Default: false

Write outputs for step 0 of the simulation. Mostly used for debugging to check on initial state and energies.

Simulation Length#

run

  • Valid values: non-negative integer

  • Default: 0

  • Units: simulations steps or time units (see below)

Lenght of simulations. The length can be specified in simulation steps or time using suffices (us, ns, ps, and fs).

minimize

  • Valid values: non-negative integer

  • Default: 0

  • Units: steps

Number of system minimization steps before starting a simulation. Note that the minimization is skipped if the simulation is restarted.

Examples#

minimize: 500
run: 100ns

Neural Network Potentials#

nnp:
  file: null
  name: null
  sel: null
  type: null
name

  • Valid values: string

  • Default: none

Name of the NNP model. Currently supported models include TorchMD-Net and ANI variants. If it’s set to ANI-2x, ANI-1x, or ANI-1ccx, the NNP will use the corresponding ANI-2x, ANI-1x, or ANI-1ccx model. In that case you don’t need to set file as it will be downloaded automatically.

file

  • Valid values: filename of an NNP file

  • Default: none

Path to a TorchMD-Net NNP file.

sel

  • Valid values: atom selection in VMD format

  • Default: none

Atom selection for the NNP. The atoms selected will be simulated with the NNP. All other atoms of the system will be simulated with the MM force field.

type

  • Valid values: torch

  • Default: none

Type of the NNP. Currently only torch model types are supported.

Examples#

Example using TorchMD-Net:

nnp:
  file: aceforce_dft_v0.2.ckpt
  name: TorchMD-Net
  sel: "resname ACE ALA NME"
  type: torch

Example using ANI-2x:

nnp:
  name: ANI-2x
  sel: "resname ACE ALA NME"
  type: torch
On this page