Merge master

.travis.yml

@@ -73,6 +73,7 @@ matrix:
            CUDA=false
            CC=clang
            CXX=clang++
+           DOCS_DEPLOY=true
            CMAKE_FLAGS=""
 
     - sudo: false
@@ -98,11 +99,11 @@ before_install:
   # but this is a fast way to get an apparently functional precompiled
   # build of swig that's more modern than what's in apt.
   - if [[ "$OPENCL" == "false" && "$CUDA" == "false" && "$TRAVIS_OS_NAME" == "linux" ]]; then
-      wget https://anaconda.org/anaconda/swig/3.0.2/download/linux-64/swig-3.0.2-0.tar.bz2;
+      wget https://anaconda.org/omnia/swig/3.0.7/download/linux-64/swig-3.0.7-0.tar.bz2;
       mkdir $HOME/swig;
-      tar -xjvf swig-3.0.2-0.tar.bz2 -C $HOME/swig;
+      tar -xjvf swig-3.0.7-0.tar.bz2 -C $HOME/swig;
       export PATH=$HOME/swig/bin:$PATH;
-      export SWIG_LIB=$HOME/swig/share/swig/3.0.2;
+      export SWIG_LIB=$HOME/swig/share/swig/3.0.7;
     fi
 
   - if [[ "$CUDA" == "true" ]]; then
@@ -140,3 +141,25 @@ script:
   - if [ -s Testing/Temporary/LastTestsFailed.log ]; then
       ctest -I FailedTests.log;
     fi
+  - if [[ ! -z "${DOCS_DEPLOY}" && "${DOCS_DEPLOY}" = "true" ]]; then
+      pip install sphinx numpydoc;
+      make DoxygenApiDocs PythonApiDocs;
+      mkdir -p api-docs;
+      mv api-python api-docs;
+      mv api-c++ api-docs;
+    fi
+
+deploy:
+  - provider: s3
+    access_key_id:
+      secure: "AjE3nuj6kVuf21mOf0aZydW/3S/uCWsaoXC/huRxkxrmsNlnHBNGHZ9N48san1IxZAQM5pyaf7Yo9gkHur9obgq+e3lNgGvPp2mfkNXtLYcLJ46JF4kYliAtutjLWskrLg25Gu3xzF4EQkqSe0Le/oWldWWbTgvvH+KRq/vTHzI="
+    secret_access_key:
+      secure: "ISDQNSG2t0666PULtffo4wsKLFdu622EzuZxmiTxvLkjQGQlqm5+qn1Gd5UMLk7Ts2E0psdnmSrf6LVVCfrrQO/hcZHiJw3ZslMPDBBlRr8Epwdldn98ULhVoyQKtjXjCPzroa2UZCl1RFs4Nwb/VdDlI490XV0Lp4Woj1AT8tY="
+    bucket: "docs.openmm.org"
+    skip_cleanup: true
+    region: us-west-1
+    local_dir: api-docs/
+    upload_dir: development
+    on:
+      branch: master
+      condition: '! -z "${DOCS_DEPLOY}" && "${DOCS_DEPLOY}" = "true"'

CMakeLists.txt

@@ -65,6 +65,11 @@ ELSE(WIN32)
     ENDIF(NOT OPENMM_INSTALL_PREFIX)
 ENDIF(WIN32)
 
+IF(WIN32)
+    ADD_DEFINITIONS(-DWIN32)
+ENDIF(WIN32)
+
+
 # Include CPU-Features for Android
 IF (ANDROID)
     INCLUDE_DIRECTORIES(${ANDROID_NDK}/sources/cpufeatures)
@@ -119,7 +124,7 @@ IF (APPLE AND (NOT PNACL))
         SET (CMAKE_OSX_ARCHITECTURES "x86_64" CACHE STRING "The processor architectures to build for" FORCE)
     ENDIF (NOT CMAKE_OSX_ARCHITECTURES)
     IF (NOT CMAKE_OSX_SYSROOT)
-        EXECUTE_PROCESS(COMMAND "xcrun" "--show-sdk-path" OUTPUT_VARIABLE XCRUN_OSX_SYSROOT RESULT_VARIABLE XCRUN_OSX_SYSROOT_STATUS)
+        EXECUTE_PROCESS(COMMAND "xcrun" "--show-sdk-path" OUTPUT_VARIABLE XCRUN_OSX_SYSROOT RESULT_VARIABLE XCRUN_OSX_SYSROOT_STATUS OUTPUT_STRIP_TRAILING_WHITESPACE)
         IF (XCRUN_OSX_SYSROOT_STATUS EQUAL 0)
             SET (CMAKE_OSX_SYSROOT "${XCRUN_OSX_SYSROOT}" CACHE STRING "SDK Path" FORCE)
         ENDIF (XCRUN_OSX_SYSROOT_STATUS EQUAL 0)

appveyor.yml

@@ -20,7 +20,7 @@ install:
   - "set PATH=C:\\fftw;%PATH%"
 
 # Download and install some OpenMM build dependencies (doxygen, swig)
-  - choco install -y doxygen.portable swig
+  - choco install -y doxygen.portable swig > null
 
 # Set CMake options
   - ps: $env:CMAKE_FLAGS='-DOPENMM_BUILD_PME_PLUGIN=ON -DFFTW_LIBRARY=C:/fftw/libfftw3f-3.lib -DFFTW_INCLUDES=C:/fftw -DCMAKE_BUILD_TYPE=Release -DOPENMM_BUILD_EXAMPLES=OFF -DCMAKE_CXX_FLAGS_RELEASE="/MD /Od /Ob0 /D NDEBUG"'

docs-source/usersguide/application.rst

@@ -1125,6 +1125,13 @@ perform integration on a modified potential energy surface to allow much faster
 sampling of conformations.  For details on how to use them, consult the API
 documentation.
 
+Compound Integrator
+-------------------
+
+The :class:`CompoundIntegrator` class is useful for cases where you want to use
+multiple integration algorithms within a single simulation.  It allows you to
+create multiple integrators, then switch back and forth between them.  For
+details on how to use it, consult the API documentation.
 
 Temperature Coupling
 ====================

libraries/pthreads/include/pthread.h

@@ -121,6 +121,9 @@
 #endif
 
 
+#if _MSC_VER >= 1900
+#include <ctime>
+#else
 /* Windows doesn't have this, so declare it ourselves. */
 struct timespec
 {
@@ -128,6 +131,7 @@ struct timespec
 	long long tv_sec;
 	long long tv_nsec;
 };
+#endif
 
 typedef struct _pthread_cleanup _pthread_cleanup;
 struct _pthread_cleanup

openmmapi/include/OpenMM.h

@@ -36,6 +36,7 @@
 #include "openmm/BrownianIntegrator.h"
 #include "openmm/CMAPTorsionForce.h"
 #include "openmm/CMMotionRemover.h"
+#include "openmm/CompoundIntegrator.h"
 #include "openmm/CustomBondForce.h"
 #include "openmm/CustomCentroidBondForce.h"
 #include "openmm/CustomCompoundBondForce.h"

openmmapi/include/openmm/CMAPTorsionForce.h

@@ -84,12 +84,12 @@ public:
     /**
      * Get the energy values of a map.
      *
-     * @param index   the index of the map for which to get energy values
-     * @param size    the size of the map along each dimension
-     * @param energy  the energy values for the map.  This must be of length size*size.
-     *                The element energy[i+size*j] contains the energy when the first
-     *                torsion angle equals i*2*PI/size and the second torsion angle
-     *                equals j*2*PI/size.
+     * @param index        the index of the map for which to get energy values
+     * @param[out] size    the size of the map along each dimension
+     * @param[out] energy  the energy values for the map.  This must be of length size*size.
+     *                     The element energy[i+size*j] contains the energy when the first
+     *                     torsion angle equals i*2*PI/size and the second torsion angle
+     *                     equals j*2*PI/size.
      */
     void getMapParameters(int index, int& size, std::vector<double>& energy) const;
     /**
@@ -121,16 +121,16 @@ public:
     /**
      * Get the force field parameters for a CMAP torsion term.
      *
-     * @param index the index of the torsion for which to get parameters
-     * @param map   the index of the map to use for this term
-     * @param a1    the index of the first particle forming the first torsion
-     * @param a2    the index of the second particle forming the first torsion
-     * @param a3    the index of the third particle forming the first torsion
-     * @param a4    the index of the fourth particle forming the first torsion
-     * @param b1    the index of the first particle forming the second torsion
-     * @param b2    the index of the second particle forming the second torsion
-     * @param b3    the index of the third particle forming the second torsion
-     * @param b4    the index of the fourth particle forming the second torsion
+     * @param index      the index of the torsion for which to get parameters
+     * @param[out] map   the index of the map to use for this term
+     * @param[out] a1    the index of the first particle forming the first torsion
+     * @param[out] a2    the index of the second particle forming the first torsion
+     * @param[out] a3    the index of the third particle forming the first torsion
+     * @param[out] a4    the index of the fourth particle forming the first torsion
+     * @param[out] b1    the index of the first particle forming the second torsion
+     * @param[out] b2    the index of the second particle forming the second torsion
+     * @param[out] b3    the index of the third particle forming the second torsion
+     * @param[out] b4    the index of the fourth particle forming the second torsion
      */
     void getTorsionParameters(int index, int& map, int& a1, int& a2, int& a3, int& a4, int& b1, int& b2, int& b3, int& b4) const;
     /**

openmmapi/include/openmm/CompoundIntegrator.h

+#ifndef OPENMM_COMPOUNDINTEGRATOR_H_
+#define OPENMM_COMPOUNDINTEGRATOR_H_
+
+/* -------------------------------------------------------------------------- *
+ *                                   OpenMM                                   *
+ * -------------------------------------------------------------------------- *
+ * This is part of the OpenMM molecular simulation toolkit originating from   *
+ * Simbios, the NIH National Center for Physics-Based Simulation of           *
+ * Biological Structures at Stanford, funded under the NIH Roadmap for        *
+ * Medical Research, grant U54 GM072970. See https://simtk.org.               *
+ *                                                                            *
+ * Portions copyright (c) 2015 Stanford University and the Authors.           *
+ * Authors: Peter Eastman                                                     *
+ * Contributors:                                                              *
+ *                                                                            *
+ * 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,   *
+ * and/or sell copies of the Software, and to permit persons to whom the      *
+ * Software is furnished to do so, subject to the following conditions:       *
+ *                                                                            *
+ * The above copyright notice and this permission notice shall be included in *
+ * all copies or substantial portions of the Software.                        *
+ *                                                                            *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,   *
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL    *
+ * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,    *
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR      *
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE  *
+ * USE OR OTHER DEALINGS IN THE SOFTWARE.                                     *
+ * -------------------------------------------------------------------------- */
+
+#include "Integrator.h"
+#include "openmm/Kernel.h"
+#include "internal/windowsExport.h"
+
+namespace OpenMM {
+
+/**
+ * This class allows you to use multiple integration algorithms within a single simulation,
+ * switching back and forth between them.  To use it, create whatever other Integrators
+ * you need, then add all of them to a CustomIntegrator:
+ * 
+ * <tt><pre>
+ * CompoundIntegrator compoundIntegrator;
+ * compoundIntegrator.addIntegrator(new VerletIntegrator(0.001));
+ * compoundIntegrator.addIntegrator(new LangevinIntegrator(300.0, 1.0, 0.001));
+ * </pre></tt>
+ * 
+ * Next create a Context, specifying the CompoundIntegrator as the Integrator to use for
+ * the Context:
+ * 
+ * <tt><pre>
+ * Context context(system, compoundIntegrator);
+ * </pre></tt>
+ * 
+ * Finally, call setCurrentIntegrator() to set which Integrator is active.  That one will
+ * be used for all calls to step() until the next time you change it.
+ * 
+ * <tt><pre>
+ * compoundIntegrator.setCurrentIntegrator(0);
+ * compoundIntegrator.step(1000); // Take 1000 steps of Verlet dynamics
+ * compoundIntegrator.setCurrentIntegrator(1);
+ * compoundIntegrator.step(1000); // Take 1000 steps of Langevin dynamics
+ * </pre></tt>
+ * 
+ * When switching between integrators, it is important to make sure they are compatible with
+ * each other, and that they will interpret the positions and velocities in the same way.
+ * Remember that leapfrog style integrators assume the positions and velocities are offset
+ * from each other by half a time step.  When switching between a leapfrog and non-leapfrog
+ * integrator, you must first adjust the velocities to avoid introducing error.  This is also
+ * true when switching between two leapfrog integrators that use different step sizes,
+ * since they will interpret the velocities as corresponding to different times.
+ */
+
+class OPENMM_EXPORT CompoundIntegrator : public Integrator {
+public:
+    /**
+     * Create a CompoundIntegrator.
+     */
+    explicit CompoundIntegrator();
+    ~CompoundIntegrator();
+    /**
+     * Get the number of Integrators that have been added to this CompoundIntegrator.
+     */
+    int getNumIntegrators() const;
+    /**
+     * Add an Integrator to this CompoundIntegrator.  The Integrator object should have
+     * been created on the heap with the "new" operator.  The CompoundIntegrator takes over
+     * ownership of it, and deletes it when the CompoundIntegrator itself is deleted.
+     * All Integrators must be added before the Context is created.
+     * 
+     * @param integrator    the Integrator to add
+     * @return the index of the Integrator that was added
+     */
+    int addIntegrator(Integrator* integrator);
+    /**
+     * Get a reference to one of the Integrators that have been added to this CompoundIntegrator.
+     * 
+     * @param index     the index of the Integrator to get
+     */
+    Integrator& getIntegrator(int index);
+    /**
+     * Get a const reference to one of the Integrators that have been added to this CompoundIntegrator.
+     * 
+     * @param index     the index of the Integrator to get
+     */
+    const Integrator& getIntegrator(int index) const;
+    /**
+     * Get the index of the current Integrator.
+     */
+    int getCurrentIntegrator() const;
+    /**
+     * Set the current Integrator.
+     * 
+     * @param index    the index of the Integrator to use
+     */
+    void setCurrentIntegrator(int index);
+    /**
+     * Get the size of each time step, in picoseconds.  This method calls getStepSize() on
+     * whichever Integrator has been set as current.
+     * 
+     * @return the step size, measured in ps
+     */
+    double getStepSize() const;
+    /**
+     * Set the size of each time step, in picoseconds.  This method calls setStepSize() on
+     * whichever Integrator has been set as current.
+     * 
+     * @param size    the step size, measured in ps
+     */
+    void setStepSize(double size);
+    /**
+     * Get the distance tolerance within which constraints are maintained, as a fraction of the constrained distance.
+     * This method calls getConstraintTolerance() on whichever Integrator has been set as current.
+     */
+    double getConstraintTolerance() const;
+    /**
+     * Set the distance tolerance within which constraints are maintained, as a fraction of the constrained distance.
+     * This method calls setConstraintTolerance() on whichever Integrator has been set as current.
+     */
+    void setConstraintTolerance(double tol);
+   /**
+     * Advance a simulation through time by taking a series of time steps.  This method
+     * calls step() on whichever Integrator has been set as current.
+     * 
+     * @param steps   the number of time steps to take
+     */
+    void step(int steps);
+protected:
+    /**
+     * This will be called by the Context when it is created.  It informs the Integrator
+     * of what context it will be integrating, and gives it a chance to do any necessary initialization.
+     * It will also get called again if the application calls reinitialize() on the Context.
+     * 
+     * The implementation calls initialize() on each Integrator that has been added to this CompoundIntegrator.
+     */
+    void initialize(ContextImpl& context);
+    /**
+     * This will be called by the Context when it is destroyed to let the Integrator do any necessary
+     * cleanup.  It will also get called again if the application calls reinitialize() on the Context.
+     * 
+     * The implementation calls cleanup() on each Integrator that has been added to this CompoundIntegrator.
+     */
+    void cleanup();
+    /**
+     * Get the names of all Kernels used by this Integrator.
+     * 
+     * The implementation returns the union of all kernel names required by all Integrators that have been added.
+     */
+    std::vector<std::string> getKernelNames();
+    /**
+     * Compute the kinetic energy of the system at the current time.
+     * 
+     * The implementation calls computeKineticEnergy() on whichever Integrator has been set as current.
+     */
+    double computeKineticEnergy();
+private:
+    int currentIntegrator;
+    std::vector<Integrator*> integrators;
+};
+
+} // namespace OpenMM
+
+#endif /*OPENMM_COMPOUNDINTEGRATOR_H_*/

openmmapi/include/openmm/Context.h

@@ -9,7 +9,7 @@
  * Biological Structures at Stanford, funded under the NIH Roadmap for        *
  * Medical Research, grant U54 GM072970. See https://simtk.org.               *
  *                                                                            *
- * Portions copyright (c) 2008-2013 Stanford University and the Authors.      *
+ * Portions copyright (c) 2008-2015 Stanford University and the Authors.      *
  * Authors: Peter Eastman                                                     *
  * Contributors:                                                              *
  *                                                                            *
@@ -165,6 +165,11 @@ public:
      * @param randomSeed     the random number seed to use when selecting velocities
      */
     void setVelocitiesToTemperature(double temperature, int randomSeed=osrngseed());
+    /**
+     * Get all adjustable parameters that have been defined by Force objects in the System, along
+     * with their current values.
+     */
+    const std::map<std::string, double>& getParameters() const;
     /**
      * Get the value of an adjustable parameter defined by a Force object in the System.
      * 

openmmapi/include/openmm/CustomAngleForce.h

@@ -159,7 +159,7 @@ public:
      * Set the default value of a global parameter.
      *
      * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
      */
     void setGlobalParameterDefaultValue(int index, double defaultValue);
     /**
@@ -175,11 +175,11 @@ 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 parameters    the list of parameters for the angle
+     * @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] parameters    the list of parameters for the angle
      */
     void getAngleParameters(int index, int& particle1, int& particle2, int& particle3, std::vector<double>& parameters) const;
     /**

openmmapi/include/openmm/CustomBondForce.h

@@ -159,7 +159,7 @@ public:
      * Set the default value of a global parameter.
      *
      * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
      */
     void setGlobalParameterDefaultValue(int index, double defaultValue);
     /**
@@ -174,10 +174,10 @@ 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 parameters    the list of parameters 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] parameters    the list of parameters for the bond
      */
     void getBondParameters(int index, int& particle1, int& particle2, std::vector<double>& parameters) const;
     /**
@@ -194,7 +194,7 @@ public:
      * an efficient method to update certain parameters in an existing Context without needing to reinitialize it.
      * Simply call setBondParameters() 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 values of per-bond parameters.
      * All other aspects of the Force (such as the energy function) are unaffected and can only be changed by reinitializing
      * the Context.  The set of particles involved in a bond cannot be changed, nor can new bonds be added.

openmmapi/include/openmm/CustomCentroidBondForce.h

@@ -85,7 +85,7 @@ namespace OpenMM {
  *
  * As an example, the following code creates a CustomCentroidBondForce that implements a harmonic force between the
  * centers of mass of two groups of particles.
- * 
+ *
  * <tt><pre>
  * CustomCentroidBondForce* force = new CustomCentroidBondForce(2, "0.5*k*distance(g1,g2)^2");
  * force->addPerBondParameter("k");
@@ -226,7 +226,7 @@ public:
      * Set the default value of a global parameter.
      *
      * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
      */
     void setGlobalParameterDefaultValue(int index, double defaultValue);
     /**
@@ -241,11 +241,11 @@ public:
     /**
      * Get the properties of a group.
      *
-     * @param index       the index of the group to get
-     * @param particles   the indices of the particles in the group
-     * @param weights     the weight used for each particle when computing the center position.
-     *                    If no weights were specified, this vector will be empty indicating that particle
-     *                    masses should be used as weights.
+     * @param index            the index of the group to get
+     * @param[out] particles   the indices of the particles in the group
+     * @param[out] weights     the weight used for each particle when computing the center position.
+     *                         If no weights were specified, this vector will be empty indicating that particle
+     *                         masses should be used as weights.
      */
     void getGroupParameters(int index, std::vector<int>& particles, std::vector<double>& weights) const;
     /**
@@ -268,9 +268,9 @@ public:
     /**
      * Get the properties of a bond.
      *
-     * @param index       the index of the bond to get
-     * @param groups      the indices of the groups in the bond
-     * @param parameters  the list of per-bond parameter values for the bond
+     * @param      index       the index of the bond to get
+     * @param[out] groups      the indices of the groups in the bond
+     * @param[out] parameters  the list of per-bond parameter values for the bond
      */
     void getBondParameters(int index, std::vector<int>& groups, std::vector<double>& parameters) const;
     /**

openmmapi/include/openmm/CustomCompoundBondForce.h

@@ -46,11 +46,11 @@ namespace OpenMM {
  * the energy depends on their positions, is configurable.  It may depend on the positions of individual particles,
  * the distances between pairs of particles, the angles formed by sets of three particles, and the dihedral
  * angles formed by sets of four particles.
- * 
+ *
  * We refer to the particles in a bond as p1, p2, p3, etc.  For each bond, CustomCompoundBondForce evaluates a
  * user supplied algebraic expression to determine the interaction energy.  The expression may depend on the
  * following variables and functions:
- * 
+ *
  * <ul>
  * <li>x1, y1, z1, x2, y2, z2, etc.: The x, y, and z coordinates of the particle positions.  For example, x1
  * is the x coordinate of particle p1, and y3 is the y coordinate of particle p3.</li>
@@ -141,7 +141,7 @@ public:
     }
     /**
      * Get the number of tabulated functions that have been defined.
-     * 
+     *
      * @deprecated This method exists only for backward compatibility.  Use getNumTabulatedFunctions() instead.
      */
     int getNumFunctions() const {
@@ -209,7 +209,7 @@ public:
      * Set the default value of a global parameter.
      *
      * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
      */
     void setGlobalParameterDefaultValue(int index, double defaultValue);
     /**
@@ -223,9 +223,9 @@ public:
     /**
      * Get the properties of a bond.
      *
-     * @param index       the index of the bond to get
-     * @param particles   the indices of the particles in the bond
-     * @param parameters  the list of per-bond parameter values for the bond
+     * @param index            the index of the bond to get
+     * @param[out] particles   the indices of the particles in the bond
+     * @param[out] parameters  the list of per-bond parameter values for the bond
      */
     void getBondParameters(int index, std::vector<int>& particles, std::vector<double>& parameters) const;
     /**
@@ -292,7 +292,7 @@ public:
      * an efficient method to update certain parameters in an existing Context without needing to reinitialize it.
      * Simply call setBondParameters() 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 values of per-bond parameters.
      * All other aspects of the Force (such as the energy function) are unaffected and can only be changed by reinitializing
      * the Context.  The set of particles involved in a bond cannot be changed, nor can new bonds be added.

openmmapi/include/openmm/CustomExternalForce.h

@@ -170,7 +170,7 @@ public:
      * Set the default value of a global parameter.
      *
      * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
      */
     void setGlobalParameterDefaultValue(int index, double defaultValue);
     /**
@@ -184,9 +184,9 @@ public:
     /**
      * Get the force field parameters for a force field term.
      *
-     * @param index         the index of the particle term for which to get parameters
-     * @param particle      the index of the particle this term is applied to
-     * @param parameters    the list of parameters for the force field term
+     * @param index              the index of the particle term for which to get parameters
+     * @param[out] particle      the index of the particle this term is applied to
+     * @param[out] parameters    the list of parameters for the force field term
      */
     void getParticleParameters(int index, int& particle, std::vector<double>& parameters) const;
     /**

openmmapi/include/openmm/CustomGBForce.h

@@ -215,7 +215,7 @@ public:
     }
     /**
      * Get the number of tabulated functions that have been defined.
-     * 
+     *
      * @deprecated This method exists only for backward compatibility.  Use getNumTabulatedFunctions() instead.
      */
     int getNumFunctions() const {
@@ -308,8 +308,8 @@ public:
     /**
      * Set the default value of a global parameter.
      *
-     * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param index         the index of the parameter for which to set the default value
+     * @param defaultValue  the default value of the parameter
      */
     void setGlobalParameterDefaultValue(int index, double defaultValue);
     /**
@@ -323,8 +323,8 @@ public:
     /**
      * Get the nonbonded force parameters for a particle.
      *
-     * @param index       the index of the particle for which to get parameters
-     * @param parameters  the list of parameters for the specified particle
+     * @param index            the index of the particle for which to get parameters
+     * @param[out] parameters  the list of parameters for the specified particle
      */
     void getParticleParameters(int index, std::vector<double>& parameters) const;
     /**
@@ -354,19 +354,19 @@ public:
     /**
      * Get the properties of a computed value.
      *
-     * @param index       the index of the computed value for which to get parameters
-     * @param name        the name of the value
-     * @param expression  an algebraic expression to evaluate when calculating the computed value.  If the
-     *                    ComputationType is SingleParticle, the expression is evaluated independently
-     *                    for each particle, and may depend on its x, y, and z coordinates, as well as the per-particle
-     *                    parameters and previous computed values for that particle.  If the ComputationType is ParticlePair
-     *                    or ParticlePairNoExclusions, the expression is evaluated once for every other
-     *                    particle in the system and summed to get the final value.  In the latter case,
-     *                    the expression may depend on the distance r between the two particles, and on
-     *                    the per-particle parameters and previous computed values for each of them.
-     *                    Append "1" to a variable name to indicate the parameter for the particle whose
-     *                    value is being calculated, and "2" to indicate the particle it is interacting with.
-     * @param type        the method to use for computing this value
+     * @param index            the index of the computed value for which to get parameters
+     * @param[out] name        the name of the value
+     * @param[out] expression  an algebraic expression to evaluate when calculating the computed value.  If the
+     *                         ComputationType is SingleParticle, the expression is evaluated independently
+     *                         for each particle, and may depend on its x, y, and z coordinates, as well as the per-particle
+     *                         parameters and previous computed values for that particle.  If the ComputationType is ParticlePair
+     *                         or ParticlePairNoExclusions, the expression is evaluated once for every other
+     *                         particle in the system and summed to get the final value.  In the latter case,
+     *                         the expression may depend on the distance r between the two particles, and on
+     *                         the per-particle parameters and previous computed values for each of them.
+     *                         Append "1" to a variable name to indicate the parameter for the particle whose
+     *                         value is being calculated, and "2" to indicate the particle it is interacting with.
+     * @param[out] type        the method to use for computing this value
      */
     void getComputedValueParameters(int index, std::string& name, std::string& expression, ComputationType& type) const;
     /**
@@ -406,18 +406,18 @@ public:
     /**
      * Get the properties of a term to the energy computation.
      *
-     * @param index       the index of the term for which to get parameters
-     * @param expression  an algebraic expression to evaluate when calculating the energy.  If the
-     *                    ComputationType is SingleParticle, the expression is evaluated once
-     *                    for each particle, and may depend on its x, y, and z coordinates, as well as the per-particle
-     *                    parameters and computed values for that particle.  If the ComputationType is ParticlePair or
-     *                    ParticlePairNoExclusions, the expression is evaluated once for every pair of
-     *                    particles in the system.  In the latter case,
-     *                    the expression may depend on the distance r between the two particles, and on
-     *                    the per-particle parameters and computed values for each of them.
-     *                    Append "1" to a variable name to indicate the parameter for the first particle
-     *                    in the pair and "2" to indicate the second particle in the pair.
-     * @param type        the method to use for computing this value
+     * @param index            the index of the term for which to get parameters
+     * @param[out] expression  an algebraic expression to evaluate when calculating the energy.  If the
+     *                         ComputationType is SingleParticle, the expression is evaluated once
+     *                         for each particle, and may depend on its x, y, and z coordinates, as well as the per-particle
+     *                         parameters and computed values for that particle.  If the ComputationType is ParticlePair or
+     *                         ParticlePairNoExclusions, the expression is evaluated once for every pair of
+     *                         particles in the system.  In the latter case,
+     *                         the expression may depend on the distance r between the two particles, and on
+     *                         the per-particle parameters and computed values for each of them.
+     *                         Append "1" to a variable name to indicate the parameter for the first particle
+     *                         in the pair and "2" to indicate the second particle in the pair.
+     * @param[out] type        the method to use for computing this value
      */
     void getEnergyTermParameters(int index, std::string& expression, ComputationType& type) const;
     /**
@@ -448,9 +448,9 @@ public:
     /**
      * Get the particles in a pair whose interaction should be excluded.
      *
-     * @param index      the index of the exclusion for which to get particle indices
-     * @param particle1  the index of the first particle in the pair
-     * @param particle2  the index of the second particle in the pair
+     * @param index           the index of the exclusion for which to get particle indices
+     * @param[out] particle1  the index of the first particle in the pair
+     * @param[out] particle2  the index of the second particle in the pair
      */
     void getExclusionParticles(int index, int& particle1, int& particle2) const;
     /**
@@ -517,7 +517,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.
-     * 
+     *
      * This method has several limitations.  The only information it updates is the values of per-particle parameters.
      * All other aspects of the Force (such as the energy function) are unaffected and can only be changed by reinitializing
      * the Context.  Also, this method cannot be used to add new particles, only to change the parameters of existing ones.

openmmapi/include/openmm/CustomHbondForce.h

@@ -171,7 +171,7 @@ public:
     }
     /**
      * Get the number of tabulated functions that have been defined.
-     * 
+     *
      * @deprecated This method exists only for backward compatibility.  Use getNumTabulatedFunctions() instead.
      */
     int getNumFunctions() const {
@@ -282,7 +282,7 @@ public:
      * Set the default value of a global parameter.
      *
      * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
      */
     void setGlobalParameterDefaultValue(int index, double defaultValue);
     /**
@@ -300,13 +300,13 @@ public:
     /**
      * Get the properties of a donor group.
      *
-     * @param index       the index of the donor group to get
-     * @param d1          the index of the first particle for this donor group
-     * @param d2          the index of the second particle for this donor group.  If the group only
-     *                    includes one particle, this will be -1.
-     * @param d3          the index of the third particle for this donor group.  If the group includes
-     *                    less than three particles, this will be -1.
-     * @param parameters  the list of per-donor parameter values for the donor
+     * @param index            the index of the donor group to get
+     * @param[out] d1          the index of the first particle for this donor group
+     * @param[out] d2          the index of the second particle for this donor group.  If the group only
+     *                         includes one particle, this will be -1.
+     * @param[out] d3          the index of the third particle for this donor group.  If the group includes
+     *                         less than three particles, this will be -1.
+     * @param[out] parameters  the list of per-donor parameter values for the donor
      */
     void getDonorParameters(int index, int& d1, int& d2, int& d3, std::vector<double>& parameters) const;
     /**
@@ -336,13 +336,13 @@ public:
     /**
      * Get the properties of an acceptor group.
      *
-     * @param index       the index of the acceptor group to get
-     * @param a1          the index of the first particle for this acceptor group
-     * @param a2          the index of the second particle for this acceptor group.  If the group only
-     *                    includes one particle, this will be -1.
-     * @param a3          the index of the third particle for this acceptor group.  If the group includes
-     *                    less than three particles, this will be -1.
-     * @param parameters  the list of per-acceptor parameter values for the acceptor
+     * @param index            the index of the acceptor group to get
+     * @param[out] a1          the index of the first particle for this acceptor group
+     * @param[out] a2          the index of the second particle for this acceptor group.  If the group only
+     *                         includes one particle, this will be -1.
+     * @param[out] a3          the index of the third particle for this acceptor group.  If the group includes
+     *                         less than three particles, this will be -1.
+     * @param[out] parameters  the list of per-acceptor parameter values for the acceptor
      */
     void getAcceptorParameters(int index, int& a1, int& a2, int& a3, std::vector<double>& parameters) const;
     /**
@@ -368,17 +368,17 @@ public:
     /**
      * Get the donor and acceptor in a pair whose interaction should be excluded.
      *
-     * @param index      the index of the exclusion for which to get donor and acceptor indices
-     * @param particle1  the index of the donor
-     * @param particle2  the index of the acceptor
+     * @param index           the index of the exclusion for which to get donor and acceptor indices
+     * @param[out] particle1  the index of the donor
+     * @param[out] particle2  the index of the acceptor
      */
     void getExclusionParticles(int index, int& donor, int& acceptor) const;
     /**
      * Get the donor and acceptor in a pair whose interaction should be excluded.
      *
      * @param index      the index of the exclusion for which to get donor and acceptor indices
-     * @param particle1  the index of the donor
-     * @param particle2  the index of the acceptor
+     * @param donor      the index of the donor
+     * @param acceptor   the index of the acceptor
      */
     void setExclusionParticles(int index, int donor, int acceptor);
     /**
@@ -437,7 +437,7 @@ public:
      * provides an efficient method to update certain parameters in an existing Context without needing to reinitialize it.
      * Simply call setDonorParameters() and setAcceptorParameters() 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 values of per-donor and per-acceptor parameters.
      * All other aspects of the Force (the energy function, nonbonded method, cutoff distance, etc.) are unaffected and can only
      * be changed by reinitializing the Context.  The set of particles involved in a donor or acceptor cannot be changed, nor can

openmmapi/include/openmm/CustomIntegrator.h

@@ -47,7 +47,7 @@ namespace OpenMM {
  * methods including both deterministic and stochastic integrators, Metropolized
  * integrators, and integrators that must integrate additional quantities along
  * with the particle positions and momenta.
- * 
+ *
  * To create an integration algorithm, you first define a set of variables the
  * integrator will compute.  Variables come in two types: <i>global</i> variables
  * have a single value, while <i>per-DOF</i> variables have a value for every
@@ -57,12 +57,12 @@ namespace OpenMM {
  * the CustomIntegrator.  All variables are persistent between integration
  * steps; once a value is set, it keeps that value until it is changed by the
  * user or recomputed in a later integration step.
- * 
+ *
  * Next, you define the algorithm as a series of computations.  To execute a
  * time step, the integrator performs the list of computations in order.  Each
  * computation updates the value of one global or per-DOF value.  There are
  * several types of computations that can be done:
- * 
+ *
  * <ul>
  * <li>Global: You provide a mathematical expression involving only global
  * variables.  It is evaluated and stored into a global variable.</li>
@@ -78,15 +78,15 @@ namespace OpenMM {
  * <li>Constrain Velocities: The particle velocities are updated so the net
  * velocity along any constrained distance is 0.</li>
  * </ul>
- * 
+ *
  * Like all integrators, CustomIntegrator ignores any particle whose mass is 0.
  * It is skipped when doing per-DOF computations, and is not included when
  * computing sums over degrees of freedom.
- * 
+ *
  * In addition to the variables you define by calling addGlobalVariable() and
  * addPerDofVariable(), the integrator provides the following pre-defined
  * variables:
- * 
+ *
  * <ul>
  * <li>dt: (global) This is the step size being used by the integrator.</li>
  * <li>energy: (global, read-only) This is the current potential energy of the
@@ -123,24 +123,24 @@ namespace OpenMM {
  * <li>A global variable is created for every adjustable parameter defined
  * in the integrator's Context.</li>
  * </ul>
- * 
+ *
  * The following example uses a CustomIntegrator to implement a velocity Verlet
  * integrator:
- * 
+ *
  * <tt><pre>
  * CustomIntegrator integrator(0.001);
  * integrator.addComputePerDof("v", "v+0.5*dt*f/m");
  * integrator.addComputePerDof("x", "x+dt*v");
  * integrator.addComputePerDof("v", "v+0.5*dt*f/m");
  * </pre></tt>
- * 
+ *
  * The first step updates the velocities based on the current forces.
  * The second step updates the positions based on the new velocities, and the
  * third step updates the velocities again.  Although the first and third steps
  * look identical, the forces used in them are different.  You do not need to
  * tell the integrator that; it will recognize that the positions have changed
  * and know to recompute the forces automatically.
- * 
+ *
  * The above example has two problems.  First, it does not respect distance
  * constraints.  To make the integrator work with constraints, you need to add
  * extra steps to tell it when and how to apply them.  Second, it never gives
@@ -149,7 +149,7 @@ namespace OpenMM {
  * or a MonteCarloBarostat can scale particle positions.  You need to add a
  * step to tell the integrator when to do this.  The following example corrects
  * both these problems, using the RATTLE algorithm to apply constraints:
- * 
+ *
  * <tt><pre>
  * CustomIntegrator integrator(0.001);
  * integrator.addPerDofVariable("x1", 0);
@@ -161,12 +161,12 @@ namespace OpenMM {
  * integrator.addComputePerDof("v", "v+0.5*dt*f/m+(x-x1)/dt");
  * integrator.addConstrainVelocities();
  * </pre></tt>
- * 
+ *
  * CustomIntegrator can be used to implement multiple time step integrators.  The
  * following example shows an r-RESPA integrator.  It assumes the quickly changing
  * forces are in force group 0 and the slowly changing ones are in force group 1.
  * It evaluates the "fast" forces four times as often as the "slow" forces.
- * 
+ *
  * <tt><pre>
  * CustomIntegrator integrator(0.004);
  * integrator.addComputePerDof("v", "v+0.5*dt*f1/m");
@@ -208,25 +208,25 @@ namespace OpenMM {
  * freedom may not give the correct answer.  For example, in a leapfrog integrator
  * the velocities are "delayed" by half a time step, so the above formula would
  * give the kinetic energy half a time step ago, not at the current time.
- * 
+ *
  * Call setKineticEnergyExpression() to set an expression for the kinetic energy.
  * It is computed for every degree of freedom (excluding ones whose mass is 0) and
  * the result is summed.  The default expression is "m*v*v/2", which is correct
  * for many integrators.
- * 
+ *
  * As example, the following line defines the correct way to compute kinetic energy
  * when using a leapfrog algorithm:
- * 
+ *
  * <tt><pre>
  * integrator.setKineticEnergyExpression("m*v1*v1/2; v1=v+0.5*dt*f/m");
  * </pre></tt>
- * 
+ *
  * The kinetic energy expression may depend on the following pre-defined variables:
  * x, v, f, m, dt.  It also may depend on user-defined global and per-DOF variables,
  * and on the values of adjustable parameters defined  in the integrator's Context.
  * It may <i>not</i> depend on any other variable, such as the potential energy,
  * the force from a single force group, or a random number.
- * 
+ *
  * Expressions may involve the operators + (add), - (subtract), * (multiply), / (divide), and ^ (power), and the following
  * functions: sqrt, exp, log, sin, cos, sec, csc, tan, cot, asin, acos, atan, sinh, cosh, tanh, erf, erfc, min, max, abs, floor, ceil, step, delta, select.  All trigonometric functions
  * are defined in radians, and log is the natural logarithm.  step(x) = 0 if x is less than 0, 1 otherwise.  delta(x) = 1 if x is 0, 0 otherwise.
@@ -278,7 +278,7 @@ public:
     };
     /**
      * Create a CustomIntegrator.
-     * 
+     *
      * @param stepSize       the step size with which to integrate the system (in picoseconds)
      */
     CustomIntegrator(double stepSize);
@@ -302,7 +302,7 @@ public:
     }
     /**
      * Define a new global variable.
-     * 
+     *
      * @param name          the name of the variable
      * @param initialValue  the variable will initially be set to this value
      * @return the index of the variable that was added
@@ -310,14 +310,14 @@ public:
     int addGlobalVariable(const std::string& name, double initialValue);
     /**
      * Get the name of a global variable.
-     * 
+     *
      * @param index    the index of the variable to get
      * @return the name of the variable
      */
     const std::string& getGlobalVariableName(int index) const;
     /**
      * Define a new per-DOF variable.
-     * 
+     *
      * @param name          the name of the variable
      * @param initialValue  the variable will initially be set to this value for
      *                      all degrees of freedom
@@ -326,14 +326,14 @@ public:
     int addPerDofVariable(const std::string& name, double initialValue);
     /**
      * Get the name of a per-DOF variable.
-     * 
+     *
      * @param index    the index of the variable to get
      * @return the name of the variable
      */
     const std::string& getPerDofVariableName(int index) const;
     /**
      * Get the current value of a global variable.
-     * 
+     *
      * @param index   the index of the variable to get
      * @return the current value of the variable
      */
@@ -347,21 +347,21 @@ public:
     double getGlobalVariableByName(const std::string& name) const;
     /**
      * Set the value of a global variable.
-     * 
+     *
      * @param index   the index of the variable to set
      * @param value   the new value of the variable
      */
     void setGlobalVariable(int index, double value);
     /**
      * Set the value of a global variable, specified by name.
-     * 
+     *
      * @param name    the name of the variable to set
      * @param value   the new value of the variable
      */
     void setGlobalVariableByName(const std::string& name, double value);
     /**
      * Get the value of a per-DOF variable.
-     * 
+     *
      * @param index   the index of the variable to get
      * @param values  the values of the variable for all degrees of freedom
      *                are stored into this
@@ -370,28 +370,28 @@ public:
     /**
      * Get the value of a per-DOF variable, specified by name.
      *
-     * @param name    the name of the variable to get
-     * @param values  the values of the variable for all degrees of freedom
-     *                are stored into this
+     * @param name         the name of the variable to get
+     * @param[out] values  the values of the variable for all degrees of freedom
+     *                     are stored into this
      */
     void getPerDofVariableByName(const std::string& name, std::vector<Vec3>& values) const;
     /**
      * Set the value of a per-DOF variable.
-     * 
+     *
      * @param index   the index of the variable to set
      * @param values  the new values of the variable for all degrees of freedom
      */
     void setPerDofVariable(int index, const std::vector<Vec3>& values);
     /**
      * Set the value of a per-DOF variable, specified by name.
-     * 
+     *
      * @param name    the name of the variable to set
      * @param values  the new values of the variable for all degrees of freedom
      */
     void setPerDofVariableByName(const std::string& name, const std::vector<Vec3>& values);
     /**
      * Add a step to the integration algorithm that computes a global value.
-     * 
+     *
      * @param variable    the global variable to store the computed value into
      * @param expression  a mathematical expression involving only global variables.
      *                    In each integration step, its value is computed and
@@ -401,7 +401,7 @@ public:
     int addComputeGlobal(const std::string& variable, const std::string& expression);
     /**
      * Add a step to the integration algorithm that computes a per-DOF value.
-     * 
+     *
      * @param variable    the per-DOF variable to store the computed value into
      * @param expression  a mathematical expression involving both global and
      *                    per-DOF variables.  In each integration step, its value
@@ -412,7 +412,7 @@ public:
     int addComputePerDof(const std::string& variable, const std::string& expression);
     /**
      * Add a step to the integration algorithm that computes a sum over degrees of freedom.
-     * 
+     *
      * @param variable    the global variable to store the computed value into
      * @param expression  a mathematical expression involving both global and
      *                    per-DOF variables.  In each integration step, its value
@@ -425,28 +425,28 @@ public:
     /**
      * Add a step to the integration algorithm that updates particle positions so
      * all constraints are satisfied.
-     * 
+     *
      * @return the index of the step that was added
      */
     int addConstrainPositions();
     /**
      * Add a step to the integration algorithm that updates particle velocities
      * so the net velocity along all constraints is 0.
-     * 
+     *
      * @return the index of the step that was added
      */
     int addConstrainVelocities();
     /**
      * Add a step to the integration algorithm that allows Forces to update the
      * context state.
-     * 
+     *
      * @return the index of the step that was added
      */
     int addUpdateContextState();
     /**
      * Add a step which begins a new "if" block.
      *
-     * @param expression  a mathematical expression involving a comparison operator
+     * @param condition   a mathematical expression involving a comparison operator
      *                    and global variables.  All steps between this one and
      *                    the end of the block are executed only if the condition
      *                    is true.
@@ -457,7 +457,7 @@ public:
     /**
      * Add a step which begins a new "while" block.
      *
-     * @param expression  a mathematical expression involving a comparison operator
+     * @param condition   a mathematical expression involving a comparison operator
      *                    and global variables.  All steps between this one and
      *                    the end of the block are executed repeatedly as long as
      *                    the condition remains true.
@@ -474,14 +474,15 @@ public:
     int endBlock();
     /**
      * Get the details of a computation step that has been added to the integration algorithm.
-     * 
-     * @param index      the index of the computation step to get
-     * @param type       on exit, the type of computation this step performs
-     * @param variable   on exit, the variable into which this step stores its result.  If this
-     *                   step does not store a result in a variable, this will be an
-     *                   empty string.
-     * @param expression on exit, the expression this step evaluates.  If this step does not
-     *                   evaluate an expression, this will be an empty string.
+     *
+     * @param      index       the index of the computation step to get
+     * @param[out] type        the type of computation this step performs
+     * @param[out] variable    the variable into which this step stores its
+     *                         result.  If this step does not store a result in
+     *                         a variable, this will be an empty string.
+     * @param[out] expression  the expression this step evaluates.  If
+     *                         this step does not evaluate an expression, this
+     *                         will be an empty string.
      */
     void getComputationStep(int index, ComputationType& type, std::string& variable, std::string& expression) const;
     /**
@@ -519,7 +520,7 @@ public:
     }
     /**
      * Advance a simulation through time by taking a series of time steps.
-     * 
+     *
      * @param steps   the number of time steps to take
      */
     void step(int steps);

openmmapi/include/openmm/CustomManyParticleForce.h

@@ -47,13 +47,13 @@ namespace OpenMM {
  * every possible set of N particles in the system.  It may depend on the positions of the individual particles,
  * the distances between pairs of particles, the angles formed by sets of three particles, and the dihedral
  * angles formed by sets of four particles.
- * 
+ *
  * Be aware that the cost of evaluating an N-particle interaction increases very rapidly with N.  Values larger
  * than N=3 are rarely used.
- * 
+ *
  * We refer to a set of particles for which the energy is being evaluated  as p1, p2, p3, etc.  The energy expression
  * may depend on the following variables and functions:
- * 
+ *
  * <ul>
  * <li>x1, y1, z1, x2, y2, z2, etc.: The x, y, and z coordinates of the particle positions.  For example, x1
  * is the x coordinate of particle p1, and y3 is the y coordinate of particle p3.</li>
@@ -68,16 +68,16 @@ namespace OpenMM {
  * that defines the interaction energy of each set of particles.  Then call addPerParticleParameter() to define per-particle
  * parameters, and addGlobalParameter() to define global parameters.  The values of per-particle parameters are specified as
  * part of the system definition, while values of global parameters may be modified during a simulation by calling Context::setParameter().
- * 
+ *
  * Next, call addParticle() once for each particle in the System to set the values of its per-particle parameters.
  * The number of particles for which you set parameters must be exactly equal to the number of particles in the
  * System, or else an exception will be thrown when you try to create a Context.  After a particle has been added,
  * you can modify its parameters by calling setParticleParameters().  This will have no effect on Contexts that already exist
  * unless you call updateParametersInContext().
- * 
+ *
  * Multi-particle interactions can be very expensive to evaluate, so they are usually used with a cutoff distance.  The exact
  * interpretation of the cutoff depends on the permutation mode, as discussed below.
- * 
+ *
  * CustomManyParticleForce also lets you specify "exclusions", particular pairs of particles whose interactions should be
  * omitted from force and energy calculations.  This is most often used for particles that are bonded to each other.
  * If you specify a pair of particles as an exclusion, <i>all</i> sets that include those two particles will be omitted.
@@ -97,7 +97,7 @@ namespace OpenMM {
  * <tt><pre>
  * force->addGlobalParameter("C", 1.0);
  * </pre></tt>
- * 
+ *
  * Notice that the expression is symmetric with respect to the particles.  It only depends on the products
  * cos(theta1)*cos(theta2)*cos(theta3) and r12*r13*r23, both of which are unchanged if the labels p1, p2, and p3 are permuted.
  * This is required because we specified SinglePermutation as the permutation mode.  (This is the default, so we did not
@@ -105,36 +105,36 @@ namespace OpenMM {
  * each set of particles.  No guarantee is made about which particle will be identified as p1, p2, etc.  Therefore, the
  * energy <i>must</i> be symmetric with respect to exchange of particles.  Otherwise, the results would be undefined because
  * permuting the labels would change the energy.
- * 
+ *
  * Not all many-particle interactions work this way.  Another common pattern is for the expression to describe an interaction
  * between one central particle and other nearby particles.  An example of this is the 3-particle piece of the Stillinger-Weber
  * potential:
- * 
+ *
  * <tt><pre>CustomManyParticleForce* force = new CustomManyParticleForce(3,
  *     "L*eps*(cos(theta1)+1/3)^2*exp(sigma*gamma/(r12-a*sigma))*exp(sigma*gamma/(r13-a*sigma));"
        "r12 = distance(p1,p2); r13 = distance(p1,p3); theta1 = angle(p3,p1,p2)");
  * force->setPermutationMode(CustomManyParticleForce::UniqueCentralParticle);
  * </pre></tt>
- * 
+ *
  * When the permutation mode is set to UniqueCentralParticle, particle p1 is treated as the central particle.  For a set of
  * N particles, the expression is evaluated N times, once with each particle as p1.  The expression can therefore treat
  * p1 differently from the other particles.  Notice that it is still symmetric with respect to p2 and p3, however.  There
  * is no guarantee about how those labels will be assigned to particles.
- * 
+ *
  * Distance cutoffs are applied in different ways depending on the permutation mode.  In SinglePermutation mode, every particle
  * in the set must be within the cutoff distance of every other particle.  If <i>any</i> two particles are further apart than
  * the cutoff distance, the interaction is skipped.  In UniqueCentralParticle mode, each particle must be within the cutoff
  * distance of the central particle, but not necessarily of all the other particles.  The cutoff may therefore exclude a subset
  * of the permutations of a set of particles.
- * 
+ *
  * Another common situation is that some particles are fundamentally different from others, causing the expression to be
  * inherently non-symmetric.  An example would be a water model that involves three particles, two of which <i>must</i> be
  * hydrogen and one of which <i>must</i> be oxygen.  Cases like this can be implemented using particle types.
- * 
+ *
  * A particle type is an integer that you specify when you call addParticle().  (If you omit the argument, it defaults
  * to 0.)  For the water model, you could specify 0 for all oxygen atoms and 1 for all hydrogen atoms.  You can then
  * call setTypeFilter() to specify the list of allowed types for each of the N particles involved in an interaction:
- * 
+ *
  * <tt><pre>
  * set&lt;int&gt; oxygenTypes, hydrogenTypes;
  * oxygenTypes.insert(0);
@@ -147,7 +147,7 @@ namespace OpenMM {
  * This specifies that of the three particles in an interaction, p1 must be oxygen while p2 and p3 must be hydrogen.
  * The energy expression will only be evaluated for triplets of particles that satisfy those requirements.  It will
  * still only be evaluated once for each triplet, so it must still be symmetric with respect to p2 and p3.
- * 
+ *
  * Expressions may involve the operators + (add), - (subtract), * (multiply), / (divide), and ^ (power), and the following
  * functions: sqrt, exp, log, sin, cos, sec, csc, tan, cot, asin, acos, atan, sinh, cosh, tanh, erf, erfc, min, max, abs, floor, ceil, step, delta, select.  All trigonometric functions
  * are defined in radians, and log is the natural logarithm.  step(x) = 0 if x is less than 0, 1 otherwise.  delta(x) = 1 if x is 0, 0 otherwise.
@@ -337,7 +337,7 @@ public:
      * Set the default value of a global parameter.
      *
      * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
      */
     void setGlobalParameterDefaultValue(int index, double defaultValue);
     /**
@@ -352,9 +352,9 @@ public:
     /**
      * Get the nonbonded force parameters for a particle.
      *
-     * @param index       the index of the particle for which to get parameters
-     * @param parameters  the list of parameters for the specified particle
-     * @param type        the type of the specified particle
+     * @param index            the index of the particle for which to get parameters
+     * @param[out] parameters  the list of parameters for the specified particle
+     * @param[out] type        the type of the specified particle
      */
     void getParticleParameters(int index, std::vector<double>& parameters, int& type) const;
     /**
@@ -367,7 +367,7 @@ public:
     void setParticleParameters(int index, const std::vector<double>& parameters, int type);
     /**
      * Add a particle pair to the list of interactions that should be excluded.
-     * 
+     *
      * In many cases, you can use createExclusionsFromBonds() rather than adding each exclusion explicitly.
      *
      * @param particle1  the index of the first particle in the pair
@@ -378,9 +378,9 @@ public:
     /**
      * Get the particles in a pair whose interaction should be excluded.
      *
-     * @param index      the index of the exclusion for which to get particle indices
-     * @param particle1  the index of the first particle in the pair
-     * @param particle2  the index of the second particle in the pair
+     * @param index           the index of the exclusion for which to get particle indices
+     * @param[out] particle1  the index of the first particle in the pair
+     * @param[out] particle2  the index of the second particle in the pair
      */
     void getExclusionParticles(int index, int& particle1, int& particle2) const;
     /**
@@ -404,16 +404,16 @@ public:
      * Get the allowed particle types for one of the particles involved in the interaction.
      * If this an empty set (the default), no filter is applied and all interactions are evaluated
      * regardless of the type of the specified particle.
-     * 
-     * @param index    the index of the particle within the interaction (between 0 and getNumParticlesPerSet())
-     * @param types    the allowed types for the specified particle
+     *
+     * @param index         the index of the particle within the interaction (between 0 and getNumParticlesPerSet())
+     * @param[out] types    the allowed types for the specified particle
      */
     void getTypeFilter(int index, std::set<int>& types) const;
     /**
      * Set the allowed particle types for one of the particles involved in the interaction.
      * If this an empty set (the default), no filter is applied and all interactions are evaluated
      * regardless of the type of the specified particle.
-     * 
+     *
      * @param index    the index of the particle within the interaction (between 0 and getNumParticlesPerSet())
      * @param types    the allowed types for the specified particle
      */
@@ -454,7 +454,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.
-     * 
+     *
      * This method has several limitations.  The only information it updates is the values of per-particle parameters.
      * All other aspects of the Force (the energy function, nonbonded method, cutoff distance, etc.) are unaffected and can
      * only be changed by reinitializing the Context.  Also, this method cannot be used to add new particles, only to change

openmmapi/include/openmm/CustomNonbondedForce.h

@@ -54,7 +54,7 @@ namespace OpenMM {
  * between the particles, as well as on any parameters you choose.  Then call addPerParticleParameter() to define per-particle
  * parameters, and addGlobalParameter() to define global parameters.  The values of per-particle parameters are specified as
  * part of the system definition, while values of global parameters may be modified during a simulation by calling Context::setParameter().
- * 
+ *
  * Next, call addParticle() once for each particle in the System to set the values of its per-particle parameters.
  * The number of particles for which you set parameters must be exactly equal to the number of particles in the
  * System, or else an exception will be thrown when you try to create a Context.  After a particle has been added,
@@ -80,17 +80,17 @@ namespace OpenMM {
  * above example, the energy only depends on the products sigma1*sigma2 and epsilon1*epsilon2, both of which are unchanged
  * if the labels 1 and 2 are reversed.  In contrast, if it depended on the difference sigma1-sigma2, the results would
  * be undefined, because reversing the labels 1 and 2 would change the energy.
- * 
+ *
  * CustomNonbondedForce can operate in two modes.  By default, it computes the interaction of every particle in the System
  * with every other particle.  Alternatively, you can restrict it to only a subset of particle pairs.  To do this, specify
  * one or more "interaction groups".  An interaction group consists of two sets of particles that should interact with
  * each other.  Every particle in the first set interacts with every particle in the second set.  For example, you might use
  * this feature to compute a solute-solvent interaction energy, while omitting all interactions between two solute atoms
  * or two solvent atoms.
- * 
+ *
  * To create an interaction group, call addInteractionGroup().  You may add as many interaction groups as you want.
  * Be aware of the following:
- * 
+ *
  * <ul>
  * <li>Exclusions are still taken into account, so the interactions between excluded pairs are omitted.</li>
  * <li>Likewise, a particle will never interact with itself, even if it appears in both sets of an interaction group.</li>
@@ -99,7 +99,7 @@ namespace OpenMM {
  * <li>If you do not add any interaction groups to a CustomNonbondedForce, it operates in the default mode where every
  * particle interacts with every other particle.</li>
  * </ul>
- * 
+ *
  * When using a cutoff, by default the interaction is sharply truncated at the cutoff distance.
  * Optionally you can instead use a switching function to make the interaction smoothly go to zero over a finite
  * distance range.  To enable this, call setUseSwitchingFunction().  You must also call setSwitchingDistance()
@@ -109,16 +109,16 @@ namespace OpenMM {
  * to write and understand.  It allows you to use the same energy expression with or without a cutoff.  Also, when using
  * a long range correction (see below), separating out the switching function allows the correction to be calculated
  * more accurately.
- * 
+ *
  * Another optional feature of this class is to add a contribution to the energy which approximates the effect of all
  * interactions beyond the cutoff in a periodic system.  When running a simulation at constant pressure, this can improve
  * the quality of the result.  Call setUseLongRangeCorrection() to enable it.
- * 
+ *
  * Computing the long range correction takes negligible work in each time step, but it does require an expensive precomputation
  * at the start of the simulation.  Furthermore, that precomputation must be repeated every time a global parameter changes
  * (or when you modify per-particle parameters by calling updateParametersInContext()).  This means that if parameters change
  * frequently, the long range correction can be very slow.  For this reason, it is disabled by default.
- * 
+ *
  * Expressions may involve the operators + (add), - (subtract), * (multiply), / (divide), and ^ (power), and the following
  * functions: sqrt, exp, log, sin, cos, sec, csc, tan, cot, asin, acos, atan, sinh, cosh, tanh, erf, erfc, min, max, abs, floor, ceil, step, delta, select.  All trigonometric functions
  * are defined in radians, and log is the natural logarithm.  step(x) = 0 if x is less than 0, 1 otherwise.  delta(x) = 1 if x is 0, 0 otherwise.
@@ -192,7 +192,7 @@ public:
     }
     /**
      * Get the number of tabulated functions that have been defined.
-     * 
+     *
      * @deprecated This method exists only for backward compatibility.  Use getNumTabulatedFunctions() instead.
      */
     int getNumFunctions() const {
@@ -318,7 +318,7 @@ public:
      * Set the default value of a global parameter.
      *
      * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
      */
     void setGlobalParameterDefaultValue(int index, double defaultValue);
     /**
@@ -332,8 +332,8 @@ public:
     /**
      * Get the nonbonded force parameters for a particle.
      *
-     * @param index       the index of the particle for which to get parameters
-     * @param parameters  the list of parameters for the specified particle
+     * @param index            the index of the particle for which to get parameters
+     * @param[out] parameters  the list of parameters for the specified particle
      */
     void getParticleParameters(int index, std::vector<double>& parameters) const;
     /**
@@ -345,7 +345,7 @@ public:
     void setParticleParameters(int index, const std::vector<double>& parameters);
     /**
      * Add a particle pair to the list of interactions that should be excluded.
-     * 
+     *
      * In many cases, you can use createExclusionsFromBonds() rather than adding each exclusion explicitly.
      *
      * @param particle1  the index of the first particle in the pair
@@ -356,9 +356,9 @@ public:
     /**
      * Get the particles in a pair whose interaction should be excluded.
      *
-     * @param index      the index of the exclusion for which to get particle indices
-     * @param particle1  the index of the first particle in the pair
-     * @param particle2  the index of the second particle in the pair
+     * @param index           the index of the exclusion for which to get particle indices
+     * @param[out] particle1  the index of the first particle in the pair
+     * @param[out] particle2  the index of the second particle in the pair
      */
     void getExclusionParticles(int index, int& particle1, int& particle2) const;
     /**
@@ -431,7 +431,7 @@ public:
     void setFunctionParameters(int index, const std::string& name, const std::vector<double>& values, double min, double max);
     /**
      * Add an interaction group.  An interaction will be computed between every particle in set1 and every particle in set2.
-     * 
+     *
      * @param set1    the first set of particles forming the interaction group
      * @param set2    the second set of particles forming the interaction group
      * @return the index of the interaction group that was added
@@ -439,15 +439,15 @@ public:
     int addInteractionGroup(const std::set<int>& set1, const std::set<int>& set2);
     /**
      * Get the parameters for an interaction group.
-     * 
-     * @param index   the index of the interaction group for which to get parameters
-     * @param set1    the first set of particles forming the interaction group
-     * @param set2    the second set of particles forming the interaction group
+     *
+     * @param index        the index of the interaction group for which to get parameters
+     * @param[out] set1    the first set of particles forming the interaction group
+     * @param[out] set2    the second set of particles forming the interaction group
      */
     void getInteractionGroupParameters(int index, std::set<int>& set1, std::set<int>& set2) const;
     /**
      * Set the parameters for an interaction group.
-     * 
+     *
      * @param index   the index of the interaction group for which to set parameters
      * @param set1    the first set of particles forming the interaction group
      * @param set2    the second set of particles forming the interaction group
@@ -458,7 +458,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.
-     * 
+     *
      * This method has several limitations.  The only information it updates is the values of per-particle parameters.
      * All other aspects of the Force (the energy function, nonbonded method, cutoff distance, etc.) are unaffected and can
      * only be changed by reinitializing the Context.  Also, this method cannot be used to add new particles, only to change

openmmapi/include/openmm/CustomTorsionForce.h

@@ -159,7 +159,7 @@ public:
      * Set the default value of a global parameter.
      *
      * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
      */
     void setGlobalParameterDefaultValue(int index, double defaultValue);
     /**
@@ -176,12 +176,12 @@ 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 parameters    the list of parameters 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] parameters    the list of parameters for the torsion
      */
     void getTorsionParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, std::vector<double>& parameters) const;
     /**
@@ -200,7 +200,7 @@ public:
      * an efficient method to update certain parameters in an existing Context without needing to reinitialize it.
      * Simply call setTorsionParameters() 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 values of per-torsion parameters.
      * All other aspects of the Force (such as the energy function) are unaffected and can only be changed by reinitializing
      * the Context.  The set of particles involved in a torsion cannot be changed, nor can new torsions be added.