openmmtools.states.CompoundThermodynamicState

class openmmtools.states.CompoundThermodynamicState(thermodynamic_state, composable_states)[source]

Thermodynamic state composed by multiple states.

Allows to extend a ThermodynamicState through composition rather than inheritance.

The class dynamically inherits from the ThermodynamicState object given in the constructor, and it preserves direct access to all its methods and attributes. It is compatible also with subclasses of ThermodynamicState, but it does not support objects which make use of __slots__.

It is the user’s responsibility to check that IComposableStates are compatible to each other (i.e. that they do not depend on and/or modify the same properties of the system). If this is not the case, consider merging them into a single IComposableStates. If an IComposableState needs to access properties of ThermodynamicState (e.g. temperature, pressure) consider extending it through normal inheritance.

It is not necessary to explicitly inherit from IComposableState for compatibility as long as all abstract methods are implemented. All its attributes and methods will still be directly accessible unless they are masked by the main ThermodynamicState or by a IComposableState that appeared before in the constructor argument composable_states.

After construction, changing the original thermodynamic_state or any of the composable_states changes the state of the compound state.

Parameters:
thermodynamic_stateThermodynamicState

The main ThermodynamicState which holds the OpenMM system.

composable_stateslist of IComposableState

Each element represent a portion of the overall thermodynamic state.

Examples

Create an alchemically modified system.

>>> from openmmtools import testsystems, alchemy
>>> factory = alchemy.AbsoluteAlchemicalFactory(consistent_exceptions=False)
>>> alanine_vacuum = testsystems.AlanineDipeptideVacuum().system
>>> alchemical_region = alchemy.AlchemicalRegion(alchemical_atoms=range(22))
>>> alanine_alchemical_system = factory.create_alchemical_system(reference_system=alanine_vacuum,
...                                                              alchemical_regions=alchemical_region)
>>> alchemical_state = alchemy.AlchemicalState.from_system(alanine_alchemical_system)

AlchemicalState implement the IComposableState interface, so it can be used with CompoundThermodynamicState. All the alchemical parameters are accessible through the compound state.

>>> import openmm
>>> from openmm import unit
>>> thermodynamic_state = ThermodynamicState(system=alanine_alchemical_system,
...                                                 temperature=300*unit.kelvin)
>>> compound_state = CompoundThermodynamicState(thermodynamic_state=thermodynamic_state,
...                                                    composable_states=[alchemical_state])
>>> compound_state.lambda_sterics
1.0
>>> compound_state.lambda_electrostatics
1.0

You can control the parameters in the OpenMM Context in this state by setting the state attributes.

>>> compound_state.lambda_sterics = 0.5
>>> integrator = openmm.VerletIntegrator(1.0*unit.femtosecond)
>>> context = compound_state.create_context(integrator)
>>> context.getParameter('lambda_sterics')
0.5
>>> compound_state.lambda_sterics = 1.0
>>> compound_state.apply_to_context(context)
>>> context.getParameter('lambda_sterics')
1.0
Attributes:
barostat

The barostat associated to the system.

beta

Thermodynamic beta in units of mole/energy.

default_box_vectors

The default box vectors of the System (read-only).

is_periodic

True if the system is in a periodic box (read-only).

kT

Thermal energy per mole.

n_particles

Number of particles (read-only).

pressure

Constant pressure of the thermodynamic state.

surface_tension

Surface tension

system

The system in this thermodynamic state.

temperature

Constant temperature of the thermodynamic state.

volume

Constant volume of the thermodynamic state (read-only).

Methods

apply_to_context(context)

Apply this compound thermodynamic state to the context.

create_context(integrator[, platform, ...])

Create a context in this ThermodynamicState.

get_system(**kwargs)

Manipulate and return the system.

get_volume([ignore_ensemble])

Volume of the periodic box (read-only).

is_context_compatible(context)

Check compatibility of the given context.

is_state_compatible(thermodynamic_state)

Check compatibility between ThermodynamicStates.

reduced_potential(context_state)

Reduced potential in this thermodynamic state.

reduced_potential_at_states(context, ...)

Efficiently compute the reduced potential for a list of compatible states.

set_system(system[, fix_state])

Allow to set the system and fix its thermodynamic state.

__init__(thermodynamic_state, composable_states)[source]

Methods

__init__(thermodynamic_state, composable_states)

apply_to_context(context)

Apply this compound thermodynamic state to the context.

create_context(integrator[, platform, ...])

Create a context in this ThermodynamicState.

get_system(**kwargs)

Manipulate and return the system.

get_volume([ignore_ensemble])

Volume of the periodic box (read-only).

is_context_compatible(context)

Check compatibility of the given context.

is_state_compatible(thermodynamic_state)

Check compatibility between ThermodynamicStates.

reduced_potential(context_state)

Reduced potential in this thermodynamic state.

reduced_potential_at_states(context, ...)

Efficiently compute the reduced potential for a list of compatible states.

set_system(system[, fix_state])

Allow to set the system and fix its thermodynamic state.

Attributes

barostat

The barostat associated to the system.

beta

Thermodynamic beta in units of mole/energy.

default_box_vectors

The default box vectors of the System (read-only).

is_periodic

True if the system is in a periodic box (read-only).

kT

Thermal energy per mole.

n_particles

Number of particles (read-only).

pressure

Constant pressure of the thermodynamic state.

surface_tension

Surface tension

system

The system in this thermodynamic state.

temperature

Constant temperature of the thermodynamic state.

volume

Constant volume of the thermodynamic state (read-only).