Added documentation for CustomManyParticleForce

docs-source/usersguide/application.rst

@@ -2298,6 +2298,61 @@ must include an attribute called :code:`radius`\ .
 CustomGBForce also allows you to define tabulated functions.  See section
 :ref:`tabulated-functions` for details.
 
+<CustomManyParticleForce>
+=========================
+
+To add a CustomManyParticleForce to the System, include a tag that looks like this:
+
+.. code-block:: xml
+
+    <CustomManyParticleForce particlesPerSet="3" permutationMode="UniqueCentralParticle"
+        bondCutoff="3" energy="scale*(distance(p1,p2)-r1)*(distance(p1,p3)-r1)">
+     <GlobalParameter name="scale" defaultValue="1"/>
+     <PerParticleParameter name="r"/>
+     <TypeFilter index="0" types="1,2"/>
+     <Atom type="0" r="0.31" filterType="0"/>
+     <Atom type="1" r="0.25" filterType="0"/>
+     <Atom type="2" r="0.33" filterType="1"/>
+     ...
+    </CustomManyParticleForce>
+
+The energy expression for the CustomManyParticleForce is specified by the
+:code:`energy` attribute.  This is a mathematical expression that gives the
+energy of each pairwise interaction as a function of various particle coordinates,
+distances, and angles.  See the API documentation for details.  :code:`particlesPerSet`
+specifies the number of particles involved in the interaction and
+:code:`permutationMode` specifies the permutation mode.
+
+The expression may depend on an arbitrary list of global or per-atom
+parameters.  Use a :code:`<GlobalParameter>` tag to define a global
+parameter, and a :code:`<PerAtomParameter>` tag to define a per-atom
+parameter.
+
+Exclusions are created automatically based on the :code:`bondCutoff` attribute.
+After setting the nonbonded parameters for all atoms, the force field calls
+:code:`createExclusionsFromBonds()` on the CustomManyParticleForce, passing in this
+value as its argument.  To avoid creating exclusions, set :code:`bondCutoff` to 0.
+
+Type filters may be specified with a :code:`<TypeFilter>` tag.  The :code:`index`
+attribute specifies the index of the particle to apply the filter to, and
+:code:`types` is a comma separated list of allowed types.
+
+Each :code:`<Atom>` tag specifies the parameters for one atom type
+(specified with the :code:`type` attribute) or atom class (specified with
+the :code:`class` attribute).  It is fine to mix these two methods, having
+some tags specify a type and others specify a class.  However you do it, you
+must make sure that a unique set of parameters is defined for every atom type.
+In addition, each :code:`<Atom>` tag must include the :code:`filterType`
+attribute, which specifies the atom type for use in type filters.
+The remaining attributes are the values to use for the per-atom parameters. All
+per-atom parameters must be specified for every :code:`<Atom>` tag, and the
+attribute name must match the name of the parameter.  For instance, if there is
+a per-atom parameter with the name “radius”, then every :code:`<Atom>` tag
+must include an attribute called :code:`radius`\ .
+
+CustomManyParticleForce also allows you to define tabulated functions.  See section
+:ref:`tabulated-functions` for details.
+
 Writing Custom Expressions
 ==========================
 

docs-source/usersguide/theory.rst

@@ -892,6 +892,54 @@ Parameters may be specified in two ways:
 * Per-bond parameters are defined by specifying a value for each bond.
 
 
+CustomManyParticleForce
+***********************
+
+CustomManyParticleForce is similar to CustomNonbondedForce in that it represents
+a custom nonbonded interaction between particles, but it allows the interaction
+to depend on more than two particles.  This allows it to represent a wide range
+of non-pairwise interactions.  It is defined by specifying the number of
+particles :math:`N` involved in the interaction and how the energy depends on
+their positions.  More specifically, it takes a user specified energy function
+
+.. math::
+   E=f(\{x_i\},\{r_i\},\{\theta_i\},\{\phi_i\})
+
+that may depend on an arbitrary set of positions {\ :math:`x_i`\ }, distances
+{\ :math:`r_i`\ }, angles {\ :math:`\theta_i`\ }, and dihedral angles
+{\ :math:`\phi_i`\ } from a particular set of :math:`N` particles.
+
+Each distance, angle, or dihedral is defined by specifying a sequence of
+particles chosen from among the particles in the set.  A distance
+variable is defined by two particles, and equals the distance between them.  An
+angle variable is defined by three particles, and equals the angle between them.
+A dihedral variable is defined by four particles, and equals the angle between
+the first and last particles about the axis formed by the middle two particles.
+It is equal to zero when the first and last particles are on the same side of
+the axis.
+
+In addition to depending on positions, distances, angles, and dihedrals, the
+energy may also depend on an arbitrary set of user defined parameters.
+Parameters may be specified in two ways:
+
+* Global parameters have a single, fixed value.
+* Per-particle parameters are defined by specifying a value for each particle.
+
+The energy function is evaluated one or more times for every unique set of
+:math:`N` particles in the system.  The exact number of times depends on the 
+*permutation mode*\ .  A set of :math:`N` particles has :math:`N!` possible
+permutations.  In :code:`SinglePermutation` mode, the function is evaluated
+for a single arbitrarily chosen one of those permutations.  In
+:code:`UniqueCentralParticle` mode, the function is evaluated for :math:`N` of
+those permutations, once with each particle as the "central particle".
+
+The number of times the energy function is evaluated can be further restricted
+by specifying *type filters*\ .  Each particle may have a "type" assigned to it,
+and then each of the :math:`N` particles involved in an interaction may be
+restricted to only a specified set of types.  This provides a great deal of
+flexibility in controlling which particles interact with each other.
+
+
 CustomGBForce
 *************