Context Class Reference

A Context stores the complete state of a simulation. More...

#include <Context.h>

Public Member Functions
	Context (const System &system, Integrator &integrator)
	Construct a new Context in which to run a simulation. More...
	Context (const System &system, Integrator &integrator, Platform &platform)
	Construct a new Context in which to run a simulation, explicitly specifying what Platform should be used to perform calculations. More...
	Context (const System &system, Integrator &integrator, Platform &platform, const std::map< std::string, std::string > &properties)
	Construct a new Context in which to run a simulation, explicitly specifying what Platform should be used to perform calculations and the values of platform-specific properties. More...
	~Context ()
const System &	getSystem () const
	Get System being simulated in this context. More...
const Integrator &	getIntegrator () const
	Get Integrator being used to by this context. More...
Integrator &	getIntegrator ()
	Get Integrator being used to by this context. More...
const Platform &	getPlatform () const
	Get the Platform being used for calculations. More...
Platform &	getPlatform ()
	Get the Platform being used for calculations. More...
State	getState (int types, bool enforcePeriodicBox=false, int groups=0xFFFFFFFF) const
	Get a State object recording the current state information stored in this context. More...
void	setState (const State &state)
	Copy information from a State object into this Context. More...
void	setTime (double time)
	Set the current time of the simulation (in picoseconds). More...
void	setPositions (const std::vector< Vec3 > &positions)
	Set the positions of all particles in the System (measured in nm). More...
void	setVelocities (const std::vector< Vec3 > &velocities)
	Set the velocities of all particles in the System (measured in nm/picosecond). More...
void	setVelocitiesToTemperature (double temperature, int randomSeed=time(NULL))
	Set the velocities of all particles in the System to random values chosen from a Boltzmann distribution at a given temperature. More...
double	getParameter (const std::string &name) const
	Get the value of an adjustable parameter defined by a Force object in the System. More...
void	setParameter (const std::string &name, double value)
	Set the value of an adjustable parameter defined by a Force object in the System. More...
void	setPeriodicBoxVectors (const Vec3 &a, const Vec3 &b, const Vec3 &c)
	Set the vectors defining the axes of the periodic box (measured in nm). More...
void	applyConstraints (double tol)
	Update the positions of particles so that all distance constraints are satisfied. More...
void	applyVelocityConstraints (double tol)
	Update the velocities of particles so the net velocity of each constrained distance is zero. More...
void	computeVirtualSites ()
	Recompute the locations of all virtual sites. More...
void	reinitialize ()
	When a Context is created, it may cache information about the System being simulated and the Force objects contained in it. More...
void	createCheckpoint (std::ostream &stream)
	Create a checkpoint recording the current state of the Context. More...
void	loadCheckpoint (std::istream &stream)
	Load a checkpoint that was written by createCheckpoint(). More...

Friends
class	Force
class	Platform

Detailed Description

A Context stores the complete state of a simulation.

More specifically, it includes:

• The current time
• The position of each particle
• The velocity of each particle
• The values of configurable parameters defined by Force objects in the System

You can retrieve a snapshot of the current state at any time by calling getState(). This allows you to record the state of the simulation at various points, either for analysis or for checkpointing. getState() can also be used to retrieve the current forces on each particle and the current energy of the System.

Constructor & Destructor Documentation

Context	(	const System &	system,
		Integrator &	integrator
	)

Construct a new Context in which to run a simulation.

Parameters

system	the System which will be simulated
integrator	the Integrator which will be used to simulate the System

Context	(	const System &	system,
		Integrator &	integrator,
		Platform &	platform
	)

Construct a new Context in which to run a simulation, explicitly specifying what Platform should be used to perform calculations.

Parameters

system	the System which will be simulated
integrator	the Integrator which will be used to simulate the System
platform	the Platform to use for calculations

Context	(	const System &	system,
		Integrator &	integrator,
		Platform &	platform,
		const std::map< std::string, std::string > &	properties
	)

Construct a new Context in which to run a simulation, explicitly specifying what Platform should be used to perform calculations and the values of platform-specific properties.

Parameters

system	the System which will be simulated
integrator	the Integrator which will be used to simulate the System
platform	the Platform to use for calculations
properties	a set of values for platform-specific properties. Keys are the property names.

~Context

(

)

Member Function Documentation

void applyConstraints

(

double

tol

)

Update the positions of particles so that all distance constraints are satisfied.

This also recomputes the locations of all virtual sites.

Parameters

tol	the distance tolerance within which constraints must be satisfied.

void applyVelocityConstraints

(

double

tol

)

Update the velocities of particles so the net velocity of each constrained distance is zero.

Parameters

tol	the velocity tolerance within which constraints must be satisfied.

void computeVirtualSites

(

)

Recompute the locations of all virtual sites.

There is rarely a reason to call this, since virtual sites are also updated by applyConstraints(). This is only for the rare situations when you want to enforce virtual sites but not constraints.

void createCheckpoint

(

std::ostream &

stream

)

Create a checkpoint recording the current state of the Context.

This should be treated as an opaque block of binary data. See loadCheckpoint() for more details.

Parameters

stream

an output stream the checkpoint data should be written to

const Integrator& getIntegrator

(

)

const

Get Integrator being used to by this context.

Integrator& getIntegrator

(

)

Get Integrator being used to by this context.

double getParameter

(

const std::string &

name

)

const

Get the value of an adjustable parameter defined by a Force object in the System.

Parameters

name	the name of the parameter to get

const Platform& getPlatform

(

)

const

Get the Platform being used for calculations.

Platform& getPlatform

(

)

Get the Platform being used for calculations.

State getState	(	int	types,
		bool	enforcePeriodicBox = false,
		int	groups = 0xFFFFFFFF
	)		const

Get a State object recording the current state information stored in this context.

Parameters

types	the set of data types which should be stored in the State object. This should be a union of DataType values, e.g. (State::Positions | State::Velocities).
enforcePeriodicBox	if false, the position of each particle will be whatever position is stored in the Context, regardless of periodic boundary conditions. If true, particle positions will be translated so the center of every molecule lies in the same periodic box.
groups	a set of bit flags for which force groups to include when computing forces and energies. Group i will be included if (groups&(1<<i)) != 0. The default value includes all groups.

const System& getSystem

(

)

const

Get System being simulated in this context.

void loadCheckpoint

(

std::istream &

stream

)

Load a checkpoint that was written by createCheckpoint().

A checkpoint contains not only publicly visible data such as the particle positions and velocities, but also internal data such as the states of random number generators. Ideally, loading a checkpoint should restore the Context to an identical state to when it was written, such that continuing the simulation will produce an identical trajectory. This is not strictly guaranteed to be true, however, and should not be relied on. For most purposes, however, the internal state should be close enough to be reasonably considered equivalent.

A checkpoint contains data that is highly specific to the Context from which it was created. It depends on the details of the System, the Platform being used, and the hardware and software of the computer it was created on. If you try to load it on a computer with different hardware, or for a System that is different in any way, loading is likely to fail. Checkpoints created with different versions of OpenMM are also often incompatible. If a checkpoint cannot be loaded, that is signaled by throwing an exception.

Parameters

stream

an input stream the checkpoint data should be read from

void reinitialize

(

)

When a Context is created, it may cache information about the System being simulated and the Force objects contained in it.

This means that, if the System or Forces are then modified, the Context might not see all of the changes. Call reinitialize() to force the Context to rebuild its internal representation of the System and pick up any changes that have been made.

This is an expensive operation, so you should try to avoid calling it too frequently.

void setParameter	(	const std::string &	name,
		double	value
	)

Set the value of an adjustable parameter defined by a Force object in the System.

Parameters

name	the name of the parameter to set
value	the value of the parameter

void setPeriodicBoxVectors	(	const Vec3 &	a,
		const Vec3 &	b,
		const Vec3 &	c
	)

Set the vectors defining the axes of the periodic box (measured in nm).

They will affect any Force that uses periodic boundary conditions.

Currently, only rectangular boxes are supported. This means that a, b, and c must be aligned with the x, y, and z axes respectively. Future releases may support arbitrary triclinic boxes.

Parameters

a	the vector defining the first edge of the periodic box
b	the vector defining the second edge of the periodic box
c	the vector defining the third edge of the periodic box

void setPositions

(

const std::vector< Vec3 > &

positions

)

Set the positions of all particles in the System (measured in nm).

This method simply sets the positions without checking to see whether they satisfy distance constraints. If you want constraints to be enforced, call applyConstraints() after setting the positions.

Parameters

positions

a vector whose length equals the number of particles in the System. The i'th element contains the position of the i'th particle.

void setState

(

const State &

state

)

Copy information from a State object into this Context.

This restores the Context to approximately the same state it was in when the State was created. If the State does not include a piece of information (e.g. positions or velocities), that aspect of the Context is left unchanged.

Even when all possible information is included in the State, the effect of calling this method is still less complete than loadCheckpoint(). For example, it does not restore the internal states of random number generators. On the other hand, it has the advantage of not being hardware specific.

void setTime

(

double

time

)

Set the current time of the simulation (in picoseconds).

void setVelocities

(

const std::vector< Vec3 > &

velocities

)

Set the velocities of all particles in the System (measured in nm/picosecond).

Parameters

velocities

a vector whose length equals the number of particles in the System. The i'th element contains the velocity of the i'th particle.

void setVelocitiesToTemperature	(	double	temperature,
		int	randomSeed = time(NULL)
	)

Set the velocities of all particles in the System to random values chosen from a Boltzmann distribution at a given temperature.

Parameters

temperature	the temperature for which to select the velocities (measured in Kelvin)
randomSeed	the random number seed to use when selecting velocities

Friends And Related Function Documentation

friend class Force

friend

friend class Platform

friend

---

The documentation for this class was generated from the following file:

• Context.h