Merge branch 'docstrings' of github.com:rmcgibbo/openmm into docstrings

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

@@ -40,11 +40,11 @@ namespace OpenMM {
 
 /**
  * This class implements a buffered 14-7 potential used to model van der Waals forces.
- * 
+ *
  * To use it, create an AmoebaVdwForce object then call addParticle() once for each particle.  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 call updateParametersInContext().
- * 
+ *
  * A unique feature of this class is that the interaction site for a particle does not need to be
  * exactly at the particle's location.  Instead, it can be placed a fraction of the distance from that
  * particle to another one.  This is typically done for hydrogens to place the interaction site slightly
@@ -84,7 +84,7 @@ public:
 
     /**
      * Set 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
@@ -96,20 +96,20 @@ 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;
 
 
     /**
      * Add the force field parameters for a vdw particle.
-     * 
+     *
      * @param parentIndex     the index of the parent particle
      * @param sigma           vdw sigma
      * @param epsilon         vdw epsilon
@@ -121,28 +121,28 @@ public:
 
     /**
      * Set sigma combining rule
-     * 
+     *
      * @param sigmaCombiningRule   sigma combining rule:  'ARITHMETIC', 'GEOMETRIC'. 'CUBIC-MEAN'
      */
     void setSigmaCombiningRule(const std::string& sigmaCombiningRule);
 
     /**
      * Get sigma combining rule
-     * 
+     *
      * @return sigmaCombiningRule   sigma combining rule:  'ARITHMETIC', 'GEOMETRIC'. 'CUBIC-MEAN'
      */
     const std::string& getSigmaCombiningRule(void) const;
 
     /**
      * Set epsilon combining rule
-     * 
+     *
      * @param epsilonCombiningRule   epsilon combining rule:   'ARITHMETIC', 'GEOMETRIC'. 'HARMONIC', 'HHG'
      */
     void setEpsilonCombiningRule(const std::string& epsilonCombiningRule);
 
     /**
      * Get epsilon combining rule
-     * 
+     *
      * @return epsilonCombiningRule   epsilon combining rule:  'ARITHMETIC', 'GEOMETRIC'. 'HARMONIC', 'HHG'
      */
     const std::string& getEpsilonCombiningRule(void) const;
@@ -169,7 +169,7 @@ public:
 
     /**
      * Set exclusions for specified particle
-     * 
+     *
      * @param particleIndex particle index
      * @param exclusions vector of exclusions
      */
@@ -177,9 +177,9 @@ 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;
 
@@ -207,7 +207,7 @@ public:
      * an efficient method to update certain parameters in an existing Context without needing to reinitialize it.
      * Simply call setParticleParameters() to modify this object's parameters, then call updateParametersInContext()
      * to copy them over to the Context.
-     * 
+     *
      * The only information this method updates is the values of per-particle parameters.  All other aspects of the Force
      * (the nonbonded method, the cutoff distance, etc.) are unaffected and can only be changed by reinitializing the Context.
      */

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,16 @@ 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 index           the index of the pair for which to get parameters
+     * @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 +156,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
+import re
 import sys
+import textwrap
+from inspect import cleandoc
+from numpydoc.docscrape import NumpyDocString
+
 
-# 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.
+# 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.
 
 input = open(sys.argv[1])
+
 while True:
     line = input.readline()
     if len(line) == 0:
@@ -15,46 +24,57 @@ 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('"""'):
-            line = stripped[3:]
-            readingParameters = False
-            while line.find('"""') == -1:
-                docstrings.append(line)
+        l = line.strip()
+        if l.startswith('"""') or l.startswith("'''"):
+            if l.count('"""') == 2 or l.count("'''") == 2:
+                docstringlines.append(l[3:-3])
+            else:
+                docstringlines.append(l[3:])
                 line = input.readline()
-                if line.strip() == 'Parameters:':
-                    readingParameters = True
+                l = line.strip()
+                while l.find('"""') == -1 and l.find("'''") == -1:
+                    docstringlines.append(line.rstrip())
                     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)            
-        
+                    l = line.strip()
+                if line.rstrip().endswith('"""') or line.rstrip().endswith("'''"):
+                    # last line
+                    docstringlines.append(line.rstrip()[:-3])
+
+        docstring = NumpyDocString(cleandoc('\n'.join(docstringlines)))
+        # print(docstringlines)
+
         # Print out the docstring in Doxygen syntax, followed by the declaration.
-        
-        for s in docstrings:
-            print("%s##%s" % (prefix, s.strip()))
-        print(declaration)
-        if len(docstrings) == 0:
-            print(line)
+        for line in docstring['Summary']:
+            print('{prefix}## {line}'.format(prefix=prefix, line=line))
+        if len(docstring['Extended Summary']) > 0:
+            print('{prefix}##'.format(prefix=prefix))
+            for line in docstring['Extended Summary']:
+                print('{prefix}## {line}'.format(prefix=prefix, line=line.strip()))
+        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, end='')
+        if len(docstringlines) == 0:
+            print(line, end='')
     else:
-        print(line)
+        print(line, end='')
\ No newline at end of file

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,22 +37,26 @@ 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
-         - E (energy) The energy cutoff to use
+
+        Parameters
+        ----------
+        dt : time
+            The integration time step to use
+        alpha : energy
+            The alpha parameter to use
+        E : energy
+            The energy cutoff to use
         """
         CustomIntegrator.__init__(self, dt)
         self.addGlobalVariable("alpha", alpha)
@@ -64,23 +68,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,21 +98,26 @@ 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
-         - alphaGroup (energy) The alpha parameter to use for the boosted force group
-         - EGroup (energy) The energy cutoff to use for the boosted force group
+
+        Parameters
+        ----------
+        dt : time
+            The integration time step to use
+        group : int
+            The force group to apply the boost to
+        alphaGroup : energy
+            The alpha parameter to use for the boosted force group
+        EGroup : energy
+            The energy cutoff to use for the boosted force group
         """
         CustomIntegrator.__init__(self, dt)
         self.addGlobalVariable("alphaGroup", alphaGroup)
@@ -124,29 +133,34 @@ 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
+
+        Parameters
+        ----------
+        groupEnergy : energy
+            the actual potential energy of the boosted force group
+
+        Returns
+        -------
+        the value of the effective potential
         """
         alphaGroup = self.getAlphaGroup()
         EGroup = self.getEGroup()
@@ -161,24 +175,31 @@ 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.
 
-        Parameters:
-         - dt (time) The integration time step to use
-         - group (int) The force group to apply the second boost to
-         - alphaTotal (energy) The alpha parameter to use for the total energy
-         - ETotal (energy) The energy cutoff to use for the total energy
-         - alphaGroup (energy) The alpha parameter to use for the boosted force group
-         - EGroup (energy) The energy cutoff to use for the boosted force group
+        Parameters
+        ----------
+        dt : time
+            The integration time step to use
+        group : int
+            The force group to apply the second boost to
+        alphaTotal : energy
+            The alpha parameter to use for the total energy
+        ETotal : energy
+            The energy cutoff to use for the total energy
+        alphaGroup : energy
+            The alpha parameter to use for the boosted force group
+        EGroup : energy
+            The energy cutoff to use for the boosted force group
         """
         CustomIntegrator.__init__(self, dt)
         self.addGlobalVariable("alphaTotal", alphaTotal)
@@ -201,46 +222,52 @@ 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
-        Returns: 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
+
+        Returns
+        -------
+        the value of the effective potential
         """
         alphaTotal = self.getAlphaTotal()
         ETotal = self.getETotal()

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,52 @@ 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
+        -------
+        System
+            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,14 +610,8 @@ 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()
         """
         # First scan through all of the bond types
@@ -631,8 +641,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):