openmmtools.multistate.MultiStateSamplerAnalyzer

class openmmtools.multistate.MultiStateSamplerAnalyzer(*args, unbias_restraint=True, restraint_energy_cutoff='auto', restraint_distance_cutoff='auto', n_equilibration_iterations=None, statistical_inefficiency=None, max_subset=100, **kwargs)

The MultiStateSamplerAnalyzer is the analyzer for a simulation generated from a MultiStateSampler simulation, implemented as an instance of the PhaseAnalyzer.

Parameters

unbias_restraintbool, optional

If True and a radially-symmetric restraint was used in the simulation, the analyzer will remove the bias introduced by the restraint by reweighting each of the end-points to a state using a square-well potential restraint.

restraint_energy_cutofffloat or ‘auto’, optional

When the restraint is unbiased, the analyzer discards all the samples for which the restrain potential energy (in kT) is above this cutoff. Effectively, this is equivalent to placing a hard wall potential at a restraint distance such that the restraint potential energy is equal to restraint_energy_cutoff.

If 'auto' and restraint_distance_cutoff is None, this will be set to the 99.9-percentile of the distribution of the restraint energies in the bound state.

restraint_distance_cutoffopenmm.unit.Quantity or ‘auto’, optional

When the restraint is unbiased, the analyzer discards all the samples for which the distance between the restrained atoms is above this cutoff. Effectively, this is equivalent to placing a hard wall potential at a restraint distance restraint_distance_cutoff.

If 'auto' and restraint_energy_cutoff is not specified, this will be set to the 99.9-percentile of the distribution of the restraint distances in the bound state.

n_equilibration_iterationsint, optional

Number of iterations to discard due to equilibration. If specified, overrides the n_equilibration_iterations computed using _get_equilibration_data(). Default is None, in which case n_equilibration_iterations will be computed using _get_equilibration_data().

statistical_inefficiencyfloat, optional

Sub-sample rate, e.g. if the statistical_inefficiency is 10, we draw a sample every 10 iterations to get the decorrelated samples. If specified, overrides the statistical_inefficiency computed using _get_equilibration_data() and n_equilibration_iterations must be specified as well. Default is None, in which case the the statistical_inefficiency will be computed using _get_equilibration_data().

max_subsetint >= 1 or None, optional, default: 100

Argument in multistate.utils.get_equilibration_data_per_sample() that specifies the maximum number of points from the timeseries_to_analyze (another argument to multistate.utils.get_equilibration_data_per_sample()) on which to compute equilibration data.

See also

PhaseAnalyzer

Attributes

unbias_restraint

restraint_energy_cutoff

restraint_distance_cutoff

mbar

n_equilibration_iterations

int: The number of equilibration iterations.

statistical_inefficiency

float: The statistical inefficiency of the sampler.

Methods

clear()	Reset all cached objects.
generate_mixing_statistics([number_equilibrated])	Compute and return replica mixing statistics.
get_effective_energy_timeseries([energies, ...])	Generate the effective energy (negative log deviance) timeseries that is generated for this phase.
get_enthalpy()	Compute the difference in enthalpy and error in that estimate from the MBAR object
get_entropy()	Compute the difference in entropy and error in that estimate from the MBAR object
get_free_energy()	Compute the free energy and error in free energy from the MBAR object
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
show_mixing_statistics([cutoff, ...])	Print summary of mixing statistics.

__init__(*args, unbias_restraint=True, restraint_energy_cutoff='auto', restraint_distance_cutoff='auto', n_equilibration_iterations=None, statistical_inefficiency=None, max_subset=100, **kwargs)

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__(*args[, unbias_restraint, ...])	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.
generate_mixing_statistics([number_equilibrated])	Compute and return replica mixing statistics.
get_effective_energy_timeseries([energies, ...])	Generate the effective energy (negative log deviance) timeseries that is generated for this phase.
get_enthalpy()	Compute the difference in enthalpy and error in that estimate from the MBAR object
get_entropy()	Compute the difference in entropy and error in that estimate from the MBAR object
get_free_energy()	Compute the free energy and error in free energy from the MBAR object
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
show_mixing_statistics([cutoff, ...])	Print summary of mixing statistics.

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.
mbar	Analyzer helper descriptor of a cached value with a dependency graph.
n_equilibration_iterations	int: The number of equilibration iterations.
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.
restraint_distance_cutoff	Analyzer helper descriptor of a cached value with a dependency graph.
restraint_energy_cutoff	Analyzer helper descriptor of a cached value with a dependency graph.
statistical_inefficiency	float: The statistical inefficiency of the sampler.
unbias_restraint	Analyzer helper descriptor of a cached value with a dependency graph.
use_full_trajectory	Analyzer helper descriptor of a cached value with a dependency graph.
use_online_data	Get the online data flag