Options for YAML files

These are all the simulation, alchemy, and file I/O options controlled by the options header in the YAML files for YANK. We have subdivided the categories below, but all settings on this page go under the options header in the YAML file:

Besides the options listed in General Options that can be specified exclusively in the options section of the YAML script, everything else can go either in options as a general setting, or in experiments.options. In the latter case, an option can be expanded combinatorially with the !Combinatorial tag.


General Options:

verbose

options:
  verbose: no

Turn on/off verbose output.

Valid Options: [no]/yes

resume_setup

options:
  resume_setup: no

Choose to resume a setup procedure. YANK will raise an error when it detects that it will overwrite an existing file in the directory specified by setup_dir.

Valid Options: [no]/yes

resume_simulation

options:
  resume_simulation: no

Choose to resume simulations. YANK will raise an error when it detects that it will overwrite an existing file in the directory specified by experiments_dir.

Valid Options: [no]/yes

output_dir

options:
  output_dir: output

The main output folder of YANK simulations. A folder will be created if none exists. Path is relative to the YAML script path

Valid Options (output): <Path String>

setup_dir

options:
  setup_dir: setup

The folder where all generate simulation setup files are stored. A folder will be created if none exists. Path is relative to the output_dir folder.

Valid Options (setup): <Path String>

experiments_dir

options:
  experiments_dir: experiments

The folder where all generate simulation setup files are stored. A folder will be created if none exists. Path is relative to to the output_dir folder.

Valid Options (experiments): <Path String>

platform

options:
  platform: fastest

The OpenMM platform used to run the calculations. The default value (fastest) automatically selects the fastest available platform. Some platforms (especially CUDA and OpenCL) may not be available on all systems.

Valid options: [fastest]/CUDA/OpenCL/CPU/Reference

precision

options:
  precision: auto

Floating point precision to use during the simulation. It can be set for OpenCL and CUDA platforms only. The default value (auto) is equivalent to mixed when the device support this precision, and single otherwise.

Valid options: [auto]/double/mixed/single

switch_experiment_interval

options:
  switch_experiments_interval: 0

When running multiple experiments using the !Combinatorial tag, this allows to switch between experiments every switch_experiments_interval iterations, and gather data about multiple molecules/conditions before completing the specified number_of_iterations. If 0, YANK will complete the combinatorial calculations sequentially.

Valid options (0): <Integer>

processes_per_experiment

options:
  processes_per_experiment: null

When running YANK on multiple processes with MPI, you can run several experiments in parallel by using this option to allocate a given number of processes to each experiment. If null, the experiments are performed one after the other on all the available MPI processes.

Valid options (null): null / <Integer>

System and Simulation Preparation:

randomize_ligand

options:
  randomize_ligand: no

Randomize the position of the ligand before starting the simulation. Only works in Implicit Solvent. The ligand will be randomly rotated and displaced by a vector with magnitude proportional to randomize_ligand_sigma_multiplier with the constraint of being at a distance greater than randomize_ligand_close_cutoff from the receptor.

Valid options: [no]/yes

randomize_ligand_sigma_multiplier

options:
  randomize_ligand_sigma_multiplier: 2.0

See randomize_ligand.

Valid options (2.0): <float>

randomize_ligand_close_cutoff

options:
  randomize_ligand_close_cutoff: 1.5 * angstrom

See randomize_ligand.

Valid options (1.5 * angstrom): <Quantity Length> [1]

temperature

options:
  temperature: 298 * kelvin

Temperature of the system.

Valid options (298 * kelvin): <Quantity Temperature> [1]

pressure

options:
  pressure: 1.0 * atmosphere

Pressure of the system. If set to null, the simulation samples as an NVT ensemble.

Valid options (1 * atmosphere): null / <Quantity Pressure> [1]

integrator_splitting

options:
  integrator_splitting: V R O R V

Sequence of “R”, “V”, “O” (and optionally “{”, “}”, “V0”, “V1”, ...) sub-steps to be executed each timestep with a space between each step. Tells the integrator how to subdivide the work of taking a full timestep, with optional HMC moves. For example: V R O R V is a BAOAB Integrator If you don’t want a splitting integrator, specify null to get a standard Langevin integrator. For more details, see the OpenMMTools documentation.

Valid options (V R O R V): <String of R, V, O, {, and/or }; white space ” ” delimiter>/null

hydrogen_mass

options:
  hydrogen_mass: 1.0 * amu

Hydrogen mass for HMR simulations.

Valid options (1*amu): <Quantity Mass> [1]

constraints

options:
  constraints: HBonds

Constrain bond lengths and angles. See OpenMM createSystem() documentation for more details.

Valid options: [Hbonds]/AllBonds/HAngles

anisotropic_dispersion_cutoff

options:
  anisotropic_dispersion_cutoff: auto

Tell YANK to compute anisotropic dispersion corrections for long-range interactions. YANK accounts for these effects by creating two additional thermodynamic states at either end of the thermodynamic cycle with larger long-range cutoffs to remove errors introduced from treating long-range interactions as a homogeneous, equal density medium. We estimate the free energy relative to these expanded cutoff states. No simulation is actually carried out at these states but energies from simulations are evaluated at them.

This option only applies if you have specified a system with periodic boundary conditions.

We put this option in the general options category instead of the solvents section since these additional states are unique to YANK’s setup.

The size of the expanded cutoff distance can be set in a few ways through this option. If auto the cutoff will be set to 0.99*min_box_size/2 if no barostat is in use or 0.8*min_box_size/2 if one is in use (to account for box size fluctuations), with min_box_size denoting the norm of the smallest OpenMM box vector defining the initial triclinic cell volume.

Valid options: [auto]/null/<Quantity Length> [1]


Simulation Parameters

switch_phase_interval

options:
  switch_phase_interval: 0

This allows to switch the simulation between the two phases of the calculation every switch_phase_interval iterations. If 0, YANK will exhaust the number_of_iterations iterations of the first phase before switching to the second one.

Valid options (0): <Integer>

minimize

options:
  minimize: yes

Minimize the input configuration before starting simulation. Highly recommended if a pre-minimized structure is provided, or if explicit solvent generation is left to YANK.

Valid Options: [yes]/no

minimize_max_iterations

options:
  minimize_max_iterations: 0

Set the maximum number of iterations the energy minimization process attempts to converge to given tolerance energy. 0 steps indicate unlimited.

Valid Options (0): <Integer>

minimize_tolerance

options:
  minimize_tolerance: 1.0 * kilojoules_per_mole / nanometers

Set the tolerance of the energy minimization process. System is considered minimized when the energy does not change by the given tolerance in subsequent iterations.

Valid Options (1.0 * kilojoules_per_mole / nanometers): <Quantity (Molar Energy)/(Length)> [1]

number_of_equilibration_iterations

options:
  number_of_equilibration_iterations: 1

Number of iterations used for equilibration before production run. Iterations written to file are post-equilibration.

Valid Options (1): <Integer>

equilibration_timestep

options:
  equilibration_timestep: 1.0 * femtosecond

Timestep of the equilibration timestep (not production).

Valid Options (1.0 * femtosecond): <Quantity Time> [1]

number_of_iterations

options:
  number_of_iterations: 1

Number of iterations for production simulation. Note: If resume_simulation is set, this option can be used to extend previous simulations past their original number of iterations.

Specifying 0 will run through the setup, create all the simulation files, store all options, and minimize the initial configurations (if specified), but will not run any production simulations.

Set this to null to run an unlimited number of iterations. The simulation will not stop unless some other criteria is stops it. We strongly recommend specifying either online free energy analysis and/or a phase switching interval to ensure there is at least some stop criteria, and all phases yield some samples.

Valid Options (1): <Integer> or null

nsteps_per_iteration

options:
  nsteps_per_iteration: 500

Number of timesteps between each iteration. We highly recommend using a number greater than 1 to improve decorrelation between iterations. Hamiltonian Replica Exchange swaps are attempted after each iteration.

Valid Options (500): <Integer>

timestep

options:
  timestep: 2.0 * femtosecond

Timestep of Langevin Dynamics production runs.

Valid Options (2.0 * femtosecond): <Quantity Time> [1]

checkpoint_interval

options:
  checkpoint_interval: 10

Specify how frequently checkpoint information should be saved to file relative to iterations. YANK simulations can be resumed only from checkpoints, so if something crashes, up to checkpoint_interval worth of iterations will be lost and YANK will resume from the most recent checkpoint.

This option helps control write-to-disk time and file sizes. The fewer times a checkpoint is written, the less of both you will get. If you want to write a checkpoint every iteration, set this to 1.

Checkpoint information includes things like full coordinates and box vectors, as well as more static information such as metadata, simulation options, and serialized thermodynamic states.

Valid Options (10): <Integer >= 1>

replica_mixing_scheme

options:
  replica_mixing_scheme: swap-all

Specifies how the Hamiltonian Replica Exchange attempts swaps between replicas. swap-all will attempt to exchange every state with every other state. swap-neighbors will attempt only exchanges between adjacent states. If null is specified, no mixing is done, and effectively disables all replica exchange functionality.

Valid Options: [swap-all]/swap-neighbors/null

collision_rate

options:
  collision_rate: 5.0 / picosecond

The collision rate used for Langevin dynamics. Default quantity of 5.0 / picosecond works well for explicit solvent. Implicit solvent will require a different collision rate, e.g. 91 / picosecond works well for TIP3P water.

Collision rates (or friction coefficients) appear in the Langevin dynamics equation as either inverse time, or one over some time constant, \(1/\tau\). When comparing collision rates, double check if the collision rate is in units of inverse time, or just time. For example: a collision rate of 5.0/ps -> \(\tau = 0.2 \, ps\).

Valid Options (5.0 / picosecond): <Quantity Inverse Time> [1]

constraint_tolerance

options:
  constraint_tolerance: 1.0e-6

Relative tolerance on the constraints of the system.

Valid Options (1.0e-6): <Scientific Notation Float>

mc_displacement_sigma

options:
  mc_displacement_sigma: 10.0 * angstroms

YANK will augment Langevin dynamics with MC moves rotating and displacing the ligand. This parameter controls the size of the displacement

Valid Options (10 * angstroms): <Quantity Length> [1]


Alchemy Parameters

annihilate_electrostatics

options:
  annihilate_electrostatics: yes

Annihilate electrostatics rather than decouple them. This means that ligand-ligand (alchemical-alchemical) nonbonded electrostatics will be turned off as well as ligand-nonligand nonbonded electrostatics.

Valid Options: [yes]/no

annihilate_sterics

options:
  annihilate_sterics: no

Annihilate sterics (Lennad-Jones or Halgren potential) rather than decouple them. This means that ligand-ligand (alchemical-alchemical) nonbonded sterics will be turned off as well as ligand-nonligand nonbonded sterics. WARNING: Do not set this option if annihilate_electrostatics is “no”.

Valid Options: [no]/yes

Steric Alchemical Options

options:
  softcore_alpha: 0.5
  softcore_a: 1
  softcore_b: 1
  softcore_c: 6

The options that control the soft core energy function for decoupling/annihilating steric interactions. Setting softcore_alpha = 0 with softcore_a = 1 gives linear scaling of the Lennard-Jones energy function.

Valid Options for softcore_alpha (0.5): <Float>

Valid Options for softcore_[a,b,c] (1,1,6): <Integer preferred, Float accepted>

Electrostatic Alchemical Options

options:
  softcore_beta: 0.0
  softcore_d: 1
  softcore_e: 1
  softcore_f: 2

The options that control the soft core energy functnon for decoupling/annihilating electrostatic interactions. Setting softcore_beta = 0 with softcore_d = 1 gives linear scaling of Coulomb’s law.

Valid Options for softcore_beta (0.0): <Float>

Valid Options for softcore_[d,e,f] (1,1,2): <Integer preferred, Float accepted>

[1](1, 2, 3, 4, 5, 6, 7, 8, 9, 10) Quantity strings are of the format: <float> * <unit> where <unit> is any valid unit specified in the “Valid Options” for an option. e.g. “<Quantity Length>” indicates any measure of length may be used for <unit> such as nanometer or angstrom. Compound units are also parsed such as kilogram / meter**3 for density. Only full unit names as they appear in the simtk.unit package (part of OpenMM) are allowed; so “nm” and “A” will be rejected.

Online Analysis Parameters

YANK also supports an online free energy analysis framework which allows running simulations up to some target error in the free energy. Note that this will pause the simulation to run this analysis. The longer the simulation gets, the slower this process becomes.

online_analysis_interval

options:
   online_analysis_interval: 100

Both the toggle and iteration count between online analysis operations. Every interval, the Multistate Bennet Acceptance Ratio estimate for the free energy is calculated and the error is computed. Some data is preserved each iteration to speed up future calculations, but this operation will still slow down as more iterations are added. We recommend choosing an interval of at least 100, if not more.

If set to null (default), then online analysis is not run.

Valid Options (null): null or <Int >= 1>

online_analysis_target_error

options:
   online_analysis_target_error: 1.0

The target error for the online analysis measured in kT per phase. Once the free energy is at or below this value, the phase will be considered complete. This value should be a number greater than 0, even though 0 is a valid option. The error free energy estimate between states is never zero except in very rare cases, so your simulation may never converge if you set this to 0.

If online_analysis_interval is null, this option does nothing.

Valid Options (0.2): <Float >= 0>

online_analysis_minimum_iterations

options:
   online_analysis_minimum_iterations: 50

Number of iterations that are skipped at the beginning of the simulation before online analysis is attempted. This is a speed option since most of the initial iterations will be either equilibration or under sampled. We recommend choosing an initial number that is at least one or two online_analysis_interval‘s for speed’s sake.

The first iteration at which online analysis is performed is not affected by this number and always tracked as the modulo of the current iteration. E.g. if you have online_analysis_interval: 100 and online_analysis_minimum_iterations: 150, online analysis would happen at iteration 200 first, not iteration 250.

If online_analysis_interval is null, this option does nothing.

Valid Options (50): <Int >=1>