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:
positionsNx3 openmm.unit.Quantity

Position vectors for N particles (length units).

velocitiesNx3 openmm.unit.Quantity, optional

Velocity vectors for N particles (velocity units).

box_vectors3x3 openmm.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_vectors3x3 openmm.unit.Quantity.

Box vectors.

potential_energy

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

kinetic_energy

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

Methods

__init__(positions[, velocities, box_vectors])

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

area_xy

The xy-area of the box (read-only)

box_vectors

Box vectors.

collective_variables

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

kinetic_energy

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

n_particles

Number of particles (read-only).

positions

Particle positions.

potential_energy

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