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)[source]¶
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'
andrestraint_distance_cutoff
isNone
, 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'
andrestraint_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 thetimeseries_to_analyze
(another argument tomultistate.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)[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__
(*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
effective_length
float: The length of the production data as a number of uncorrelated samples
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
andj
forMultiPhaseAnalyzer
instancesreporter
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