Package ffx.openmm

Class CustomCVForce

java.lang.Object
ffx.openmm.Force
ffx.openmm.CustomCVForce
public class CustomCVForce extends Force
This class supports energy functions that depend on collective variables. To use it, you define a set of collective variables (scalar valued functions that depend on the particle positions), and an algebraic expression for the energy as a function of the collective variables. The expression also may involve tabulated functions, and may depend on arbitrary global parameters.

Each collective variable is defined by a Force object. The Force's potential energy is computed, and that becomes the value of the variable. This provides enormous flexibility in defining collective variables, especially by using custom forces. Anything that can be computed as a potential function can also be used as a collective variable.

To use this class, create a CustomCVForce object, passing an algebraic expression to the constructor that defines the potential energy. Then call addCollectiveVariable() to define collective variables and addGlobalParameter() to define global parameters. The values of global parameters may be modified during a simulation by calling Context::setParameter().

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.

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

    • CustomCVForce

      public CustomCVForce(String energy)
      Create a new CustomCVForce.
      Parameters:
      energy - The energy function as an algebraic expression.

  • Method Details

    • addCollectiveVariable

      public int addCollectiveVariable(String name, com.sun.jna.ptr.PointerByReference force)
      Add a collective variable to the force.
      Parameters:
      name - The name of the collective variable.
      force - The Force object that defines the collective variable.
      Returns:
      The index of the collective variable that was added.

    • addCollectiveVariable

      public int addCollectiveVariable(com.sun.jna.Pointer name, com.sun.jna.ptr.PointerByReference force)
      Add a collective variable to the force.
      Parameters:
      name - The name of the collective variable.
      force - The Force object that defines the collective variable.
      Returns:
      The index of the collective variable that was added.

    • addEnergyParameterDerivative

      public void addEnergyParameterDerivative(String name)
      Add an energy parameter derivative to the force.
      Parameters:
      name - The name of the parameter to compute the derivative with respect to.

    • addEnergyParameterDerivative

      public void addEnergyParameterDerivative(com.sun.jna.Pointer name)
      Add an energy parameter derivative to the force.
      Parameters:
      name - The name of the parameter to compute the derivative with respect to.

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

    • addTabulatedFunction

      public int addTabulatedFunction(String name, TabulatedFunction function)
      Add a tabulated function to the force.
      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, TabulatedFunction function)
      Add a tabulated function to the force.
      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

    • getCollectiveVariable

      public com.sun.jna.ptr.PointerByReference getCollectiveVariable(int index)
      Get a collective variable by index.
      Parameters:
      index - The index of the collective variable.
      Returns:
      The Force object that defines the collective variable.

    • getCollectiveVariableName

      public String getCollectiveVariableName(int index)
      Get the name of a collective variable.
      Parameters:
      index - The index of the collective variable.
      Returns:
      The name of the collective variable.

    • getCollectiveVariableValues

      public void getCollectiveVariableValues(Context context, com.sun.jna.ptr.PointerByReference values)
      Get the values of all collective variables in a given context.
      Parameters:
      context - The context for which to get the values.
      values - The values of the collective variables (output).

    • getEnergyFunction

      public String getEnergyFunction()
      Get the energy function.
      Returns:
      The energy function as an algebraic expression.

    • getEnergyParameterDerivativeName

      public String getEnergyParameterDerivativeName(int index)
      Get the name of an energy parameter derivative.
      Parameters:
      index - The index of the parameter derivative.
      Returns:
      The name of the parameter derivative.

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

    • getInnerContext

      public com.sun.jna.ptr.PointerByReference getInnerContext(Context context)
      Get the inner context used for evaluating collective variables.
      Parameters:
      context - The main context.
      Returns:
      The inner context.

    • getNumCollectiveVariables

      public int getNumCollectiveVariables()
      Get the number of collective variables.
      Returns:
      The number of collective variables.

    • getNumEnergyParameterDerivatives

      public int getNumEnergyParameterDerivatives()
      Get the number of energy parameter derivatives.
      Returns:
      The number of energy parameter derivatives.

    • getNumGlobalParameters

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

    • getNumTabulatedFunctions

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

    • getTabulatedFunction

      public com.sun.jna.ptr.PointerByReference getTabulatedFunction(int index)
      Get a tabulated function by index.
      Parameters:
      index - The index of the function.
      Returns:
      The TabulatedFunction object.

    • getTabulatedFunctionName

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

    • setEnergyFunction

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

    • setEnergyFunction

      public void setEnergyFunction(com.sun.jna.Pointer energy)
      Set the energy function.
      Parameters:
      energy - The energy function as an algebraic expression.

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

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