Merge pull request #1943 from peastman/membrane

Created membrane builder

docs-source/usersguide/application.rst

@@ -1649,6 +1649,29 @@ Allowed values for :code:`positiveIon` are ``'Cs+'``, ``'K+'``, ``'Li+'``, ``'Na
 some force fields do not include parameters for all of these ion types, so you
 need to use types that are supported by your chosen force field.
 
+Adding a Membrane
+*****************
+
+If you want to simulate a membrane protein, you may need to create a membrane as
+well.  You can do this by calling :meth:`addMembrane`.  Call it *instead* of
+:meth:`addSolvent`, not in addition to it.  This one method adds the membrane,
+solvent, and ions all at once, making sure the lipid head groups are properly
+solvated.  For example, this creates a POPC membrane, ensuring at least 1 nm of
+padding on all sides:
+::
+
+    modeller.addMembrane(forcefield, lipidType='POPC', minimumPadding=1*nanometer)
+
+The membrane is added in the XY plane, and the existing protein is assumed to already be oriented
+and positioned correctly.  When possible, it is recommended to start with a model
+from the `Orientations of Proteins in Membranes`_ (OPM) database.  Otherwise, it
+is up to you to select the protein position yourself.
+
+Because this method also adds solvent, it takes many of the same arguments as
+:meth:`addSolvent`.  See the API documentation for details.
+
+.. _`Orientations of Proteins in Membranes`: http://opm.phar.umich.edu
+
 .. _adding-or-removing-extra-particles:
 
 Adding or Removing Extra Particles

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

@@ -113,7 +113,8 @@ class Topology(object):
         return len(self._chains)
 
     def getNumBonds(self):
-        """Return the number of bonds in the Topology."""
+        """Return the number of bonds in the Topology.
+        """
         return len(self._bonds)
 
     def addChain(self, id=None):

wrappers/python/tests/TestModeller.py

@@ -3,6 +3,7 @@ from validateModeller import *
 from simtk.openmm.app import *
 from simtk.openmm import *
 from simtk.unit import *
+from collections import defaultdict
 if sys.version_info >= (3, 0):
     from io import StringIO
 else:
@@ -1075,6 +1076,31 @@ class TestModeller(unittest.TestCase):
                 expectedDist = 0.09 if j == 0 else 0.147
                 self.assertTrue(dist > (expectedDist-0.01)*nanometers and dist < (expectedDist+0.01)*nanometers)
 
+
+    def test_addMembrane(self):
+        """Test adding a membrane."""
+        pdb = PDBFile('systems/alanine-dipeptide-implicit.pdb')
+        modeller = Modeller(pdb.topology, pdb.positions)
+        ff = ForceField('amber14-all.xml', 'amber14/tip3p.xml')
+
+        # Add a membrane around alanine dipeptide???  I know, it's a silly thing to do,
+        # but it's fast, and all we care about is whether it works!
+
+        modeller.addMembrane(ff, minimumPadding=0.5*nanometers, ionicStrength=1*molar)
+        resCount = defaultdict(int)
+        for res in modeller.topology.residues():
+            resCount[res.name] += 1
+        self.assertTrue(resCount['POP'] > 1)
+        self.assertTrue(resCount['HOH'] > 1)
+        self.assertTrue(resCount['CL'] > 1)
+        self.assertEqual(resCount['CL'], resCount['NA'])
+        self.assertEqual(1, resCount['ALA'])
+        originalSize = max(pdb.positions) - min(pdb.positions)
+        newSize = modeller.topology.getUnitCellDimensions()
+        for i in range(3):
+            self.assertTrue(newSize[i] >= originalSize[i]+0.5*nanometers)
+
+
     def assertVecAlmostEqual(self, p1, p2, tol=1e-7):
         scale = max(1.0, norm(p1),)
         for i in range(3):