Package ffx.openmm

Class CustomHbondForce

java.lang.Object
ffx.openmm.Force
ffx.openmm.CustomHbondForce
public class CustomHbondForce extends Force
This class supports a wide variety of energy functions used to represent hydrogen bonding. It computes interactions between "donor" particle groups and "acceptor" particle groups, where each group may include up to three particles. Typically a donor group consists of a hydrogen atom and the atoms it is bonded to, and an acceptor group consists of a negatively charged atom and the atoms it is bonded to.

We refer to the particles in a donor group as d1, d2 and d3, and the particles in an acceptor group as a1, a2, and a3. For each donor and each acceptor, CustomHbondForce evaluates a user supplied algebraic expression to determine the interaction energy. The expression may depend on arbitrary distances, angles, and dihedral angles defined by any of the six particles involved. The function distance(p1, p2) is the distance between the particles p1 and p2 (where "p1" and "p2" should be replaced by the names of the actual particles to calculate the distance between), angle(p1, p2, p3) is the angle formed by the three specified particles, and dihedral(p1, p2, p3, p4) is the dihedral angle formed by the four specified particles.

The expression also may involve tabulated functions, and may depend on arbitrary global, per-donor, and per-acceptor parameters. It also optionally supports periodic boundary conditions and cutoffs for long range interactions.

To use this class, create a CustomHbondForce object, passing an algebraic expression to the constructor that defines the interaction energy between each donor and acceptor. Then call addPerDonorParameter() to define per-donor parameters, addPerAcceptorParameter() to define per-acceptor parameters, and addGlobalParameter() to define global parameters. The values of per-donor and per-acceptor 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 addDonor() and addAcceptor() to define donors and acceptors and specify their parameter values. After a donor or acceptor has been added, you can modify its parameters by calling setDonorParameters() or setAcceptorParameters(). This will have no effect on Contexts that already exist unless you call updateParametersInContext().

CustomHbondForce also lets you specify "exclusions", particular combinations of donors and acceptors whose interactions should be omitted from force and energy calculations. This is most often used for particles that are bonded to each other.

As an example, the following code creates a CustomHbondForce that implements a simple harmonic potential to keep the distance between a1 and d1, and the angle formed by a1-d1-d2, near ideal values: 


 CustomHbondForce force = new CustomHbondForce("k*(distance(a1,d1)-r0)^2*(angle(a1,d1,d2)-theta0)^2");

This force depends on three parameters: k, r0, and theta0. The following code defines these as per-donor parameters: 


 force.addPerDonorParameter("k");
 force.addPerDonorParameter("r0");
 force.addPerDonorParameter("theta0");

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

In addition, you can call addTabulatedFunction() to define a new function based on tabulated values. You specify the function by creating a TabulatedFunction object. That function can then appear in the expression.

  • Constructor Details

    • CustomHbondForce

      public CustomHbondForce(String energy)
      Create a new CustomHbondForce.
      Parameters:
      energy - The energy expression for the hydrogen bond interaction.

  • Method Details

    • addAcceptor

      public int addAcceptor(int a1, int a2, int a3, com.sun.jna.ptr.PointerByReference parameters)
      Add an acceptor to the force.
      Parameters:
      a1 - The index of the first atom that defines the acceptor.
      a2 - The index of the second atom that defines the acceptor.
      a3 - The index of the third atom that defines the acceptor.
      parameters - The parameters for the acceptor.
      Returns:
      The index of the acceptor that was added.

    • addDonor

      public int addDonor(int d1, int d2, int d3, com.sun.jna.ptr.PointerByReference parameters)
      Add a donor to the force.
      Parameters:
      d1 - The index of the first atom that defines the donor.
      d2 - The index of the second atom that defines the donor.
      d3 - The index of the third atom that defines the donor.
      parameters - The parameters for the donor.
      Returns:
      The index of the donor that was added.

    • addExclusion

      public int addExclusion(int donor, int acceptor)
      Add an exclusion to the force.
      Parameters:
      donor - The index of the donor.
      acceptor - The index of the acceptor.
      Returns:
      The index of the exclusion that was added.

    • addFunction

      public int addFunction(String name, com.sun.jna.ptr.PointerByReference function, double min, double max)
      Add a tabulated function that may appear in the energy expression.
      Parameters:
      name - The name of the function as it appears in expressions.
      function - A TabulatedFunction object defining the function.
      min - The minimum value of the independent variable for which the function is defined.
      max - The maximum value of the independent variable for which the function is defined.
      Returns:
      The index of the function that was added.

    • addFunction

      public int addFunction(com.sun.jna.Pointer name, com.sun.jna.ptr.PointerByReference function, double min, double max)
      Add a tabulated function that may appear in the energy expression.
      Parameters:
      name - The name of the function as it appears in expressions.
      function - A TabulatedFunction object defining the function.
      min - The minimum value of the independent variable for which the function is defined.
      max - The maximum value of the independent variable for which the function is defined.
      Returns:
      The index of the function that was added.

    • addGlobalParameter

      public int addGlobalParameter(String name, double defaultValue)
      Add a global parameter to the force.
      Parameters:
      name - The name of the parameter.
      defaultValue - The default value of the parameter.
      Returns:
      The index of the parameter that was added.

    • addGlobalParameter

      public int addGlobalParameter(com.sun.jna.Pointer name, double defaultValue)
      Add a global parameter to the force.
      Parameters:
      name - The name of the parameter.
      defaultValue - The default value of the parameter.
      Returns:
      The index of the parameter that was added.

    • addPerAcceptorParameter

      public int addPerAcceptorParameter(String name)
      Add a per-acceptor parameter to the force.
      Parameters:
      name - The name of the parameter.
      Returns:
      The index of the parameter that was added.

    • addPerAcceptorParameter

      public int addPerAcceptorParameter(com.sun.jna.Pointer name)
      Add a per-acceptor parameter to the force.
      Parameters:
      name - The name of the parameter.
      Returns:
      The index of the parameter that was added.

    • addPerDonorParameter

      public int addPerDonorParameter(String name)
      Add a per-donor parameter to the force.
      Parameters:
      name - The name of the parameter.
      Returns:
      The index of the parameter that was added.

    • addPerDonorParameter

      public int addPerDonorParameter(com.sun.jna.Pointer name)
      Add a per-donor parameter to the force.
      Parameters:
      name - The name of the parameter.
      Returns:
      The index of the parameter that was added.

    • addTabulatedFunction

      public int addTabulatedFunction(String name, com.sun.jna.ptr.PointerByReference function)
      Add a tabulated function that may appear in the energy expression.
      Parameters:
      name - The name of the function as it appears in expressions.
      function - A TabulatedFunction object defining the function.
      Returns:
      The index of the function that was added.

    • addTabulatedFunction

      public int addTabulatedFunction(com.sun.jna.Pointer name, com.sun.jna.ptr.PointerByReference function)
      Add a tabulated function that may appear in the energy expression.
      Parameters:
      name - The name of the function as it appears in expressions.
      function - A TabulatedFunction object defining the function.
      Returns:
      The index of the function that was added.

    • destroy

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

    • getAcceptorParameters

      public void getAcceptorParameters(int index, com.sun.jna.ptr.IntByReference a1, com.sun.jna.ptr.IntByReference a2, com.sun.jna.ptr.IntByReference a3, com.sun.jna.ptr.PointerByReference parameters)
      Get the parameters for an acceptor.
      Parameters:
      index - The index of the acceptor.
      a1 - The index of the first atom that defines the acceptor (output).
      a2 - The index of the second atom that defines the acceptor (output).
      a3 - The index of the third atom that defines the acceptor (output).
      parameters - The parameters for the acceptor (output).

    • getAcceptorParameters

      public void getAcceptorParameters(int index, IntBuffer a1, IntBuffer a2, IntBuffer a3, com.sun.jna.ptr.PointerByReference parameters)
      Get the parameters for an acceptor.
      Parameters:
      index - The index of the acceptor.
      a1 - The index of the first atom that defines the acceptor (output).
      a2 - The index of the second atom that defines the acceptor (output).
      a3 - The index of the third atom that defines the acceptor (output).
      parameters - The parameters for the acceptor (output).

    • getCutoffDistance

      public double getCutoffDistance()
      Get the cutoff distance.
      Returns:
      The cutoff distance, measured in nm.

    • getDonorParameters

      public void getDonorParameters(int index, com.sun.jna.ptr.IntByReference d1, com.sun.jna.ptr.IntByReference d2, com.sun.jna.ptr.IntByReference d3, com.sun.jna.ptr.PointerByReference parameters)
      Get the parameters for a donor.
      Parameters:
      index - The index of the donor.
      d1 - The index of the first atom that defines the donor (output).
      d2 - The index of the second atom that defines the donor (output).
      d3 - The index of the third atom that defines the donor (output).
      parameters - The parameters for the donor (output).

    • getDonorParameters

      public void getDonorParameters(int index, IntBuffer d1, IntBuffer d2, IntBuffer d3, com.sun.jna.ptr.PointerByReference parameters)
      Get the parameters for a donor.
      Parameters:
      index - The index of the donor.
      d1 - The index of the first atom that defines the donor (output).
      d2 - The index of the second atom that defines the donor (output).
      d3 - The index of the third atom that defines the donor (output).
      parameters - The parameters for the donor (output).

    • getEnergyFunction

      public String getEnergyFunction()
      Get the energy expression for the force.
      Returns:
      The energy expression for the force.

    • getExclusionParticles

      public void getExclusionParticles(int index, com.sun.jna.ptr.IntByReference donor, com.sun.jna.ptr.IntByReference acceptor)
      Get the particles in an exclusion.
      Parameters:
      index - The index of the exclusion.
      donor - The index of the donor (output).
      acceptor - The index of the acceptor (output).

    • getExclusionParticles

      public void getExclusionParticles(int index, IntBuffer donor, IntBuffer acceptor)
      Get the particles in an exclusion.
      Parameters:
      index - The index of the exclusion.
      donor - The index of the donor (output).
      acceptor - The index of the acceptor (output).

    • getFunctionParameters

      public void getFunctionParameters(int index, com.sun.jna.ptr.PointerByReference name, com.sun.jna.ptr.PointerByReference function, com.sun.jna.ptr.DoubleByReference min, com.sun.jna.ptr.DoubleByReference max)
      Get the parameters for a tabulated function.
      Parameters:
      index - The index of the function.
      name - The name of the function as it appears in expressions (output).
      function - A TabulatedFunction object defining the function (output).
      min - The minimum value of the independent variable for which the function is defined (output).
      max - The maximum value of the independent variable for which the function is defined (output).

    • getFunctionParameters

      public void getFunctionParameters(int index, com.sun.jna.ptr.PointerByReference name, com.sun.jna.ptr.PointerByReference function, DoubleBuffer min, DoubleBuffer max)
      Get the parameters for a tabulated function.
      Parameters:
      index - The index of the function.
      name - The name of the function as it appears in expressions (output).
      function - A TabulatedFunction object defining the function (output).
      min - The minimum value of the independent variable for which the function is defined (output).
      max - The maximum value of the independent variable for which the function is defined (output).

    • getGlobalParameterDefaultValue

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

    • 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.

    • getNonbondedMethod

      public int getNonbondedMethod()
      Get the nonbonded method.
      Returns:
      The nonbonded method.

    • getNumAcceptors

      public int getNumAcceptors()
      Get the number of acceptors.
      Returns:
      The number of acceptors.

    • getNumDonors

      public int getNumDonors()
      Get the number of donors.
      Returns:
      The number of donors.

    • getNumExclusions

      public int getNumExclusions()
      Get the number of exclusions.
      Returns:
      The number of exclusions.

    • getNumFunctions

      @Deprecated public int getNumFunctions()
      Deprecated.
      This method exists only for backward compatibility. Use getNumTabulatedFunctions() instead.
      Get the number of tabulated functions.
      Returns:
      The number of tabulated functions.

    • getNumGlobalParameters

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

    • getNumPerAcceptorParameters

      public int getNumPerAcceptorParameters()
      Get the number of per-acceptor parameters.
      Returns:
      The number of per-acceptor parameters.

    • getNumPerDonorParameters

      public int getNumPerDonorParameters()
      Get the number of per-donor parameters.
      Returns:
      The number of per-donor parameters.

    • getNumTabulatedFunctions

      public int getNumTabulatedFunctions()
      Get the number of tabulated functions.
      Returns:
      The number of tabulated functions.

    • getPerAcceptorParameterName

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

    • getPerDonorParameterName

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

    • getTabulatedFunction

      public com.sun.jna.ptr.PointerByReference getTabulatedFunction(int index)
      Get a reference to a tabulated function that may appear in the energy expression.
      Parameters:
      index - The index of the function.
      Returns:
      The TabulatedFunction object defining the function.

    • getTabulatedFunctionName

      public String getTabulatedFunctionName(int index)
      Get the name of a tabulated function that may appear in the energy expression.
      Parameters:
      index - The index of the function.
      Returns:
      The name of the function as it appears in expressions.

    • setAcceptorParameters

      public void setAcceptorParameters(int index, int a1, int a2, int a3, com.sun.jna.ptr.PointerByReference parameters)
      Set the parameters for an acceptor.
      Parameters:
      index - The index of the acceptor.
      a1 - The index of the first atom that defines the acceptor.
      a2 - The index of the second atom that defines the acceptor.
      a3 - The index of the third atom that defines the acceptor.
      parameters - The parameters for the acceptor.

    • setCutoffDistance

      public void setCutoffDistance(double distance)
      Set the cutoff distance.
      Parameters:
      distance - The cutoff distance, measured in nm.

    • setDonorParameters

      public void setDonorParameters(int index, int d1, int d2, int d3, com.sun.jna.ptr.PointerByReference parameters)
      Set the parameters for a donor.
      Parameters:
      index - The index of the donor.
      d1 - The index of the first atom that defines the donor.
      d2 - The index of the second atom that defines the donor.
      d3 - The index of the third atom that defines the donor.
      parameters - The parameters for the donor.

    • setEnergyFunction

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

    • setEnergyFunction

      public void setEnergyFunction(com.sun.jna.Pointer energy)
      Set the energy expression for the force.
      Parameters:
      energy - The energy expression for the force.

    • setExclusionParticles

      public void setExclusionParticles(int index, int donor, int acceptor)
      Set the particles in an exclusion.
      Parameters:
      index - The index of the exclusion.
      donor - The index of the donor.
      acceptor - The index of the acceptor.

    • setFunctionParameters

      public void setFunctionParameters(int index, String name, com.sun.jna.ptr.PointerByReference function, double min, double max)
      Set the parameters for a tabulated function.
      Parameters:
      index - The index of the function.
      name - The name of the function as it appears in expressions.
      function - A TabulatedFunction object defining the function.
      min - The minimum value of the independent variable for which the function is defined.
      max - The maximum value of the independent variable for which the function is defined.

    • setFunctionParameters

      public void setFunctionParameters(int index, com.sun.jna.Pointer name, com.sun.jna.ptr.PointerByReference function, double min, double max)
      Set the parameters for a tabulated function.
      Parameters:
      index - The index of the function.
      name - The name of the function as it appears in expressions.
      function - A TabulatedFunction object defining the function.
      min - The minimum value of the independent variable for which the function is defined.
      max - The maximum value of the independent variable for which the function is defined.

    • setGlobalParameterDefaultValue

      public void setGlobalParameterDefaultValue(int index, double defaultValue)
      Set the default value of a global parameter.
      Parameters:
      index - The index of the parameter.
      defaultValue - 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.

    • setGlobalParameterName

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

    • setNonbondedMethod

      public void setNonbondedMethod(int method)
      Set the nonbonded method.
      Parameters:
      method - The nonbonded method.

    • setPerAcceptorParameterName

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

    • setPerAcceptorParameterName

      public void setPerAcceptorParameterName(int index, com.sun.jna.Pointer name)
      Set the name of a per-acceptor parameter.
      Parameters:
      index - The index of the parameter.
      name - The name of the parameter.

    • setPerDonorParameterName

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

    • setPerDonorParameterName

      public void setPerDonorParameterName(int index, com.sun.jna.Pointer name)
      Set the name of a per-donor parameter.
      Parameters:
      index - The index of the parameter.
      name - The name of the parameter.

    • updateParametersInContext

      public void updateParametersInContext(Context context)
      Update the parameters in a Context to match those stored in this Force object.
      Parameters:
      context - The Context in which to update the parameters.

    • 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.