Configuration Files

Configuration files are one of the main ways AToM-OpenMM workflows are controlled. The newer tutorials use YAML files because they are readable, easy to copy between related calculations, and can be combined with system-specific settings generated by the setup scripts.

AToM-OpenMM can still read .cntl, .yaml/.yml, and .json files. Some older tutorials use *_asyncre.cntl directly; they remain useful examples, but new workflow documentation should focus on the YAML-based pattern.

Newer YAML Workflow

The newer ABFE and RBFE tutorials use this structure:

scripts/
  setup-settings.sh
  defaults.yaml
  run-atm.py
  run_template.sh
complexes/
  system-name/
    system-name.yaml
    run.sh

The roles are:

File	Role
setup-settings.sh	Lists the systems or perturbations to prepare, such as receptors, ligands, peptide pairs, mutation residues, or alignment inputs.
defaults.yaml	Stores shared simulation options used across all systems in the tutorial.
run-atm.py	Combines the shared defaults with system-specific information and generated atom selections.
system-name.yaml	The generated per-system options file written into each calculation directory.
run.sh	Launches preparation, production, and analysis for one system or perturbation.

For most edits, start with scripts/defaults.yaml. It controls the common settings shared across the calculation set. The YAML files include comments, so the file itself is often the most compact reference.

Keyword Breakdown

The tables below explain the main keywords used by the newer defaults.yaml files and the generated per-system YAML files. The YAML comments remain the quickest reminder while editing; this section adds context and notes about which workflows use each setting.

Alchemical schedule

Keyword	Meaning
TEMPERATURES	Simulation temperature list. Most examples use one temperature.
LAMBDAS	Labels the alchemical states and determines the number of replica states.
DIRECTION	Direction of each alchemical state. Positive and negative directions define the two legs of the ATM cycle.
INTERMEDIATE	Marks intermediate states, commonly around the midpoint of the alchemical path.
LAMBDA1	First softplus lambda parameter for each state.
LAMBDA2	Second softplus lambda parameter for each state.

Soft-core and bias parameters

Keyword	Meaning
ALPHA	Softplus sharpness parameter.
U0	Softplus energy offset parameter, in kcal/mol.
W0COEFF	Additive bias coefficient for each state.
UMAX	Maximum energy parameter for the soft-core binding energy, in kcal/mol.
ACORE	Dimensionless soft-core parameter.
UBCORE	Soft-core energy parameter, in kcal/mol.

Runtime and sampling

Keyword	Meaning
WALL_TIME	Requested production runtime in minutes. Keep this consistent with scheduler limits.
MAX_SAMPLES	Target maximum number of perturbation-energy samples per replica. Tutorial values are intentionally small.
CYCLE_TIME	Time interval between replica-exchange scheduling cycles, in seconds.
CHECKPOINT_TIME	Time interval between checkpoint writes, in seconds.
SUBJOBS_BUFFER_SIZE	Size of the fast execution queue, expressed as a fractional number relative to the number of GPU devices.
PRODUCTION_STEPS	Number of MD steps each replica runs per production segment.

Output frequency

Keyword	Meaning
PRNT_FREQUENCY	Interval, in MD steps, for printing replica data.
TRJ_FREQUENCY	Interval, in MD steps, for trajectory frame output.
VERBOSE	Enables more detailed output when supported by the workflow.

Dynamics and force fields

Keyword	Meaning
FRICTION_COEFF	Langevin friction coefficient.
HMASS	Hydrogen mass used for hydrogen mass repartitioning.
TIME_STEP	MD time step, in ps.
LIGAND_FORCE_FIELD	Force field used for the physical ligand.

Binding-site and positional restraints

Keyword	Meaning
RCPT_CHAIN_NAMES	Receptor chain IDs used to build the receptor frame and identify receptor atoms.
CM_KF	Force constant for the flat-bottom binding-site center-of-mass restraint, in kcal/mol/Angstrom squared.
CM_TOL	Radius/tolerance of the flat-bottom binding-site restraint, in Angstroms.
POSRE_FORCE_CONSTANT	Force constant for positional restraints, in kcal/mol/Angstrom squared.
POSRE_TOLERANCE	Radius/tolerance for positional restraints, in Angstroms.

Workflow-specific keywords

ABFE with a ghost ligand:

Keyword	Meaning
GHOST_MASS	Mass assigned to the one-atom noninteracting ghost ligand.

Small-molecule RBFE:

Keyword	Meaning
LIGAND_FORCE_FIELD	Force field used for ligands and cofactors, such as OpenFF or GAFF.
ALIGN_KF_SEP	Separation component of the ligand alignment restraint. A value of zero is used in variable-displacement examples.
ALIGN_K_THETA	Orientation component of the ligand alignment restraint.
ALIGN_K_PSI	Roll component of the ligand alignment restraint.
ALIGN_LIGAND1_REF_ATOMS	Generated reference atom indexes for ligand 1 alignment.
ALIGN_LIGAND2_REF_ATOMS	Generated reference atom indexes for ligand 2 alignment.

Protein-peptide RBFE:

Keyword	Meaning
MUTATION_RESID	Generated mutation residue identifier used to define common and variable peptide atoms.
PP_BACKBONE	Optional peptide backbone atom names used by the protein-peptide helper.
ALIGN_KF_SEP, ALIGN_K_THETA, ALIGN_K_PSI	Alignment restraint settings used by the RBFE production workflow.

System Specific keywords

These settings regulate in detail the nature of the alchemical transformations. They are usually generated automatically by the workflow scripts.

Keyword	Meaning
BASENAME	Job name used to derive input and output filenames.
WORKDIR	Calculation working directory.
DISPLACEMENT	Vector that places the second ligand, peptide, or ghost in the displaced solvent position.
LIGOFFSET	Offset used internally for ligand placement and ATM setup.
LIGAND1_ATOMS, LIGAND2_ATOMS	Atom indexes for the two alchemical partners. In ghost-ligand ABFE, ligand 2 is the ghost.
LIGAND1_VAR_ATOMS, LIGAND2_VAR_ATOMS	Variable atom indexes affected by the alchemical transformation.
LIGAND1_ATTACH_ATOM, LIGAND2_ATTACH_ATOM	Attachment atoms used for displacement and visualization helpers.
LIGAND1_CM_ATOMS, LIGAND2_CM_ATOMS	Atom indexes used to define ligand centers of mass.
RCPT_CM_ATOMS	Receptor atoms defining the binding-site center.
RCPT_FRAME_ATOMS_O, RCPT_FRAME_ATOMS_Z, RCPT_FRAME_ATOMS_Y	Receptor atom groups defining the internal receptor frame.
POS_RESTRAINED_ATOMS	Atom indexes subject to positional restraints.
EXCLUSION_POT_MOL1_INDEXES, EXCLUSION_POT_MOL2_INDEXES	Atom indexes used by the short-range exclusion potential.

Tutorial defaults are usually set for short demonstration runs. For quantitative work, increase MAX_SAMPLES, WALL_TIME, and scheduler time limits consistently.

Generated Per-System YAML

The helper workflows write a merged YAML file into each calculation directory. This file records the final options used by rbfe_structprep, rbfe_production, and related analysis calls.

When debugging, compare:

• scripts/defaults.yaml: shared settings you intended to use.
• scripts/setup-settings.sh: systems, pairs, and workflow-specific setup inputs.
• complexes/<system>/<system>.yaml: final generated options for one calculation.
• The log file: echoed runtime options and progress messages.

In general, edit defaults.yaml for shared simulation behavior and edit setup files for system lists or pair definitions. Treat generated per-system YAML files as records of a specific prepared calculation unless you are deliberately debugging or restarting that calculation.