Experiments Header in YAML Files

The experiments header is the final object that YANK needs to run a free energy simulation. Multiple experiments can be defined in a single YAML file and each one is considered a fully defined free energy calculation.

Experiments Syntax

experiments:
  system: {UserDefinedSystem}
  protocol: {UserDefinedProtocol}
  sampler: {UserDefinedSampler}
  restraint:
    type: FlatBottom
    {Restraint Parameter}
    ...
  options:
    {Any Valid Option}
    {Any Valid Option}
    ...

This is the structure of an experiment.

It takes a {UserDefinedSystem} (see systems) and a {UserDefinedProtocol} (see protocols) to create the experiment and are the only required arguments. You can also specify any {UserDefinedSampler} (see samplers), however this is optional and will fill in with a default sampler.

The restraint is an optional keyword that applies a restraint to the ligand to keep it close to the receptor. The only required keyword is type. Valid types are: FlatBottom/Harmonic/Boresch/RMSD/PeriodicTorsionBoresch/null. If not specified, assumes null. Every restraint has his own set of optional parameters that are passed directly to the Python constructor of the restraint. See the API documentation in yank.restraints for the available parameters; you can use the links below to jump to each of individual restraint types, the keyword arguments for each restraint type are accepted as arguments in the YAML file:

The options directive lets you overwrite any global setting specified in the header options for this specific experiment.

One option is to select restrained atoms through Topgraphical Regions defined as part of your molecule’s regions. You can also select atoms through a compound region where regions are combined through set operators and/or.

Note: The Boresch-like and RMSD restraints require that the ligand and receptor are close to each other to make sure the standard state correction computation is stable. We recommend only using the Boresch, PeriodicTorsionBoresch, or RMSD, options if you know the binding mode of your system already!

Running Multiple Experiments

A single experiment can be defined by the following example. However, if one would like to run multiple experiments from the same YAML file, then follow these instructions:

  1. Create an outermost header above experiments with whatever name of experiment you want to run. We label this as {UserDefinedExperiment}.
  2. Define your {UserDefinedExperiment} by creating sub-directives just as you would in the main experiment header (se the Experiments Syntax for description).
  3. Repeat this process for as many experiments as you want.
  4. Create an experiments header below your user defined ones with the syntax: experiments: [{UserDefinedExperiment}, {UserDefinedExperiment}, ...] where the list is the experiments you defined.
  • NOTE: There are no sub-directives under the experiments header when invoked this way.

Here is an example

{UserDefinedExperiment}:
  system: {UserDefinedSystem}
  protocol: {UserDefinedProtocol}
  restraint:
    type: FlatBottom
{ASecondUserDefinedExperiment}:
  system: {UserDefinedSystem}
  protocol: {UserDefinedProtocol}
  restraint:
    type: Boresch
experiments: [{UserDefinedExperiment}, {ASecondUserDefinedExperiment}]