.. _yaml_protocols_head:

Protocols Header for YAML Files
*******************************

The ``protocols`` header tells YANK which alchemical thermodynamic path to draw samples along. Together with a :doc:`system <systems>`, this header makes a complete :doc:`experiment <experiments>`.

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


----


.. _yaml_protocols_example:

Protocols Syntax
================
.. code-block:: yaml

   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 :ref:`restraints are specified <yaml_protocols_alchemical_path>`)
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}``:

* :ref:`Ligand/Receptor Free Energies Setup by YANK <yaml_systems_receptor_ligand>`

  * ``{PhaseName1}`` -> ``complex``
  * ``{PhaseName2}`` -> ``solvent``

* :ref:`Hydration Free Energies Setup by YANK <yaml_systems_hydration>`

  * ``{PhaseName1}`` -> ``solvent1``
  * ``{PhaseName2}`` -> ``solvent2``

* :ref:`Arbitrary Phase Free Energies Setup by User <yaml_systems_user_defined>`

  * ``{PhaseName1}`` -> ``phase1``
  * ``{PhaseName2}`` -> ``phase2``

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: ...


.. _yaml_protocols_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`` :ref:`in experiments is specified <yaml_experiments_syntax>`. 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:

* :ref:`The Harmonic restraint in our detailed binding free energy tutorial <p-xylene-explicit>`
* :ref:`The FlatBottom restraint in our host-guest binding free energy tutorial <host_guest_implicit>`
* `The Boresh restraint in our YANK GitHub Examples <https://github.com/choderalab/yank-examples/tree/master/examples/binding/abl-imatinib>`_

Valid Arguments: <Identical Sized List of Floats>