Package ffx.numerics.estimator

Class MultistateBennettAcceptanceRatio

java.lang.Object

ffx.numerics.estimator.SequentialEstimator

ffx.numerics.estimator.MultistateBennettAcceptanceRatio

All Implemented Interfaces:

BootstrappableEstimator, StatisticalEstimator, OptimizationInterface

public class MultistateBennettAcceptanceRatio
extends SequentialEstimator
implements BootstrappableEstimator, OptimizationInterface

The MultistateBennettAcceptanceRatio class defines a statistical estimator based on a generalization to the Bennett Acceptance Ratio (BAR) method for multiple lambda windows. It requires an input of K X N array of energies (every window at every snap at every lambda value). No support for different number of snapshots at each window. This will be caught by the filter, but not by the Harmonic Oscillators testcase.

This class implements the method discussed in: Shirts, M. R. and Chodera, J. D. (2008) Statistically optimal analysis of snaps from multiple equilibrium states. J. Chem. Phys. 129, 124105. doi:10.1063/1.2978177

This class is based heavily on the pymbar code, which is available from Github.

Since:

1.0

Author:

Matthew J. Speranza

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MultistateBennettAcceptanceRatio.HarmonicOscillatorsTestCase	Harmonic oscillators test case generates data for testing the MBAR implementation
static enum	MultistateBennettAcceptanceRatio.SeedType	Enum of MBAR seed types.

Field Summary

Fields

Modifier and Type	Field	Description
static boolean	FORCE_ZEROS_SEED
double[]	rtValues
static boolean	VERBOSE

Fields inherited from class ffx.numerics.estimator.SequentialEstimator

eAll, eAllFlat, eAt, eHigh, eLow, lamValues, nTrajectories, snaps, temperatures

Constructor Summary

Constructors

Constructor	Description
MultistateBennettAcceptanceRatio(double[] lambdaValues, double[][][] energiesAll, double[] temperature)	Constructor for MBAR estimator.
MultistateBennettAcceptanceRatio(double[] lambdaValues, double[][][] energiesAll, double[] temperature, double tolerance, MultistateBennettAcceptanceRatio.SeedType seedType)	Constructor for MBAR estimator.
MultistateBennettAcceptanceRatio(double[] lambdaValues, int[] snaps, double[][] eAllFlat, double[] temperature, double tolerance, MultistateBennettAcceptanceRatio.SeedType seedType)

Method Summary

Modifier and Type	Method	Description
MultistateBennettAcceptanceRatio	copyEstimator()	Return a copy of this Estimator.
double	energy(double[] x)	MBAR objective function evaluation at a given free energy estimate for L-BFGS optimization.
double	energyAndGradient(double[] x, double[] g)	MBAR objective function evaluation and gradient at a given free energy estimate for L-BFGS optimization.
void	estimateDG()	Get the MBAR free-energy estimates at each lambda value.
void	estimateDG(boolean randomSamples)	MBAR solved with self-consistent iteration and Newton/L-BFGS optimization.
BennettAcceptanceRatio	getBAR()
double[]	getBinEnergies()	Gets the free energy change per bin/window.
double[]	getBinEnthalpies()	Gets the enthalpy per bin/window.
double[]	getBinEntropies()
double[]	getBinUncertainties()	Gets the uncertainty in free energy associated with each bin/window.
double[]	getCoordinates(double[] parameters)	Load the current value of the parameters.
double	getFreeEnergy()	Returns the estimated free energy (usually in kcal/mol).
double[]	getMBARFreeEnergies()
int	getNumberOfVariables()	Get the number of variables being operated on.
double[]	getObservationEnsembleAverages()
double[]	getObservationEnsembleUncertainties()
double[][]	getReducedPotentials()
double[]	getScaling()	Get the problem scaling.
int[]	getSnaps()
double	getTIIntegral()
double	getTotalEnergy()	Get the total energy of the system
double	getUncertainty()	Returns the uncertainty in the free energy estimate.
double[][]	getUncertaintyMatrix()
static void	main(String[] args)	Example MBAR code usage and comparison with analytic answers for Harmonic Oscillators.
int	numberOfBins()	Returns the number of windows (BAR, etc), bins (WHAM, etc), or other sub-values used to compute free energy.
void	setBiasData(double[][] biasData)
void	setBiasData(double[][][] biasAll, boolean multiDataObservable)	Weight observable by exp(bias/RT) prior to computing expectation when set.
void	setObservableData(double[][][] oAll, boolean multiDataObservable, boolean uncertainties)
void	setObservableData(double[][] oAll, boolean uncertainties)
void	setScaling(double[] scaling)	Scale the problem.
static String[]	testMBARMethods()	Test all MBAR methods individually with a simple Harmonic Oscillator test case with an excess of samples.
static void	writeFile(double[][] energies, File file, double temperature)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface ffx.numerics.estimator.BootstrappableEstimator

sumBootstrapEnthalpyUncertainty, sumBootstrapResults, sumBootstrapUncertainty, sumEnthalpyBootstrapResults

Methods inherited from interface ffx.numerics.OptimizationInterface

destroy, energy, energyAndGradient, getUnderlyingPotentials, scaleCoordinates, scaleCoordinatesAndGradient, unscaleCoordinates

Field Details

rtValues

public double[] rtValues

FORCE_ZEROS_SEED

public static boolean FORCE_ZEROS_SEED

VERBOSE

public static boolean VERBOSE

Constructor Details

MultistateBennettAcceptanceRatio

public MultistateBennettAcceptanceRatio(double[] lambdaValues,
 double[][][] energiesAll,
 double[] temperature)

Constructor for MBAR estimator.

Parameters:

lambdaValues - array of lambda values

energiesAll - array of energies at each lambda value

temperature - array of temperatures

MultistateBennettAcceptanceRatio

public MultistateBennettAcceptanceRatio(double[] lambdaValues,
 double[][][] energiesAll,
 double[] temperature,
 double tolerance,
 MultistateBennettAcceptanceRatio.SeedType seedType)

Constructor for MBAR estimator.

Parameters:

lambdaValues - array of lambda values

energiesAll - array of energies at each lambda value

temperature - array of temperatures

tolerance - convergence tolerance

seedType - seed type for MBAR

MultistateBennettAcceptanceRatio

public MultistateBennettAcceptanceRatio(double[] lambdaValues,
 int[] snaps,
 double[][] eAllFlat,
 double[] temperature,
 double tolerance,
 MultistateBennettAcceptanceRatio.SeedType seedType)

Method Details

estimateDG

public void estimateDG()

Get the MBAR free-energy estimates at each lambda value.

Specified by:

estimateDG in interface BootstrappableEstimator

estimateDG

public void estimateDG(boolean randomSamples)

MBAR solved with self-consistent iteration and Newton/L-BFGS optimization.

Specified by:

estimateDG in interface BootstrappableEstimator

Parameters:

randomSamples - Whether to draw random samples with replacement (one bootstrap trial).

setBiasData

public void setBiasData(double[][][] biasAll,
 boolean multiDataObservable)

Weight observable by exp(bias/RT) prior to computing expectation when set.

Parameters:

biasAll -

multiDataObservable -

setBiasData

public void setBiasData(double[][] biasData)

setObservableData

public void setObservableData(double[][][] oAll,
 boolean multiDataObservable,
 boolean uncertainties)

setObservableData

public void setObservableData(double[][] oAll,
 boolean uncertainties)

getTIIntegral

public double getTIIntegral()

energy

public double energy(double[] x)

MBAR objective function evaluation at a given free energy estimate for L-BFGS optimization.

Specified by:

energy in interface OptimizationInterface

Parameters:

x - Input parameters.

Returns:

The objective function value at the given parameters.

energyAndGradient

public double energyAndGradient(double[] x,
 double[] g)

MBAR objective function evaluation and gradient at a given free energy estimate for L-BFGS optimization.

Specified by:

energyAndGradient in interface OptimizationInterface

Parameters:

x - Input parameters.

g - The gradient with respect to each parameter.

Returns:

The objective function value at the given parameters.

getCoordinates

public double[] getCoordinates(double[] parameters)

Description copied from interface: OptimizationInterface

Load the current value of the parameters. If the supplied array is null or not large enough, a new one should be created. The filled array is returned.

Specified by:

getCoordinates in interface OptimizationInterface

Parameters:

parameters - Supplied array.

Returns:

The array filled with parameter values.

getNumberOfVariables

public int getNumberOfVariables()

Description copied from interface: OptimizationInterface

Get the number of variables being operated on.

Specified by:

getNumberOfVariables in interface OptimizationInterface

Returns:

Number of variables.

getScaling

public double[] getScaling()

Description copied from interface: OptimizationInterface

Get the problem scaling.

Specified by:

getScaling in interface OptimizationInterface

Returns:

The scaling value used for each variable.

setScaling

public void setScaling(double[] scaling)

Description copied from interface: OptimizationInterface

Scale the problem. A good choice for optimization is the square root of the median eigenvalue of a typical Hessian.

Specified by:

setScaling in interface OptimizationInterface

Parameters:

scaling - The scaling value to use for each variable.

getTotalEnergy

public double getTotalEnergy()

Description copied from interface: OptimizationInterface

Get the total energy of the system

Specified by:

getTotalEnergy in interface OptimizationInterface

Returns:

the total energy

getBAR

public BennettAcceptanceRatio getBAR()

copyEstimator

public MultistateBennettAcceptanceRatio copyEstimator()

Description copied from interface: BootstrappableEstimator

Return a copy of this Estimator. Each implementation should specify its own type as the return type. Intended to make parallelization of bootstrapping easy.

Specified by:

copyEstimator in interface BootstrappableEstimator

Returns:

A copy of this Estimator.

getBinEnergies

public double[] getBinEnergies()

Description copied from interface: StatisticalEstimator

Gets the free energy change per bin/window.

Specified by:

getBinEnergies in interface StatisticalEstimator

Returns:

Individual bin/window free energy changes.

getMBARFreeEnergies

public double[] getMBARFreeEnergies()

getReducedPotentials

public double[][] getReducedPotentials()

getSnaps

public int[] getSnaps()

getBinUncertainties

public double[] getBinUncertainties()

Description copied from interface: StatisticalEstimator

Gets the uncertainty in free energy associated with each bin/window.

Specified by:

getBinUncertainties in interface StatisticalEstimator

Returns:

Individual bin/window uncertainties.

getObservationEnsembleAverages

public double[] getObservationEnsembleAverages()

getObservationEnsembleUncertainties

public double[] getObservationEnsembleUncertainties()

getUncertaintyMatrix

public double[][] getUncertaintyMatrix()

getFreeEnergy

public double getFreeEnergy()

Description copied from interface: StatisticalEstimator

Returns the estimated free energy (usually in kcal/mol).

Specified by:

getFreeEnergy in interface StatisticalEstimator

Returns:

Free energy estimate.

getUncertainty

public double getUncertainty()

Description copied from interface: StatisticalEstimator

Returns the uncertainty in the free energy estimate.

Specified by:

getUncertainty in interface StatisticalEstimator

Returns:

Uncertainty in the free energy estimate.

numberOfBins

public int numberOfBins()

Description copied from interface: StatisticalEstimator

Returns the number of windows (BAR, etc), bins (WHAM, etc), or other sub-values used to compute free energy.

Specified by:

numberOfBins in interface StatisticalEstimator

Returns:

Total number of sub-values used to compute free energy.

getBinEnthalpies

public double[] getBinEnthalpies()

Description copied from interface: StatisticalEstimator

Gets the enthalpy per bin/window.

Specified by:

getBinEnthalpies in interface StatisticalEstimator

Returns:

Individual bin/window enthalpy.

getBinEntropies

public double[] getBinEntropies()

writeFile

public static void writeFile(double[][] energies,
 File file,
 double temperature)

testMBARMethods

public static String[] testMBARMethods()

Test all MBAR methods individually with a simple Harmonic Oscillator test case with an excess of samples. "PASS" indicates that the test passed, while "FAIL" followed by the method name indicates that the test failed.

Last updated - 06/11/2024

Returns:

array of test results

main

public static void main(String[] args)

Example MBAR code usage and comparison with analytic answers for Harmonic Oscillators.

Parameters:

args -