CustomSummation

class CustomSummation(*args)

Bases: object

This class allows users to define a custom function of a fixed number of arguments, which can be evaluated in an openmm.Platform. Such function is a sum whose terms depend on the function arguments, as well as on a number of per-term and overall parameters.

CustomSummation evaluates a user supplied algebraic expression to determine the value of each term. In this expression, we refer to the custom function arguments as x1, y1, z1, x2, y2, z2, x3, etc.

The expression 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.

The expression may also depend on the following variables and functions:

  • p1, p2, p3, …: names given to three-dimensional points defined as

    (x1, y1, z1), (x2, y2, z2), and so on. If the number of arguments is not a multiple of 3, the last of these points is completed with zeros.

  • distance(p1, p2): the distance between points p1 and p2 (where p1 and p2 may

    be replaced by any valid point names.

  • angle(p1, p2, p3): the angle formed by the three specified points.

  • dihedral(p1, p2, p3, p4): the dihedral angle formed by the four specified

    points, guaranteed to be in the range \([-\pi, +\pi]\).

This class also supports the functions pointdistance(), pointangle(), and pointdihedral(), which require 6, 9, and 12 arguments, respectively. These functions are similar to distance(), angle(), and dihedral(), but their arguments can be any evaluatable expressions. For example, the following expression computes the distance from point p1 to the midpoint between p2 and p3.

>>> expression = "pointdistance(x1, y1, z1, (x2+x3)/2, (y2+y3)/2, (z2+z3)/2)"

To use this class, create a CustomSummation object, passing the following data to the constructor:

  1. the number of arguments

  2. an algebraic expression that defines each term of the sum

  3. a dictionary of overall parameter names and their values

  4. a list of per-term parameter names

  5. the openmm.Platform to use for the calculations

  6. a dictionary of platform-specific property names and values

In order to evaluate the sum, call evaluate(). This class also has the ability to compute derivatives of the sum with respect to the arguments. To do so, call evaluateDerivative().

The function is initialized without any terms, meaning that any call to evaluate() or evaluateDerivative() will return 0. You must call addTerm() to add terms to the summation and specify their parameters. After all terms have been added, then call update() to turn them effective. You can still add more terms after that or modify the parameters of existing terms by calling setTerm(). However, none of these changes become effective until update() is called again.

Finally, you can change the overall parameters of the summation by calling setParameters(). These change become effective immediately, with no need for neither a reinitialization nor an update.

Parameters:

  • numArgs (int) – The number of arguments the generated function takes.

  • expression (str) – The algebraic expression that defines each term in the summation.

  • overallParameters (Dict[str, float]) – A dictionary containing the names and default values of the parameters that are shared by all terms of the summation. Not to be confused with global context parameters

  • perTermParameters (List[str]) – A list containing the names of the parameters that are unique to each term of the summation

  • platform (OpenMM::Platform) – The platform that will be used to evaluate the summation

  • properties (Dict[str, str]) – A dictionary defining a set of values for platform-specific properties

Examples

The following code creates a CustomSummation that evaluates a Gaussian mixture in a three-dimensional space. All kernels have the same standard deviation, but different means. A kernel is added for each vertex of a unit cube. Then, the sum is evaluated for a point in the middle of the cube.

>>> function = openmmlab.CustomSummation(
...     3,
...     "exp(-((x1-mux)^2+(y1-muy)^2+(z1-muz)^2)/(2*sigma^2))/sqrt(6.2832*sigma^2)",
...     {"sigma": 1.0},
...     ["mux", "muy", "muz"],
...     openmm.Platform.getPlatformByName("CUDA")
... )

>>> function.addTerm([0.0, 0.0, 0.0])

>>> function.addTerm([0.0, 0.0, 1.0])

>>> function.addTerm([0.0, 1.0, 0.0])

>>> function.addTerm([0.0, 1.0, 1.0])

>>> function.addTerm([1.0, 0.0, 0.0])

>>> function.addTerm([1.0, 0.0, 1.0])

>>> function.addTerm([1.0, 1.0, 0.0])

>>> function.addTerm([1.0, 1.0, 1.0])

>>> function.update()

>>> value = function.evaluate([0.5, 0.5, 0.5])
__init__(*args)

Methods

addTerm(parameters)

Add a new term to the summation.

evaluate(arguments)

Evaluate the function.

evaluateDerivative(arguments, which)

Evaluate a derivative of the function.

getExpression()

Get the expression for each term of the summation.

getNumArguments()

Get the number of arguments this summation expects.

getNumTerms()

Get the number of terms in the summation.

getOverallParameters()

Get a dictionary with the names and values of the overall parameters.

getParameter(name)

Get the value of an overall parameter.

getPerTermParameters()

Get a list of the names of the per-term parameters.

getPlatform()

Get the platform used to evaluate the summation.

getPlatformProperties()

Get the platform-specific properties used to evaluate the summation.

getTerm(index)

Get the parameters of a term.

setParameter(name, value)

Set the value of an overall parameter.

setTerm(index, parameters)

Set the parameters of a term.

update()

Update the custom summation after adding new terms or changing parameters of existing ones.

Attributes

thisown

The membership flag
addTerm(parameters)

Add a new term to the summation.

Note

This method does not take effect immediately. You must call update() to turn it effective.

Parameters:

parameters (List[float]) – the parameters of the new term

Returns:

int – the index of the new term

Raises:

ValueError – if the passed vector has the wrong number of parameters

evaluate(arguments)

Evaluate the function.

Parameters:

arguments (List[float]) – a vector of argument values

Returns:

float – the value of the function

evaluateDerivative(arguments, which)

Evaluate a derivative of the function.

Parameters:

  • arguments (List[float]) – a vector of argument values

  • which (int) – the index of the argument for which to evaluate the derivative

Returns:

float – the value of the derivative

getExpression()

Get the expression for each term of the summation.

getNumArguments()

Get the number of arguments this summation expects.

getNumTerms()

Get the number of terms in the summation.

getOverallParameters()

Get a dictionary with the names and values of the overall parameters.

getParameter(name)

Get the value of an overall parameter.

Parameters:

name (str) – the name of the parameter

Returns:

float – the value of the parameter

getPerTermParameters()

Get a list of the names of the per-term parameters.

getPlatform()

Get the platform used to evaluate the summation.

getPlatformProperties()

Get the platform-specific properties used to evaluate the summation.

getTerm(index)

Get the parameters of a term.

Parameters:

index (int) – the index of the term

Returns:

List[float] – the list of parameters values

setParameter(name, value)

Set the value of an overall parameter.

Note

This method will take effect immediately, with no need to call update().

Parameters:

  • name (str) – the name of the parameter

  • value (float) – the value of the parameter

setTerm(index, parameters)

Set the parameters of a term.

Note

This method does not take effect immediately. You must call update() to turn it effective.

Parameters:

  • index (int) – the index of the term

  • parameters (List[float]) – the new parameters for the term

Raises:

ValueError – if the passed vector has the wrong number of parameters

update()

Update the custom summation after adding new terms or changing parameters of existing ones.