Improve docstrings

Swigged python docstrings now include documented return values and type
information or their arguments. They are generated in numpydoc format.
Furthermore, all of the Python app layer docstrings have been changed
to numpydoc format. The filterPythonFiles.py script which helps to
generate the Doxygen Python API docs has been updated to reflect these
changes.

openmmapi/include/openmm/System.h

@@ -44,19 +44,19 @@ class OPENMM_EXPORT VirtualSite;
 /**
  * This class represents a molecular system.  The definition of a System involves
  * four elements:
- * 
+ *
  * <ol>
  * <li>The set of particles in the system</li>
  * <li>The forces acting on them</li>
  * <li>Pairs of particles whose separation should be constrained to a fixed value</li>
  * <li>For periodic systems, the dimensions of the periodic box</li>
  * </ol>
- * 
+ *
  * The particles and constraints are defined directly by the System object, while
  * forces are defined by objects that extend the Force class.  After creating a
  * System, call addParticle() once for each particle, addConstraint() for each constraint,
  * and addForce() for each Force.
- * 
+ *
  * In addition, particles may be designated as "virtual sites".  These are particles
  * whose positions are computed automatically based on the positions of other particles.
  * To define a virtual site, call setVirtualSite(), passing in a VirtualSite object
@@ -94,7 +94,7 @@ public:
      * the particle and not modify its position or velocity.  This is most often
      * used for virtual sites, but can also be used as a way to prevent a particle
      * from moving.
-     * 
+     *
      * @param index the index of the particle for which to get the mass
      */
     double getParticleMass(int index) const;
@@ -103,7 +103,7 @@ public:
      * the particle and not modify its position or velocity.  This is most often
      * used for virtual sites, but can also be used as a way to prevent a particle
      * from moving.
-     * 
+     *
      * @param index  the index of the particle for which to set the mass
      * @param mass   the mass of the particle
      */
@@ -120,7 +120,7 @@ public:
     void setVirtualSite(int index, VirtualSite* virtualSite);
     /**
      * Get whether a particle is a VirtualSite.
-     * 
+     *
      * @param index  the index of the particle to check
      */
     bool isVirtualSite(int index) const {
@@ -129,7 +129,7 @@ public:
     /**
      * Get VirtualSite object for a particle.  If the particle is not a virtual
      * site, this throws an exception.
-     * 
+     *
      * @param index  the index of the particle to get
      */
     const VirtualSite& getVirtualSite(int index) const;
@@ -151,17 +151,17 @@ public:
     int addConstraint(int particle1, int particle2, double distance);
     /**
      * Get the parameters defining a distance constraint.
-     * 
+     *
      * @param index     the index of the constraint for which to get parameters
-     * @param particle1 the index of the first particle involved in the constraint
-     * @param particle2 the index of the second particle involved in the constraint
-     * @param distance  the required distance between the two particles, measured in nm
+     * @param[out] particle1 the index of the first particle involved in the constraint
+     * @param[out] particle2 the index of the second particle involved in the constraint
+     * @param[out] distance  the required distance between the two particles, measured in nm
      */
     void getConstraintParameters(int index, int& particle1, int& particle2, double& distance) const;
     /**
      * Set the parameters defining a distance constraint.  Particles whose mass is 0 cannot participate
      * in constraints.
-     * 
+     *
      * @param index     the index of the constraint for which to set parameters
      * @param particle1 the index of the first particle involved in the constraint
      * @param particle2 the index of the second particle involved in the constraint
@@ -170,7 +170,7 @@ public:
     void setConstraintParameters(int index, int particle1, int particle2, double distance);
     /**
      * Remove a constraint from the System.
-     * 
+     *
      * @param index    the index of the constraint to remove
      */
     void removeConstraint(int index);
@@ -194,7 +194,7 @@ public:
     }
     /**
      * Get a const reference to one of the Forces in this System.
-     * 
+     *
      * @param index  the index of the Force to get
      */
     const Force& getForce(int index) const;
@@ -216,9 +216,9 @@ public:
      * created Context will have its box vectors set to these.  They will affect
      * any Force added to the System that uses periodic boundary conditions.
      *
-     * @param a      on exit, this contains the vector defining the first edge of the periodic box
-     * @param b      on exit, this contains the vector defining the second edge of the periodic box
-     * @param c      on exit, this contains the vector defining the third edge of the periodic box
+     * @param[out] a     the vector defining the first edge of the periodic box
+     * @param[out] b     the vector defining the second edge of the periodic box
+     * @param[out] c     the vector defining the third edge of the periodic box
      */
     void getDefaultPeriodicBoxVectors(Vec3& a, Vec3& b, Vec3& c) const;
     /**

plugins/amoeba/openmmapi/include/openmm/AmoebaAngleForce.h

@@ -128,20 +128,20 @@ public:
      * @param particle2     the index of the second particle connected by the angle
      * @param particle3     the index of the third particle connected by the angle
      * @param length        the equilibrium angle, measured in degrees
-     * @param quadratic k   the quadratic force constant for the angle, measured in kJ/mol/radian^2
-     * @return the index of the angle that was added
+     * @param quadraticK    the quadratic force constant for the angle, measured in kJ/mol/radian^2
+     * @return              the index of the angle that was added
      */
     int addAngle(int particle1, int particle2, int particle3, double length, double quadraticK);
 
     /**
      * Get the force field parameters for an angle term.
      * 
-     * @param index         the index of the angle for which to get parameters
-     * @param particle1     the index of the first particle connected by the angle
-     * @param particle2     the index of the second particle connected by the angle
-     * @param particle3     the index of the third particle connected by the angle
-     * @param length        the equilibrium angle, measured in degrees
-     * @param quadratic k   the quadratic force constant for the angle, measured in kJ/mol/radian^2
+     * @param index              the index of the angle for which to get parameters
+     * @param[out] particle1     the index of the first particle connected by the angle
+     * @param[out] particle2     the index of the second particle connected by the angle
+     * @param[out] particle3     the index of the third particle connected by the angle
+     * @param[out] length        the equilibrium angle, measured in degrees
+     * @param[out] quadraticK    the quadratic force constant for the angle, measured in kJ/mol/radian^2
      */
     void getAngleParameters(int index, int& particle1, int& particle2, int& particle3, double& length, double& quadraticK) const;
 
@@ -153,7 +153,7 @@ public:
      * @param particle2     the index of the second particle connected by the angle
      * @param particle3     the index of the third particle connected by the angle
      * @param length        the equilibrium angle, measured in degrees
-     * @param quadratic k   the quadratic force constant for the angle, measured in kJ/mol/radian^2
+     * @param quadraticK    the quadratic force constant for the angle, measured in kJ/mol/radian^2
      */
     void setAngleParameters(int index, int particle1, int particle2, int particle3, double length, double quadraticK);
     /**

plugins/amoeba/openmmapi/include/openmm/AmoebaBondForce.h

@@ -100,7 +100,7 @@ public:
      * @param particle1     the index of the first particle connected by the bond
      * @param particle2     the index of the second particle connected by the bond
      * @param length        the equilibrium length of the bond, measured in nm
-     * @param k             the quadratic force constant for the bond
+     * @param quadraticK    the quadratic force constant for the bond
      * @return the index of the bond that was added
      */
 
@@ -109,11 +109,11 @@ public:
     /**
      * Get the force field parameters for a bond term.
      * 
-     * @param index         the index of the bond for which to get parameters
-     * @param particle1     the index of the first particle connected by the bond
-     * @param particle2     the index of the second particle connected by the bond
-     * @param length        the equilibrium length of the bond, measured in nm
-     * @param quadratic k   the quadratic force constant for the bond
+     * @param index              the index of the bond for which to get parameters
+     * @param[out] particle1     the index of the first particle connected by the bond
+     * @param[out] particle2     the index of the second particle connected by the bond
+     * @param[out] length        the equilibrium length of the bond, measured in nm
+     * @param[out] quadraticK    the quadratic force constant for the bond
      */
 
     void getBondParameters(int index, int& particle1, int& particle2, double& length, double& quadraticK) const;
@@ -121,11 +121,11 @@ public:
     /**
      * Set the force field parameters for a bond term.
      * 
-     * @param index     the index of the bond for which to set parameters
-     * @param particle1 the index of the first particle connected by the bond
-     * @param particle2 the index of the second particle connected by the bond
-     * @param length    the equilibrium length of the bond, measured in nm
-     * @param k         the quadratic force constant for the bond
+     * @param index       the index of the bond for which to set parameters
+     * @param particle1   the index of the first particle connected by the bond
+     * @param particle2   the index of the second particle connected by the bond
+     * @param length      the equilibrium length of the bond, measured in nm
+     * @param quadraticK  the quadratic force constant for the bond
      */
     void setBondParameters(int index, int particle1, int particle2, double length, double quadraticK);
     /**

plugins/amoeba/openmmapi/include/openmm/AmoebaGeneralizedKirkwoodForce.h

@@ -79,10 +79,10 @@ public:
     /**
      * Get the force field parameters for a particle.
      * 
-     * @param index          the index of the particle for which to get parameters
-     * @param charge         the charge of the particle, measured in units of the proton charge
-     * @param radius         the atomic radius of the particle, measured in nm
-     * @param scalingFactor  the scaling factor for the particle
+     * @param      index          the index of the particle for which to get parameters
+     * @param[out] charge         the charge of the particle, measured in units of the proton charge
+     * @param[out] radius         the atomic radius of the particle, measured in nm
+     * @param[out] scalingFactor  the scaling factor for the particle
      */
     void getParticleParameters(int index, double& charge, double& radius, double& scalingFactor) const;
 

plugins/amoeba/openmmapi/include/openmm/AmoebaInPlaneAngleForce.h

@@ -129,7 +129,7 @@ public:
      * @param particle3     the index of the third particle connected by the angle
      * @param particle4     the index of the fourth particle connected by the angle
      * @param length        the equilibrium angle, measured in radians
-     * @param quadratic k   the quadratic force constant for the angle measured in kJ/mol/radian^2
+     * @param quadraticK    the quadratic force constant for the angle measured in kJ/mol/radian^2
      * @return the index of the angle that was added
      */
     int addAngle(int particle1, int particle2, int particle3, int particle4, double length, 
@@ -138,13 +138,13 @@ public:
     /**
      * Get the force field parameters for an angle term.
      * 
-     * @param index         the index of the angle for which to get parameters
-     * @param particle1     the index of the first particle connected by the angle
-     * @param particle2     the index of the second particle connected by the angle
-     * @param particle3     the index of the third particle connected by the angle
-     * @param particle4     the index of the fourth particle connected by the angle
-     * @param length        the equilibrium angle, measured in radians
-     * @param quadratic k   the quadratic force constant for the angle measured in kJ/mol/radian^2
+     * @param index              the index of the angle for which to get parameters
+     * @param[out] particle1     the index of the first particle connected by the angle
+     * @param[out] particle2     the index of the second particle connected by the angle
+     * @param[out] particle3     the index of the third particle connected by the angle
+     * @param[out] particle4     the index of the fourth particle connected by the angle
+     * @param[out] length        the equilibrium angle, measured in radians
+     * @param[out] quadraticK    the quadratic force constant for the angle measured in kJ/mol/radian^2
      */
     void getAngleParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, double& length,
                             double& quadraticK) const;
@@ -158,7 +158,7 @@ public:
      * @param particle3     the index of the third particle connected by the angle
      * @param particle4     the index of the fourth particle connected by the angle
      * @param length        the equilibrium angle, measured in radians
-     * @param quadratic k   the quadratic force constant for the angle, measured in kJ/mol/radian^2
+     * @param quadraticK    the quadratic force constant for the angle, measured in kJ/mol/radian^2
      */
     void setAngleParameters(int index, int particle1, int particle2, int particle3, int particle4, double length, double quadraticK);
     /**

plugins/amoeba/openmmapi/include/openmm/AmoebaMultipoleForce.h

@@ -148,7 +148,7 @@ public:
      * Set the Ewald alpha parameter.  If this is 0 (the default), a value is chosen automatically
      * based on the Ewald error tolerance.
      *
-     * @param Ewald alpha parameter
+     * @param aewald alpha parameter
      */
     void setAEwald(double aewald);
 
@@ -171,7 +171,7 @@ public:
      * Set the PME grid dimensions.  If Ewald alpha is 0 (the default), this is ignored and grid dimensions
      * are chosen automatically based on the Ewald error tolerance.
      *
-     * @param the PME grid dimensions
+     * @param gridDimension   the PME grid dimensions
      */
     void setPmeGridDimensions(const std::vector<int>& gridDimension);
 
@@ -180,12 +180,12 @@ public:
      * on the allowed grid sizes, the values that are actually used may be slightly different from those
      * specified with setPmeGridDimensions(), or the standard values calculated based on the Ewald error tolerance.
      * See the manual for details.
-     * 
-     * @param context the Context for which to get the parameters
-     * @param alpha   the separation parameter
-     * @param nx      the number of grid points along the X axis
-     * @param ny      the number of grid points along the Y axis
-     * @param nz      the number of grid points along the Z axis
+     *
+     * @param context      the Context for which to get the parameters
+     * @param[out] alpha   the separation parameter
+     * @param[out] nx      the number of grid points along the X axis
+     * @param[out] ny      the number of grid points along the Y axis
+     * @param[out] nz      the number of grid points along the Z axis
      */
     void getPMEParametersInContext(const Context& context, double& alpha, int& nx, int& ny, int& nz) const;
 
@@ -211,17 +211,17 @@ public:
     /**
      * Get the multipole parameters for a particle.
      *
-     * @param index                the index of the atom for which to get parameters
-     * @param charge               the particle's charge
-     * @param molecularDipole      the particle's molecular dipole (vector of size 3)
-     * @param molecularQuadrupole  the particle's molecular quadrupole (vector of size 9)
-     * @param axisType             the particle's axis type
-     * @param multipoleAtomZ       index of first atom used in constructing lab<->molecular frames
-     * @param multipoleAtomX       index of second atom used in constructing lab<->molecular frames
-     * @param multipoleAtomY       index of second atom used in constructing lab<->molecular frames
-     * @param thole                Thole parameter
-     * @param dampingFactor        dampingFactor parameter
-     * @param polarity             polarity parameter
+     * @param index                     the index of the atom for which to get parameters
+     * @param[out] charge               the particle's charge
+     * @param[out] molecularDipole      the particle's molecular dipole (vector of size 3)
+     * @param[out] molecularQuadrupole  the particle's molecular quadrupole (vector of size 9)
+     * @param[out] axisType             the particle's axis type
+     * @param[out] multipoleAtomZ       index of first atom used in constructing lab<->molecular frames
+     * @param[out] multipoleAtomX       index of second atom used in constructing lab<->molecular frames
+     * @param[out] multipoleAtomY       index of second atom used in constructing lab<->molecular frames
+     * @param[out] thole                Thole parameter
+     * @param[out] dampingFactor        dampingFactor parameter
+     * @param[out] polarity             polarity parameter
      */
     void getMultipoleParameters(int index, double& charge, std::vector<double>& molecularDipole, std::vector<double>& molecularQuadrupole,
                                 int& axisType, int& multipoleAtomZ, int& multipoleAtomX, int& multipoleAtomY, double& thole, double& dampingFactor, double& polarity) const;
@@ -237,6 +237,8 @@ public:
      * @param multipoleAtomZ       index of first atom used in constructing lab<->molecular frames
      * @param multipoleAtomX       index of second atom used in constructing lab<->molecular frames
      * @param multipoleAtomY       index of second atom used in constructing lab<->molecular frames
+     * @param thole                thole parameter
+     * @param dampingFactor        damping factor parameter
      * @param polarity             polarity parameter
      */
     void setMultipoleParameters(int index, double charge, const std::vector<double>& molecularDipole, const std::vector<double>& molecularQuadrupole,
@@ -256,7 +258,7 @@ public:
      *
      * @param index                the index of the atom for which to set parameters
      * @param typeId               CovalentTypes type
-     * @param covalentAtoms        output vector of covalent atoms associated w/ the specfied CovalentType
+     * @param[out] covalentAtoms   output vector of covalent atoms associated w/ the specfied CovalentType
      */
     void getCovalentMap(int index, CovalentType typeId, std::vector<int>& covalentAtoms) const;
 
@@ -264,7 +266,7 @@ public:
      * Get the CovalentMap for an atom
      *
      * @param index                the index of the atom for which to set parameters
-     * @param covalentLists        output vector of covalent lists of atoms
+     * @param[out] covalentLists   output vector of covalent lists of atoms
      */
     void getCovalentMaps(int index, std::vector < std::vector<int> >& covalentLists) const;
 
@@ -278,7 +280,7 @@ public:
     /**
      * Set the max number of iterations to be used in calculating the mutual induced dipoles
      *
-     * @param max number of iterations
+     * @param inputMutualInducedMaxIterations   number of iterations
      */
     void setMutualInducedMaxIterations(int inputMutualInducedMaxIterations);
 
@@ -292,7 +294,7 @@ public:
     /**
      * Set the target epsilon to be used to test for convergence of iterative method used in calculating the mutual induced dipoles
      *
-     * @param target epsilon
+     * @param inputMutualInducedTargetEpsilon   target epsilon
      */
     void setMutualInducedTargetEpsilon(double inputMutualInducedTargetEpsilon);
 
@@ -301,7 +303,7 @@ public:
      * which is acceptable.  This value is used to select the grid dimensions and separation (alpha)
      * parameter so that the average error level will be less than the tolerance.  There is not a
      * rigorous guarantee that all forces on all atoms will be less than the tolerance, however.
-     * 
+     *
      * This can be overridden by explicitly setting an alpha parameter and grid dimensions to use.
      */
     double getEwaldErrorTolerance() const;
@@ -310,25 +312,25 @@ public:
      * which is acceptable.  This value is used to select the grid dimensions and separation (alpha)
      * parameter so that the average error level will be less than the tolerance.  There is not a
      * rigorous guarantee that all forces on all atoms will be less than the tolerance, however.
-     * 
+     *
      * This can be overridden by explicitly setting an alpha parameter and grid dimensions to use.
      */
     void setEwaldErrorTolerance(double tol);
 
     /**
      * Get the induced dipole moments of all particles.
-     * 
-     * @param context    the Context for which to get the induced dipoles
-     * @param dipoles    the induced dipole moment of particle i is stored into the i'th element
+     *
+     * @param context         the Context for which to get the induced dipoles
+     * @param[out] dipoles    the induced dipole moment of particle i is stored into the i'th element
      */
     void getInducedDipoles(Context& context, std::vector<Vec3>& dipoles);
-    
+
     /**
      * Get the electrostatic potential.
      *
      * @param inputGrid    input grid points over which the potential is to be evaluated
      * @param context      context
-     * @param outputElectrostaticPotential output potential
+     * @param[out] outputElectrostaticPotential output potential
      */
 
     void getElectrostaticPotential(const std::vector< Vec3 >& inputGrid,
@@ -336,7 +338,7 @@ public:
 
     /**
      * Get the system multipole moments.
-     * 
+     *
      * This method is most useful for non-periodic systems.  When called for a periodic system, only the
      * <i>lowest nonvanishing moment</i> has a well defined value.  This means that if the system has a net
      * nonzero charge, the dipole and quadrupole moments are not well defined and should be ignored.  If the
@@ -344,11 +346,11 @@ public:
      * the quadrupole moment is still undefined and should be ignored.
      *
      * @param context      context
-     * @param outputMultipoleMoments (charge,
-                                      dipole_x, dipole_y, dipole_z,
-                                      quadrupole_xx, quadrupole_xy, quadrupole_xz,
-                                      quadrupole_yx, quadrupole_yy, quadrupole_yz,
-                                      quadrupole_zx, quadrupole_zy, quadrupole_zz)
+     * @param[out] outputMultipoleMoments (charge,
+                                           dipole_x, dipole_y, dipole_z,
+                                           quadrupole_xx, quadrupole_xy, quadrupole_xz,
+                                           quadrupole_yx, quadrupole_yy, quadrupole_yz,
+                                           quadrupole_zx, quadrupole_zy, quadrupole_zz)
      */
     void getSystemMultipoleMoments(Context& context, std::vector< double >& outputMultipoleMoments);
     /**
@@ -356,7 +358,7 @@ public:
      * provides an efficient method to update certain parameters in an existing Context without needing to reinitialize it.
      * Simply call setMultipoleParameters() to modify this object's parameters, then call updateParametersInContext() to
      * copy them over to the Context.
-     * 
+     *
      * This method has several limitations.  The only information it updates is the parameters of multipoles.
      * All other aspects of the Force (the nonbonded method, the cutoff distance, etc.) are unaffected and can only be
      * changed by reinitializing the Context.  Furthermore, this method cannot be used to add new multipoles,

plugins/amoeba/openmmapi/include/openmm/AmoebaOutOfPlaneBendForce.h

@@ -133,12 +133,12 @@ public:
     /**
      * Get the force field parameters for an out-of-plane bend term.
      * 
-     * @param index         the index of the outOfPlaneBend for which to get parameters
-     * @param particle1     the index of the first particle connected by the outOfPlaneBend
-     * @param particle2     the index of the second particle connected by the outOfPlaneBend
-     * @param particle3     the index of the third particle connected by the outOfPlaneBend
-     * @param particle4     the index of the fourth particle connected by the outOfPlaneBend
-     * @param k             the force constant for the out-of-plane bend
+     * @param index              the index of the outOfPlaneBend for which to get parameters
+     * @param[out] particle1     the index of the first particle connected by the outOfPlaneBend
+     * @param[out] particle2     the index of the second particle connected by the outOfPlaneBend
+     * @param[out] particle3     the index of the third particle connected by the outOfPlaneBend
+     * @param[out] particle4     the index of the fourth particle connected by the outOfPlaneBend
+     * @param[out] k             the force constant for the out-of-plane bend
      */
     void getOutOfPlaneBendParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, double& k) const;
 

plugins/amoeba/openmmapi/include/openmm/AmoebaPiTorsionForce.h

@@ -79,14 +79,14 @@ public:
     /**
      * Get the force field parameters for a torsion term.
      * 
-     * @param index         the index of the torsion for which to get parameters
-     * @param particle1     the index of the first particle connected by the torsion
-     * @param particle2     the index of the second particle connected by the torsion
-     * @param particle3     the index of the third particle connected by the torsion
-     * @param particle4     the index of the fourth particle connected by the torsion
-     * @param particle5     the index of the fifth particle connected by the torsion
-     * @param particle6     the index of the sixth particle connected by the torsion
-     * @param k             the force constant for the torsion
+     * @param index              the index of the torsion for which to get parameters
+     * @param[out] particle1     the index of the first particle connected by the torsion
+     * @param[out] particle2     the index of the second particle connected by the torsion
+     * @param[out] particle3     the index of the third particle connected by the torsion
+     * @param[out] particle4     the index of the fourth particle connected by the torsion
+     * @param[out] particle5     the index of the fifth particle connected by the torsion
+     * @param[out] particle6     the index of the sixth particle connected by the torsion
+     * @param[out] k             the force constant for the torsion
      */
     void getPiTorsionParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, int& particle5, int& particle6, double& k) const;
 

plugins/amoeba/openmmapi/include/openmm/AmoebaStretchBendForce.h

@@ -81,15 +81,15 @@ public:
     /**
      * Get the force field parameters for a stretch-bend term.
      * 
-     * @param index         the index of the stretch-bend for which to get parameters
-     * @param particle1     the index of the first particle connected by the stretch-bend
-     * @param particle2     the index of the second particle connected by the stretch-bend
-     * @param particle3     the index of the third particle connected by the stretch-bend
-     * @param lengthAB      the equilibrium length of the stretch-bend in bond ab [particle1, particle2], measured in nm
-     * @param lengthCB      the equilibrium length of the stretch-bend in bond cb [particle3, particle2], measured in nm
-     * @param angle         the equilibrium angle in radians
-     * @param k1            the force constant of the product of bond ab and angle a-b-c
-     * @param k2            the force constant of the product of bond bc and angle a-b-c
+     * @param index              the index of the stretch-bend for which to get parameters
+     * @param[out] particle1     the index of the first particle connected by the stretch-bend
+     * @param[out] particle2     the index of the second particle connected by the stretch-bend
+     * @param[out] particle3     the index of the third particle connected by the stretch-bend
+     * @param[out] lengthAB      the equilibrium length of the stretch-bend in bond ab [particle1, particle2], measured in nm
+     * @param[out] lengthCB      the equilibrium length of the stretch-bend in bond cb [particle3, particle2], measured in nm
+     * @param[out] angle         the equilibrium angle in radians
+     * @param[out] k1            the force constant of the product of bond ab and angle a-b-c
+     * @param[out] k2            the force constant of the product of bond bc and angle a-b-c
      */
     void getStretchBendParameters(int index, int& particle1, int& particle2, int& particle3, double& lengthAB,
                                   double& lengthCB, double& angle, double& k1, double& k2) const;

plugins/amoeba/openmmapi/include/openmm/AmoebaTorsionTorsionForce.h

@@ -89,14 +89,14 @@ public:
     /**
      * Get the force field parameters for a torsion-torsion term.
      *
-     * @param index                     the index of the torsion-torsion for which to get parameters
-     * @param particle1                 the index of the first particle connected by the torsion-torsion
-     * @param particle2                 the index of the second particle connected by the torsion-torsion
-     * @param particle3                 the index of the third particle connected by the torsion-torsion
-     * @param particle4                 the index of the fourth particle connected by the torsion-torsion
-     * @param particle5                 the index of the fifth particle connected by the torsion-torsion
-     * @param chiralCheckAtomIndex      the index of the particle connected to particle3, but not particle2 or particle4 to be used in chirality check
-     * @param gridIndex                 the grid index
+     * @param index                          the index of the torsion-torsion for which to get parameters
+     * @param[out] particle1                 the index of the first particle connected by the torsion-torsion
+     * @param[out] particle2                 the index of the second particle connected by the torsion-torsion
+     * @param[out] particle3                 the index of the third particle connected by the torsion-torsion
+     * @param[out] particle4                 the index of the fourth particle connected by the torsion-torsion
+     * @param[out] particle5                 the index of the fifth particle connected by the torsion-torsion
+     * @param[out] chiralCheckAtomIndex      the index of the particle connected to particle3, but not particle2 or particle4 to be used in chirality check
+     * @param[out] gridIndex                 the grid index
      */
     void getTorsionTorsionParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, int& particle5, int& chiralCheckAtomIndex, int& gridIndex) const;
 
@@ -117,7 +117,7 @@ public:
     /**
      * Get the torsion-torsion grid at the specified index
      *
-     * @param gridIndex     the grid index
+     * @param  index        the grid index
      * @return grid         return grid reference
      */
     const std::vector<std::vector<std::vector<double> > >& getTorsionTorsionGrid(int index) const;

plugins/amoeba/openmmapi/include/openmm/AmoebaVdwForce.h

@@ -97,12 +97,12 @@ public:
     /**
      * Get the force field parameters for a vdw particle.
      * 
-     * @param particleIndex   the particle index
-     * @param parentIndex     the index of the parent particle
-     * @param sigma           vdw sigma
-     * @param epsilon         vdw epsilon
-     * @param reductionFactor the fraction of the distance along the line from the parent particle to this particle
-     *                        at which the interaction site should be placed
+     * @param particleIndex        the particle index
+     * @param[out] parentIndex     the index of the parent particle
+     * @param[out] sigma           vdw sigma
+     * @param[out] epsilon         vdw epsilon
+     * @param[out] reductionFactor the fraction of the distance along the line from the parent particle to this particle
+     *                             at which the interaction site should be placed
      */
     void getParticleParameters(int particleIndex, int& parentIndex, double& sigma, double& epsilon, double& reductionFactor) const;
 
@@ -178,8 +178,8 @@ public:
     /**
      * Get exclusions for specified particle
      * 
-     * @param particleIndex particle index
-     * @param exclusions vector of exclusions
+     * @param particleIndex    particle index
+     * @param[out] exclusions  vector of exclusions
      */
     void getParticleExclusions(int particleIndex, std::vector<int>& exclusions) const;
 

plugins/amoeba/openmmapi/include/openmm/AmoebaWcaDispersionForce.h

@@ -75,9 +75,9 @@ public:
     /**
      * Get the force field parameters for a WCA dispersion particle.
      * 
-     * @param particleIndex   the particle index
-     * @param radius          radius
-     * @param epsilon         epsilon 
+     * @param particleIndex        the particle index
+     * @param[out] radius          radius
+     * @param[out] epsilon         epsilon 
      */
     void getParticleParameters(int particleIndex, double& radius, double& epsilon) const;
 

plugins/drude/openmmapi/include/openmm/DrudeForce.h

@@ -44,7 +44,7 @@ namespace OpenMM {
  * it applies: an anisotropic harmonic force connecting each Drude particle to its parent particle; and
  * a screened Coulomb interaction between specific pairs of dipoles.  The latter is typically used between
  * closely bonded particles whose Coulomb interaction would otherwise be fully excluded.
- * 
+ *
  * To use this class, create a DrudeForce object, then call addParticle() once for each Drude particle in the
  * System to define its parameters.  After a particle has been added, you can modify its force field parameters
  * by calling setParticleParameters().  This will have no effect on Contexts that already exist unless you
@@ -91,19 +91,19 @@ public:
     /**
      * Get the parameters for a Drude particle.
      *
-     * @param index           the index of the Drude particle for which to get parameters
-     * @param particle        the index within the System of the Drude particle
-     * @param particle1       the index within the System of the particle to which the Drude particle is attached
-     * @param particle2       the index within the System of the second particle used for defining anisotropic polarizability.
-     *                        This may be set to -1, in which case aniso12 will be ignored.
-     * @param particle3       the index within the System of the third particle used for defining anisotropic polarizability.
-     *                        This may be set to -1, in which case aniso34 will be ignored.
-     * @param particle4       the index within the System of the fourth particle used for defining anisotropic polarizability.
-     *                        This may be set to -1, in which case aniso34 will be ignored.
-     * @param charge          The charge on the Drude particle
-     * @param polarizability  The isotropic polarizability
-     * @param aniso12         The scale factor for the polarizability along the direction defined by particle1 and particle2
-     * @param aniso34         The scale factor for the polarizability along the direction defined by particle3 and particle4
+     * @param index                the index of the Drude particle for which to get parameters
+     * @param[out] particle        the index within the System of the Drude particle
+     * @param[out] particle1       the index within the System of the particle to which the Drude particle is attached
+     * @param[out] particle2       the index within the System of the second particle used for defining anisotropic polarizability.
+     *                             This may be set to -1, in which case aniso12 will be ignored.
+     * @param[out] particle3       the index within the System of the third particle used for defining anisotropic polarizability.
+     *                             This may be set to -1, in which case aniso34 will be ignored.
+     * @param[out] particle4       the index within the System of the fourth particle used for defining anisotropic polarizability.
+     *                             This may be set to -1, in which case aniso34 will be ignored.
+     * @param[out] charge          The charge on the Drude particle
+     * @param[out] polarizability  The isotropic polarizability
+     * @param[out] aniso12         The scale factor for the polarizability along the direction defined by particle1 and particle2
+     * @param[out] aniso34         The scale factor for the polarizability along the direction defined by particle3 and particle4
      */
     void getParticleParameters(int index, int& particle, int& particle1, int& particle2, int& particle3, int& particle4, double& charge, double& polarizability, double& aniso12, double& aniso34) const;
     /**
@@ -135,16 +135,15 @@ public:
     int addScreenedPair(int particle1, int particle2, double thole);
     /**
      * Get the force field parameters for screened pair.
-     * 
-     * @param index      the index of the pair for which to get parameters
-     * @param particle1  the index within this Force of the first particle involved in the interaction
-     * @param particle2  the index within this Force of the second particle involved in the interaction
-     * @param thole      the Thole screening factor
+     *
+     * @param[out] particle1  the index within this Force of the first particle involved in the interaction
+     * @param[out] particle2  the index within this Force of the second particle involved in the interaction
+     * @param[out] thole      the Thole screening factor
      */
     void getScreenedPairParameters(int index, int& particle1, int& particle2, double& thole) const;
     /**
      * Set the force field parameters for screened pair.
-     * 
+     *
      * @param index      the index of the pair for which to get parameters
      * @param particle1  the index within this Force of the first particle involved in the interaction
      * @param particle2  the index within this Force of the second particle involved in the interaction
@@ -156,7 +155,7 @@ public:
      * provides an efficient method to update certain parameters in an existing Context without needing to reinitialize it.
      * Simply call setParticleParameters() and setScreenedPairParameters() to modify this object's parameters, then call
      * updateParametersInContext() to copy them over to the Context.
-     * 
+     *
      * This method has several limitations.  It can be used to modify the numeric parameters associated with a particle or
      * screened pair (polarizability, thole, etc.), but not the identities of the particles they involve.  It also cannot
      * be used to add new particles or screenedPairs, only to change the parameters of existing ones.

serialization/include/openmm/serialization/SerializationNode.h

@@ -105,7 +105,7 @@ public:
     /**
      * Determine whether this node has a property with a particular node.
      *
-     * @param the name of the property to check for
+     * @param name  the name of the property to check for
      */
     bool hasProperty(const std::string& name) const;
     /**

wrappers/python/filterPythonFiles.py

 from __future__ import print_function
+from numpydoc.docscrape import NumpyDocString
 import sys
+import textwrap
+
 
 # Doxygen does a bad job of generating documentation based on docstrings.  This script is run as a filter
 # on each file, and converts the docstrings into Doxygen style comments so we get better documentation.
@@ -15,46 +18,51 @@ while True:
         split = stripped.split()
         if split[0] == 'class' and split[1][0].islower():
             # Classes that start with a lowercase letter were defined by SWIG.  We want to hide them.
-            print("%s## @private" % prefix)
+            print("%s## @private" % prefix, end='')
         if split[1][0] == '_' and split[1][1] != '_':
             # Names starting with a single _ are assumed to be private.
-            print("%s## @private" % prefix)
-        
+            print("%s## @private" % prefix, end='')
+
         # We're at the start of a class or function definition.  Find all lines that contain the declaration.
-        
+
         declaration = line
         while len(line) > 0 and line.find(':') == -1:
             line = input.readline()
             declaration += line
-        
+
         # Now look for a docstring.
-        
-        docstrings = []
+
+        docstringlines = []
         line = input.readline()
         stripped = line.lstrip()
-        if stripped.startswith('"""'):
+        if stripped.startswith('"""') or stripped.startswith("'''"):
             line = stripped[3:]
             readingParameters = False
-            while line.find('"""') == -1:
-                docstrings.append(line)
-                line = input.readline()
-                if line.strip() == 'Parameters:':
-                    readingParameters = True
+            if line.find('"""') != -1 or line.find(("'''")) != -1:
+                docstringlines.append(line.rstrip()[:-3])
+            else:
+                while line.find('"""') == -1:
+                    docstringlines.append(line)
                     line = input.readline()
-                stripped = line.lstrip()
-                if readingParameters and stripped.startswith('- '):
-                    line = "@param %s" % stripped[2:]
-                elif stripped.startswith('Returns:'):
-                    line = "@return %s" % stripped[8:]
-            line = line[:line.find('"""')]
-            docstrings.append(line)            
-        
+        docstring = NumpyDocString(''.join(docstringlines))
+
         # Print out the docstring in Doxygen syntax, followed by the declaration.
-        
-        for s in docstrings:
-            print("%s##%s" % (prefix, s.strip()))
+        sep = '\n{prefix}##\n{prefix}## '.format(prefix=prefix)
+        for line in textwrap.wrap(' '.join(docstring['Summary'])):
+            print('{prefix}## {line}'.format(prefix=prefix, line=line))
+        if len(docstring['Extended Summary']) > 0:
+            print('{prefix}##'.format(prefix=prefix))
+            print('{prefix}## {ext_summary}'.format(prefix=prefix, ext_summary=sep.join(docstring['Extended Summary'])))
+        print('{prefix}##'.format(prefix=prefix))
+        for name, type, descr in docstring['Parameters']:
+            print('{prefix}## @param {name} ({type}) {descr}'.format(prefix=prefix, type=type, name=name, descr=''.join(descr)))
+        for name, type, descr in docstring['Returns']:
+            if type == '':
+                type = name
+            print('{prefix}## @return ({type}) {descr}'.format(prefix=prefix, type=type, name=name, descr=''.join(descr)))
+
         print(declaration)
-        if len(docstrings) == 0:
-            print(line)
+        if len(docstringlines) == 0:
+            print(line, end='')
     else:
-        print(line)
\ No newline at end of file
+        print(line, end='')

wrappers/python/simtk/openmm/amd.py

@@ -10,7 +10,7 @@ Portions copyright (c) 2012 Stanford University and the Authors.
 Authors: Peter Eastman, Steffen Lindert
 Contributors:
 
-Permission is hereby granted, free of charge, to any person obtaining a 
+Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the "Software"),
 to deal in the Software without restriction, including without limitation
 the rights to use, copy, modify, merge, publish, distribute, sublicense,
@@ -37,18 +37,18 @@ from simtk.unit import kilojoules_per_mole, is_quantity
 
 class AMDIntegrator(CustomIntegrator):
     """AMDIntegrator implements the aMD integration algorithm.
-    
+
     The system is integrated based on a modified potential.  Whenever the energy V(r) is less than a
     cutoff value E, the following effective potential is used:
-    
+
     V*(r) = V(r) + (E-V(r))^2 / (alpha+E-V(r))
-    
+
     For details, see Hamelberg et al., J. Chem. Phys. 127, 155102 (2007).
     """
-    
+
     def __init__(self, dt, alpha, E):
         """Create an AMDIntegrator.
-        
+
         Parameters:
          - dt (time) The integration time step to use
          - alpha (energy) The alpha parameter to use
@@ -64,23 +64,23 @@ class AMDIntegrator(CustomIntegrator):
         self.addComputePerDof("x", "x+dt*v")
         self.addConstrainPositions()
         self.addComputePerDof("v", "(x-oldx)/dt")
-    
+
     def getAlpha(self):
         """Get the value of alpha for the integrator."""
         return self.getGlobalVariable(0)*kilojoules_per_mole
-    
+
     def setAlpha(self, alpha):
         """Set the value of alpha for the integrator."""
         self.setGlobalVariable(0, alpha)
-    
+
     def getE(self):
         """Get the energy threshold E for the integrator."""
         return self.getGlobalVariable(1)*kilojoules_per_mole
-    
+
     def setE(self, E):
         """Set the energy threshold E for the integrator."""
         self.setGlobalVariable(1, E)
-    
+
     def getEffectiveEnergy(self, energy):
         """Given the actual potential energy of the system, return the value of the effective potential."""
         alpha = self.getAlpha()
@@ -94,16 +94,16 @@ class AMDIntegrator(CustomIntegrator):
 
 class AMDForceGroupIntegrator(CustomIntegrator):
     """AMDForceGroupIntegrator implements a single boost aMD integration algorithm.
-    
+
     This is similar to AMDIntegrator, but is applied based on the energy of a single force group
     (typically representing torsions).
-    
+
     For details, see Hamelberg et al., J. Chem. Phys. 127, 155102 (2007).
     """
-    
+
     def __init__(self, dt, group, alphaGroup, EGroup):
         """Create a AMDForceGroupIntegrator.
-        
+
         Parameters:
          - dt (time) The integration time step to use
          - group (int) The force group to apply the boost to
@@ -124,26 +124,26 @@ class AMDForceGroupIntegrator(CustomIntegrator):
         self.addComputePerDof("x", "x+dt*v")
         self.addConstrainPositions()
         self.addComputePerDof("v", "(x-oldx)/dt")
-    
+
     def getAlphaGroup(self):
         """Get the value of alpha for the boosted force group."""
         return self.getGlobalVariable(0)*kilojoules_per_mole
-    
+
     def setAlphaGroup(self, alpha):
         """Set the value of alpha for the boosted force group."""
         self.setGlobalVariable(0, alpha)
-    
+
     def getEGroup(self):
         """Get the energy threshold E for the boosted force group."""
         return self.getGlobalVariable(1)*kilojoules_per_mole
-    
+
     def setEGroup(self, E):
         """Set the energy threshold E for the boosted force group."""
         self.setGlobalVariable(1, E)
-    
+
     def getEffectiveEnergy(self, groupEnergy):
         """Given the actual group energy of the system, return the value of the effective potential.
-        
+
         Parameters:
           - groupEnergy (energy): the actual potential energy of the boosted force group
         Returns: the value of the effective potential
@@ -161,14 +161,14 @@ class AMDForceGroupIntegrator(CustomIntegrator):
 
 class DualAMDIntegrator(CustomIntegrator):
     """DualAMDIntegrator implements a dual boost aMD integration algorithm.
-    
+
     This is similar to AMDIntegrator, but two different boosts are applied to the potential:
     one based on the total energy, and one based on the energy of a single force group
     (typically representing torsions).
 
     For details, see Hamelberg et al., J. Chem. Phys. 127, 155102 (2007).
     """
-    
+
     def __init__(self, dt, group, alphaTotal, ETotal, alphaGroup, EGroup):
         """Create a DualAMDIntegrator.
 
@@ -201,42 +201,42 @@ class DualAMDIntegrator(CustomIntegrator):
         self.addComputePerDof("x", "x+dt*v")
         self.addConstrainPositions()
         self.addComputePerDof("v", "(x-oldx)/dt")
-    
+
     def getAlphaTotal(self):
         """Get the value of alpha for the total energy."""
         return self.getGlobalVariable(0)*kilojoules_per_mole
-    
+
     def setAlphaTotal(self, alpha):
         """Set the value of alpha for the total energy."""
         self.setGlobalVariable(0, alpha)
-    
+
     def getETotal(self):
         """Get the energy threshold E for the total energy."""
         return self.getGlobalVariable(1)*kilojoules_per_mole
-    
+
     def setETotal(self, E):
         """Set the energy threshold E for the total energy."""
         self.setGlobalVariable(1, E)
-    
+
     def getAlphaGroup(self):
         """Get the value of alpha for the boosted force group."""
         return self.getGlobalVariable(2)*kilojoules_per_mole
-    
+
     def setAlphaGroup(self, alpha):
         """Set the value of alpha for the boosted force group."""
         self.setGlobalVariable(2, alpha)
-    
+
     def getEGroup(self):
         """Get the energy threshold E for the boosted force group."""
         return self.getGlobalVariable(3)*kilojoules_per_mole
-    
+
     def setEGroup(self, E):
         """Set the energy threshold E for the boosted force group."""
         self.setGlobalVariable(3, E)
-    
+
     def getEffectiveEnergy(self, totalEnergy, groupEnergy):
         """Given the actual potential energy of the system, return the value of the effective potential.
-        
+
         Parameters:
          - totalEnergy (energy): the actual potential energy of the whole system
          - groupEnergy (energy): the actual potential energy of the boosted force group

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

@@ -60,12 +60,17 @@ class AmberInpcrdFile(object):
     def __init__(self, file, loadVelocities=None, loadBoxVectors=None):
         """Load an inpcrd file.
 
-        An inpcrd file contains atom positions and, optionally, velocities and periodic box dimensions.
-
-        Parameters:
-         - file (string) the name of the file to load
-         - loadVelocities (boolean=None) deprecated. Velocities are loaded automatically if present
-         - loadBoxVectors (boolean=None) deprecated. Box vectors are loaded automatically if present
+        An inpcrd file contains atom positions and, optionally, velocities and
+        periodic box dimensions.
+
+        Parameters
+        ----------
+        file : str
+             The name of the file to load
+        loadVelocities : bool
+             Deprecated. Velocities are loaded automatically if present
+        loadBoxVectors : bool
+            Deprecated. Box vectors are loaded automatically if present
         """
         self.file = file
         if loadVelocities is not None or loadBoxVectors is not None:
@@ -84,8 +89,11 @@ class AmberInpcrdFile(object):
     def getPositions(self, asNumpy=False):
         """Get the atomic positions.
 
-        Parameters:
-         - asNumpy (boolean=False) if true, the values are returned as a numpy array instead of a list of Vec3s
+        Parameters
+        ----------
+        asNumpy : bool=False
+            if true, the values are returned as a numpy array instead of a list
+            of Vec3s
         """
         if asNumpy:
             if self._numpyPositions is None:
@@ -97,8 +105,10 @@ class AmberInpcrdFile(object):
     def getVelocities(self, asNumpy=False):
         """Get the atomic velocities.
 
-        Parameters:
-         - asNumpy (boolean=False) if true, the vectors are returned as numpy arrays instead of Vec3s
+        Parameters
+        ----------
+        asNumpy : bool=False
+            if true, the vectors are returned as numpy arrays instead of Vec3s
         """
         if self.velocities is None:
             raise AttributeError('velocities not found in %s' % self.file)
@@ -112,8 +122,11 @@ class AmberInpcrdFile(object):
     def getBoxVectors(self, asNumpy=False):
         """Get the periodic box vectors.
 
-        Parameters:
-         - asNumpy (boolean=False) if true, the values are returned as a numpy array instead of a list of Vec3s
+        Parameters
+        ----------
+        asNumpy : bool=False
+            if true, the values are returned as a numpy array instead of a list
+            of Vec3s
         """
         if self.boxVectors is None:
             raise AttributeError('Box information not found in %s' % self.file)

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

@@ -151,29 +151,51 @@ class AmberPrmtopFile(object):
                      implicitSolventKappa=None, temperature=298.15*unit.kelvin,
                      soluteDielectric=1.0, solventDielectric=78.5,
                      removeCMMotion=True, hydrogenMass=None, ewaldErrorTolerance=0.0005):
-        """Construct an OpenMM System representing the topology described by this prmtop file.
-
-        Parameters:
-         - nonbondedMethod (object=NoCutoff) The method to use for nonbonded interactions.  Allowed values are
-           NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
-         - nonbondedCutoff (distance=1*nanometer) The cutoff distance to use for nonbonded interactions
-         - constraints (object=None) Specifies which bonds angles should be implemented with constraints.
-           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
-         - implicitSolvent (object=None) If not None, the implicit solvent model to use.  Allowed values are HCT, OBC1, OBC2, GBn, or GBn2.
-         - implicitSolventSaltConc (float=0.0*unit.moles/unit.liter) The salt concentration for GB 
-                    calculations (modelled as a debye screening parameter). It is converted to the debye length (kappa)
-                    using the provided temperature and solventDielectric
-         - temperature (float=300*kelvin) Temperature of the system. Only used to compute the Debye length from
-                    implicitSolventSoltConc
-         - implicitSolventKappa (float units of 1/length) If this value is set, implicitSolventSaltConc will be ignored.
-         - soluteDielectric (float=1.0) The solute dielectric constant to use in the implicit solvent model.
-         - solventDielectric (float=78.5) The solvent dielectric constant to use in the implicit solvent model.
-         - removeCMMotion (boolean=True) If true, a CMMotionRemover will be added to the System
-         - hydrogenMass (mass=None) The mass to use for hydrogen atoms bound to heavy atoms.  Any mass added to a hydrogen is
-           subtracted from the heavy atom to keep their total mass the same.
-         - ewaldErrorTolerance (float=0.0005) The error tolerance to use if nonbondedMethod is Ewald or PME.
-        Returns: the newly created System
+        """Construct an OpenMM System representing the topology described by this
+        prmtop file.
+
+        Parameters
+        ----------
+        nonbondedMethod : object=NoCutoff
+            The method to use for nonbonded interactions.  Allowed values are
+            NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
+        nonbondedCutoff : distance=1*nanometer
+            The cutoff distance to use for nonbonded interactions
+        constraints : object=None
+            Specifies which bonds angles should be implemented with constraints.
+            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
+        implicitSolvent : object=None
+            If not None, the implicit solvent model to use.  Allowed values are
+            HCT, OBC1, OBC2, GBn, or GBn2.
+        implicitSolventSaltConc : float=0.0*unit.moles/unit.liter
+            The salt concentration for GB calculations (modelled as a debye
+            screening parameter). It is converted to the debye length (kappa)
+            using the provided temperature and solventDielectric
+        temperature : float=300*kelvin
+            Temperature of the system. Only used to compute the Debye length
+            from implicitSolventSoltConc
+        implicitSolventKappa : float units of 1/length
+            If this value is set, implicitSolventSaltConc will be ignored.
+        soluteDielectric : float=1.0
+            The solute dielectric constant to use in the implicit solvent model.
+        solventDielectric : float=78.5
+            The solvent dielectric constant to use in the implicit solvent
+            model.
+        removeCMMotion : boolean=True
+            If true, a CMMotionRemover will be added to the System
+        hydrogenMass : mass=None
+            The mass to use for hydrogen atoms bound to heavy atoms.  Any mass
+            added to a hydrogen is subtracted from the heavy atom to keep their
+            total mass the same.
+        ewaldErrorTolerance : float=0.0005
+            The error tolerance to use if nonbondedMethod is Ewald or PME.
+
+        Returns
+        -------
+            the newly created System
         """
         if self._prmtop.chamber:
             raise ValueError("CHAMBER-style topology file detected. CHAMBER "

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

 """
 Provides a class for parsing CHARMM-style coordinate files, namely CHARMM .crd
 (coordinate) files and CHARMM .rst (restart) file. Uses CharmmFile class in
-_charmmfile.py for reading files 
+_charmmfile.py for reading files
 
 This file is part of the OpenMM molecular simulation toolkit originating from
 Simbios, the NIH National Center for Physics-Based Simulation of Biological
@@ -49,12 +49,17 @@ class CharmmCrdFile(object):
     Reads and parses a CHARMM coordinate file (.crd) into its components,
     namely the coordinates, CHARMM atom types, resid, resname, etc.
 
-    Main attributes:
-        - natom (int) : Number of atoms in the system
-        - resname (list) : Names of all residues
-        - positions (list) : All cartesian coordinates [x1, y1, z1, x2, ...]
-
-    Example:
+    Attributes
+    ----------
+    natom : int
+        Number of atoms in the system
+    resname : list
+        Names of all residues
+    positions : list
+        All cartesian coordinates [x1, y1, z1, x2, ...]
+
+    Examples
+    --------
     >>> chm = CharmmCrdFile('testfiles/1tnm.crd')
     >>> print '%d atoms; %d coords' % (chm.natom, len(chm.positions))
     1414 atoms; 1414 coords
@@ -91,15 +96,15 @@ class CharmmCrdFile(object):
                 intitle = False
             elif line.strip()[0] != '*':
                 intitle = False
-            else: 
+            else:
                 intitle = True
 
         while len(line.strip()) == 0:      # Skip whitespace
             line = crdfile.readline()
-        
+
         try:
             self.natom = int(line.strip().split()[0])
-            
+
             for row in range(self.natom):
                 line = crdfile.readline().strip().split()
                 self.atomno.append(int(line[0]))
@@ -131,14 +136,21 @@ class CharmmRstFile(object):
     Reads and parses data, velocities and coordinates from a CHARMM restart
     file (.rst) of file name 'fname' into class attributes
 
-    Main attributes:
-        - natom (int) : Number of atoms in the system
-        - resname (list) : Names of all residues
-        - positions (list) : All cartesian coordinates [x1, y1, z1, x2, ...]
-        - positionsold (list) : Old cartesian coordinates
-        - velocities (list) : List of all cartesian velocities
-
-    Example:
+    Attributes
+    ----------
+    natom : int
+        Number of atoms in the system
+    resname : list
+        Names of all residues
+    positions : list
+        All cartesian coordinates [x1, y1, z1, x2, ...]
+    positionsold : list
+        Old cartesian coordinates
+    velocities : list
+        List of all cartesian velocities
+
+    Examples
+    --------
     >>> chm = CharmmRstFile('testfiles/sample-charmm.rst')
     >>> print chm.header[0]
     REST    37     1
@@ -155,7 +167,7 @@ class CharmmRstFile(object):
         self.positionsold = []
         self.positions = []
         self.velocities = []
-        
+
         self.ff_version = 0
         self.natom = 0
         self.npriv = 0
@@ -169,7 +181,7 @@ class CharmmRstFile(object):
     def _parse(self, fname):
 
         crdfile = open(fname, 'r')
-        readingHeader = True 
+        readingHeader = True
 
         while readingHeader:
             line = crdfile.readline()
@@ -177,7 +189,7 @@ class CharmmRstFile(object):
                 raise CharmmFileError('Premature end of file')
             line = line.strip()
             words = line.split()
-            if len(line) != 0:  
+            if len(line) != 0:
                 if words[0] == 'ENERGIES' or words[0] == '!ENERGIES':
                     readingHeader = False
                 else:
@@ -191,14 +203,14 @@ class CharmmRstFile(object):
                 if line[0][0:5] == 'NATOM' or line[0][0:6] == '!NATOM':
                     try:
                         line = self.header[row+1].strip().split()
-                        self.natom = int(line[0])     
+                        self.natom = int(line[0])
                         self.npriv = int(line[1])     # num. previous steps
-                        self.nstep = int(line[2])     # num. steps in file  
-                        self.nsavc = int(line[3])     # coord save frequency 
+                        self.nstep = int(line[2])     # num. steps in file
+                        self.nsavc = int(line[3])     # coord save frequency
                         self.nsavv = int(line[4])     # velocities "
                         self.jhstrt = int(line[5])    # Num total steps?
                         break
-                   
+
                     except (ValueError, IndexError) as e:
                         raise CharmmFileError('Problem parsing CHARMM restart')
 
@@ -244,7 +256,7 @@ class CharmmRstFile(object):
             if len(line) < 3*CHARMMLEN:
                 raise CharmmFileError("Less than 3 coordinates present in "
                                       "coordinate row or positions may be "
-                                      "truncated.") 
+                                      "truncated.")
 
             line = line.replace('D','E')     # CHARMM uses 'D' for exponentials
 

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

@@ -51,41 +51,43 @@ class CharmmParameterSet(object):
     the information found in the MASS section of the CHARMM topology file
     (TOP/RTF) and all of the information in the parameter files (PAR)
 
-    Parameters:
-        - filenames : List of topology, parameter, and stream files to load into
-          the parameter set. The following file type suffixes are recognized.
-          Unrecognized file types raise a TypeError
-            .rtf, .top -- Residue topology file
-            .par, .prm -- Parameter file
-            .str -- Stream file
-            .inp -- If "par" is in the file name, it is a parameter file. If
+    Parameters
+    ----------
+    filenames : List of topology, parameter, and stream files to load into the parameter set.
+        The following file type suffixes are recognized. Unrecognized file types raise a TypeError
+          * .rtf, .top -- Residue topology file
+          * .par, .prm -- Parameter file
+          * .str -- Stream file
+          * .inp -- If "par" is in the file name, it is a parameter file. If
                     "top" is in the file name, it is a topology file. Otherwise,
                     raise TypeError
 
-    Attributes:
-        All type lists are dictionaries whose keys are tuples (with however
-        many elements are needed to define that type of parameter). The types
-        that can be in any order are SORTED.
-        
-        - atom_types_str
-        - atom_types_int
-        - atom_types_tuple
-        - bond_types
-        - angle_types
-        - urey_bradley_types
-        - dihedral_types
-        - improper_types
-        - cmap_types
-        - nbfix_types
-
-        The dihedral types can be multiterm, so the values for each dict key is
-        actually a list of DihedralType instances. The atom_types are dicts that
-        match the name (str), number (int), or (name, number) tuple (tuple) to
-        the atom type. The tuple is guaranteed to be the most robust, although
-        when only the integer or string is available the other dictionaries are
-        helpful
-
-    Example:
+    Attributes
+    ----------
+    All type lists are dictionaries whose keys are tuples (with however
+    many elements are needed to define that type of parameter). The types
+    that can be in any order are SORTED.
+
+    - atom_types_str
+    - atom_types_int
+    - atom_types_tuple
+    - bond_types
+    - angle_types
+    - urey_bradley_types
+    - dihedral_types
+    - improper_types
+    - cmap_types
+    - nbfix_types
+
+    The dihedral types can be multiterm, so the values for each dict key is
+    actually a list of DihedralType instances. The atom_types are dicts that
+    match the name (str), number (int), or (name, number) tuple (tuple) to
+    the atom type. The tuple is guaranteed to be the most robust, although
+    when only the integer or string is available the other dictionaries are
+    helpful
+
+    Examples
+    --------
     >>> params = CharmmParameterSet('charmm22.top', 'charmm22.par', 'file.str')
     """
 
@@ -113,7 +115,7 @@ class CharmmParameterSet(object):
         self.cmap_types = dict()
         self.nbfix_types = dict()
         self.parametersets = []
-        
+
         # Load all of the files
         tops, pars, strs = [], [], []
         for arg in args:
@@ -150,23 +152,30 @@ class CharmmParameterSet(object):
         Instantiates a CharmmParameterSet from a Topology file and a Parameter
         file (or just a Parameter file if it has all information)
 
-        Parameters:
-            - tfile (str) : Name of the Topology (RTF/TOP) file
-            - pfile (str) : Name of the Parameter (PAR) file
-            - sfiles (list of str) : List or tuple of stream (STR) file names.
-            - permissive (bool) : Accept non-bonbded parameters for undefined 
-                                  atom types (default False)
-
-        Returns:
+        Parameters
+        -----------
+        tfile : str
+            Name of the Topology (RTF/TOP) file
+        pfile : str
+            Name of the Parameter (PAR) file
+        sfiles : list of str
+            List or tuple of stream (STR) file names.
+        permissive : bool=False
+            Accept non-bonbded parameters for undefined atom types
+
+        Returns
+        -------
+        CharmmParameterSet
             New CharmmParameterSet populated with the parameters found in the
             provided files.
-            
-        Notes:
-            The RTF file is read first (if provided), followed by the PAR file,
-            followed by the list of stream files (in the order they are
-            provided). Parameters in each stream file will overwrite those that
-            came before (or simply append to the existing set if they are
-            different)
+
+        Notes
+        -----
+        The RTF file is read first (if provided), followed by the PAR file,
+        followed by the list of stream files (in the order they are
+        provided). Parameters in each stream file will overwrite those that
+        came before (or simply append to the existing set if they are
+        different)
         """
         inst = cls()
         if tfile is not None:
@@ -183,21 +192,24 @@ class CharmmParameterSet(object):
         return inst
 
     def readParameterFile(self, pfile, permissive=False):
-        """
-        Reads all of the parameters from a parameter file. Versions 36 and
-        later of the CHARMM force field files have an ATOMS section defining
-        all of the atom types.  Older versions need to load this information
-        from the RTF/TOP files.
-
-        Parameters:
-            - pfile (str) : Name of the CHARMM PARameter file to read
-            - permissive (bool) : Accept non-bonbded parameters for undefined 
-                                  atom types (default False)
-
-        Notes: The atom types must all be loaded by the end of this routine.
-        Either supply a PAR file with atom definitions in them or read in a
-        RTF/TOP file first. Failure to do so will result in a raised
-        RuntimeError.
+        """Reads all of the parameters from a parameter file. Versions 36 and later
+        of the CHARMM force field files have an ATOMS section defining all of
+        the atom types.  Older versions need to load this information from the
+        RTF/TOP files.
+
+        Parameters
+        ----------
+        pfile : str
+            Name of the CHARMM PARameter file to read
+        permissive : bool
+            Accept non-bonbded parameters for undefined atom types (default:
+            False).
+
+        Notes
+        -----
+        The atom types must all be loaded by the end of this routine. Either
+        supply a PAR file with atom definitions in them or read in a RTF/TOP
+        file first. Failure to do so will result in a raised RuntimeError.
         """
         conv = CharmmParameterSet._convert
         if isinstance(pfile, str):
@@ -353,7 +365,7 @@ class CharmmParameterSet(object):
                         if dtype.per == dihedral.per:
                             # Replace. Warn if they are different
                             if dtype != dihedral:
-                                warnings.warn('Replacing dihedral %r with %r' % 
+                                warnings.warn('Replacing dihedral %r with %r' %
                                               (dtype, dihedral))
                             self.dihedral_types[key]
                             replaced = True
@@ -487,7 +499,7 @@ class CharmmParameterSet(object):
             ty = CmapType(current_cmap_res, current_cmap_data)
             self.cmap_types[current_cmap] = ty
 
-        # If in permissive mode create an atomtype for every type used in  
+        # If in permissive mode create an atomtype for every type used in
         # the nonbonded parameters. This is a work-around for when all that's
         # available is a CHARMM22 inp file, which has no ATOM/MASS fields
 
@@ -499,7 +511,7 @@ class CharmmParameterSet(object):
             for key in nonbonded_types:
                 if not key in self.atom_types_str:
                     atype =AtomType(name=key, number=idx, mass= float('NaN'), atomic_number= 1 )
-                    self.atom_types_str[key] = atype 
+                    self.atom_types_str[key] = atype
                     self.atom_types_int[idx] = atype
                     idx=idx+1
 
@@ -518,14 +530,17 @@ class CharmmParameterSet(object):
         if own_handle: f.close()
 
     def readTopologyFile(self, tfile):
-        """
-        Reads _only_ the atom type definitions from a topology file. This is
+        """Reads _only_ the atom type definitions from a topology file. This is
         unnecessary for versions 36 and later of the CHARMM force field.
 
-        Parameters:
-            - tfile (str) : Name of the CHARMM TOPology file to read
+        Parameters
+        ----------
+        tfile : str
+            : Name of the CHARMM TOPology file to read
 
-        Note: The CHARMM TOPology file is also called a Residue Topology File
+        Notes
+        -----
+        The CHARMM TOPology file is also called a Residue Topology File
         """
         conv = CharmmParameterSet._convert
         if isinstance(tfile, str):
@@ -564,12 +579,13 @@ class CharmmParameterSet(object):
         if own_handle: f.close()
 
     def readStreamFile(self, sfile):
-        """
-        Reads RTF and PAR sections from a stream file and dispatches the
+        """Reads RTF and PAR sections from a stream file and dispatches the
         sections to readTopologyFile or readParameterFile
 
-        Parameters:
-            - sfile (str or CharmmStreamFile) : Stream file to parse
+        Parameters
+        ----------
+        sfile : str or CharmmStreamFile
+            Stream file to parse
         """
         if isinstance(sfile, CharmmStreamFile):
             f = sfile
@@ -594,15 +610,13 @@ class CharmmParameterSet(object):
         bond, angle, dihedral, improper, or cmap type will pair with EVERY key
         in the type mapping dictionaries that points to the equivalent type
 
-        Returns:
-            - Returns the instance that is being condensed.
-
-        Notes:
-            The return value allows you to condense the types at construction
-            time.
-
-        Example:
+        Example
+        -------
         >>> params = CharmmParameterSet('charmm.prm').condense()
+
+        Returns
+        -------
+        self
         """
         # First scan through all of the bond types
         self._condense_types(self.bond_types)
@@ -631,8 +645,10 @@ class CharmmParameterSet(object):
         """
         Loops through the given dict and condenses all types.
 
-        Parameter:
-            - typedict : Type dictionary to condense
+        Parameters
+        ----------
+        typedict
+            Type dictionary to condense
         """
         keylist = list(typedict.keys())
         for i in range(len(keylist) - 1):