openmmtools.multistate.multistateanalyzer.PhaseAnalyzer

class openmmtools.multistate.multistateanalyzer.PhaseAnalyzer(reporter, name=None, reference_states=(0, -1), max_n_iterations=None, analysis_kwargs=None, registry=<openmmtools.multistate.multistateanalyzer.ObservablesRegistry object>, use_online_data=True, use_full_trajectory=False)

Analyzer for a single phase of a MultiState simulation.

Uses the reporter from the simulation to determine the location of all variables.

To compute a specific observable in an implementation of this class, add it to the ObservableRegistry and then implement a get_X where X is the name of the observable you want to compute. See the ObservablesRegistry for information about formatting the observables.

Analyzer works in units of kT unless specifically stated otherwise. To convert back to a unit set, just multiply by the .kT property.

A PhaseAnalyzer also needs an ObservablesRegistry to track how to handle each observable given implemented within for things like error and cross-phase analysis.

Parameters:

reportermultistate.MultiStateReporter instance

Reporter from MultiState which ties to the simulation data on disk.

namestr, Optional

Unique name you want to assign this phase, this is the name that will appear in MultiPhaseAnalyzer’s. If not set, it will be given the arbitrary name “phase#” where # is an integer, chosen in order that it is assigned to the MultiPhaseAnalyzer.

max_n_iterationsint, optional

The maximum number of iterations to analyze. If not provided, all the iterations will be analyzed.

reference_statestuple of ints, length 2, Optional, Default: (0,-1)

Integers i and j of the state that is used for reference in observables, “O”. These values are only used when reporting single numbers or combining observables through MultiPhaseAnalyzer (since the number of states between phases can be different). Calls to functions such as get_free_energy in a single Phase results in the O being returned for all states.

For O completely defined by the state itself (i.e. no differences between states, e.g. Temperature), only O[i] is used

For O where differences between states are required (e.g. Free Energy): O[i,j] = O[j] - O[i]

For O defined by the phase as a whole, the reference states are not needed.

analysis_kwargsNone or dict, optional

Dictionary of extra keyword arguments to pass into the analysis tool, typically MBAR. For instance, the initial guess of relative free energies to give to MBAR would be something like: {'initial_f_k':[0,1,2,3]}

use_online_databool, optional, Default: True

Attempt to read online analysis data as a way to hot-start the analysis computation. This will attempt to read the data stored by the MultiStateAnalyzer.

If this is set to False, the online analysis data is not read.

If this is set to False after being initialized, the CachedProperty dependencies are all invalidated and properties will be computed from scratch on next observables

If no online data is found, this setting has no effect

use_full_trajectorybool, optional, Default: False

Force the analysis to use the full trajectory when automatically computing equilibration and decorrelation.

Normal behavior (when this is False) is to discard the initial trajectory due to automatic equilibration detection, and then subsample that data to generate decorelated samples. Setting this to True ignores this effect, even if the equilibration data is computed.

This can be changed after the PhaseAnalyzer has been created to re-compute properties with or without the full trajectory.

registryObservablesRegistry instance

Instanced ObservablesRegistry with all observables implemented through a get_X function classified and registered. Any cross-phase analysis must use the same instance of an ObservablesRegistry

Attributes:

name

User-readable string name of the phase

observables

List of observables that the instanced analyzer can compute/fetch.

max_n_iterations

reference_states

Tuple of reference states i and j for MultiPhaseAnalyzer instances

n_iterations

int: The total number of iterations of the phase.

n_replicas

int: Number of replicas.

n_states

int: Number of sampled thermodynamic states.

kT

Quantity of boltzmann constant times temperature of the phase in units of energy per mol

reporter

Sampler Reporter tied to this object.

registry

use_online_data

Get the online data flag

use_full_trajectory

Methods

clear()	Reset all cached objects.
get_effective_energy_timeseries([energies, ...])	Generate the effective energy (negative log deviance) timeseries that is generated for this phase
read_energies()	Extract energies from the ncfile and order them by replica, state, iteration.
read_logZ([iteration])	Extract logZ estimates from the ncfile, if present.
read_log_weights()	Extract log weights from the ncfile, if present.
reformat_energies_for_mbar(u_kln[, n_k])	Convert [replica, state, iteration] data into [state, total_iteration] data

See also

ObservablesRegistry

__init__(reporter, name=None, reference_states=(0, -1), max_n_iterations=None, analysis_kwargs=None, registry=<openmmtools.multistate.multistateanalyzer.ObservablesRegistry object>, use_online_data=True, use_full_trajectory=False)

The reporter provides the hook into how to read the data, all other options control where differences are measured from and how each phase interfaces with other phases.

Methods

__init__(reporter[, name, reference_states, ...])	The reporter provides the hook into how to read the data, all other options control where differences are measured from and how each phase interfaces with other phases.
clear()	Reset all cached objects.
get_effective_energy_timeseries([energies, ...])	Generate the effective energy (negative log deviance) timeseries that is generated for this phase
read_energies()	Extract energies from the ncfile and order them by replica, state, iteration.
read_logZ([iteration])	Extract logZ estimates from the ncfile, if present.
read_log_weights()	Extract log weights from the ncfile, if present.
reformat_energies_for_mbar(u_kln[, n_k])	Convert [replica, state, iteration] data into [state, total_iteration] data

Attributes

has_log_weights	Return True if the storage has log weights, False otherwise
kT	Quantity of boltzmann constant times temperature of the phase in units of energy per mol
max_n_iterations	Analyzer helper descriptor of a cached value with a dependency graph.
n_iterations	int: The total number of iterations of the phase.
n_replicas	int: Number of replicas.
n_states	int: Number of sampled thermodynamic states.
name	User-readable string name of the phase
observables	List of observables that the instanced analyzer can compute/fetch.
reference_states	Tuple of reference states i and j for MultiPhaseAnalyzer instances
reporter	Sampler Reporter tied to this object.
use_full_trajectory	Analyzer helper descriptor of a cached value with a dependency graph.
use_online_data	Get the online data flag