# openmmtools.states.SamplerState¶

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

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):
...
openmmtools.states.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)[source]

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

Methods

 __init__(positions[, velocities, box_vectors]) Initialize self. 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)[source]

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

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. sampler_state : SamplerState A new SamplerState object.
has_nan()[source]

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

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. is_compatible : bool True if this SamplerState can be applied 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)[source]

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