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: .. code-block:: yaml

{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: .. code-block:: yaml

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>