# ACEMD Command Reference¶

## Configuration¶

Commands for configuring the simulation integration

• comfreq <+ve integer>: The frequency with which motion of the centre of mass of the system will be removed. Do not change. Default: 1
• energyfreq <+ve integer>: The frequency with which ACEMD will calculate system energies. Default: 1
• energyoutputfreq <+ve integer>: The frequency with which ACEMD will output system energies to the stdout log. Default: energyfreq
• hydrogenscale <+ve float>: Amount by which to scale the mass of H atoms. Additional mass will be removed from any bound atom. The maximum and recommended value is 4. When set, timestep 4.0 is possible. Default: 1.0
• outputunits kcal | kJ: Units for energies shown in stdout log. Default: kcal
• pairlistdist <float>: Specify the buffer size for grid cells. This parameter generally should not be changed. Setting this to equal the cutoff will disable the use of pairlists. Default: cutoff + 1.5
• pairlistfreq <+ve integer>: The number of steps between successive pairlist regenerations. For single-GPU runs, pairlists are by default updated only when necessary. Default: As required (serial runs) or 7 (parallel runs)
• protocol <name>: Specify a pre-defined protocol commandset to use. Protocols will be searched for in the current working directory, $HOME/protocol and finally$ACEMD_HOME/protocol. Protocol files are expected to have the filename ‘.tcl’.
• rigidbonds none | all: Enable holonomic constraints on all hydrogen-heavy atom bond terms. This removes fast modes of oscillation, making a higher timestep possible. With rigidbonds all, timestep 2.5 is possible. In conjunction with hydrogenscale 4., a timestep of 4.0 is stable. Default: none
• run <+ve integer>: The number of simulation iterations to perform. Default: 0
• runtime <+ve integer>: The amount of walltime to run for. Accumulated over restarts.
• seed <+ve integer>: Seed for Langevin PRNG. This doesn’t need setting. Default: system time
• timestep <+ve float>: Integration timestep in fs. Default: 1.0
• verbose Returns 1 if ACEMD was started with the –verbose flag.

## Input¶

Commands for specifying input files.

• coordinates <filename>: Filename for initial structure coordinates, in PDB format. Default: structure.pdb
• velocities <filename>: Initial velocity field, in PDB format. Overrides ‘temperature’.
• bincoordinates <filename>: Filename for initial structure coordinates, in NAMD Bincoor format.
• binindex <filename>: Default: Filename for index file to set initial timestep (as made by a check-point)
• binvelocities <filename>: Initial velocity field, in NAMD Bincoor format. Overrides ‘temperature’.
• celldimension <X> <Y> <Z>: Dimensions of the unit cell. If not set, ACEMD will guess based on extent of input coordinates. celldimension will be overridden by an extendedsystem file.
• extendedsystem <filename>: If set, specifies an extended system .xsc file, from which a cell dimension will be read. This overrides any guessed box size, or explicit ‘celldimension’.

## Output¶

Commands for specifying output files and frequency.

• outputname <filename>: Filename prefix for terminal coordinate and velocity files, written in NAMD Bincoor format. Default: output
• wrap on | off: Enable to wrap coordinates in the output trajectory back into the periodic cell. Default: off
• xtcfile <filename>: The filename for the output coordinate trajectory in XTC format. Default: output.xtc
• xtcfreq <+ve integer>: Frequency with which coordinate snapshots are written to the XTC trajectory file. If 0, no sampling is done.
• dcdfile <filename>: The filename for the output coordinate trajectory in DCD format. Default: output.dcd
• dcdfreq <+ve integer>: Frequency with which coordinate snapshots are written to the DCD trajectory file. If 0, no sampling is done.
• veldcdfile <filename>: The filename for the output velocity trajectory in DCD format. Default: output.vel.dcd
• veldcdfreq <+ve integer>: Frequency with which coordinate snapshots are written to the DCD trajectory file. If 0, no sampling is done.
• restart on | off: Enable the saving of checkpoint files, for restarting simulations. Default: off
• restartfreq <+ve integer>: Frequency with which ACEMD saves checkpoint files. Default: 0
• restartname <filename>: Prefix for checkpoint file filenames. Default: restart
• restartsave on | off: Enable the creation of checkpoint file backups. By default old checkpoints will be over-written. Default: off

## Forcefield¶

These commands pertain to all force fields.

• exclude none | 1-2 | 1-3 | 1-4 | scaled1-4: This parameter specifies which pairs of bonded atoms should be excluded from non-bonded interactions. 1-2, 1-3 and 1-4 suppresses the electrostatic interactions between atoms <2, <3 and <4 bond terms away from one-another. With the value of scaled1-4, all 1-3 pairs are excluded and all pairs that match the 1-4 criteria are modified. The CHARMM force field specifies alternate LJ parameters for 1-4 pairs. Electrostatic interactions between scaled1-4 pairs are modified by the value of 1-4scaling. Default: none
• 1-4scaling <+ve float>: Scaling factor for 1-4 electrostatic interactions. This factor is only used when the exclude command is set to scaled1-4. In this case, this factor is used to modify the electrostatic interactions between 1-4 atom pairs. If the exclude parameter is set to anything but scaled1-4, this parameter has no effect regardless of its value. For CHARMM use 1.0, for Amber 0.833333. Default: (0.0,1.0)
• switchdist (0.0,cutoff): Range beyond which to begin to apply the switching functions. Default: cutoff-1.5
• switching on | off: Enable to apply smoothing and switching functions to electrostatic and VdW forces. When set, switchdist must also be set. Default: off
• tabular vdw | elec <file>: Default: Load a tabulated vdw or electrostatic potential
• vdwforceswitching on | off: Enable force switching of the VdW potential. Default: off
• vdwgeometricsigma on | off: Enable geometric sigma combination rule for LJ parameters. This is important for the OPLS force-field. Default: off

## Charmm¶

These commands pertain to options specific to the CHARMM force field. Please read the force-field section for more details

• parameters <filename>: CHARMM force-field parameter file (PRM)
• structure <filename>: CHARMM structure topology in PSF format

## Amber¶

These commands pertain to options specific to the Amber force field. Please read the force-field section for more details

• amber on | off: Indicate that the Amber force field is to be used. If set, parmfile is required and neither structure nor parameters are used. Default: off
• parmfile <filename>: The filename of the Amber PRMTOP parameter file.

## Martini¶

These commands pertain to options specific to the Martini force field.

• cosangles on | off: Enable cosine form angle potential for Martini force field. Default: off
• dielectric <+ve float>: Dielectric constant. Set to 15.0 when using Martini FF . Default: 1.0
• martiniswitching on | off: Enable Martini force field switching function. Default: off
• pme on | off: Enable the use of PME for long-range electrostatics. Disable when using Martini. Default: on

## Electrostatics¶

These commands control the PME method used to calculate the long-range contribution to the electrostatic potential. PME should usually be used in all CHARMM and Amber simulations. We recommend a cutoff of 9A and a PME grid spacing of 1 angstrom.

• cutoff <+ve float>: Cutoff distance for direct-space electrostatic interaction evaluation. Default: 9.0
• dielectric <+ve float>: Dielectric constant. Set to 15.0 when using Martini FF . Default: 1.0
• fullelectfrequency <+ve integer>: The frequency in interactions between successive calculations of long-range (PME) electrostatics. Default: 2
• pme on | off: Enable the use of PME for long-range electrostatics. Disable when using Martini. Default: on
• pmefreq <+ve integer>: The frequency with which PME long-range electrostatics are calculated. Default: 2
• pmegridsizex <+ve integer>: The X size of the PME mesh.
• pmegridsizey <+ve integer>: The Y size of the PME mesh.
• pmegridsizez <+ve integer>: The Z size of the PME mesh.
• pmegridspacing <+ve float>: The spacing of the PME mesh in 1/A. The mesh size can be set explicitly with pmegridsize[xyz]. Default: 1.0
• pmetolerance <+ve float>: The direct space Ewald coefficient. Do not change. Default: 1.e-6

## Barostat¶

ACEMD implements a Berendsen barostat designed for the equilibration of molecular systems (globular and in a membrane) to then start NVT production runs. With the system sizes which are achievable nowadays it is not necessary to have a pressure control in the production run, unless you really know what you are doing (for large number of atoms all ensembles are equivalent statistically). For molecular systems up to 100,000 atoms in a membrane allow for an equilibration of 20 ns, for globular proteins 1 to 5 ns are sufficient.

• berendsenpressure on | off: Set to enable the Berendsen pressure bath barostatic control. Default: off
• berendsenpressurecompressibility <+ve float>: The compressibility factor for the barostat, (1/bar). Default: 4.57e-5
• berendsenpressurerelaxationtime <+ve float>: Relaxation time for the barostat (fs). Default: 400.
• berendsenpressuretarget <+ve float>: The target pressure (Bar) for the barostat. Default: 1.01325
• useconstantratio on | off: Enable to keep the ratio of the X-Y dimensions constant while allowing the Z dimension to fluctuate independently. Enable this for membrane systems. Default: off
• useconstantx on | off: Keep the unit cell X dimension constant. Default: off
• useconstanty on | off: Keep the unit cell Y dimension constant. Default: off
• useconstantz on | off: Keep the unit cell Z dimension constant. Default: off
• useflexiblecell on | off: Enable to allow the three orthogonal dimensions of the periodic cell to fluctuate independently. Default: off

## Thermostat¶

The Langevin thermostat is needed to keep the system in the NVT ensemble. This is the suggested ensemble for production runs. The langevindamping should be as small as possible in order to thermalize the system without affecting the transport parameters (diffusion).

• langevin on | off: Enable the Langevin thermostat. Default: off
• langevindamping <+ve float>: Langevin damping constant gamma (1/ps). 0.1 is recommended for production NVT simulations, and 1.0 during equilibration. Default: 0.1
• langevintemp <+ve float>: The set point (in K) for the Langevin thermostat. Default: 0.
• temperature <+ve float>: Temperature (in K) for initial velocity field. Will be overridden by binvelocities. Default: 0.

## Constraints¶

These commands allow positional restraints to be applied to a simulation. This is useful when equilibrating a system, to ensure that a structure does not diverge from a reference conformation

• consref <filename>: Specify a PDB file giving reference positions for constrained atoms. Entries with a beta > 0. will be constrained, and the value will be used as the strength of the harmonic potential (subject to scaling by constraintscaling). The occupancy column is used to specify the directions in which the restraint is applied. This takes the following values: 0 for XYZ, 1 for X, 2 for Y, 3 for Z, 4 for XY, 5 for YZ and 6 for XZ. .
• constraints on | off: Set to enable positional constraints on specified atoms. Default: off
• constraintscaling <float>: The harmonic constraint energy function is multiplied by this parameter, making it possible to gradually turn off constraints during equilibration. This parameter is used only if constraints is set to on. Default: 0.

## External Forces¶

These commands allow additional biasing forces to be applied to the simulation. Two types of external force are currently implemented: an oscillating electrical field and a flat, pairwise repulsive potential

• efield on | off: Apply an external electic field to the system. Function is E(t) =k.cos(omega.t-phi). Default: off
• efieldfrequency <float>: The frequency of the external electic field, in THz. Default: 1.
• efieldphase <float>: The phase at timestep 0 of the external electric field, in degrees. Default: 0.
• efieldvector <3vec>: The vector along which to apply the external electric field. Units are kcal/(mol Angstrom e). Default: {1.0 0.0 0.0}
• repulsionadd <atomid> | <groupid>: Add to the list of atoms that feel a mutual repulsive force.
• repulsionconstant <float>: Set the strength of the repulsive potential (kcal/mol). Default: 1.0
• repulsionrange <+ve float>: Set the cutoff for the repulsive potential (Angstrom). Default: 20.0
• repulsionref <filename>: Reference PDB file for repulsive force. All atoms with beta>0 will be used.

## Minimisation¶

Commands for performing energy minimisation. This is often required to remove any steric conflicts from a newly-constructed model

• mindis <+ve float>: Minimisation bracketing distance. Default: 1.0
• mineval <+ve integer>: Maximum number of force evaluations per minimisation iteration. Default: 50
• minimize <+ve integer>: Number of steps of conjugate-gradient minimisation to perform. Default: 0
• mintol <+ve float>: Minimisation force tolerance. Default: 0.01

## Interactive¶

ACEMD supports VMD’s Interactive Molecular Dynamics (IMD) mode. IMD is read-only: VMD cannot be used to apply external forces

• imd on | off: Enable to allow a VMD session direct connection to ACEMD, using the IMD Connect extension (read only, forces cannot be applied). Default: off
• imdfreq <+ve integer>: The frequency with which the IMD feed is updated. Default: 1000
• imdport <+ve integer>: The TCP port that ACEMD will listen on for incoming IMD connections. Default: 54321

## Extensions¶

Commands for enabling TCL and C plugin extensions.

• pluginarg <tag> <key> <value>: Pass a configuration argument to a loaded plugin. specifies a plugin identifier set in a previous call to ‘pluginload’. Gives a name to the argument and its value.
• pluginfreq <+ve integer>: The frequency with which plugin forces will be evaluated. Applies to all active plugins. Default: 1
• pluginload <tag> <filename>: Load a plugin specified by the file . specifies an identifier for subsequent references to the plugin by ‘pluginarg’. ACEMD will attempt to load the plugin from the current working directory, $ACED_HOME/plugin and$HOME/plugin/ . It will permute the filename with the prefix ‘lib’ and suffix ‘.so’. If a plugin cannot be found, ACEMD will issue a warning but continue running.
• tclforces on | off: Enable TCL force scripting. If set, the procedures calcforces_init, calcforces, calcforces_endstep and calcforces_terminate must be defined. Default: off
• tclforcesfreq <+ve integer>: The frequency with which the procedure calcforces will be called. Default: 1

## TCL Extension¶

Commands useful in TCL Extension Programming. See the ACEMD Extension Programming Guide for more information

• addatom <+ve integer>: Request coordinates of this atom for next force evaluation, and the calculated total force on this atom for current force evaluation. Request remains in effect until clearconfig is called.
• addforce <atomid | groupid> <force vector>: Applies force (in kcal mol A) to atom or group. addforce should only be called from within the calcforces procedure.
• addgroup <atomid list>: Request center of mass coordinates of this group for next force evaluation. Returns a group ID that may then be used to find coordinates and apply forces just like a regular atom ID. Aggregate forces may then be applied to the group as whole. Request remains in effect until clearconfig is called.
• anglegrad <coor1> <coor2> <coor3>: This command takes the angle, theta, defined by the three coordinates and returns a list of the gradients dtheta/dr.
• berendsenpressure on | off: Set to enable the Berendsen pressure bath barostatic control. Default: off
• cellresize { X Y Z }: Force a resizing of the unit cell to the given dimensions. Likely to crash a simulation unless used with caution.
• cellsize Return a 3vec containing the current dimensions of the unit cell.
• clearconfig Clears the current list of requested atoms. After clearconfig, calls to addatom and addgroup can be used to build a new configuration.
• computevirial Return the 3x3 virial tensor. Requires the barostat to have been enabled (although it may have been switched off subsequently.
• constraints on | off: Set to enable positional constraints on specified atoms. Default: off
• constraintscaling <float>: The harmonic constraint energy function is multiplied by this parameter, making it possible to gradually turn off constraints during equilibration. This parameter is used only if constraints is set to on. Default: 0.
• dihedralgrad <coor1> <coor2> <coor3> <coor4>: This command takes the dihedra, phi, defined by the four input coordinates and returns a list of the gradients dphi/dr.
• ensemblerecv <var>: Receive data send from another ensemble instance using ‘ensemble_send’ into.
• ensemblesend <rank> <var>: Send the contents of to ensemble instance with index. Must be matched with an ‘ensemble_recv’ on the destination instance.
• getangle <coor1> <coor2> <coor3>: Returns the angle (from 0 to 180) defined by the three coordinates.
• getbond <coor1> <coor2>: Returns the length of the bond between the two coordinates.
• getdihedral <coor1> <coor2> <coor3> <coor4>: Returns the dihedral (from -180 to 180) defined by the four coordinates.
• getenergies Returns a 3vec containing the total potential energy, the kinetic energy and the current temperature of the system. This is valid only from within the calcforces_endstep procedure.
• getensemblerank Returns the 0-based index of this instance of ACEMD within any ensemble, or 0 otherwise.
• getensemblesize Returns the number of ACEMD instances participating in any ensemble simulation, or 1 otherwise.
• getiterationcount Return the current simulation interaction number.
• getiterationtime Return the timestep in fs.
• getnatoms Return the number of atoms in the system.
• getstep Returns the current iteration number.
• gpuversion Returns an integer giving the compute capability of the GPU.
• langevintemp <+ve float>: The set point in K for the Langevin thermostat. Default: 0.
• loadcharges <var>: Loads requested atom and group charges (in e) into a local array. loadcharges should only be called from within the calcforces procedure.
• loadcoords <var>: Loads requested atom and group coordinates (in Angstrom) into a local array. loadcoords should only be called from within the calcforces procedure.
• loadmasses <var>: Loads requested atom and group masses (in amu) into a local array. loadmasses should only be called from within the calcforces procedure.
• loadvelocities <var>: Loads requested atom and group velocities into a local array. loadcoords should only be called from within the calcforces procedure.
• mindist <coor1> <coor2>: Returns the vector of the shortest distance between two coordinates, taking into account the periodic boundaries of the system. The result is a four element list containing a unit vector followed by a length.
• nbenergy <groupid A> <groupid B>: Returns a list containing the electrostatic and VdW energies computed between the atoms in groups A and B. An infinite cutoff is assumed.
• print <string>: Print to the stdout log.
• readpdb <var> <filename>: Load a PDB file and put the contents in the TCL variable named , in the form of a list of 4vecs. Each 4vec contains the position of an atom followed by the temperature (beta) factor. If is not specified, that specified for ‘coordinates’ will be used.
• repulsionadd <atomid> | <groupid>: Add to the list of atoms that feel a mutual repulsive force.
• repulsionconstant <float>: Set the strength of the repulsive potential (kcal/mol). Default: 1.0
• repulsionrange <+ve float>: Set the cutoff for the repulsive potential (Angstrom). Default: 20.0
• repulsionref <filename>: Reference PDB file for repulsive force. All atoms with beta>0 will be used.
• scalevelocities <float>: Scale the velocity field for the simulation. Should only be called from within calcforces_endstep.
• terminate Terminate the simulation in an orderly manner.
• vecadd <3vec A> <3vec B>: Return the sum A+B of two vectors.
• vecdot <3vec A> <3vec B>: Return the dot product of vectors A and B.
• veclength <3vec>: Return the magnitude of vector A sqrt(a.x*a.x + a.y*a.y + a.z*a.z).
• veclength2 <3vec>: Return the square of the magnitude of vector A (a.x*a.x + a.y*a.y + a.z*a.z).
• vecnormalise <3vec A>: Return vector A normalised to unit length.
• vecscale <3vec A> <scalar B>: Scale the vector A by scalar B.
• vecsub <3vec A> <3vec B>: Return the difference A-B between two vectors.
• verbose Returns 1 if ACEMD was started with the –verbose flag.

## Analysis¶

Custom analysis functions

• metric on | off: When on, enable distance metric recording. Default: off
• metricfile <filename>: The output file for calculated metric. Default: metric.dat
• metricfreq <integer>: The frequency with which distance metrics will be calculated and output. Default: 25000
• metricref <filename>: Configuration of the two groups of atoms between which a distance metric will be computed. Groups are specified with the beta values of 1 and 2. Default: metric.pdb