openmmtools.integrators.LangevinIntegrator¶

class
openmmtools.integrators.
LangevinIntegrator
(temperature=Quantity(value=298.0, unit=kelvin), collision_rate=Quantity(value=1.0, unit=/picosecond), timestep=Quantity(value=1.0, unit=femtosecond), splitting='V R O R V', constraint_tolerance=1e08, measure_shadow_work=False, measure_heat=False)[source]¶ Integrates Langevin dynamics with a prescribed operator splitting.
 One way to divide the Langevin system is into three parts which can each be solved “exactly:”
 R: Linear “drift” / Constrained “drift”
Deterministic update of positions, using current velocities x < x + v dt
 V: Linear “kick” / Constrained “kick”
Deterministic update of velocities, using current forces v < v + (f/m) dt
where f = force, m = mass
 O: OrnsteinUhlenbeck
Stochastic update of velocities, simulating interaction with a heat bath v < av + b sqrt(kT/m) R
where a = e^(gamma dt) b = sqrt(1  e^(2gamma dt)) R is i.i.d. standard normal
We can then construct integrators by solving each part for a certain timestep in sequence. (We can further split up the V step by force group, evaluating cheap but fastfluctuating forces more frequently than expensive but slowfluctuating forces. Since forces are only evaluated in the V step, we represent this by including in our “alphabet” V0, V1, …)
When the system contains holonomic constraints, these steps are confined to the constraint manifold.
References
[Leimkuhler and Matthews, 2015] Molecular dynamics: with deterministic and stochastic numerical methods, Chapter 7
Examples
 VVVR
 splitting=”O V R V O”
 BAOAB:
 splitting=”V R O R V”
 gBAOAB, with K_r=3:
 splitting=”V R R R O R R R V”
 gBAOAB with solventsolute splitting, K_r=K_p=2:
 splitting=”V0 V1 R R O R R V1 R R O R R V1 V0”
Attributes:  _kinetic_energy : str
This is 0.5*m*v*v by default, and is the expression used for the kinetic energy
 shadow_work : unit.Quantity with units of energy
Shadow work (if integrator was constructed with measure_shadow_work=True)
 heat : unit.Quantity with units of energy
Heat (if integrator was constructed with measure_heat=True)
Methods
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 perDOF value. addComputeSum
(self, variable, expression)Add a step to the integration algorithm that computes a sum over degrees of freedom. addComputeTemperatureDependentConstants
(…)Wrap the ComputePerDof into an ifblock executed only when kT changes. 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 perDOF 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. deserialize_xml
(xml_serialization)Shortcut to deserialize the XML representation and the restore interface. 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. getKineticEnergyExpression
(self)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 perDOF variables that have been defined. getNumTabulatedFunctions
(self)Get the number of tabulated functions that have been defined. getPerDofVariable
(self, index)getPerDofVariable(self, index) > PyObject * getPerDofVariableByName
(self, name)Get the value of a perDOF variable, specified by name. getPerDofVariableName
(self, index)Get the name of a perDOF variable. getRandomNumberSeed
(self)Get the random number seed. getStepSize
(self)Get the size of each time step, in picoseconds. getTabulatedFunction
(self, index)getTabulatedFunction(self, index) > TabulatedFunction getTabulatedFunctionName
(self, index)Get the name of a tabulated function that may appear in expressions. getTemperature
()Return the temperature of the heat bath. get_acceptance_rate
()Get acceptance rate for Metropolized integrators. get_heat
([dimensionless])Get the current accumulated heat. get_shadow_work
([dimensionless])Get the current accumulated shadow work. is_restorable
(openmm_object)Check if the custom integrator or force has a restorable interface. is_thermostated
(integrator)Return true if the integrator is a ThermostatedIntegrator. pretty_format
([as_list, step_types_to_highlight])Generate a humanreadable version of each integrator step. pretty_print
()Prettyprint the computation steps of this integrator. reset
()Reset all statistics (heat, shadow work, acceptance rates, step). reset_ghmc_statistics
()Reset GHMC acceptance rate statistics. reset_heat
()Reset heat. reset_shadow_work
()Reset shadow work. reset_steps
()Reset step counter. restore_interface
(integrator)Restore the original interface of a CustomIntegrator. 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. setKineticEnergyExpression
(self, expression)Set the expression to use for computing the kinetic energy. setPerDofVariable
(self, index, values)Set the value of a perDOF variable. setPerDofVariableByName
(self, name, values)Set the value of a perDOF variable, specified by name. setRandomNumberSeed
(self, seed)Set the random number seed. setStepSize
(self, size)Set the size of each time step, in picoseconds. setTemperature
(temperature)Set the temperature of the heat bath. step
(self, steps)Advance a simulation through time by taking a series of time steps. 
__init__
(temperature=Quantity(value=298.0, unit=kelvin), collision_rate=Quantity(value=1.0, unit=/picosecond), timestep=Quantity(value=1.0, unit=femtosecond), splitting='V R O R V', constraint_tolerance=1e08, measure_shadow_work=False, measure_heat=False)[source]¶ Create a Langevin integrator with the prescribed operator splitting.
Parameters:  splitting : string, default: “V R O R V”
Sequence of “R”, “V”, “O” (and optionally “{“, “}”, “V0”, “V1”, …) substeps to be executed each timestep.
Forces are only used in Vstep. Handle multiple force groups by appending the force group index to Vsteps, e.g. “V0” will only use forces from force group 0. “V” will perform a step using all forces. “{” will cause metropolization, and must be followed later by a “}”.
 temperature : np.unit.Quantity compatible with kelvin, default: 298.0*unit.kelvin
Fictitious “bath” temperature
 collision_rate : np.unit.Quantity compatible with 1/picoseconds, default: 1.0/unit.picoseconds
Collision rate
 timestep : np.unit.Quantity compatible with femtoseconds, default: 1.0*unit.femtoseconds
Integration timestep
 constraint_tolerance : float, default: 1.0e8
Tolerance for constraint solver
 measure_shadow_work : boolean, default: False
Accumulate the shadow work performed by the symplectic substeps, in the global shadow_work
 measure_heat : boolean, default: False
Accumulate the heat exchanged with the bath in each step, in the global heat
Methods
__init__
([temperature, unit, …])Create a Langevin integrator with the prescribed operator splitting. 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 perDOF value. addComputeSum
(self, variable, expression)Add a step to the integration algorithm that computes a sum over degrees of freedom. addComputeTemperatureDependentConstants
(…)Wrap the ComputePerDof into an ifblock executed only when kT changes. 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 perDOF 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. deserialize_xml
(xml_serialization)Shortcut to deserialize the XML representation and the restore interface. 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. getKineticEnergyExpression
(self)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 perDOF variables that have been defined. getNumTabulatedFunctions
(self)Get the number of tabulated functions that have been defined. getPerDofVariable
(self, index)getPerDofVariable(self, index) > PyObject * getPerDofVariableByName
(self, name)Get the value of a perDOF variable, specified by name. getPerDofVariableName
(self, index)Get the name of a perDOF variable. getRandomNumberSeed
(self)Get the random number seed. getStepSize
(self)Get the size of each time step, in picoseconds. getTabulatedFunction
(self, index)getTabulatedFunction(self, index) > TabulatedFunction getTabulatedFunctionName
(self, index)Get the name of a tabulated function that may appear in expressions. getTemperature
()Return the temperature of the heat bath. get_acceptance_rate
()Get acceptance rate for Metropolized integrators. get_heat
([dimensionless])Get the current accumulated heat. get_shadow_work
([dimensionless])Get the current accumulated shadow work. is_restorable
(openmm_object)Check if the custom integrator or force has a restorable interface. is_thermostated
(integrator)Return true if the integrator is a ThermostatedIntegrator. pretty_format
([as_list, step_types_to_highlight])Generate a humanreadable version of each integrator step. pretty_print
()Prettyprint the computation steps of this integrator. reset
()Reset all statistics (heat, shadow work, acceptance rates, step). reset_ghmc_statistics
()Reset GHMC acceptance rate statistics. reset_heat
()Reset heat. reset_shadow_work
()Reset shadow work. reset_steps
()Reset step counter. restore_interface
(integrator)Restore the original interface of a CustomIntegrator. 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. setKineticEnergyExpression
(self, expression)Set the expression to use for computing the kinetic energy. setPerDofVariable
(self, index, values)Set the value of a perDOF variable. setPerDofVariableByName
(self, name, values)Set the value of a perDOF variable, specified by name. setRandomNumberSeed
(self, seed)Set the random number seed. setStepSize
(self, size)Set the size of each time step, in picoseconds. setTemperature
(temperature)Set the temperature of the heat bath. 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
acceptance_rate
Get acceptance rate for Metropolized integrators. heat
is_metropolized
Return True if this integrator is Metropolized, False otherwise. kT
The thermal energy in simtk.openmm.Quantity shadow_work

acceptance_rate
¶ Get acceptance rate for Metropolized integrators.

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:  int
the index of the step that was added

addComputePerDof
(self, variable, expression) → int¶ Add a step to the integration algorithm that computes a perDOF value.
Parameters:  variable : string
the perDOF variable to store the computed value into
 expression : string
a mathematical expression involving both global and perDOF variables. In each integration step, its value is computed for every degree of freedom and stored into the specified variable.
Returns:  int
the index of the step that was added

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 perDOF 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:  int
the index of the step that was added

addComputeTemperatureDependentConstants
(compute_per_dof)¶ Wrap the ComputePerDof into an ifblock executed only when kT changes.
Parameters:  compute_per_dof : dict of str: str
A dictionary of variable_name: expression.

addConstrainPositions
(self) → int¶ Add a step to the integration algorithm that updates particle positions so all constraints are satisfied.
Returns:  int
the index of the step that was added

addConstrainVelocities
(self) → int¶ Add a step to the integration algorithm that updates particle velocities so the net velocity along all constraints is 0.
Returns:  int
the index of the step that was added

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:  int
the index of the variable that was added

addPerDofVariable
(self, name, initialValue) → int¶ Define a new perDOF 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:  int
the index of the variable that was added

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:  int
the index of the function that was added

addUpdateContextState
(self) → int¶ Add a step to the integration algorithm that allows Forces to update the context state.
Returns:  int
the index of the step that was added

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:  int
the index of the step that was added

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:  int
the index of the step that was added

classmethod
deserialize_xml
(xml_serialization)¶ Shortcut to deserialize the XML representation and the restore interface.
Parameters:  xml_serialization : str
The XML representation of the OpenMM custom force/integrator.
Returns:  openmm_object
The deserialized OpenMM force/integrator with the original interface restored (if restorable).

endBlock
(self) → int¶ Add a step which marks the end of the most recently begun “if” or “while” block.
Returns:  int
the index of the step that was added

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.

getConstraintTolerance
(self) → double¶ Get the distance tolerance within which constraints are maintained, as a fraction of the constrained distance.

getGlobalVariable
(self, index) → double¶ Get the current value of a global variable.
Parameters:  index : int
the index of the variable to get
Returns:  double
the current value of the variable

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:  double
the current value of the parameter

getGlobalVariableName
(self, index) → std::string const &¶ Get the name of a global variable.
Parameters:  index : int
the index of the variable to get
Returns:  string
the name of the variable

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.

getNumComputations
(self) → int¶ Get the number of computation steps that have been added.

getNumGlobalVariables
(self) → int¶ Get the number of global variables that have been defined.

getNumPerDofVariables
(self) → int¶ Get the number of perDOF variables that have been defined.

getNumTabulatedFunctions
(self) → int¶ Get the number of tabulated functions that have been defined.

getPerDofVariable
(self, index)¶ getPerDofVariable(self, index) > PyObject *

getPerDofVariableByName
(self, name)¶ Get the value of a perDOF variable, specified by name.
Parameters:  name : string
the name of the variable to get
Returns:  values : vector< Vec3 >
the values of the variable for all degrees of freedom are stored into this

getPerDofVariableName
(self, index) → std::string const &¶ Get the name of a perDOF variable.
Parameters:  index : int
the index of the variable to get
Returns:  string
the name of the variable

getRandomNumberSeed
(self) → int[source]¶ Get the random number seed. See setRandomNumberSeed() for details.

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:  double
the step size, measured in ps

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:  TabulatedFunction
the TabulatedFunction object defining the function

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:  string
the name of the function as it appears in expressions

getTemperature
()¶ Return the temperature of the heat bath.
Returns:  temperature : unit.Quantity
The temperature of the heat bath in kelvins.

get_acceptance_rate
()[source]¶ Get acceptance rate for Metropolized integrators.
Returns:  acceptance_rate : float
Acceptance rate. An Exception is thrown if the integrator is not Metropolized.

get_heat
(dimensionless=False)[source]¶ Get the current accumulated heat.
Parameters:  dimensionless : bool, optional, default=False
If specified, the work is returned in reduced (kT) unit.
Returns:  work : unit.Quantity or float
If dimensionless=True, the heat in kT (float). Otherwise, the unitbearing heat in units of energy.

get_shadow_work
(dimensionless=False)[source]¶ Get the current accumulated shadow work.
Parameters:  dimensionless : bool, optional, default=False
If specified, the work is returned in reduced (kT) unit.
Returns:  work : unit.Quantity or float
If dimensionless=True, the protocol work in kT (float). Otherwise, the unitbearing protocol work in units of energy.

is_metropolized
¶ Return True if this integrator is Metropolized, False otherwise.

classmethod
is_restorable
(openmm_object)¶ Check if the custom integrator or force has a restorable interface.
Parameters:  openmm_object : object
The custom integrator or force to check.
Returns:  True if the object has a restorable interface, False otherwise.

classmethod
is_thermostated
(integrator)¶ Return true if the integrator is a ThermostatedIntegrator.
This can be useful when you only have access to the Context CustomIntegrator, which loses all extra function during serialization.
Parameters:  integrator : simtk.openmm.Integrator
The integrator to check.
Returns:  True if the original CustomIntegrator class inherited from
 ThermostatedIntegrator, False otherwise.

kT
¶ The thermal energy in simtk.openmm.Quantity

pretty_format
(as_list=False, step_types_to_highlight=None)¶ Generate a humanreadable version of each integrator step.
Parameters:  as_list : bool, optional, default=False
If True, a list of humanreadable strings will be returned. If False, these will be concatenated into a single humanreadable string.
 step_types_to_highlight : list of int, optional, default=None
If specified, these step types will be highlighted.
Returns:  readable_lines : list of str
A list of humanreadable versions of each step of the integrator

pretty_print
()¶ Prettyprint the computation steps of this integrator.

classmethod
restore_interface
(integrator)¶ Restore the original interface of a CustomIntegrator.
The function restore the methods of the original class that inherited from ThermostatedIntegrator. Return False if the interface could not be restored.
Parameters:  integrator : simtk.openmm.CustomIntegrator
The integrator to which add methods.
Returns:  True if the original class interface could be restored, False otherwise.

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

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.

setPerDofVariable
(self, index, values)¶ Set the value of a perDOF 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 perDOF 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

setRandomNumberSeed
(self, seed)[source]¶ 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 nondeterministic 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.

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

setTemperature
(temperature)¶ Set the temperature of the heat bath.
Parameters:  temperature : unit.Quantity
The new temperature of the heat bath (temperature units).