Cooking with Yank Start

Yank/experiment.py

@@ -580,8 +580,8 @@ class ExperimentBuilder(object):
     # These are options that can be specified only in the main "options" section.
     GENERAL_DEFAULT_OPTIONS = {
         'verbose': False,
-        'resume_setup': False,
-        'resume_simulation': False,
+        'resume_setup': True,
+        'resume_simulation': True,
         'output_dir': 'output',
         'setup_dir': 'setup',
         'experiments_dir': 'experiments',

Yank/tests/test_experiment.py

@@ -2753,6 +2753,7 @@ def test_run_experiment():
 
         # We setup a molecule and with resume_setup: now we can't do the experiment
         err_msg = ''
+        exp_builder._options['resume_setup'] = False
         exp_builder._db._setup_molecules('p-xylene')
         try:
             exp_builder.run_experiments()
@@ -2799,6 +2800,7 @@ def test_run_experiment():
                 assert yaml.load(f) == [['complex', 1], ['solvent', -1]]
 
         # Now we can't run the experiment again with resume_simulation: no
+        exp_builder._options['resume_simulation'] = False
         try:
             exp_builder.run_experiments()
         except YamlParseError as e:
@@ -2868,6 +2870,8 @@ def test_automatic_alchemical_path():
         yaml_script['protocols']['hydration-protocol']['solvent2']['alchemical_path'] = 'auto'
         yaml_script['experiments']['system'] = 'hydration-system'
         yaml_script['experiments']['protocol'] = 'hydration-protocol'
+        yaml_script['options']['resume_setup'] = False
+        yaml_script['options']['resume_simulation'] = False
 
         exp_builder = ExperimentBuilder(yaml_script)
 

docs/_templates/layout.html

@@ -2,4 +2,9 @@
 
 {% set script_files = script_files + ['_static/toggle_sections.js'] %}
 
-{% set css_files = css_files + ["_static/custom.css"] %}
+{% set css_files = css_files + ["_static/custom.css"] %}
+
+{# replace below block hashes with % to activate #}
+{% if 'cook' in pagename %}
+{% set logo = 'cookingyank2.png' %}
+{% endif %}

docs/index.rst

@@ -50,6 +50,7 @@ Getting YANK Up and Running
    installation
    running
    yamlpages/index
+   yank-yaml-cookbook/index
    whatsnew
    examples/index
    faq

docs/yamlpages/options.rst

@@ -40,6 +40,9 @@ Turn on/off verbose output.
 
 Valid Options: [no]/yes
 
+Recommended Recipes:
+
+* :ref:`yaml_cookbook_basics_npt`
 
 
 
@@ -53,14 +56,16 @@ Valid Options: [no]/yes
 .. code-block:: yaml
 
    options:
-     resume_setup: no
+     resume_setup: yes
 
-Choose to resume a setup procedure. YANK will raise an error when it detects that it will overwrite an existing file in
-the directory specified by :ref:`setup_dir <yaml_options_setup_dir>`.
+Choose to resume a setup procedure. If ``no``, YANK will raise an error when it detects that it will overwrite an
+existing file in the directory specified by :ref:`setup_dir <yaml_options_setup_dir>`.
 
-Valid Options: [no]/yes
+Valid Options: [yes]/no
 
+Recommended Recipes:
 
+* :ref:`yaml_cookbook_basics_paths`
 
 
 .. _yaml_options_resume_simulation:
@@ -72,14 +77,16 @@ Valid Options: [no]/yes
 .. code-block:: yaml
 
    options:
-     resume_simulation: no
+     resume_simulation: yes
 
-Choose to resume simulations. YANK will raise an error when it detects that it will overwrite an existing file in the
-directory specified by :ref:`experiments_dir <yaml_options_experiments_dir>`.
+Choose to resume simulations. If ``no``, YANK will raise an error when it detects that it will overwrite an existing
+file in the directory specified by :ref:`experiments_dir <yaml_options_experiments_dir>`.
 
-Valid Options: [no]/yes
+Valid Options: [yes]/no
 
+Recommended Recipes:
 
+* :ref:`yaml_cookbook_basics_paths`
 
 
 
@@ -98,7 +105,9 @@ The main output folder of YANK simulations. A folder will be created if none exi
 
 Valid Options (output): <Path String>
 
+Recommended Recipes:
 
+* :ref:`yaml_cookbook_basics_paths`
 
 
 .. _yaml_options_setup_dir:
@@ -117,7 +126,9 @@ Path is relative to the :ref:`output_dir <yaml_options_output_dir>` folder.
 
 Valid Options (setup): <Path String>
 
+Recommended Recipes:
 
+* :ref:`yaml_cookbook_basics_paths`
 
 
 .. _yaml_options_experiments_dir:
@@ -136,7 +147,9 @@ relative to to the :ref:`output_dir <yaml_options_output_dir>` folder.
 
 Valid Options (experiments): <Path String>
 
+Recommended Recipes:
 
+* :ref:`yaml_cookbook_basics_paths`
 
 
 .. _yaml_options_platform:

docs/yank-yaml-cookbook/cookingbasics/cookingnpt.rst

@@ -0,0 +1,17 @@
+.. _yaml_cookbook_basics_npt:
+
+Basic NPT Simulation Recipe
+***************************
+
+This recipe shows a stock NPT setup in the :ref:`yaml-options-head`. We will run the simulations at
+1 atmosphere and 300 Kelvin.
+
+NPT simulations by their nature are run with periodic boundary conditions, so they
+support explicit solvent, which we will also set. For this recipe, we choose the Particle Mesh Ewald (PME) nonbonded
+method which works well with periodic systems and explicit solvents.
+
+Here in the NPT, we also turn verbosity on to see if everything gets setup correctly. For your run, you may choose
+to turn it off.
+
+.. literalinclude:: raw_cooking_basics/rawnpt.yaml
+   :language: yaml

docs/yank-yaml-cookbook/cookingbasics/cookingnvt.rst

@@ -0,0 +1,20 @@
+.. _yaml_cookbook_basics_nvt:
+
+Basic NVT Simulation Recipe
+***************************
+
+This recipe shows a stock NVT setup in the :ref:`yaml-options-head`. We will run the simulations at 300 Kelvin.
+
+NVT simulations by their nature are NOT periodic, so the the molecules can drift in an infinite medium. The coordinates
+for this systems are often re-centered to prevent the numerical value of their positions from drifting into infinite.
+However, this process takes the center of mass of the whole system and shifts it. If you have multiple molecules (e.g.
+waters) which can drift apart, you can quickly find your system drifting into vapor phase with molecules so far
+away that no useful statistics can be gathered. Because of this, only implicit solvent should be simulated under
+these conditions.
+
+For this recipe, we choose the Generalized Born (GB) model augmented with the hydrophobic solvent accessible surface
+area (SA) model; GBSA for short. This model has several implementations and we have selected the
+Onufriev-Bashford-Case variant 2 model (``OBC2``).
+
+.. literalinclude:: raw_cooking_basics/rawnvt.yaml
+   :language: yaml

docs/yank-yaml-cookbook/cookingbasics/cookingpaths.rst

@@ -0,0 +1,29 @@
+.. _yaml_cookbook_basics_paths:
+
+Basic Path Manipulation Recipe
+******************************
+
+Sometimes you may want to output your setup and simulation results in another place. This can happen on clusters and
+shared directories where there may be a common repository of directories where the YAML script lives, but the work
+directory or drive is located elsewhere.
+
+This recipe manipulates the output directories for a YANK setup and simulation. Normally, the default options are
+chosen and these don't have to be set.
+
+There are two flavors here. The first assumes the YAML script is in a directory which can be written to and has
+the space to store the YANK experiments. The second is a very uncommon recipe where a central molecule setup directory
+is used. This is extremely uncommon but for similar experiments may be helpful. Because the default settings of these
+options exist, in most cases, you will likely never use these recipes.
+
+.. note::
+
+    The ``output_dir`` path is *relative* to the *YAML file location*, but the other paths are relative to
+    ``output_dir`` Keep this in mind when setting paths.
+    Absolute paths, however, are always respected.
+
+
+.. literalinclude:: raw_cooking_basics/rawpathscommon.yaml
+   :language: yaml
+
+.. literalinclude:: raw_cooking_basics/rawpathsrare.yaml
+   :language: yaml

docs/yank-yaml-cookbook/cookingbasics/index.rst

@@ -0,0 +1,17 @@
+.. _yaml_cookbook_basics:
+
+Basics Blocks for YANK YAML
+***************************
+
+This chapter covers some of the basic blocks and stocks for YANK's YAML files. These will serve as the foundation
+for the more specific blocks later on. They will serve as mix and match (even though some options may overwrite others)
+for all the concrete recipes used later.
+
+----
+
+.. toctree::
+   :maxdepth: 2
+
+   cookingnpt
+   cookingnvt
+   cookingpaths

docs/yank-yaml-cookbook/cookingbasics/raw_cooking_basics/rawnpt.yaml

@@ -0,0 +1,16 @@
+options:
+  verbose: yes
+  resume_setup: yes
+  resume_simulation: yes
+  pressure: 1*atmosphere
+  temperature: 300*kelvin
+
+solvents:
+  explicit_water:  # This can be called whatever you want
+    nonbonded_method: PME
+    switch_distance: 11*angstroms
+    nonbonded_cutoff: 12*angstroms
+    ewald_error_tolerance: 1.0e-4
+    clearance: 9*angstroms
+    positive_ion: Na+
+    negative_ion: Cl-

docs/yank-yaml-cookbook/cookingbasics/raw_cooking_basics/rawnvt.yaml

@@ -0,0 +1,11 @@
+options:
+  verbose: no
+  resume_setup: yes
+  resume_simulation: yes
+  pressure: null  # Null indicates no pressure control.
+  temperature: 300*kelvin
+
+solvents:
+  GBSA:  # This can be called whatever you want
+    nonbonded_method: NoCutoff
+    implicit_solvent: OBC2 # Onufriev-Bashford-Case GBSA model, name is related to Implicit solvents in OpenMM

docs/yank-yaml-cookbook/cookingbasics/raw_cooking_basics/rawpathscommon.yaml

@@ -0,0 +1,6 @@
+# A much more common recipe
+options:
+  resume_setup: yes
+  resume_experiment: yes
+  # Sets output directory to this folder name relative to this script
+  output_dir: kinase_sims

docs/yank-yaml-cookbook/cookingbasics/raw_cooking_basics/rawpathsrare.yaml

@@ -0,0 +1,9 @@
+# An uncommon recipe
+options:
+  resume_setup: yes  # Because we are using some common repository of molecules/systems
+  resume_experiment: no  # Do NOT try to use any existing experiment folder (not recommended)
+  output_dir: /data/mygroup/me/yank_simulations/kinase_sims
+  # Absolute path, no relativity
+  setup_dir: /data/mygroup/me/yank_simulations/molecule_repository  # This assumes some common setup (very uncommon)
+  # Relative to the output_dir
+  experiments_dir: experiments  # This is the default so setting this with "experiments" is the same as omitting this key

docs/yank-yaml-cookbook/index.rst

@@ -0,0 +1,76 @@
+.. _yaml_cookbook_head:
+
+Cookbook for YAML Options
+*************************
+
+Having all the options laid out in front of you is good for advanced users, but sometimes practical examples are much more helpful.
+Here you can find the YANK YAML Cookbook: A handy guide to making your
+A series of examples that may help you understanding how to put together the options and settings found on the
+:ref:`main YAML pages <yaml_head>`.
+
+There are a few things to keep in mind with these recipes:
+
+* Arbitrary named keys (such as the YANK name for the ``molecules``) will be given example concrete values
+* Paths are all examples and will not reflect your path structure, replaces as needed unless explicitly stated the
+  entry is to be taken literally.
+
+----
+
+.. toctree::
+   :maxdepth: 2
+
+   cookingbasics/index
+   cookingbinding
+   cookinghydration
+
+
+
+Dont worry about this area down here, I'm keeping it for notes purposes, it will all get deleted in final draft
+
+* :doc:`options <options>`
+
+
+    * :ref:`setup_dir <yaml_options_setup_dir>`
+    * :ref:`experiments_dir <yaml_options_experiments_dir>`
+    * :ref:`platform <yaml_options_platform>`
+    * :ref:`precision <yaml_options_precision>`
+    * :ref:`max_n_contexts <yaml_options_max_n_contexts>`
+    * :ref:`switch_experiment_interval <yaml_options_switch_experiment_interval>`
+    * :ref:`processes_per_experiment <yaml_options_processes_per_experiment>`
+
+
+    * :ref:`randomize_ligand <yaml_options_randomize_ligand>`
+    * :ref:`randomize_ligand_sigma_multiplier <yaml_options_randomize_ligand_sigma_multiplier>`
+    * :ref:`randomize_ligand_close_cutoff <yaml_options_ligand_close_cutoff>`
+    * :ref:`hydrogen_mass <yaml_options_hydrogen_mass>`
+    * :ref:`constraints <yaml_options_constraints>`
+
+
+    * :ref:`switch_phase_interval <yaml_options_switch_phase_interval>`
+    * :ref:`minimize <yaml_options_minimize>`
+    * :ref:`minimize_max_iterations <yaml_options_minimize_max_iterations>`
+    * :ref:`minimize_tolerance <yaml_options_minimize_tolerance>`
+    * :ref:`number_of_equilibration_iterations <yaml_options_number_of_equilibration_iterations>`
+    * :ref:`equilibration_timestep <yaml_options_equilibration_timestep>`
+    * :ref:`default_number_of_iterations <yaml_options_default_number_of_iterations>`
+    * :ref:`default_nsteps_per_iteration <yaml_options_default_nsteps_per_iteration>`
+    * :ref:`default_timestep <yaml_options_default_timestep>`
+    * :ref:`checkpoint_interval <yaml_options_checkpoint_interval>`
+    * :ref:`store_solute_trajectory <yaml_options_store_solute_trajectory>`
+    * :ref:`constraint_tolerance <yaml_options_constraint_tolerance>`
+    * :ref:`yaml_options_anisotropic_dispersion_cutoff`
+
+
+    * :ref:`annihilate_electrostatics <yaml_options_annihilate_electrostatics>`
+    * :ref:`annihilate_sterics <yaml_options_annihilate_sterics>`
+    * :ref:`softcore_alpha <yaml_options_alchemical_sterics>`
+    * :ref:`softcore_beta <yaml_options_alchemical_electrostatics>`
+    * :ref:`softcore_a <yaml_options_alchemical_sterics>`
+    * :ref:`softcore_b <yaml_options_alchemical_sterics>`
+    * :ref:`softcore_c <yaml_options_alchemical_sterics>`
+    * :ref:`softcore_d <yaml_options_alchemical_electrostatics>`
+    * :ref:`softcore_e <yaml_options_alchemical_electrostatics>`
+    * :ref:`softcore_f <yaml_options_alchemical_electrostatics>`
+    * :ref:`alchemical_pme_treatment <yaml_options_alchemical_pme_treatment>`
+    * :ref:`disable_alchemical_dispersion_correction <yaml_options_disable_alchemical_dispersion_correction>`
+    * :ref:`split_alchemical_forces <yaml_options_split_alchemical_forces>`