# openmmtools.integrators.ThermostatedIntegrator¶

class openmmtools.integrators.ThermostatedIntegrator(temperature, *args, **kwargs)[source]

Add temperature functions to a CustomIntegrator.

This class is intended to be inherited by integrators that maintain the stationary distribution at a given temperature. The constructor adds a global variable named “kT” defining the thermal energy at the given temperature. This global variable is updated through the temperature setter and getter.

It also provide a utility function to handle per-DOF constants that must be computed only when the temperature changes.

Notice that the CustomIntegrator internally stored by a Context object will loose setter and getter and any extra function you define. The same happens when you copy your integrator. You can restore the methods with the static method ThermostatedIntegrator.restore_interface().

Parameters: temperature : unit.Quantity The temperature of the integrator heat bath (temperature units). timestep : unit.Quantity The timestep to pass to the CustomIntegrator constructor (time units).

Examples

We can inherit from ThermostatedIntegrator to automatically define setters and getters for the temperature and to add a per-DOF constant “sigma” that we need to update only when the temperature is changed.

>>> from simtk import openmm, unit
>>> class TestIntegrator(ThermostatedIntegrator):
...     def __init__(self, temperature=298.0*unit.kelvin, timestep=1.0*unit.femtoseconds):
...         super(TestIntegrator, self).__init__(temperature, timestep)
...         self.addPerDofVariable("sigma", 0)  # velocity standard deviation
...


We instantiate the integrator normally.

>>> integrator = TestIntegrator(temperature=350*unit.kelvin)
>>> integrator.getTemperature()
Quantity(value=350.0, unit=kelvin)
>>> integrator.setTemperature(380.0*unit.kelvin)
>>> integrator.getTemperature()
Quantity(value=380.0, unit=kelvin)
>>> integrator.getGlobalVariableByName('kT')
3.1594995390636815


Notice that a CustomIntegrator loses any extra method after a serialization cycle.

>>> integrator_serialization = openmm.XmlSerializer.serialize(integrator)
>>> deserialized_integrator = openmm.XmlSerializer.deserialize(integrator_serialization)
>>> deserialized_integrator.getTemperature()
Traceback (most recent call last):
...
AttributeError: type object 'object' has no attribute '__getattr__'


We can restore the original interface with a class method

>>> ThermostatedIntegrator.restore_interface(integrator)
True
>>> integrator.getTemperature()
Quantity(value=380.0, unit=kelvin)
>>> integrator.setTemperature(400.0*unit.kelvin)
>>> isinstance(integrator, TestIntegrator)
True

Attributes: global_variable_names The set of global variable names defined for this integrator. kT The thermal energy in simtk.openmm.Quantity

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 per-DOF 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 if-block 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 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. 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 per-DOF 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 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(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. 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 human-readable version of each integrator step. pretty_print() Pretty-print the computation steps of this integrator. 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 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. 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, *args, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

Methods

 __init__(temperature, *args, **kwargs) Initialize self. 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. addComputeTemperatureDependentConstants(…) Wrap the ComputePerDof into an if-block 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 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. 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 per-DOF 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 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(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. 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 human-readable version of each integrator step. pretty_print() Pretty-print the computation steps of this integrator. 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 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. 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 global_variable_names The set of global variable names defined for this integrator. kT The thermal energy in simtk.openmm.Quantity
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. int the index of the step that was added
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. 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 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. int the index of the step that was added
addComputeTemperatureDependentConstants(compute_per_dof)[source]

Wrap the ComputePerDof into an if-block 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 int the index of the variable that was added
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 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. 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. 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. 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. 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 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 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 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 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 per-DOF 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 per-DOF variable, specified by name.

Parameters: name : string the name of the variable to get 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 per-DOF variable.

Parameters: index : int the index of the variable to get string the name of the variable
getRandomNumberSeed(self) → int

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 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 string the name of the function as it appears in expressions
getTemperature()[source]

Return the temperature of the heat bath.

Returns: temperature : unit.Quantity The temperature of the heat bath in kelvins.
global_variable_names

The set of global variable names defined for this integrator.

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. True if the object has a restorable interface, False otherwise.
classmethod is_thermostated(integrator)[source]

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. 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 human-readable version of each integrator step.

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

Pretty-print the computation steps of this integrator.

classmethod restore_interface(integrator)[source]

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

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)[source]

Set the temperature of the heat bath.

Parameters: temperature : unit.Quantity The new temperature of the heat bath (temperature units).
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