Merge pull request #1099 from choderalab/tutorial

Add YAML syntax tutorial and fix MC atoms

Yank/experiment.py

@@ -1305,6 +1305,10 @@ def _validate_molecules(cls, molecules_description):
                     required: yes
                     type: string
                     nullable: yes
+                net_charge:
+                    required: no
+                    type: integer
+                    nullable: yes
         select:
             required: no
             dependencies: filepath
@@ -1342,15 +1346,6 @@ def _validate_molecules(cls, molecules_description):
         modeller:
             required: no
             dependencies: filepath
-        openeye:
-            required: no
-            excludes: filepath
-        antechamber:
-            required: no
-            excludes: filepath
-        epik:
-            required: no
-            excludes: filepath
         """
         peptide_schema = {**yaml.load(peptide_schema_yaml), **common_molecules_schema}
 
@@ -2902,7 +2897,8 @@ def _create_experiment_sampler(self, experiment_description, default_mc_atoms):
         if mcmc_move_id is None:
             mcmc_move = self._create_default_mcmc_move(experiment_description, default_mc_atoms)
         else:
-            mcmc_move = schema.call_mcmc_move_constructor(self._mcmc_moves[mcmc_move_id])
+            mcmc_move = schema.call_mcmc_move_constructor(self._mcmc_moves[mcmc_move_id],
+                                                          atom_subset=default_mc_atoms)
         constructor_description['mcmc_moves'] = mcmc_move
         # Create the sampler.
         return schema.call_sampler_constructor(constructor_description)

Yank/pipeline.py

@@ -1674,8 +1674,13 @@ def _setup_molecules(self, *args):
                                                       residue_name=residue_name)
 
                     utils.Mol2File(mol2_file_path).round_charge()  # normalize charges
-                    net_charge = None  # we don't need Epik's net charge
+                    # We don't need Epik's or input net charge as antechamber will
+                    # infer the net charge from the sum of the OpenEye charges.
+                    net_charge = None
                     mol_descr['filepath'] = mol2_file_path
+                # Check if use specified a net_charge, but don't overwrite Epik's protonation state.
+                elif net_charge is not None:
+                    net_charge = mol_descr['antechamber'].get('net_charge', None)
 
                 # Generate parameters
                 charge_method = mol_descr['antechamber']['charge_method']

Yank/schema/validator.py

@@ -175,7 +175,7 @@ def _check_type_keyword(constructor_description):
 
 
 def call_constructor(parent_cls, constructor_description, special_conversions=None,
-                     convert_quantity_strings=False):
+                     convert_quantity_strings=False, **default_kwargs):
     """Convert the constructor representation into an object.
 
     Parameters
@@ -192,6 +192,8 @@ def call_constructor(parent_cls, constructor_description, special_conversions=No
         If True, all the string constructor values are attempted to be
         converted to quantities before creating the object (default is
         False).
+    **default_kwargs
+        Overwrite the default value of the constructor keyword arguments.
 
     Returns
     -------
@@ -221,8 +223,15 @@ def call_constructor(parent_cls, constructor_description, special_conversions=No
     except ValueError as e:
         raise RuntimeError(str(e))
 
-    # Validate init keyword arguments.
+    # Read the keyword arguments of the constructor.
     constructor_kwargs = utils.get_keyword_args(subcls.__init__, try_mro_from_class=subcls)
+
+    # Overwrite eventual keyword arguments.
+    for k, v in default_kwargs.items():
+        if k in constructor_kwargs and k not in constructor_description:
+            constructor_description[k] = v
+
+    # Validate init keyword arguments.
     try:
         constructor_kwargs = utils.validate_parameters(
             parameters=constructor_description, template_parameters=constructor_kwargs,
@@ -256,7 +265,27 @@ def call_restraint_constructor(constructor_description):
                             convert_quantity_strings=True)
 
 
-def call_mcmc_move_constructor(constructor_description):
+def call_mcmc_move_constructor(constructor_description, **default_kwargs):
+    """Create an MCMCMove from a dict representation of the constructor parameters.
+
+    Parameters
+    ----------
+    constructor_description : dict
+        A dict containing the keyword ``'type'`` to indicate the class
+        of the MCMCMove and all the keyword arguments to pass to its
+        constructor. If ``'type'`` is ``'SequenceMove'``, the ``'move_list'``
+        keyword should be a list of dict representations of the single
+        moves.
+    **default_kwargs
+        Overwrite the the default keyword argument of the MCMCMove constructor
+        or, if a ``SequenceMove`` is instantiated, the constructors of the move
+        list.
+
+    Returns
+    -------
+    mcmc_move : openmmtools.mcmc.MCMCMove
+        The intantiation of the ``MCMCMove`` object.
+    """
     # Check if this is a sequence of moves and we need to unnest the constructors.
     # If we end up with other nested constructors, we'll probably need a general strategy.
     _check_type_keyword(constructor_description)
@@ -273,7 +302,7 @@ def call_mcmc_move_constructor(constructor_description):
     moves = []
     for mcmc_move_constructor in mcmc_moves_constructors:
         moves.append(call_constructor(mmtools.mcmc.MCMCMove, mcmc_move_constructor,
-                                      convert_quantity_strings=True))
+                                      convert_quantity_strings=True, **default_kwargs))
     if is_sequence_move:
         return mmtools.mcmc.SequenceMove(move_list=moves)
     return moves[0]

docs/index.rst

@@ -29,6 +29,7 @@ Features
 Get going
 ---------
 * `Get YANK up and running now <quickstart.html>`_
+* `Read the YAML syntax tutorial <tutorial.html>`_
 
 Get involved
 ------------
@@ -44,21 +45,22 @@ Getting YANK Up and Running
 ---------------------------
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    quickstart
    installation
+   tutorial
    running
    yamlpages/index
-   whatsnew
    examples/index
    faq
+   whatsnew
 
 The Science Behind YANK
 -----------------------
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    theory
    algorithms