openmmtools.cache.ContextCache

class openmmtools.cache.ContextCache(platform=None, platform_properties=None, **kwargs)

LRU cache hosting the minimum amount of incompatible Contexts.

Two Contexts are compatible if they are in a compatible ThermodynamicState, and have compatible integrators. In general, two integrators are compatible if they have the same serialized state, but ContextCache can decide to store a single Context to optimize memory when two integrators differ by only few parameters that can be set after the Context is initialized. These parameters include all the global variables defined by a CustomIntegrator.

You can force ContextCache to consider an integrator global variable incompatible by adding it to the blacklist ContextCache.INCOMPATIBLE_INTEGRATOR_ATTRIBUTES. Similarly, you can add other attributes that should be considered compatible through the whitelist ContextCache.COMPATIBLE_INTEGRATOR_ATTRIBUTES. If an attribute in that dictionary is not found in the integrator, the cache will search for a corresponding getter and setter.

Parameters:

platformopenmm.Platform, optional

The OpenMM platform to use to create Contexts. If None, OpenMM tries to select the fastest one available (default is None).

platform_propertiesdict, optional

A dictionary of platform properties for the OpenMM platform. Only valid if the platform is not None (default is None).

**kwargs

Parameters to pass to the underlying LRUCache constructor such as capacity and time_to_live.

Attributes:

platform

The OpenMM platform to use to create Contexts.

capacity

The maximum number of Context cached.

time_to_live

The Contexts expiration date in number of accesses to the LRUCache.

Methods

empty()	Clear up cache and remove all Contexts.
get_context(thermodynamic_state[, integrator])	Return a context in the given thermodynamic state.

set_platform

Warning

Python instance attributes are not copied when ContextCache.get_context() is called. You can force this by setting adding them to the whitelist ContextCache.COMPATIBLE_INTEGRATOR_ATTRIBUTES, but if modifying your Python attributes won’t modify the OpenMM serialization, this will likely cause problems so this is discouraged unless you know exactly what you are doing.

See also

LRUCache

states.ThermodynamicState.is_state_compatible

Examples

>>> from openmm import unit
>>> from openmmtools import testsystems
>>> from openmmtools.states import ThermodynamicState
>>> alanine = testsystems.AlanineDipeptideExplicit()
>>> thermodynamic_state = ThermodynamicState(alanine.system, 310*unit.kelvin)
>>> time_step = 1.0*unit.femtosecond

Two compatible thermodynamic states generate only a single cached Context. ContextCache can also (in few explicitly supported cases) recycle the same Context even if the integrators differ by some parameters.

>>> context_cache = ContextCache()
>>> context1, integrator1 = context_cache.get_context(thermodynamic_state,
...                                                   openmm.VerletIntegrator(time_step))
>>> thermodynamic_state.temperature = 300*unit.kelvin
>>> time_step2 = 2.0*unit.femtosecond
>>> context2, integrator2 = context_cache.get_context(thermodynamic_state,
...                                                   openmm.VerletIntegrator(time_step2))
>>> id(context1) == id(context2)
True
>>> len(context_cache)
1

When we switch to NPT the states are not compatible and so neither the Contexts are.

>>> integrator2 = openmm.VerletIntegrator(2.0*unit.femtosecond)
>>> thermodynamic_state_npt = copy.deepcopy(thermodynamic_state)
>>> thermodynamic_state_npt.pressure = 1.0*unit.atmosphere
>>> context3, integrator3 = context_cache.get_context(thermodynamic_state_npt,
...                                                   openmm.VerletIntegrator(time_step))
>>> id(context1) == id(context3)
False
>>> len(context_cache)
2

You can set a capacity and a time to live for contexts like in a normal LRUCache.

>>> context_cache = ContextCache(capacity=1, time_to_live=5)
>>> context2, integrator2 = context_cache.get_context(thermodynamic_state,
...                                                   openmm.VerletIntegrator(time_step))
>>> context3, integrator3 = context_cache.get_context(thermodynamic_state_npt,
...                                                   openmm.VerletIntegrator(time_step))
>>> len(context_cache)
1

__init__(platform=None, platform_properties=None, **kwargs)

Methods

__init__([platform, platform_properties])
empty()	Clear up cache and remove all Contexts.
get_context(thermodynamic_state[, integrator])	Return a context in the given thermodynamic state.
set_platform(new_platform[, platform_properties])

Attributes

COMPATIBLE_INTEGRATOR_ATTRIBUTES
INCOMPATIBLE_INTEGRATOR_ATTRIBUTES
capacity	The maximum number of Context cached.
platform	The OpenMM platform to use to create Contexts.
time_to_live	The Contexts expiration date in number of accesses to the LRUCache.