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_vectors
3x3 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.
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)