Package ffx.openmm

Class CustomAngleForce

java.lang.Object
ffx.openmm.Force
ffx.openmm.CustomAngleForce
Direct Known Subclasses:
AngleForce
public class CustomAngleForce extends Force
This class implements interactions between sets of three particles that depend on the angle between them. Unlike HarmonicAngleForce, the functional form of the interaction is completely customizable, and may involve arbitrary algebraic expressions. In addition to the angle formed by the particles, it may depend on arbitrary global and per-angle parameters.

To use this class, create a CustomAngleForce object, passing an algebraic expression to the constructor that defines the interaction energy between each set of particles. The expression may depend on theta, the angle formed by the particles, as well as on any parameters you choose. Then call addPerAngleParameter() to define per-angle parameters, and addGlobalParameter() to define global parameters. The values of per-angle parameters are specified as part of the system definition, while values of global parameters may be modified during a simulation by calling Context.setParameter(). Finally, call addAngle() once for each angle. After an angle has been added, you can modify its parameters by calling setAngleParameters(). This will have no effect on Contexts that already exist unless you call updateParametersInContext().

As an example, the following code creates a CustomAngleForce that implements a harmonic potential: 

    CustomAngleForce force = new CustomAngleForce("0.5*k*(theta-theta0)^2");

This force depends on two parameters: the spring constant k and equilibrium angle theta0. The following code defines these parameters: 

    force.addPerAngleParameter("k");
    force.addPerAngleParameter("theta0");

This class also has the ability to compute derivatives of the potential energy with respect to global parameters. Call addEnergyParameterDerivative() to request that the derivative with respect to a particular parameter be computed. You can then query its value in a Context by calling getState() on it.

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, atan2, 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. select(x,y,z) = z if x = 0, y otherwise.

  • Constructor Details

    • CustomAngleForce

      public CustomAngleForce(String energy)
      Create a CustomAngleForce.
      Parameters:
      energy - an algebraic expression giving the interaction energy between three particles as a function of theta, the angle between them

  • Method Details

    • addAngle

      public int addAngle(int i1, int i2, int i3, DoubleArray parameters)
      Add an angle term to the force field.
      Parameters:
      i1 - the index of the first particle connected by the angle
      i2 - the index of the second particle connected by the angle
      i3 - the index of the third particle connected by the angle
      parameters - the list of parameters for the new angle
      Returns:
      the index of the angle that was added

    • addEnergyParameterDerivative

      public void addEnergyParameterDerivative(String name)
      Request that this Force compute the derivative of its energy with respect to a global parameter. The parameter must have already been added with addGlobalParameter().
      Parameters:
      name - the name of the parameter

    • addGlobalParameter

      public int addGlobalParameter(String name, double value)
      Add a new global parameter that the interaction may depend on. The default value provided to this method is the initial value of the parameter in newly created Contexts. You can change the value at any time by calling setParameter() on the Context.
      Parameters:
      name - the name of the parameter
      value - the default value of the parameter
      Returns:
      the index of the parameter that was added

    • addPerAngleParameter

      public int addPerAngleParameter(String name)
      Add a new per-angle parameter that the interaction may depend on.
      Parameters:
      name - the name of the parameter
      Returns:
      the index of the parameter that was added

    • destroy

      public void destroy()
      Destroy the force.
      Specified by:
      destroy in class Force

    • getAngleParameters

      public void getAngleParameters(int index, IntBuffer i1, IntBuffer i2, IntBuffer i3, DoubleArray parameters)
      Get the force field parameters for an angle term.
      Parameters:
      index - the index of the angle for which to get parameters
      i1 - the index of the first particle connected by the angle
      i2 - the index of the second particle connected by the angle
      i3 - the index of the third particle connected by the angle
      parameters - the list of parameters for the angle

    • getAngleParameters

      public void getAngleParameters(int index, com.sun.jna.ptr.IntByReference i1, com.sun.jna.ptr.IntByReference i2, com.sun.jna.ptr.IntByReference i3, DoubleArray parameters)
      Get the force field parameters for an angle term.
      Parameters:
      index - the index of the angle for which to get parameters
      i1 - the index of the first particle connected by the angle
      i2 - the index of the second particle connected by the angle
      i3 - the index of the third particle connected by the angle
      parameters - the list of parameters for the angle

    • getEnergyFunction

      public String getEnergyFunction()
      Get the algebraic expression that gives the interaction energy for each angle

    • getEnergyParameterDerivativeName

      public String getEnergyParameterDerivativeName(int index)
      Get the name of a global parameter with respect to which this Force should compute the derivative of the energy.
      Parameters:
      index - the index of the parameter derivative, between 0 and getNumEnergyParameterDerivatives()
      Returns:
      the parameter name

    • getGlobalParameterDefaultValue

      public double getGlobalParameterDefaultValue(int index)
      Get the default value of a global parameter.
      Parameters:
      index - the index of the parameter for which to get the default value
      Returns:
      the parameter default value

    • getGlobalParameterName

      public String getGlobalParameterName(int index)
      Get the name of a global parameter.
      Parameters:
      index - The index of the parameter.
      Returns:
      The name of the parameter.

    • getNumAngles

      public int getNumAngles()
      Get the number of angles.
      Returns:
      The number of angles.

    • getNumEnergyParameterDerivatives

      public int getNumEnergyParameterDerivatives()
      Get the number of parameters with respect to which the derivative of the energy should be computed.
      Returns:
      The number of parameters.

    • getNumGlobalParameters

      public int getNumGlobalParameters()
      Get the number of global parameters.
      Returns:
      The number of global parameters.

    • getNumPerAngleParameters

      public int getNumPerAngleParameters()
      Get the number of per-angle parameters.
      Returns:
      The number of per-angle parameters.

    • getPerAngleParameterName

      public String getPerAngleParameterName(int index)
      Get the name of a per-angle parameter.
      Parameters:
      index - The index of the parameter.
      Returns:
      The name of the parameter.

    • setAngleParameters

      public void setAngleParameters(int index, int i1, int i2, int i3, DoubleArray parameters)
      Set the parameters for one angle in the OpenMM System.
      Parameters:
      index - The index of the angle.
      i1 - The index of the first atom.
      i2 - The index of the second atom.
      i3 - The index of the third atom.
      parameters - The angle parameters.

    • setEnergyFunction

      public void setEnergyFunction(String energy)
      Set the energy function expression.
      Parameters:
      energy - The energy function expression.

    • setGlobalParameterDefaultValue

      public void setGlobalParameterDefaultValue(int index, double value)
      Set the default value of a global parameter.
      Parameters:
      index - The index of the parameter.
      value - The default value of the parameter.

    • setGlobalParameterName

      public void setGlobalParameterName(int index, String name)
      Set the name of a global parameter.
      Parameters:
      index - The index of the parameter.
      name - The name of the parameter.

    • setPerAngleParameterName

      public void setPerAngleParameterName(int index, String name)
      Set the name of a per-angle parameter.
      Parameters:
      index - The index of the parameter.
      name - The name of the parameter.

    • setUsesPeriodicBoundaryConditions

      public void setUsesPeriodicBoundaryConditions(boolean periodic)
      Set whether this force uses periodic boundary conditions.
      Parameters:
      periodic - If true, periodic boundary conditions will be used.

    • updateParametersInContext

      public void updateParametersInContext(Context context)
      Update the parameters in the OpenMM Context.
      Parameters:
      context - The OpenMM Context.

    • usesPeriodicBoundaryConditions

      public boolean usesPeriodicBoundaryConditions()
      Check if the force uses periodic boundary conditions.
      Overrides:
      usesPeriodicBoundaryConditions in class Force
      Returns:
      True if the force uses periodic boundary conditions.