Fix docstrings, docs, and method names.

docs-source/usersguide/application.rst

@@ -1965,7 +1965,7 @@ Missing residue templates
 =========================
 
 .. CAUTION::
-   This feature is experimental, and its API is subject to change.
+   These features are experimental, and its API is subject to change.
 
 You can use the :method:`getUnmatchedResidues()` method to get a list of residues
 in the provided :code:`topology` object that do not currently have a matching
@@ -1981,12 +1981,18 @@ with residue template definitions, or identifying which additional residues need
 to be parameterized.
 
 As a convenience for parameterizing new residues, you can also get a list of
-residues and empty residue templates using :method:`getUniqueUnmatchedResidues`
+residues and empty residue templates using :method:`generateTemplatesForUnmatchedResidues`
 ::
 
     pdb = PDBFile('input.pdb')
     forcefield = ForceField('amber99sb.xml', 'tip3p.xml')
-    [residues, templates] = forcefield.getUniqueUnmatchedResidues(topology)
+    [templates, residues] = forcefield.generateTemplatesForUnmatchedResidues(topology)
+    # Se the atom types
+    for template in templates:
+        for atom in template.atoms:
+            atom.type = ... # set the atom types here
+        # Register the template with the forcefield.
+        forcefield.registerResidueTemplate(template)
 
 <HarmonicBondForce>
 ===================

wrappers/python/simtk/openmm/app/forcefield.py

@@ -602,7 +602,7 @@ class ForceField(object):
         Returns
         -------
         unmatched_residues : list of Residue
-            List of residue templates from `topology` for which no forcefield residue templates are available.
+            List of Residue objects from `topology` for which no forcefield residue templates are available.
             Note that multiple instances of the same residue appearing at different points in the topology may be returned.
 
         This method may be of use in generating missing residue templates or diagnosing parameterization failures.
@@ -620,8 +620,8 @@ class ForceField(object):
 
         return unmatched_residues
 
-    def getUniqueUnmatchedResidues(self, topology):
-        """Returns a unique list of Residue objects from specified topology for which no forcefield templates are available.
+    def generateTemplatesForUnmatchedResidues(self, topology):
+        """Generate forcefield residue templates for residues in specified topology for which no forcefield templates are available.
 
         Parameters
         ----------
@@ -630,11 +630,13 @@ class ForceField(object):
 
         Returns
         -------
-        unmatched_residues : list of Residue
-            List of residue templates from `topology` for which no forcefield residue templates are available.
-            Note that only a single instances each missing residue type will be returned.
+        templates : list of _TemplateData
+            List of forcefield residue templates corresponding to residues in `topology` for which no forcefield templates are currently available.
+            Atom types will be set to `None`, but template name, atom names, elements, and connectivity will be taken from corresponding Residue objects.
+        residues : list of Residue
+            List of Residue objects that were used to generate the templates.
+            `residues[index]` is the Residue that was used to generate the template `templates[index]`
 
-        This method may be of use in generating missing residue templates.
         """
         # Get a non-unique list of unmatched residues.
         unmatched_residues = self.getUnmatchedResidues(topology)
@@ -659,7 +661,7 @@ class ForceField(object):
                 signatures.add(signature)
                 templates.append(template)
 
-        return [unique_unmatched_residues, templates]
+        return [templates, unique_unmatched_residues]
 
     def createSystem(self, topology, nonbondedMethod=NoCutoff, nonbondedCutoff=1.0*unit.nanometer,
                      constraints=None, rigidWater=True, removeCMMotion=True, hydrogenMass=None, **args):

wrappers/python/tests/TestForceField.py

@@ -365,8 +365,8 @@ class TestForceField(unittest.TestCase):
         self.assertEqual(unmatched_residues[0].chain.id, 'X')
         self.assertEqual(unmatched_residues[0].id, '1')
 
-    def test_getUniqueUnmatchedResidues(self):
-        """Test retrieval of list of residues for which no templates are available."""
+    def test_ggenerateTemplatesForUnmatchedResidues(self):
+        """Test generation of blank forcefield residue templates for unmatched residues."""
         #
         # Test where we generate parameters for only a ligand.
         #
@@ -377,12 +377,12 @@ class TestForceField(unittest.TestCase):
         forcefield = ForceField('tip3p.xml')
         # Get list of unmatched residues.
         unmatched_residues = forcefield.getUnmatchedResidues(pdb.topology)
-        [unique_unmatched_residues, templates] = forcefield.getUniqueUnmatchedResidues(pdb.topology)
+        [templates, residues] = forcefield.generateTemplatesForUnmatchedResidues(pdb.topology)
         # Check results.
         self.assertEqual(len(unmatched_residues), 24)
-        self.assertEqual(len(unique_unmatched_residues), 2)
+        self.assertEqual(len(residues), 2)
         self.assertEqual(len(templates), 2)
-        unique_names = set([ residue.name for residue in unique_unmatched_residues ])
+        unique_names = set([ residue.name for residue in residues ])
         self.assertTrue('HOH' not in unique_names)
         self.assertTrue('NA' in unique_names)
         self.assertTrue('CL' in unique_names)
@@ -419,7 +419,7 @@ class TestForceField(unittest.TestCase):
         # Create a ForceField object.
         forcefield = ForceField('amber99sb.xml', 'tip3p.xml', StringIO(simple_ffxml_contents))
         # Get list of unique unmatched residues.
-        [residues, templates] = forcefield.getUniqueUnmatchedResidues(pdb.topology)
+        [templates, residues] = forcefield.generateTemplatesForUnmatchedResidues(pdb.topology)
         # Add residue templates to forcefield.
         for template in templates:
             # Replace atom types.