Lots of improvements to Python API documentation

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

@@ -21,6 +21,7 @@ from dcdfile import DCDFile
 from dcdreporter import DCDReporter
 from modeller import Modeller
 from statedatareporter import StateDataReporter
+from element import Element
 
 # Enumerated values
 

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

@@ -56,9 +56,12 @@ class AmberInpcrdFile(object):
         """
         results = amber_file_parser.readAmberCoordinates(file, read_velocities=loadVelocities, read_box=loadBoxVectors)
         if loadVelocities:
+            ## The atom positions read from the inpcrd file
             self.positions = results[0]
             if loadBoxVectors:
+                ## The periodic box vectors read from the inpcrd file
                 self.boxVectors = results[1]
+                ## The atom velocities read from the inpcrd file
                 self.velocities = results[2]
             else:
                 self.velocities = results[1]

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

@@ -52,12 +52,13 @@ class AmberPrmtopFile(object):
     def __init__(self, file):
         """Load a prmtop file."""
         top = Topology()
+        ## The Topology read from the prmtop file
         self.topology = top
         
         # Load the prmtop file
         
         prmtop = amber_file_parser.PrmtopLoader(file)
-        self.prmtop = prmtop
+        self._prmtop = prmtop
 
         # Add atoms to the topology
 
@@ -132,7 +133,7 @@ class AmberPrmtopFile(object):
                      ff.PME:'PME'}
         if nonbondedMethod not in methodMap:
             raise ValueError('Illegal value for nonbonded method')
-        if not self.prmtop.getIfBox() and nonbondedMethod in (ff.CutoffPeriodic, ff.Ewald, ff.PME):
+        if not self._prmtop.getIfBox() and nonbondedMethod in (ff.CutoffPeriodic, ff.Ewald, ff.PME):
             raise ValueError('Illegal nonbonded method for a non-periodic system')
         if nonbondedMethod == ff.NoCutoff:
             nonbondedCutoff = None
@@ -158,7 +159,7 @@ class AmberPrmtopFile(object):
             implicitString = 'GBn'
         else:
             raise ValueError('Illegal value for implicit solvent model')
-        sys = amber_file_parser.readAmberSystem(prmtop_loader=self.prmtop, shake=constraintString, nonbondedCutoff=nonbondedCutoff,
+        sys = amber_file_parser.readAmberSystem(prmtop_loader=self._prmtop, shake=constraintString, nonbondedCutoff=nonbondedCutoff,
                                                  nonbondedMethod=methodMap[nonbondedMethod], flexibleConstraints=False, gbmodel=implicitString,
                                                  soluteDielectric=soluteDielectric, solventDielectric=solventDielectric, rigidWater=rigidWater)
         if removeCMMotion:

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

@@ -38,7 +38,7 @@ from simtk.unit import nanometer
 class DCDReporter(object):
     """DCDReporter outputs a series of frames from a Simulation to a DCD file.
     
-    To use it, create a DCDReporter, than add it to the Simulation's list of reporters.
+    To use it, create a DCDReporter, then add it to the Simulation's list of reporters.
     """
     
     def __init__(self, file, reportInterval):

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

@@ -37,22 +37,38 @@ __version__ = "1.0"
 from simtk.unit import daltons
 
 class Element:
-    elements_by_symbol = {}
+    """An Element represents a chemical element.
+    
+    The simtk.openmm.app.element module contains objects for all the standard chemical elements,
+    such as element.hydrogen or element.carbon.  You can also call the static method Element.getBySymbol() to
+    look up the Element with a particular chemical symbol."""
+
+    _elements_by_symbol = {}
     
     def __init__(self, number, name, symbol, mass):
+        ## The atomic number of the element
         self.atomic_number = number
+        ## The name of the element
         self.name = name
+        ## The chemical symbol of the element
         self.symbol = symbol
+        ## The atomic mass of the element
         self.mass = mass
         # Index this element in a global table
         s = symbol.strip().upper()
-        assert s not in Element.elements_by_symbol
-        Element.elements_by_symbol[s] = self
+        assert s not in Element._elements_by_symbol
+        Element._elements_by_symbol[s] = self
 
+    @staticmethod
+    def getBySymbol(symbol):
+        """Get the Element with a particular chemical symbol."""
+        s = symbol.strip().upper()
+        return Element._elements_by_symbol[s]
 
+# This is for backward compatibility.
 def get_by_symbol(symbol):
     s = symbol.strip().upper()
-    return Element.elements_by_symbol[s]
+    return Element._elements_by_symbol[s]
 
 
 hydrogen =       Element(  1, "hydrogen", "H", 1.007947*daltons)

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

@@ -65,7 +65,7 @@ class ForceField(object):
         """Load one or more XML files and create a ForceField object based on them.
         
         Parameters:
-         - A list of XML files defining the force field.  Each entry may be an absolute file path, a path relative to the
+         - files A list of XML files defining the force field.  Each entry may be an absolute file path, a path relative to the
            current working directory, or a path relative to this module's data subdirectory (for built in force fields).
         """
         self._atomTypes = {}
@@ -251,7 +251,7 @@ class ForceField(object):
            Allowed values are None, HBonds, AllBonds, or HAngles.
          - rigidWater (boolean=True) If true, water molecules will be fully rigid regardless of the value passed for the constraints argument
          - removeCMMotion (boolean=True) If true, a CMMotionRemover will be added to the System
-         - - Arbitrary additional keyword arguments may also be specified.  This allows extra parameters to be specified that are specific to
+         - args Arbitrary additional keyword arguments may also be specified.  This allows extra parameters to be specified that are specific to
            particular force fields.
         Returns: the newly created System
         """

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

@@ -63,9 +63,11 @@ class Modeller(object):
          - topology (Topology) the initial Topology of the model
          - positions (list) the initial atomic positions
         """
+        ## The Topology describing the structure of the system
         self.topology = topology
         if not is_quantity(positions):
             positions = positions*nanometers
+        ## The list of atom positions
         self.positions = positions
         
     def getTopology(self):

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

@@ -65,6 +65,7 @@ class PDBFile(object):
         """
         top = Topology()
         coords = [];
+        ## The Topology read from the PDB file
         self.topology = top
         
         # Load the PDB file
@@ -119,6 +120,7 @@ class PDBFile(object):
                     atomByNumber[atom.serial_number] = newAtom
                     pos = atom.get_position().value_in_unit(nanometers)
                     coords.append(Vec3(pos[0], pos[1], pos[2]))
+        ## The atom positions read from the PDB file
         self.positions = coords*nanometers
         self.topology.setUnitCellDimensions(pdb.get_unit_cell_dimensions())
         self.topology.createStandardBonds()

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

@@ -37,7 +37,7 @@ from simtk.openmm.app import PDBFile
 class PDBReporter(object):
     """PDBReporter outputs a series of frames from a Simulation to a PDB file.
     
-    To use it, create a PDBReporter, than add it to the Simulation's list of reporters.
+    To use it, create a PDBReporter, then add it to the Simulation's list of reporters.
     """
     
     def __init__(self, file, reportInterval):

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

@@ -53,19 +53,25 @@ class Simulation(object):
         """Create a Simulation.
         
         Parameters:
-         - topology (Topology) A Topology describing the the system to simulation
+         - topology (Topology) A Topology describing the the system to simulate
          - system (System) The OpenMM System object to simulate
          - integrator (Integrator) The OpenMM Integrator to use for simulating the System
          - platform (Platform=None) If not None, the OpenMM Platform to use
          - platformProperties (map=None) If not None, a set of platform-specific properties to pass
            to the Context's constructor
         """
+        ## The Topology describing the system being simulated
         self.topology = topology
+        ## The System being simulated
         self.system = system
+        ## The Integrator used to advance the simulation
         self.integrator = integrator
+        ## The index of the current time step
         self.currentStep = 0
+        ## A list of reporters to invoke during the simulation
         self.reporters = []
         if platform is None:
+            ## The Context containing the current state of the simulation
             self.context = mm.Context(system, integrator)
         elif platformProperties is None:
             self.context = mm.Context(system, integrator, platform)

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

@@ -49,12 +49,12 @@ class StateDataReporter(object):
         Parameters:
          - file (string or file) The file to write to, specified as a file name or file object
          - reportInterval (int) The interval (in time steps) at which to write frames
-         - step (boolean=True) Whether to write the current step index to the file
-         - time (boolean=True) Whether to write the current time to the file
+         - step (boolean=False) Whether to write the current step index to the file
+         - time (boolean=False) Whether to write the current time to the file
          - potentialEnergy (boolean=False) Whether to write the potential energy to the file
          - kineticEnergy (boolean=False) Whether to write the kinetic energy to the file
          - totalEnergy (boolean=False) Whether to write the total energy to the file
-         - temperature(boolean=False) Whether to write the instantaneous temperature to the file
+         - temperature (boolean=False) Whether to write the instantaneous temperature to the file
          - volume (boolean=False) Whether to write the periodic box volume to the file
          - density (boolean=False) Whether to write the system density to the file
          - separator (string=',') The separator to use between columns in the file

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

@@ -205,9 +205,12 @@ class Topology(object):
                     self.addBond(sg1, sg2)
 
 class Chain(object):
+    """A Chain object represents a chain within a Topology."""
     def __init__(self, index, topology):
         """Construct a new Chain.  You should call addChain() on the Topology instead of calling this directly."""
+        ## The index of the Chain within its Topology
         self.index = index
+        ## The Topology this Chain belongs to
         self.topology = topology
         self._residues = []
     
@@ -222,10 +225,14 @@ class Chain(object):
                 yield atom
 
 class Residue(object):
+    """A Residue object represents a residue within a Topology."""
     def __init__(self, name, index, chain):
         """Construct a new Residue.  You should call addResidue() on the Topology instead of calling this directly."""
+        ## The name of the Residue
         self.name = name
+        ## The index of the Residue within its Topology
         self.index = index
+        ## The Chain this Residue belongs to
         self.chain = chain
         self._atoms = []
     
@@ -234,10 +241,16 @@ class Residue(object):
         return iter(self._atoms)
 
 class Atom(object):
+    """An Atom object represents a residue within a Topology."""
+    
     def __init__(self, name, element, index, residue):
         """Construct a new Atom.  You should call addAtom() on the Topology instead of calling this directly."""
+        ## The name of the Atom
         self.name = name
+        ## That Atom's element
         self.element = element
+        ## The index of the Atom within its Topology
         self.index = index
+        ## The Residue this Atom belongs to
         self.residue = residue