The AToM Control File Reference

AToM uses Configobj to read settings from a control file. The configobj keywords, their meaning, and syntax are listed below organized by topic. See this example to see how the sequence of keywords come together.

Job Settings

JOB_TRANSPORT

(string) The job transport is the means by which replicas are executed on GPU devices. LOCAL_OPENMM is the only job transport system currently supported. Each local GPU is managed by a different process using the Python multiprocessing module.

BASENAME

(string) The basename of the job. In particular, AToM will look for a file called BASENAME_sys.xml and BASENAME.pdb to read the OpenMM System definition and the chemical topology of the system. To start production, AToM will also look for an OpenMM restart file called BASENAME_0.xml.

WALL_TIME

(int) Execution wall time in minutes. AToM will terminate gracefully after this time is exceeded.

MAX_SAMPLES

(int) If specified, AToM will terminate gracefully after each replica collects these many perturbation energy samples.

CYCLE_TIME

(int) The wall-clock time interval in seconds between rounds of replica exchange attempts in seconds

CHECKPOINT_TIME 

(int) The wall-clock time interval between simulation checkpointing in seconds.

NODEFILE

(str) The file name of the file listing the compute devices. Each line corresponds to each compute device. The format of each line is:

<hostname>, <platformID>:<deviceID>, <core-count>, <platform>, <username>, <tempdir> 

AToM currently works within a single server only, so <hostname> must be the name of the local host. <platformID>  is specific to the OpenCL platform, otherwise is set to 0.  <deviceID> is the device ID of the GPU, if using a GPU device.   <platform>  is the name of OpenMM platform (CPU, OpenCL, CUDA, or HIP where supported).  <core-count>, which is specific to the CPU platform, is the number of cpu cores.  <username>, and  <tempdir> are not currently used. For example. a nodefile such as:

localhost, 0:0, 1, CUDA, ,/tmp

localhost, 0:1, 1, CUDA, ,/tmp

specifies two NVIDIA GPU devices.

SUBJOBS_BUFFER_SIZE

(float) To reduce latencies, AToM keeps some replicas in a fast execution queue ready to be sent to a compute device as soon as it becomes available. SUBJOBS_BUFFER_SIZE specifies the number of replicas to keep in the fast execution queue in terms of a fraction of the number of compute devices. For example, if there are four compute devices and SUBJOBS_BUFFER_SIZE = 0.5, two replicas are kept in the fast execution queue.

PRODUCTION_STEPS

(int) The number of MD steps that a replica performs each time is placed on a compute device for execution.

PRNT_FREQUENCY

(int) The interval, specified in the number of MD steps, in between writes of samples to disk. Must be a multiple of PRODUCTION_STEPS.

TRJ_FREQUENCY

(int) The interval, specified in the number of MD steps, in between writes of trajectory frames to disk. Must be a multiple of PRODUCTION_STEPS.

TIME_STEP

(float) MD time step in ps

FRICTION_COEFF

(float) Langevin thermostat friction coefficient in 1/ps

OPENMM_PLATFORM

(str) OpenMM platform for the system preparation step. One of CPU, OpenCL, CUDA, or HIP where supported.

Alchemical Transfer Schedule Settings

LIGAND_ATOMS

(array of ints) List of the atoms indexes (starting from zero) of the ligand for an absolute binding free energy calculation.  

LIGAND1_ATOMS

LIGAND2_ATOMS 

(array of ints) List of the atoms indexes (starting from zero) of the first and second ligand for a relative binding free energy calculation.  

DISPLACEMENT

(array of 3 floats) The alchemical transfer displacement vector in angstroms. The displacement vector transfers the ligand from the binding site to a position in the solvent bulk. In the case of a relative binding free energy calculation, the second ligand is displaced from the solvent bulk to the receptor binding site by the opposite displacement.

LAMBDAS 

DIRECTION

INTERMEDIATE

LAMBDA1

LAMBDA2 

ALPHA

U0

W0COEFF

(arrays of floats) These 8 arrays, all of the same length, specify the parameters of softplus alchemical potential energy function that defines the sequence of alchemical states. See Azimi et al. (2022) LAMBDAS, LAMBDA1, LAMBDA2, DIRECTION, and INTERMEDIATE are dimensionless. The values of the other arrays are in kcal/mol.

TEMPERATURES

(array of floats) List of temperature states. Replicas are created for every possible combinations of temperature and alchemical states. Only one temperature has been tested.

UMAX 

ACORE

UBCORE

(floats) The umax, a, and u0 parameters of the softcore perturbation energy. UMAX and UBCORE are in kcal/mol, ACORE is dimensionless. See  See Azimi et al. (2022) 

Binding Site Restraint

The binding site region is defined by a flat-bottom harmonic restraint between the centroid of the ligand(s) and the centroid of a set of atoms of the receptor.

LIGAND_CM_ATOMS

(array of ints) List of the atoms indexes (starting from zero) that define the centroid of the ligand (absolute binding free energy calculation).  

LIGAND1_CM_ATOMS

LIGAND2_CM_ATOMS

(array of ints) List of the atoms indexes (starting from zero) that define the centroid of the first and second ligand (relative binding free energy calculation)

RCPT_CM_ATOMS

(array of ints) List of the atom indexes (starting from zero) that define the centroid of the receptor.   

CM_KF

(float) force constant (in kcal/(mol A^2)) of the binding site restraint.

CM_TOL

(float) Tolerance (in A) of the binding site restraint.

Ligand Alignment Restraint (RBFE)

In relative binding free energy calculations it is customary to keep the internal reference frames of the two ligands aligned by means of suitable positional and orientational restraints. See  See Azimi et al. (2022) 

ALIGN_LIGAND1_REF_ATOMS

ALIGN_LIGAND2_REF_ATOMS

(arrays of 3 ints) List of the atom indexes that define the internal coordinate frame of each ligand. These are indexes within the ligand molecule. That is, index 0 corresponds to the first atom of a molecule. 

ALIGN_KF_SEP

ALIGN_K_THETA

ALIGN_K_PSI

(floats) The force constants of the alignment restraints. ALIGN_KF_SEP is in kcal/(mol A^2), and ALIGN_K_THETA, ALIGN_K_PSI are in kcal/mol.

Other Restraints

POS_RESTRAINED_ATOMS

(array of ints) List of the indexes (starting from zero) of the atoms positionally restrained to their initial positions. 

POSRE_FORCE_CONSTANT

POSRE_TOLERANCE

(floats) Force constant (in kcal/mol/A^2) and tolerance of the positional restraint flat-bottom harmonic potential.