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)
hydrogenmass: 4.032 # Hydrogen mass for HMR (amu)
#--- 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 withparameters
.
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.
hydrogenMass
Valid values: positive real number
Default: 4.032
Units: amu
Mass of a hydrogen atom for the mass repartitioning.
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 themDefault:
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
stringsDefault: []
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
: microsecondsns
: nanosecondsps
: picosecondsfs
: femtosecondsor 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
orxtc
extensionDefault:
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
extensionDefault: 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
extensionDefault: 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