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)[source]¶
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
whereX
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 theMultiPhaseAnalyzer
.- 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
andj
of the state that is used for reference in observables, “O”. These values are only used when reporting single numbers or combining observables throughMultiPhaseAnalyzer
(since the number of states between phases can be different). Calls to functions such asget_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, theCachedProperty
dependencies are all invalidated and properties will be computed from scratch on next observablesIf 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
See also
- 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
andj
forMultiPhaseAnalyzer
instancesn_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
- __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)[source]¶
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
andj
forMultiPhaseAnalyzer
instancesreporter
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