Skip to content

GitLab

Commit 98d053d4 authored by Robert McGibbon's avatar Robert McGibbon
Browse files

Improve docstrings 

Swigged python docstrings now include documented return values and type
information or their arguments. They are generated in numpydoc format.
Furthermore, all of the Python app layer docstrings have been changed
to numpydoc format. The filterPythonFiles.py script which helps to
generate the Doxygen Python API docs has been updated to reflect these
changes.
parent 596a4197
Hide whitespace changes
Inline Side-by-side
Showing with 333 additions and 332 deletions
openmmapi/include/openmm/CMAPTorsionForce.h
View file @ 98d053d4
......@@ -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/CustomAngleForce.h
View file @ 98d053d4
......@@ -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
View file @ 98d053d4
......@@ -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
View file @ 98d053d4
......@@ -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
View file @ 98d053d4
......@@ -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
View file @ 98d053d4
......@@ -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
View file @ 98d053d4
......@@ -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
View file @ 98d053d4
......@@ -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
View file @ 98d053d4
......@@ -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
View file @ 98d053d4
......@@ -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
View file @ 98d053d4
......@@ -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
View file @ 98d053d4
......@@ -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.
......
openmmapi/include/openmm/GBSAOBCForce.h
View file @ 98d053d4
......@@ -40,14 +40,14 @@ namespace OpenMM {
/**
* This class implements an implicit solvation force using the GBSA-OBC model.
*
*
* To use this class, create a GBSAOBCForce object, then call addParticle() once for each particle in the
* System to define its parameters. The number of particles for which you define GBSA 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 force field parameters
* by calling setParticleParameters(). This will have no effect on Contexts that already exist unless you
* call updateParametersInContext().
*
*
* When using this Force, the System should also include a NonbondedForce, and both objects must specify
* identical charges for all particles. Otherwise, the results will not be correct. Furthermore, if the
* nonbonded method is set to CutoffNonPeriodic or CutoffPeriodic, you should call setReactionFieldDielectric(1.0)
......@@ -98,16 +98,16 @@ public:
int addParticle(double charge, double radius, double scalingFactor);
/**
* 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 GBSA radius of the particle, measured in nm
* @param scalingFactor the OBC 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 GBSA radius of the particle, measured in nm
* @param[out] scalingFactor the OBC scaling factor for the particle
*/
void getParticleParameters(int index, double& charge, double& radius, double& scalingFactor) const;
/**
* Set the force field parameters for a particle.
*
*
* @param index the index of the particle for which to set parameters
* @param charge the charge of the particle, measured in units of the proton charge
* @param radius the GBSA radius of the particle, measured in nm
......@@ -177,7 +177,7 @@ public:
* provides 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. Furthermore, this method cannot be used to add new particles, only to
......
openmmapi/include/openmm/GBVIForce.h
View file @ 98d053d4
......@@ -46,13 +46,13 @@ namespace OpenMM {
* 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 force field parameters
* by calling setParticleParameters().
*
*
* @deprecated This class is not supported by most platforms, and will eventually be removed. You can implement the same force with CustomGBForce.
*/
class OPENMM_EXPORT GBVIForce : public Force {
public:
/**
/**
* This is an enumeration of the different methods that may be used for handling long range nonbonded forces.
*/
enum NonbondedMethod {
......@@ -70,9 +70,9 @@ public:
* each other particle. Interactions beyond the cutoff distance are ignored.
*/
CutoffPeriodic = 2,
};
};
/**
/**
* This is an enumeration of the different methods that may be used for scaling of the Born radii.
*/
enum BornRadiusScalingMethod {
......@@ -84,7 +84,7 @@ public:
* Use quintic spline scaling function
*/
QuinticSpline = 1
};
};
/*
* Create a GBVIForce.
......@@ -108,16 +108,16 @@ public:
int addParticle(double charge, double radius, double gamma);
/**
* 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 GBSA radius of the particle, measured in nm
* @param gamma the gamma parameter
*
* @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 GBSA radius of the particle, measured in nm
* @param[out] gamma the gamma parameter
*/
void getParticleParameters(int index, double& charge, double& radius, double& gamma) const;
/**
* Set the force field parameters for a particle.
*
*
* @param index the index of the particle for which to set parameters
* @param charge the charge of the particle, measured in units of the proton charge
* @param radius the GB/VI radius of the particle, measured in nm
......@@ -125,36 +125,36 @@ public:
*/
void setParticleParameters(int index, double charge, double radius, double gamma);
/**
* Add a bond
* Add a bond
*
* @param particle1 the index of the first particle
* @param particle1 the index of the first particle
* @param particle2 the index of the second particle
* @param distance the distance between the two particles, measured in nm
* @return the index of the bond that was added
*/
int addBond(int particle1, int particle2, double distance);
/**
/**
* Get the parameters defining a bond
*
* @param index the index of the bond for which to get parameters
* @param particle1 the index of the first particle involved in the bond
* @param particle2 the index of the second particle involved in the bond
* @param distance the distance between the two particles, measured in nm
*
* @param index the index of the bond for which to get parameters
* @param[out] particle1 the index of the first particle involved in the bond
* @param[out] particle2 the index of the second particle involved in the bond
* @param[out] distance the distance between the two particles, measured in nm
*/
void getBondParameters(int index, int& particle1, int& particle2, double& distance) const;
/**
* Set 1-2 bonds
*
*
* @param index index of the bond for which to set parameters
* @param particle1 index of first atom in bond
* @param particle2 index of second atom in bond
* @param bondLength bond length, measured in nm
*/
void setBondParameters( int index, int particle1, int particle2, double bondLength);
/**
/**
* Get number of bonds
*
*
* @return number of bonds
*/
int getNumBonds() const;
......@@ -183,49 +183,49 @@ public:
void setSoluteDielectric(double dielectric) {
soluteDielectric = dielectric;
}
/**
/**
* Get the method used for handling long range nonbonded interactions.
*/
NonbondedMethod getNonbondedMethod() const;
/**
/**
* Set the method used for handling long range nonbonded interactions.
*/
void setNonbondedMethod(NonbondedMethod method);
/**
/**
* Get the cutoff distance (in nm) being used for nonbonded interactions. If the NonbondedMethod in use
* is NoCutoff, this value will have no effect.
*
* @return the cutoff distance, measured in nm
*/
double getCutoffDistance() const;
/**
/**
* Set the cutoff distance (in nm) being used for nonbonded interactions. If the NonbondedMethod in use
* is NoCutoff, this value will have no effect.
*
* @param distance the cutoff distance, measured in nm
*/
void setCutoffDistance(double distance);
/**
/**
* Get Born radius scaling method
*/
BornRadiusScalingMethod getBornRadiusScalingMethod() const;
/**
/**
* Set Born radius scaling method
*/
void setBornRadiusScalingMethod( BornRadiusScalingMethod method);
/**
/**
* Get the lower limit factor used in the quintic spline scaling method (typically 0.5-0.8)
*/
double getQuinticLowerLimitFactor() const;
/**
/**
* Set the lower limit factor used in the quintic spline scaling method (typically 0.5-0.8)
*/
void setQuinticLowerLimitFactor(double quinticLowerLimitFactor );
/**
/**
* Get the upper limit used in the quintic spline scaling method, measured in nm (~5.0)
*/
double getQuinticUpperBornRadiusLimit() const;
/**
/**
* Set the upper limit used in the quintic spline scaling method, measured in nm (~5.0)
*/
void setQuinticUpperBornRadiusLimit(double quinticUpperBornRadiusLimit);
......
openmmapi/include/openmm/HarmonicAngleForce.h
View file @ 98d053d4
......@@ -72,18 +72,18 @@ public:
int addAngle(int particle1, int particle2, int particle3, double angle, double k);
/**
* 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 forming the angle
* @param particle2 the index of the second particle forming the angle
* @param particle3 the index of the third particle forming the angle
* @param angle the equilibrium angle, measured in radians
* @param k the harmonic 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 forming the angle
* @param[out] particle2 the index of the second particle forming the angle
* @param[out] particle3 the index of the third particle forming the angle
* @param[out] angle the equilibrium angle, measured in radians
* @param[out] k the harmonic force constant for the angle, measured in kJ/mol/radian^2
*/
void getAngleParameters(int index, int& particle1, int& particle2, int& particle3, double& angle, double& k) const;
/**
* Set the force field parameters for an angle term.
*
*
* @param index the index of the angle for which to set parameters
* @param particle1 the index of the first particle forming the angle
* @param particle2 the index of the second particle forming the angle
......@@ -97,7 +97,7 @@ public:
* an efficient method to update certain parameters in an existing Context without needing to reinitialize it.
* Simply call setAngleParameters() 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-angle parameters. The set of particles involved
* in a angle cannot be changed, nor can new angles be added.
*/
......
openmmapi/include/openmm/HarmonicBondForce.h
View file @ 98d053d4
......@@ -71,17 +71,17 @@ public:
int addBond(int particle1, int particle2, double length, double k);
/**
* 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 k the harmonic force constant for the bond, measured in kJ/mol/nm^2
*
* @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] k the harmonic force constant for the bond, measured in kJ/mol/nm^2
*/
void getBondParameters(int index, int& particle1, int& particle2, double& length, double& k) const;
/**
* 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
......@@ -94,7 +94,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.
*
*
* The only information this method updates is the values of per-bond parameters. The set of particles involved
* in a bond cannot be changed, nor can new bonds be added.
*/
......
openmmapi/include/openmm/NonbondedForce.h
View file @ 98d053d4
......@@ -65,13 +65,13 @@ namespace OpenMM {
* This class provides a convenience method for this case called createExceptionsFromBonds(). You pass to it
* a list of bonds and the scale factors to use for 1-4 interactions. It identifies all pairs of particles which
* are separated by 1, 2, or 3 bonds, then automatically creates exceptions for them.
*
*
* When using a cutoff, by default Lennard-Jones interactions are 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()
* to specify the distance at which the interaction should begin to decrease. The switching distance must be
* less than the cutoff distance.
*
*
* Another optional feature of this class (enabled by default) is to add a contribution to the energy which approximates
* the effect of all Lennard-Jones interactions beyond the cutoff in a periodic system. When running a simulation
* at constant pressure, this can improve the quality of the result. Call setUseDispersionCorrection() to set whether
......@@ -182,7 +182,7 @@ public:
* which is acceptable. This value is used to select the reciprocal space cutoff and separation
* 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.
*
*
* For PME calculations, if setPMEParameters() is used to set alpha to something other than 0,
* this value is ignored.
*/
......@@ -192,7 +192,7 @@ public:
* which is acceptable. This value is used to select the reciprocal space cutoff and separation
* 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.
*
*
* For PME calculations, if setPMEParameters() is used to set alpha to something other than 0,
* this value is ignored.
*/
......@@ -200,17 +200,17 @@ public:
/**
* Get the parameters to use for PME calculations. If alpha is 0 (the default), these parameters are
* ignored and instead their values are chosen based on the Ewald error tolerance.
*
* @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[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 getPMEParameters(double& alpha, int& nx, int& ny, int& nz) const;
/**
* Set the parameters to use for PME calculations. If alpha is 0 (the default), these parameters are
* ignored and instead their values are chosen based on the Ewald error tolerance.
*
*
* @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
......@@ -222,12 +222,12 @@ public:
* on the allowed grid sizes, the values that are actually used may be slightly different from those
* specified with setPMEParameters(), 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;
/**
......@@ -246,10 +246,10 @@ public:
/**
* Get the nonbonded force 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 sigma the sigma parameter of the Lennard-Jones potential (corresponding to the van der Waals radius of the particle), measured in nm
* @param epsilon the epsilon parameter of the Lennard-Jones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol
* @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] sigma the sigma parameter of the Lennard-Jones potential (corresponding to the van der Waals radius of the particle), measured in nm
* @param[out] epsilon the epsilon parameter of the Lennard-Jones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol
*/
void getParticleParameters(int index, double& charge, double& sigma, double& epsilon) const;
/**
......@@ -282,20 +282,20 @@ public:
int addException(int particle1, int particle2, double chargeProd, double sigma, double epsilon, bool replace = false);
/**
* Get the force field parameters for an interaction that should be calculated differently from others.
*
* @param index the index of the interaction for which to get parameters
* @param particle1 the index of the first particle involved in the interaction
* @param particle2 the index of the second particle involved in the interaction
* @param chargeProd the scaled product of the atomic charges (i.e. the strength of the Coulomb interaction), measured in units of the proton charge squared
* @param sigma the sigma parameter of the Lennard-Jones potential (corresponding to the van der Waals radius of the particle), measured in nm
* @param epsilon the epsilon parameter of the Lennard-Jones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol
*
* @param index the index of the interaction for which to get parameters
* @param[out] particle1 the index of the first particle involved in the interaction
* @param[out] particle2 the index of the second particle involved in the interaction
* @param[out] chargeProd the scaled product of the atomic charges (i.e. the strength of the Coulomb interaction), measured in units of the proton charge squared
* @param[out] sigma the sigma parameter of the Lennard-Jones potential (corresponding to the van der Waals radius of the particle), measured in nm
* @param[out] epsilon the epsilon parameter of the Lennard-Jones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol
*/
void getExceptionParameters(int index, int& particle1, int& particle2, double& chargeProd, double& sigma, double& epsilon) const;
/**
* Set the force field parameters for an interaction that should be calculated differently from others.
* If chargeProd and epsilon are both equal to 0, this will cause the interaction to be completely omitted from
* force and energy calculations.
*
*
* @param index the index of the interaction for which to get parameters
* @param particle1 the index of the first particle involved in the interaction
* @param particle2 the index of the second particle involved in the interaction
......@@ -347,7 +347,7 @@ public:
* time step integrators to evaluate direct and reciprocal space interactions at different intervals: setForceGroup()
* specifies the group for direct space, and setReciprocalSpaceForceGroup() specifies the group for reciprocal space.
* If this is -1 (the default value), the same force group is used for reciprocal space as for direct space.
*
*
* @param group the group index. Legal values are between 0 and 31 (inclusive), or -1 to use the same force group
* that is specified for direct space.
*/
......@@ -357,7 +357,7 @@ public:
* provides an efficient method to update certain parameters in an existing Context without needing to reinitialize it.
* Simply call setParticleParameters() and setExceptionParameters() 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 particles and exceptions.
* 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, only the chargeProd, sigma, and epsilon values of an exception
......
openmmapi/include/openmm/PeriodicTorsionForce.h
View file @ 98d053d4
......@@ -74,20 +74,20 @@ public:
int addTorsion(int particle1, int particle2, int particle3, int particle4, int periodicity, double phase, double k);
/**
* Get the force field parameters for a periodic torsion term.
*
* @param index the index of the torsion for which to get parameters
* @param particle1 the index of the first particle forming the torsion
* @param particle2 the index of the second particle forming the torsion
* @param particle3 the index of the third particle forming the torsion
* @param particle4 the index of the fourth particle forming the torsion
* @param periodicity the periodicity of the torsion
* @param phase the phase offset of the torsion, measured in radians
* @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 forming the torsion
* @param[out] particle2 the index of the second particle forming the torsion
* @param[out] particle3 the index of the third particle forming the torsion
* @param[out] particle4 the index of the fourth particle forming the torsion
* @param[out] periodicity the periodicity of the torsion
* @param[out] phase the phase offset of the torsion, measured in radians
* @param[out] k the force constant for the torsion
*/
void getTorsionParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, int& periodicity, double& phase, double& k) const;
/**
* Set the force field parameters for a periodic torsion term.
*
*
* @param index the index of the torsion for which to set parameters
* @param particle1 the index of the first particle forming the torsion
* @param particle2 the index of the second particle forming the torsion
......@@ -103,7 +103,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.
*
*
* The only information this method updates is the values of per-torsion parameters. The set of particles involved
* in a torsion cannot be changed, nor can new torsions be added.
*/
......
openmmapi/include/openmm/RBTorsionForce.h
View file @ 98d053d4
......@@ -77,23 +77,23 @@ public:
int addTorsion(int particle1, int particle2, int particle3, int particle4, double c0, double c1, double c2, double c3, double c4, double c5);
/**
* Get the force field parameters for a Ryckaert-Bellemans torsion term.
*
* @param index the index of the torsion for which to get parameters
* @param particle1 the index of the first particle forming the torsion
* @param particle2 the index of the second particle forming the torsion
* @param particle3 the index of the third particle forming the torsion
* @param particle4 the index of the fourth particle forming the torsion
* @param c0 the coefficient of the constant term, measured in kJ/mol
* @param c1 the coefficient of the 1st order term, measured in kJ/mol
* @param c2 the coefficient of the 2nd order term, measured in kJ/mol
* @param c3 the coefficient of the 3rd order term, measured in kJ/mol
* @param c4 the coefficient of the 4th order term, measured in kJ/mol
* @param c5 the coefficient of the 5th order term, measured in kJ/mol
*
* @param index the index of the torsion for which to get parameters
* @param[out] particle1 the index of the first particle forming the torsion
* @param[out] particle2 the index of the second particle forming the torsion
* @param[out] particle3 the index of the third particle forming the torsion
* @param[out] particle4 the index of the fourth particle forming the torsion
* @param[out] c0 the coefficient of the constant term, measured in kJ/mol
* @param[out] c1 the coefficient of the 1st order term, measured in kJ/mol
* @param[out] c2 the coefficient of the 2nd order term, measured in kJ/mol
* @param[out] c3 the coefficient of the 3rd order term, measured in kJ/mol
* @param[out] c4 the coefficient of the 4th order term, measured in kJ/mol
* @param[out] c5 the coefficient of the 5th order term, measured in kJ/mol
*/
void getTorsionParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, double& c0, double& c1, double& c2, double& c3, double& c4, double& c5) const;
/**
* Set the force field parameters for a Ryckaert-Bellemans torsion term.
*
*
* @param index the index of the torsion for which to set parameters
* @param particle1 the index of the first particle forming the torsion
* @param particle2 the index of the second particle forming the torsion
......@@ -112,7 +112,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.
*
*
* The only information this method updates is the values of per-torsion parameters. The set of particles involved
* in a torsion cannot be changed, nor can new torsions be added.
*/
......
openmmapi/include/openmm/State.h
View file @ 98d053d4
......@@ -43,7 +43,7 @@ namespace OpenMM {
/**
* A State object records a snapshot of the current state of a simulation at a point in time.
* You create it by calling getState() on a Context.
*
*
* When a State is created, you specify what information should be stored in it. This saves
* time and memory by only copying in the information that you actually want. This is especially
* important for forces and energies, since they may need to be calculated. If you query a
......@@ -81,7 +81,7 @@ public:
const std::vector<Vec3>& getForces() const;
/**
* Get the total kinetic energy of the system. If this State does not contain energies, this will throw an exception.
*
*
* Note that this may be different from simply mv<sup>2</sup>/2 summed over all particles. For example, a leapfrog
* integrator will store velocities offset by half a step, so they must be adjusted before computing the kinetic energy.
* This routine returns the kinetic energy at the current time, computed in a way that is appropriate for whatever
......@@ -95,9 +95,9 @@ public:
/**
* Get the vectors defining the axes of the periodic box (measured in nm).
*
* @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 getPeriodicBoxVectors(Vec3& a, Vec3& b, Vec3& c) const;
/**
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment