Protocols Header for YAML Files

The protocols header tells YANK which alchemical thermodynamic path to draw samples along. Together with a system, this header makes a complete experiment.

Just like in molecules, protocols can have arbitrary, user defined names. In the examples, these user defined names are marked as {UserDefinedProtocol}.

Protocols Syntax

protocols:
  {UserDefinedProtocol}:
    {PhaseName1}:
      alchemical_path:
        lambda_electrostatics: [1.00, 0.75, 0.50, 0.25, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00]
        lambda_sterics:        [1.00, 1.00, 1.00, 1.00, 1.00, 0.95, 0.90, 0.85, 0.80, 0.75, 0.70, 0.65, 0.60, 0.50, 0.40, 0.30, 0.20, 0.10, 0.00]
    {PhaseName2}:
      alchemical_path:
        lambda_electrostatics: [1.00, 0.75, 0.50, 0.25, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00]
        lambda_sterics:        [1.00, 1.00, 1.00, 1.00, 1.00, 0.95, 0.90, 0.85, 0.80, 0.75, 0.70, 0.65, 0.60, 0.50, 0.40, 0.30, 0.20, 0.10, 0.00]

This is the only valid format for the protocols header (unless restraints are specified) and consists of multiple parts which we break down here.

The {PhaseName1} and {PhaseName2} headers are system dependent headers. The {UserDefinedSystem and {UserDefinedProtocol} are combined in the experiements header to make on object. Each {PhaseNameX} in the {UserDefinedProtocol} must match with the expected type of system created. Below is the recommended mappings of each {PhaseNameX}:

More generally, the {PhaseNameX} only has to contain the keyword for the system you expect. For instance, in the Ligand/Receptor case, the following would also be a valid structure:

{UserDefinedProtocol}:
  RICKsolventROLL:
    alchemical_path: ..
  my_complex_phase:
    alchemical_path: ..

Where RICKsolventROLL would correspond to the solvent phase since it contains the phrase “solvent”, and my_complex_phase would correspond to the complex phase for the same reason.

If you want to name them whatever you would like and instead rely on the which sign is used for the free energy evaluation, you can invoke {UserDefinedProtocol}: !Ordered to make the first entry the + sign and the second - sign in the free energy difference. Here is an example:

absolute-binding: !Ordered
  plus_sign_phase:
    alchemical_path: ...
  minus_sign_phase:
    alchemical_path: ...

alchemical_path, lambda_electrostatics, lambda_sterics, and lambda_restraints

The lambda_electrostatics, lambda_sterics, and lambda_restraints directives define the alchemical states that YANK will sample at. Each directive accepts an equal sized list of floats as arguments and each index of the list corresponds to what value of lambda those interactions will be controlled by at that state. The index can be thought of as the column if the lists were stacked as a 2D array, and the state is fully described by the column, not a single row by itself.

Syntax is identical to the example above.

Only lambda_restraints are optional and do not need to be specified for each phase and system. Further, the directive only applies if restraint in experiments is specified. How and where the lambda_restraints should be will be up to the user. To see use cases of this directive, please see any of the following:

Valid Arguments: <Identical Sized List of Floats>/auto

Automatic Path Determination

protocols:
  {UserDefinedProtocol}:
    {PhaseName1}:
      alchemical_path: auto

YANK can automatically determine the parameters for lambda_X for you. YANK will distribute states between the fully coupled and fully decoupled states for you based on the restraint scheme, class of transformation, and input system. States are distributed such that the standard deviation of potential energy differences between the states is equal, which should improve replica mixing between the states over placing the states yourself.

Specifying the option auto for your alchemical_path will start the process as shown in the example. The process may take a while, but the final path is saved as a new .yaml file in your output_dir/experiments, and immediately used as the input for your simulation.

temperature and pressure

It is possible to vary temperature and pressure along the alchemical path, but the end states must have the same values. The number of window must be identical to the other lambda variables. A short example:

Valid Arguments: <List of Quantities>

Protocols How-To Video