CustomIntegrator¶
- class openmm.openmm.CustomIntegrator(*args)¶
This is an Integrator that can be used to implemented arbitrary, user defined integration algorithms. It is flexible enough to support a wide range of methods including both deterministic and stochastic integrators, Metropolized integrators, and integrators that must integrate additional quantities along with the particle positions and momenta.
To create an integration algorithm, you first define a set of variables the integrator will compute. Variables come in two types: global variables have a single value, while per-DOF variables have a value for every degree of freedom (x, y, or z coordinate of a particle). You can define as many variables as you want of each type. The value of any variable can be computed by the integration algorithm, or set directly by calling a method on the CustomIntegrator. All variables are persistent between integration steps; once a value is set, it keeps that value until it is changed by the user or recomputed in a later integration step.
Next, you define the algorithm as a series of computations. To execute a time step, the integrator performs the list of computations in order. Each computation updates the value of one global or per-DOF value. There are several types of computations that can be done:
Global: You provide a mathematical expression involving only global variables. It is evaluated and stored into a global variable.
Per-DOF: You provide a mathematical expression involving both global and per-DOF variables. It is evaluated once for every degree of freedom, and the values are stored into a per-DOF variable.
Sum: You provide a mathematical expression involving both global and per-DOF variables. It is evaluated once for every degree of freedom. All of those values are then added together, and the sum is stored into a global variable.
Constrain Positions: The particle positions are updated so that all distance constraints are satisfied.
Constrain Velocities: The particle velocities are updated so the net velocity along any constrained distance is 0.
Like all integrators, CustomIntegrator ignores any particle whose mass is 0. It is skipped when doing per-DOF computations, and is not included when computing sums over degrees of freedom.
In addition to the variables you define by calling addGlobalVariable() and addPerDofVariable(), the integrator provides the following pre-defined variables:
dt: (global) This is the step size being used by the integrator.
energy: (global, read-only) This is the current potential energy of the system.
energy0, energy1, energy2, …: (global, read-only) This is similar to energy, but includes only the contribution from forces in one force group. A single computation step may only depend on a single energy variable (energy, energy0, energy1, etc.).
x: (per-DOF) This is the current value of the degree of freedom (the x, y, or z coordinate of a particle).
v: (per-DOF) This is the current velocity associated with the degree of freedom (the x, y, or z component of a particle’s velocity).
f: (per-DOF, read-only) This is the current force acting on the degree of freedom (the x, y, or z component of the force on a particle).
f0, f1, f2, …: (per-DOF, read-only) This is similar to f, but includes only the contribution from forces in one force group. A single computation step may only depend on a single force variable (f, f0, f1, etc.).
m: (per-DOF, read-only) This is the mass of the particle the degree of freedom is associated with.
uniform: (either global or per-DOF, read-only) This is a uniformly distributed random number between 0 and 1. Every time an expression is evaluated, a different value will be used. When used in a per-DOF expression, a different value will be used for every degree of freedom. Note, however, that if this variable appears multiple times in a single expression, the same value is used everywhere it appears in that expression.
gaussian: (either global or per-DOF, read-only) This is a Gaussian distributed random number with mean 0 and variance 1. Every time an expression is evaluated, a different value will be used. When used in a per-DOF expression, a different value will be used for every degree of freedom. Note, however, that if this variable appears multiple times in a single expression, the same value is used everywhere it appears in that expression.
A global variable is created for every adjustable parameter defined in the integrator’s Context.
The following example uses a CustomIntegrator to implement a velocity Verlet integrator:
CustomIntegrator integrator(0.001); integrator.addComputePerDof("v", "v+0.5*dt*f/m"); integrator.addComputePerDof("x", "x+dt*v"); integrator.addComputePerDof("v", "v+0.5*dt*f/m");
The first step updates the velocities based on the current forces. The second step updates the positions based on the new velocities, and the third step updates the velocities again. Although the first and third steps look identical, the forces used in them are different. You do not need to tell the integrator that; it will recognize that the positions have changed and know to recompute the forces automatically.
The above example has two problems. First, it does not respect distance constraints. To make the integrator work with constraints, you need to add extra steps to tell it when and how to apply them. Second, it never gives Forces an opportunity to update the context state. This should be done every time step so that, for example, an AndersenThermostat can randomize velocities or a MonteCarloBarostat can scale particle positions. You need to add a step to tell the integrator when to do this. The following example corrects both these problems, using the RATTLE algorithm to apply constraints:
CustomIntegrator integrator(0.001); integrator.addPerDofVariable("x1", 0); integrator.addUpdateContextState(); integrator.addComputePerDof("v", "v+0.5*dt*f/m"); integrator.addComputePerDof("x", "x+dt*v"); integrator.addComputePerDof("x1", "x"); integrator.addConstrainPositions(); integrator.addComputePerDof("v", "v+0.5*dt*f/m+(x-x1)/dt"); integrator.addConstrainVelocities();
CustomIntegrator can be used to implement multiple time step integrators. The following example shows an r-RESPA integrator. It assumes the quickly changing forces are in force group 0 and the slowly changing ones are in force group 1. It evaluates the “fast” forces four times as often as the “slow” forces.
CustomIntegrator integrator(0.004); integrator.addComputePerDof("v", "v+0.5*dt*f1/m"); for (int i = 0; i < 4; i++) { integrator.addComputePerDof("v", "v+0.5*(dt/4)*f0/m"); integrator.addComputePerDof("x", "x+(dt/4)*v"); integrator.addComputePerDof("v", "v+0.5*(dt/4)*f0/m"); } integrator.addComputePerDof("v", "v+0.5*dt*f1/m");
The sequence of computations in a CustomIntegrator can include flow control in the form of “if” and “while” blocks. The computations inside an “if” block are executed either zero or one times, depending on whether a condition is true. The computations inside a “while” block are executed repeatedly for as long as the condition remains true. Be very careful when writing “while” blocks; there is nothing to stop you from creating an infinite loop!
For example, suppose you are writing a Monte Carlo algorithm. Assume you have already computed a new set of particle coordinates “xnew” and a step acceptance probability “acceptanceProbability”. The following lines use an “if” block to decide whether to accept the step, and if it is accepted, store the new positions into “x”.
integrator.beginIfBlock("uniform < acceptanceProbability"); integrator.addComputePerDof("x", "xnew"); integrator.endBlock();
The condition in an “if” or “while” block is evaluated globally, so it may only involve global variables, not per-DOF ones. It may use any of the following comparison operators: =, <. >, !=, <=, >=. Blocks may be nested inside each other.
“Per-DOF” computations can also be thought of as per-particle computations that operate on three component vectors. For example, “x+dt*v” means to take the particle’s velocity (a vector), multiply it by the step size, and add the position (also a vector). The result is a new vector that can be stored into a per-DOF variable with addComputePerDof(), or it can be summed over all components of all particles with addComputeSum(). Because the calculation is done on vectors, you can use functions that operate explicitly on vectors rather than just computing each component independently. For example, the following line uses a cross product to compute the angular momentum of each particle and stores it into a per-DOF variable.
integrator.addComputePerDof("angularMomentum", "m*cross(x, v)");
Here are two more examples that may be useful as starting points for writing your own integrators. The first one implements the algorithm used by the standard VerletIntegrator class. This is a leapfrog algorithm, in contrast to the velocity Verlet algorithm shown above, so it only requires applying constraints once in each time step.
CustomIntegrator integrator(dt); integrator.addPerDofVariable("x0", 0); integrator.addUpdateContextState(); integrator.addComputePerDof("x0", "x"); integrator.addComputePerDof("v", "v+dt*f/m"); integrator.addComputePerDof("x", "x+dt*v"); integrator.addConstrainPositions(); integrator.addComputePerDof("v", "(x-x0)/dt");
The second one implements the algorithm used by the standard LangevinMiddleIntegrator class. kB is Boltzmann’s constant.
CustomIntegrator integrator(dt); integrator.addGlobalVariable("a", exp(-friction*dt)); integrator.addGlobalVariable("b", sqrt(1-exp(-2*friction*dt))); integrator.addGlobalVariable("kT", kB*temperature); integrator.addPerDofVariable("x1", 0); integrator.addUpdateContextState(); integrator.addComputePerDof("v", "v + dt*f/m"); integrator.addConstrainVelocities(); integrator.addComputePerDof("x", "x + 0.5*dt*v"); integrator.addComputePerDof("v", "a*v + b*sqrt(kT/m)*gaussian"); integrator.addComputePerDof("x", "x + 0.5*dt*v"); integrator.addComputePerDof("x1", "x"); integrator.addConstrainPositions(); integrator.addComputePerDof("v", "v + (x-x1)/dt");
Another feature of CustomIntegrator is that it can use derivatives of the potential energy with respect to context parameters. These derivatives are typically computed by custom forces, and are only computed if a Force object has been specifically told to compute them by calling addEnergyParameterDerivative() on it. CustomIntegrator provides a deriv() function for accessing these derivatives in global or per-DOF expressions. For example, “deriv(energy, lambda)” is the derivative of the total potentially energy with respect to the parameter lambda. You can also restrict it to a single force group by specifying a different variable for the first argument, such as “deriv(energy1, lambda)”.
An Integrator has one other job in addition to evolving the equations of motion: it defines how to compute the kinetic energy of the system. Depending on the integration method used, simply summing (mv^2)/2 over all degrees of freedom may not give the correct answer. For example, in a leapfrog integrator the velocities are “delayed” by half a time step, so the above formula would give the kinetic energy half a time step ago, not at the current time.
Call setKineticEnergyExpression() to set an expression for the kinetic energy. It is computed for every degree of freedom (excluding ones whose mass is 0) and the result is summed. The default expression is “m*v*v/2”, which is correct for many integrators.
As example, the following line defines the correct way to compute kinetic energy when using a leapfrog algorithm:
integrator.setKineticEnergyExpression("m*v1*v1/2; v1=v+0.5*dt*f/m");
The kinetic energy expression may depend on the following pre-defined variables: x, v, f, m, dt. It also may depend on user-defined global and per-DOF variables, and on the values of adjustable parameters defined in the integrator’s Context. It may not depend on any other variable, such as the potential energy, the force from a single force group, or a random number.
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. An expression may also involve intermediate quantities that are defined following the main expression, using “;” as a separator.
Expressions used in ComputePerDof and ComputeSum steps can also use the following functions that operate on vectors: cross(a, b) is the cross product of two vectors; dot(a, b) is the dot product of two vectors; _x(a), _y(a), and _z(a) extract a single component from a vector; and vector(a, b, c) creates a new vector with the x component of the first argument, the y component of the second argument, and the z component of the third argument. Remember that every quantity appearing in a vector expression is a vector. Functions that appear to return a scalar really return a vector whose components are all the same. For example, _z(a) returns the vector (a.z, a.z, a.z). Likewise, wherever a constant appears in the expression, it really means a vector whose components all have the same value.
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 expressions.
- __init__(self, stepSize) → CustomIntegrator¶
- __init__(self, other) → CustomIntegrator
Create a CustomIntegrator.
- Parameters
stepSize (double) – the step size with which to integrate the system (in picoseconds)
Methods
__init__
(-> CustomIntegrator)Create a CustomIntegrator.
addComputeGlobal
(self, variable, expression)Add a step to the integration algorithm that computes a global value.
addComputePerDof
(self, variable, expression)Add a step to the integration algorithm that computes a per-DOF value.
addComputeSum
(self, variable, expression)Add a step to the integration algorithm that computes a sum over degrees of freedom.
addConstrainPositions
(self)Add a step to the integration algorithm that updates particle positions so all constraints are satisfied.
addConstrainVelocities
(self)Add a step to the integration algorithm that updates particle velocities so the net velocity along all constraints is 0.
addGlobalVariable
(self, name, initialValue)Define a new global variable.
addPerDofVariable
(self, name, initialValue)Define a new per-DOF variable.
addTabulatedFunction
(self, name, function)Add a tabulated function that may appear in expressions.
addUpdateContextState
(self)Add a step to the integration algorithm that allows Forces to update the context state.
beginIfBlock
(self, condition)Add a step which begins a new “if” block.
beginWhileBlock
(self, condition)Add a step which begins a new “while” block.
endBlock
(self)Add a step which marks the end of the most recently begun “if” or “while” block.
getComputationStep
(self, index)Get the details of a computation step that has been added to the integration algorithm.
getConstraintTolerance
(self)Get the distance tolerance within which constraints are maintained, as a fraction of the constrained distance.
getGlobalVariable
(self, index)Get the current value of a global variable.
getGlobalVariableByName
(self, name)Get the current value of a global variable, specified by name.
getGlobalVariableName
(self, index)Get the name of a global variable.
Get which force groups to use for integration.
Get the expression to use for computing the kinetic energy.
getNumComputations
(self)Get the number of computation steps that have been added.
getNumGlobalVariables
(self)Get the number of global variables that have been defined.
getNumPerDofVariables
(self)Get the number of per-DOF variables that have been defined.
getNumTabulatedFunctions
(self)Get the number of tabulated functions that have been defined.
getPerDofVariableByName
(self, name)Get the value of a per-DOF variable, specified by name.
getPerDofVariableName
(self, index)Get the name of a per-DOF variable.
getRandomNumberSeed
(self)Get the random number seed.
getStepSize
(self)Get the size of each time step, in picoseconds.
getTabulatedFunction
(-> TabulatedFunction)Get a reference to a tabulated function that may appear in expressions.
getTabulatedFunctionName
(self, index)Get the name of a tabulated function that may appear in expressions.
setConstraintTolerance
(self, tol)Set the distance tolerance within which constraints are maintained, as a fraction of the constrained distance.
setGlobalVariable
(self, index, value)Set the value of a global variable.
setGlobalVariableByName
(self, name, value)Set the value of a global variable, specified by name.
setIntegrationForceGroups
(groups)Set which force groups to use for integration.
setKineticEnergyExpression
(self, expression)Set the expression to use for computing the kinetic energy.
setPerDofVariable
(self, index, values)Set the value of a per-DOF variable.
setPerDofVariableByName
(self, name, values)Set the value of a per-DOF variable, specified by name.
setRandomNumberSeed
(self, seed)Set the random number seed.
setStepSize
(self, size)Set the size of each time step, in picoseconds.
step
(self, steps)Advance a simulation through time by taking a series of time steps.
Attributes
BlockEnd
ComputeGlobal
ComputePerDof
ComputeSum
ConstrainPositions
ConstrainVelocities
IfBlockStart
UpdateContextState
WhileBlockStart
The membership flag
- property thisown¶
The membership flag
- getNumGlobalVariables(self) → int¶
Get the number of global variables that have been defined.
- getNumPerDofVariables(self) → int¶
Get the number of per-DOF variables that have been defined.
- getNumComputations(self) → int¶
Get the number of computation steps that have been added.
- getNumTabulatedFunctions(self) → int¶
Get the number of tabulated functions that have been defined.
- addGlobalVariable(self, name, initialValue) → int¶
Define a new global variable.
- Parameters
name (string) – the name of the variable
initialValue (double) – the variable will initially be set to this value
- Returns
the index of the variable that was added
- Return type
int
- getGlobalVariableName(self, index) → std::string const &¶
Get the name of a global variable.
- Parameters
index (int) – the index of the variable to get
- Returns
the name of the variable
- Return type
string
- addPerDofVariable(self, name, initialValue) → int¶
Define a new per-DOF variable.
- Parameters
name (string) – the name of the variable
initialValue (double) – the variable will initially be set to this value for all degrees of freedom
- Returns
the index of the variable that was added
- Return type
int
- getPerDofVariableName(self, index) → std::string const &¶
Get the name of a per-DOF variable.
- Parameters
index (int) – the index of the variable to get
- Returns
the name of the variable
- Return type
string
- getGlobalVariable(self, index) → double¶
Get the current value of a global variable.
- Parameters
index (int) – the index of the variable to get
- Returns
the current value of the variable
- Return type
double
- getGlobalVariableByName(self, name) → double¶
Get the current value of a global variable, specified by name.
- Parameters
name (string) – the name of the variable to get
- Returns
the current value of the parameter
- Return type
double
- setGlobalVariable(self, index, value)¶
Set the value of a global variable.
- Parameters
index (int) – the index of the variable to set
value (double) – the new value of the variable
- setGlobalVariableByName(self, name, value)¶
Set the value of a global variable, specified by name.
- Parameters
name (string) – the name of the variable to set
value (double) – the new value of the variable
- getPerDofVariableByName(self, name)¶
Get the value of a per-DOF variable, specified by name.
- Parameters
name (string) – the name of the variable to get
- Returns
values – the values of the variable for all degrees of freedom are stored into this
- Return type
vector< Vec3 >
- setPerDofVariable(self, index, values)¶
Set the value of a per-DOF variable.
- Parameters
index (int) – the index of the variable to set
values (vector< Vec3 >) – the new values of the variable for all degrees of freedom
- setPerDofVariableByName(self, name, values)¶
Set the value of a per-DOF variable, specified by name.
- Parameters
name (string) – the name of the variable to set
values (vector< Vec3 >) – the new values of the variable for all degrees of freedom
- addComputeGlobal(self, variable, expression) → int¶
Add a step to the integration algorithm that computes a global value.
- Parameters
variable (string) – the global variable to store the computed value into
expression (string) – a mathematical expression involving only global variables. In each integration step, its value is computed and stored into the specified variable.
- Returns
the index of the step that was added
- Return type
int
- addComputePerDof(self, variable, expression) → int¶
Add a step to the integration algorithm that computes a per-DOF value.
- Parameters
variable (string) – the per-DOF variable to store the computed value into
expression (string) – a mathematical expression involving both global and per-DOF variables. In each integration step, its value is computed for every degree of freedom and stored into the specified variable.
- Returns
the index of the step that was added
- Return type
int
- addComputeSum(self, variable, expression) → int¶
Add a step to the integration algorithm that computes a sum over degrees of freedom.
- Parameters
variable (string) – the global variable to store the computed value into
expression (string) – a mathematical expression involving both global and per-DOF variables. In each integration step, its value is computed for every degree of freedom. Those values are then added together, and the sum is stored in the specified variable.
- Returns
the index of the step that was added
- Return type
int
- addConstrainPositions(self) → int¶
Add a step to the integration algorithm that updates particle positions so all constraints are satisfied.
- Returns
the index of the step that was added
- Return type
int
- addConstrainVelocities(self) → int¶
Add a step to the integration algorithm that updates particle velocities so the net velocity along all constraints is 0.
- Returns
the index of the step that was added
- Return type
int
- addUpdateContextState(self) → int¶
Add a step to the integration algorithm that allows Forces to update the context state.
- Returns
the index of the step that was added
- Return type
int
- beginIfBlock(self, condition) → int¶
Add a step which begins a new “if” block.
- Parameters
condition (string) – a mathematical expression involving a comparison operator and global variables. All steps between this one and the end of the block are executed only if the condition is true.
- Returns
the index of the step that was added
- Return type
int
- beginWhileBlock(self, condition) → int¶
Add a step which begins a new “while” block.
- Parameters
condition (string) – a mathematical expression involving a comparison operator and global variables. All steps between this one and the end of the block are executed repeatedly as long as the condition remains true.
- Returns
the index of the step that was added
- Return type
int
- endBlock(self) → int¶
Add a step which marks the end of the most recently begun “if” or “while” block.
- Returns
the index of the step that was added
- Return type
int
- getComputationStep(self, index)¶
Get the details of a computation step that has been added to the integration algorithm.
- Parameters
index (int) – the index of the computation step to get
- Returns
type (ComputationType) – the type of computation this step performs
variable (string) – the variable into which this step stores its result. If this step does not store a result in a variable, this will be an empty string.
expression (string) – the expression this step evaluates. If this step does not evaluate an expression, this will be an empty string.
- addTabulatedFunction(self, name, function) → int¶
Add a tabulated function that may appear in expressions.
- Parameters
name (string) – the name of the function as it appears in expressions
function (TabulatedFunction *) – a TabulatedFunction object defining the function. The TabulatedFunction should have been created on the heap with the “new” operator. The integrator takes over ownership of it, and deletes it when the integrator itself is deleted.
- Returns
the index of the function that was added
- Return type
int
- getTabulatedFunction(self, index) → TabulatedFunction¶
- getTabulatedFunction(self, index) → TabulatedFunction
Get a reference to a tabulated function that may appear in expressions.
- Parameters
index (int) – the index of the function to get
- Returns
the TabulatedFunction object defining the function
- Return type
- getTabulatedFunctionName(self, index) → std::string const &¶
Get the name of a tabulated function that may appear in expressions.
- Parameters
index (int) – the index of the function to get
- Returns
the name of the function as it appears in expressions
- Return type
string
- getKineticEnergyExpression(self) → std::string const &¶
Get the expression to use for computing the kinetic energy. The expression is evaluated for every degree of freedom. Those values are then added together, and the sum is reported as the current kinetic energy.
- setKineticEnergyExpression(self, expression)¶
Set the expression to use for computing the kinetic energy. The expression is evaluated for every degree of freedom. Those values are then added together, and the sum is reported as the current kinetic energy.
- getRandomNumberSeed(self) → int¶
Get the random number seed. See setRandomNumberSeed() for details.
- setRandomNumberSeed(self, seed)¶
Set the random number seed. The precise meaning of this parameter is undefined, and is left up to each Platform to interpret in an appropriate way. It is guaranteed that if two simulations are run with different random number seeds, the sequence of random numbers will be different. On the other hand, no guarantees are made about the behavior of simulations that use the same seed. In particular, Platforms are permitted to use non-deterministic algorithms which produce different results on successive runs, even if those runs were initialized identically.
If seed is set to 0 (which is the default value assigned), a unique seed is chosen when a Context is created from this Force. This is done to ensure that each Context receives unique random seeds without you needing to set them explicitly.
- step(self, steps)¶
Advance a simulation through time by taking a series of time steps.
- Parameters
steps (int) – the number of time steps to take
- getPerDofVariable(self, index)¶
- getPerDofVariable(self, index) → PyObject *
- getConstraintTolerance(self) → double¶
Get the distance tolerance within which constraints are maintained, as a fraction of the constrained distance.
- getIntegrationForceGroups(self) → int¶
Get which force groups to use for integration. By default, all force groups are included. This is interpreted as a set of bit flags: the forces from group i will be included if (groups&(1<<i)) != 0.
- getStepSize(self) → double¶
Get the size of each time step, in picoseconds. If this integrator uses variable time steps, the size of the most recent step is returned.
- Returns
the step size, measured in ps
- Return type
double
- setConstraintTolerance(self, tol)¶
Set the distance tolerance within which constraints are maintained, as a fraction of the constrained distance.
- setIntegrationForceGroups(groups)¶
Set which force groups to use for integration. By default, all force groups are included.
- Parameters
groups (set or int) – a set of indices for which force groups to include when integrating the equations of motion. Alternatively, the groups can be passed as a single unsigned integer interpreted as a bitmask, in which case group i will be included if (groups&(1<<i)) != 0.
- setStepSize(self, size)¶
Set the size of each time step, in picoseconds. If this integrator uses variable time steps, the effect of calling this method is undefined, and it may simply be ignored.
- Parameters
size (double) – the step size, measured in ps