openmmtools.states.SamplerState

class openmmtools.states.SamplerState(positions, velocities=None, box_vectors=None)

State carrying the configurational properties of a system.

Represent the portion of the state of a Context that changes with integration. When initialized through the normal constructor, the object is only partially defined as the energy attributes are None until the SamplerState is updated with update_from_context. The state can still be applied to a newly created context to set its positions, velocities and box vectors. To initialize all attributes, use the alternative constructor from_context.

Parameters:

positions : Nx3 simtk.unit.Quantity

Position vectors for N particles (length units).

velocities : Nx3 simtk.unit.Quantity, optional

Velocity vectors for N particles (velocity units).

box_vectors : 3x3 simtk.unit.Quantity

Current box vectors (length units).

Examples

>>> from openmmtools import testsystems
>>> toluene_test = testsystems.TolueneVacuum()
>>> sampler_state = SamplerState(toluene_test.positions)

At this point only the positions are defined

>>> sampler_state.velocities is None
True
>>> sampler_state.total_energy is None
True

but it can still be used to set up a context

>>> temperature = 300.0*unit.kelvin
>>> thermodynamic_state = ThermodynamicState(toluene_test.system, temperature)
>>> integrator = openmm.VerletIntegrator(1.0*unit.femtosecond)
>>> context = thermodynamic_state.create_context(integrator)
>>> sampler_state.apply_to_context(context)  # Set initial positions.

A SamplerState cannot be updated by an incompatible context which here is defined as having the same number of particles

>>> hostguest_test = testsystems.HostGuestVacuum()
>>> incompatible_state = ThermodynamicState(hostguest_test.system, temperature)
>>> integrator2 = openmm.VerletIntegrator(1.0*unit.femtosecond)
>>> incompatible_context = incompatible_state.create_context(integrator2)
>>> incompatible_context.setPositions(hostguest_test.positions)
>>> sampler_state.is_context_compatible(incompatible_context)
False
>>> sampler_state.update_from_context(incompatible_context)
Traceback (most recent call last):
...
SamplerStateError: Specified positions with inconsistent number of particles.

Create a new SamplerState instead

>>> sampler_state2 = SamplerState.from_context(context)
>>> sampler_state2.potential_energy is not None
True

It is possible to slice a sampler state to obtain positions and particles of a subset of atoms

>>> sliced_sampler_state = sampler_state[:10]
>>> sliced_sampler_state.n_particles
10

Attributes:

positions

Particle positions.

velocities

Particle velocities.

box_vectors : 3x3 simtk.unit.Quantity.

Box vectors.

potential_energy

simtk.unit.Quantity or None: Potential energy of this configuration.

kinetic_energy

simtk.unit.Quantity or None: Kinetic energy of this configuration.

total_energy

The sum of potential and kinetic energy (read-only).

volume

The volume of the box (read-only)

n_particles

Number of particles (read-only).

collective_variables

dict or None: Collective variables for this configuration if present in Context

Methods

apply_to_context(context[, ignore_velocities])	Set the context state.
from_context(context_state[, …])	Alternative constructor.
has_nan()	Check that energies and positions are finite.
is_context_compatible(context)	Check compatibility of the given context.
update_from_context(context_state[, …])	Read the state from the given Context or State object.

__init__(positions, velocities=None, box_vectors=None)

x.__init__(…) initializes x; see help(type(x)) for signature

Methods

__init__(positions[, velocities, box_vectors])	x.__init__(…) initializes x; see help(type(x)) for signature
apply_to_context(context[, ignore_velocities])	Set the context state.
from_context(context_state[, …])	Alternative constructor.
has_nan()	Check that energies and positions are finite.
is_context_compatible(context)	Check compatibility of the given context.
update_from_context(context_state[, …])	Read the state from the given Context or State object.

Attributes

box_vectors	Box vectors.
collective_variables	dict or None: Collective variables for this configuration if present in Context
kinetic_energy	simtk.unit.Quantity or None: Kinetic energy of this configuration.
n_particles	Number of particles (read-only).
positions	Particle positions.
potential_energy	simtk.unit.Quantity or None: Potential energy of this configuration.
total_energy	The sum of potential and kinetic energy (read-only).
velocities	Particle velocities.
volume	The volume of the box (read-only)

apply_to_context(context, ignore_velocities=False)

Set the context state.

If velocities and box vectors have not been specified in the constructor, they are not set.

Parameters:

context : simtk.openmm.Context

The context to set.

ignore_velocities : bool, optional

If True, velocities are not set in the Context even if they are defined. This can be useful if you only need to use the Context only to compute energies.

box_vectors

Box vectors.

An 3x3 simtk.unit.Quantity object.

collective_variables

dict or None: Collective variables for this configuration if present in Context

classmethod from_context(context_state, ignore_collective_variables=False)

Alternative constructor.

Read all the configurational properties from a Context object or an OpenMM State object. This guarantees that all attributes (including energy attributes) are initialized.

Parameters:

context_state : simtk.openmm.Context or simtk.openmm.State

The object to read. If a State object, it must contain information about positions, velocities and energy.

ignore_collective_variables : bool, optional

If True, the collective variables are not updated from the Context, and will be invalidated. If a State is passed in, this raises an error if False, otherwise, it would be ambiguous between a State tied to a System with collective variables, and one without.

Returns:

sampler_state : SamplerState

A new SamplerState object.

has_nan()

Check that energies and positions are finite.

Returns:

True if the potential energy or any of the generalized coordinates

are nan.

is_context_compatible(context)

Check compatibility of the given context.

The context is compatible if this SamplerState can be applied through apply_to_context.

Parameters:

context : simtk.openmm.Context

The context to test.

Returns:

is_compatible : bool

True if this SamplerState can be applied to context.

See also

SamplerState.apply_to_context

kinetic_energy

simtk.unit.Quantity or None: Kinetic energy of this configuration.

n_particles

Number of particles (read-only).

positions

Particle positions.

An Nx3 simtk.unit.Quantity object, where N is the number of particles.

Raises:

SamplerStateError

If set to an array with a number of particles different than n_particles.

potential_energy

simtk.unit.Quantity or None: Potential energy of this configuration.

total_energy

The sum of potential and kinetic energy (read-only).

update_from_context(context_state, ignore_positions=False, ignore_velocities=False, ignore_collective_variables=False)

Read the state from the given Context or State object.

The context must be compatible. Use SamplerState.from_context if you want to build a new sampler state from an incompatible.

Parameters:

context_state : simtk.openmm.Context or simtk.openmm.State

The object to read. If a State, it must contain information on positions, velocities and energies. Collective variables can only be updated from a Context, NOT a State at the moment.

ignore_positions : bool, optional

If True, the positions (and potential energy) are not updated from the Context. This can cause the SamplerState to no longer be consistent between its variables, so the defaults err on the side of updating everything, if possible. Only use if you know what you are doing.

ignore_velocities : bool, optional

If True, the velocities (and kinetic energy) are not updated from the Context. This can cause the SamplerState to no longer be consistent between its variables, so the defaults err on the side of updating everything, if possible. Only use if you know what you are doing.

ignore_collective_variables : bool, optional

If True, the collective variables are not updated from the Context. If a State is passed in, this raises an error if False, otherwise, it would be ambiguous between a State tied to a System with collective variables, and one without.

Raises:

SamplerStateError

If the given context is not compatible, or if a State is given without setting ignore_collective_variables

velocities

Particle velocities.

An Nx3 simtk.unit.Quantity object, where N is the number of particles.

Raises:

SamplerStateError

If set to an array with a number of particles different than n_particles.

volume

The volume of the box (read-only)