mici.states module#

Objects for recording state of a Markov chain and caching computations.

class mici.states.ChainState(*, _call_counts=None, _read_only=False, _dependencies=None, _cache=None, **variables)[source]#

Bases: object

Markov chain state.

As well as recording the chain state variable values, the state object is also used to cache derived quantities to avoid recalculation if these values are subsequently reused.

Additionally for ChainState instances initialized with a _call_counts dictionary, any memoized system methods (i.e. those decorated with cache_in_state or cache_in_state_with_aux) will update a counter for the method in the state _call_counts dictionary attribute every time the decorated method is called (i.e. when there isn’t a valid cached value available).

Create a new ChainState instance.

Any keyword arguments passed to the constructor (with names not starting with an underscore) will be used to set state variable attributes of state object for example

state = ChainState(pos=pos_val, mom=mom_val, dir=dir_val)

will return a ChainState instance state with variable attributes state.pos, state.mom and state.dir with initial values set to pos_val, mom_val and dir_val respectively.

Keyword arguments with a leading underscore in the name are reserved for additional arguments to the constructor not corresponding to state variables. Additionally the name copy should not be used as attribute access to this name will be blocked by the copy method.

Parameters:

**variables (ArrayLike) – Keyword arguments corresponding to state variables. All names must not begin with an underscore and no name can be copy. See description above for details.
_call_counts (dict[str, int] | None) – If a dictionary (or Counter) is passed this will be used to store counts of the number of calls of system methods decorated with cache_in_state or cache_in_state_with_aux when called on this state object and when no cached value for the method is available so that the wrapped method is called. The _call_counts attribute persists between all copies of a state so will count any decorated method calls on copies of the state as well - e.g. all copies of a state in a sampled Markov chain, allowing the _call_counts attribute to be used to monitor the number of method call while sampling a chain.
_read_only (bool) – If True a mici.errors.ReadOnlyStateError exception will be raised when attempting to set any attributes of the state object after construction. Defaults to False.
_dependencies (dict[str, set[str]] | None) – Intended for internal use only. If not None this should be a dictionary with string keys corresponding to the state variable names and values which are sets of strings indicating any dependencies of the relevant state variable in the cache.
_cache (dict[str, Any] | None) – Intended for internal use only. If not None this should be a dictionary with keys corresponding to unique identifiers for methods decorated with the cache_in_state or cache_in_state_with_aux decorators and values corresponding to cached computed outputs of these methods or None for when a cached output is not available.

copy(*, read_only=False)[source]#

Create a deep copy of the state object.

Parameters:: read_only (bool) – Whether the state copy should be read-only.
Returns:: A copy of the state object with variable attributes that are independent copies of the original state object’s variables.
Return type:: ChainState

mici.states.cache_in_state(*depends_on)[source]#

Memoizing decorator for system methods.

Used to decorate mici.systems.System methods which compute a function of one or more chain state variable(s), with the decorated method caching the value returned by the method being wrapped in the ChainState object to prevent the need for recomputation on future calls if the state variables the returned value depends on have not been changed in between the calls.

Additionally for ChainState instances initialized with a _call_counts argument, the memoized method will update a counter for the method in the _call_counts attribute every time the method being decorated is called (i.e. when there isn’t a valid cached value available).

Parameters:: *depends_on (str) – One or more strings corresponding to the names of any state variables the value returned by the method depends on, e.g. pos or mom, such that the cache in the state object is correctly cleared when the value of any of these variables (attributes) of the state object changes.
Return type:: Callable[[SystemStateMethod], SystemStateMethod]

mici.states.cache_in_state_with_aux(depends_on, auxiliary_outputs)[source]#

Memoizing decorator for system methods with possible auxiliary outputs.

Used to decorate System methods which compute a function of one or more chain state variable(s), with the decorated method caching the value or values returned by the method being wrapped in the ChainState object to prevent the need for recomputation on future calls if the state variables the returned value(s) depends on have not been changed in between the calls.

Compared to the cache_in_state decorator, this variant allows for methods which may optionally also return additional auxiliary outputs, such as intermediate result computed while computing the primary output, which correspond to the output of another system method decorated with the cache_in_state or cache_in_state_with_aux decorators. If such auxiliary outputs are returned they are also used to update cache entry for the corresponding decorated method, potentially saving recomputation in subsequent calls to that method. A common instance of this pattern is in derivative values computed using automatic differentiation (AD), with the primal value being differentiated usually either calculated alongside the derivative (in forward-mode AD) or calculated first in a forward-pass before the derivatives are calculated in a reverse-pass (in reverse-mode AD). By caching the value of the primal computed as part of the derivative calculation, a subsequent call to a method corresponding to calculation of the primal itself will retrieve the cached value and not recompute the primal, providing the relevant state variables the primal (and derivative) depend on have not been changed in between.

Parameters:

depends_on (Iterable[str]) – A string or tuple of strings, with each string corresponding to the name of a state variables the value(s) returned by the method depends on, e.g. ‘pos’ or ‘mom’, such that the cache in the state object is correctly cleared when the value of any of these variables (attributes) of the state object changes.
auxiliary_outputs (Iterable[str]) – A string or tuple of strings, with each string defining an auxiliary output the wrapped method may additionally return in addition to the primary output. If auxiliary outputs are returned, the returned value should be a tuple with first entry the ‘primary’ output corresponding to the value associated with the name of the method and the subsequent entries in the tuple corresponding to the auxiliary outputs in the order specified by the entries in the auxiliary_outputs argument. If the primary output is itself a tuple, it must be wrapped in another tuple even when no auxiliary outputs are being returned.

Return type:

Callable[[SystemStateWithAuxMethod], SystemStateMethod]