Experiment

Tools to build Yank experiments from a YAML configuration file.

This is not something that should be normally invoked by the user, and instead created by going through the Command Line Interface with the yank script command.

yank.experiment.get_openmm_nonbonded_methods_strings()

Get the list of valid OpenMM Nonbonded methods YANK can process

Returns:valid_methods : list of str

yank.experiment.get_openmm_implicit_nb_method_strings()

Get the subset of nonbonded method strings which work for implicit solvent

Returns:valid_methods : list of str

yank.experiment.get_openmm_explicit_nb_method_strings()

Get the subset of nonbonded method strings which work for explicit solvent

Returns:valid_methods : list of str

yank.experiment.to_openmm_app(input_string)

Converter function to be used with yank.utils.validate_parameters().

Parameters:

input_string : str

Method name of openmm.app to fetch

Returns:

method : Method of openmm.app

Returns openmm.app.{input_string}

yank.experiment.convert_if_quantity(value)

Try to convert a passed value to quantity

Parameters:

value : int, float, or simtk.unit.Quantity as string

This function tries to take a string which can be converted to a quantity with the yank.utils.quantity_from_string(), or just a number

Returns:

output : value or simtk.unit.Quantity

Returns either the Quantity which was converted from string, or the original value.

exception yank.experiment.YamlParseError(message)

Represent errors occurring during parsing of Yank YAML file.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class yank.experiment.YankLoader(*args, **kwargs)

PyYAML Loader that recognized !Combinatorial nodes and load OrderedDicts.

static combinatorial_constructor(loader, node)

Constructor for YAML !Combinatorial entries.

static ordered_constructor(loader, node)

Constructor for YAML !Ordered tag.

class yank.experiment.YankDumper(*args, **kwargs)

PyYAML Dumper that always return sequences in flow style and maps in block style.

static combinatorial_representer(dumper, data)

YAML representer CombinatorialLeaf nodes.

static ordered_representer(dumper, data)

YAML representer OrderedDict nodes.

class yank.experiment.AlchemicalPhaseFactory(sampler, thermodynamic_state, sampler_states, topography, protocol, storage, restraint=None, alchemical_regions=None, alchemical_factory=None, metadata=None, **options)

YANK simulation phase entirely contained as one object.

Creates a full phase to simulate, expects Replica Exchange simulation for now.

Parameters:

sampler : yank.repex.ReplicaExchange

Sampler which will carry out the simulation

thermodynamic_state : openmmtools.states.ThermodynamicState

Reference thermodynamic state without any alchemical modifications

sampler_states : openmmtools.states.SamplerState

Sampler state to initialize from, including the positions of the atoms

topography : yank.yank.Topography

Topography defining the ligand atoms and other atoms

protocol : dict of lists

Alchemical protocol to create states from.

Format should be {parameter_name : parameter_values}

where parameter_name is the name of the specific alchemical parameter (e.g. lambda_sterics), and parameter_values is a list of values for that parameter where each entry is one state.

Each of the parameter_values lists for every parameter_name should be the same length.

storage : yank.repex.Reporter or str

Reporter object to use, or file path to create the reporter at Will be a yank.repex.Reporter internally if str is given

restraint : yank.restraint.ReceptorLigandRestraint or None, Optional, Default: None

Optional restraint to apply to the system

alchemical_regions : openmmtools.alchemy.AlchemicalRegion or None, Optional, Default: None

Alchemical regions which define which atoms to modify.

alchemical_factory : openmmtools.alchemy.AbsoluteAlchemicalFactory, Optional, Default: None

Alchemical factory with which to create the alchemical system with if you don’t want to use all the previously defined options. This is passed on to yank.yank.AlchemicalPhase

metadata : dict

Additional metdata to pass on to yank.yank.AlchemicalPhase

options : dict

Additional options to setup the rest of the process. See the DEFAULT_OPTIONS for this class in the source code or look at the options header for the YAML options.

create_alchemical_phase()

Create the alchemical phase based on all the options

This only creates it, but does nothing else to prepare for simulations. The initialize_alchemical_phase will actually minimize, randomize ligand, and/or equilibrate if requested.

Returns:alchemical_phase : yank.yank.AlchemicalPhase

See also

initialize_alchemical_phase

initialize_alchemical_phase()

Create and set all the initial options for the alchemical phase

This minimizes, randomizes_ligand, and equilibrates the alchemical_phase on top of creating it, if the various options are set

Returns:alchemical_phase : yank.yank.AlchemicalPhase

class yank.experiment.Experiment(phases, number_of_iterations, switch_phase_interval)

An experiment built by ExperimentBuilder.

This is a completely defined experiment with all parameters and settings ready to go.

It is highly recommended to NOT use this class directly, and instead rely on the ExperimentBuilder class to parse all options, configure all phases, properly set up the experiments, and even run them.

These experiments are frequently created with the ExperimentBuilder.build_experiments() method.

Parameters:

phases : list of yank.yank.AlchemicalPhases

Phases to run for the experiment

number_of_iterations : int or infinity

Total number of iterations each phase will be run for. Both float('inf') and numpy.inf are accepted for infinity.

switch_phase_interval : int

Number of iterations each phase will be run before the cycling to the next phase

See also

ExperimentBuilder

Attributes

iteration

pair of int, Current total number of iterations which have been run for each phase.

iteration

pair of int, Current total number of iterations which have been run for each phase.

run(n_iterations=None)

Run the experiment

Runs until either the maximum number of iterations have been reached or the sampler for that phase reports its own completion (e.g. online analysis)

Parameters:

n_iterations : int or None, Optional, Default: None

Optional parameter to run for a finite number of iterations instead of up to the maximum number of iterations.

class yank.experiment.ExperimentBuilder(script=None, job_id=None, n_jobs=None)

Parse YAML configuration file and build the experiment.

The relative paths indicated in the script are assumed to be relative to the script directory. However, if ExperimentBuilder is initiated with a string rather than a file path, the paths will be relative to the user’s working directory.

The class firstly perform a dry run to check if this is going to overwrite some files and raises an exception if it finds already existing output folders unless the options resume_setup or resume_simulation are True.

Parameters:

script : str or dict

A path to the YAML script or the YAML content. If not specified, you can load it later by using parse() (default is None).

job_id : None or int

If you want to split the experiments among different executions, you can set this to an integer 1 <= job_id <= n_jobs, and this ExperimentBuilder will run only 1/n_jobs of the experiments.

n_jobs : None or int

If job_id is specified, this is the total number of jobs that you are running in parallel from your script.

See also

Experiment

Examples

>>> import textwrap
>>> import openmmtools as mmtools
>>> import yank.utils
>>> setup_dir = yank.utils.get_data_filename(os.path.join('..', 'examples',
...                                          'p-xylene-implicit', 'input'))
>>> pxylene_path = os.path.join(setup_dir, 'p-xylene.mol2')
>>> lysozyme_path = os.path.join(setup_dir, '181L-pdbfixer.pdb')
>>> with mmtools.utils.temporary_directory() as tmp_dir:
...     yaml_content = '''
...     ---
...     options:
...       number_of_iterations: 1
...       output_dir: {}
...     molecules:
...       T4lysozyme:
...         filepath: {}
...       p-xylene:
...         filepath: {}
...         antechamber:
...           charge_method: bcc
...     solvents:
...       vacuum:
...         nonbonded_method: NoCutoff
...     systems:
...         my_system:
...             receptor: T4lysozyme
...             ligand: p-xylene
...             solvent: vacuum
...             leap:
...               parameters: [leaprc.gaff, leaprc.ff14SB]
...     protocols:
...       absolute-binding:
...         complex:
...           alchemical_path:
...             lambda_electrostatics: [1.0, 0.9, 0.8, 0.6, 0.4, 0.2, 0.0]
...             lambda_sterics: [1.0, 0.9, 0.8, 0.6, 0.4, 0.2, 0.0]
...         solvent:
...           alchemical_path:
...             lambda_electrostatics: [1.0, 0.8, 0.6, 0.3, 0.0]
...             lambda_sterics: [1.0, 0.8, 0.6, 0.3, 0.0]
...     experiments:
...       system: my_system
...       protocol: absolute-binding
...     '''.format(tmp_dir, lysozyme_path, pxylene_path)
>>> yaml_builder = ExperimentBuilder(textwrap.dedent(yaml_content))
>>> yaml_builder.run_experiments()

update_yaml(script)

Update the current yaml content and reparse it

Parameters:

script : str or dict

String which accepts multiple forms of YAML content that is one of the following:

File path to the YAML file

String containing all the YAML data

Dict of yaml content you wish to replace

See also

utils.update_nested_dict

parse(script)

Parse the given YAML configuration file.

Validate the syntax and load the script into memory. This does not build the actual experiment.

Parameters:

script : str or dict

A path to the YAML script or the YAML content.

Raises:

YamlParseError

If the input YAML script is syntactically incorrect.

run_experiments()

Set up and run all the Yank experiments.

See also

Experiment

build_experiments()

Generator to configure, build, and yield an experiment

Yields:Experiment

setup_experiments()

Set up all systems required for the Yank experiments without running them.

status()

Iterate over the status of all experiments in dictionary form.

The status of each experiment is set to “completed” if both phases in the experiments have been completed, “pending” if they are both pending, and “ongoing” otherwise.

Yields:

experiment_status : namedtuple

The status of the experiment. It contains the following fields:

name : str

The name of the experiment.

status : str

One between “completed”, “ongoing”, or “pending”.

number_of_iterations : int

The total number of iteration set for this experiment.

job_id : int or None

If njobs is specified, this includes the job id associated to this experiment.

phases : dict

phases[phase_name] is a namedtuple describing the status of phase phase_name. The namedtuple has two fields: iteration and status.

verbose

bool: the log verbosity.

output_dir

The path to the main output directory.

setup_dir

The path to the setup files directory relative to the output folder..