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 ClassesModifier and TypeClassDescriptionstatic class
Harmonic oscillators test case generates data for testing the MBAR implementationstatic enum
Enum of MBAR seed types. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic boolean
double[]
static boolean
Fields inherited from class ffx.numerics.estimator.SequentialEstimator
eAll, eAllFlat, eLambda, eLambdaMinusdL, eLambdaPlusdL, lamValues, nSamples, nStates, temperatures
-
Constructor Summary
ConstructorsConstructorDescriptionMultistateBennettAcceptanceRatio
(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 TypeMethodDescriptionReturn 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
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.getBAR()
double[]
double[]
getCoordinates
(double[] parameters) Load the current value of the parameters.double[]
Gets the enthalpy change between each pair of states.double[]
Gets the uncertainty in free energy difference between each pair of states.double[]
Gets the free energy difference between each pair of states.double[]
int
Returns the number of windows (BAR, etc), bins (WHAM, etc), or other sub-values used to compute the total free energy difference.int
Get the number of variables being operated on.double[]
double[]
double[][]
double[]
Get the problem scaling.int[]
getSnaps()
double
double
Get the total energy of the systemdouble
Gets the total enthalpy difference between the first and last state.double
Returns the total uncertainty in the computed free energy difference between the first and last state.double
Returns the total free energy difference between the first and last state.double[][]
static void
Example MBAR code usage and comparison with analytic answers for Harmonic Oscillators.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[]
Test all MBAR methods individually with a simple Harmonic Oscillator test case with an excess of samples.static void
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
getTotalEnthalpyDifference, getTotalEnthalpyUncertainty, getTotalFEDifferenceUncertainty, getTotalFreeEnergyDifference
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 valuesenergiesAll
- array of energies at each lambda valuetemperature
- 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 valuesenergiesAll
- array of energies at each lambda valuetemperature
- array of temperaturestolerance
- convergence toleranceseedType
- 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 interfaceBootstrappableEstimator
-
estimateDG
public void estimateDG(boolean randomSamples) MBAR solved with self-consistent iteration and Newton/L-BFGS optimization.- Specified by:
estimateDG
in interfaceBootstrappableEstimator
- 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 interfaceOptimizationInterface
- 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 interfaceOptimizationInterface
- 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 interfaceOptimizationInterface
- 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 interfaceOptimizationInterface
- Returns:
- Number of variables.
-
getScaling
public double[] getScaling()Description copied from interface:OptimizationInterface
Get the problem scaling.- Specified by:
getScaling
in interfaceOptimizationInterface
- 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 interfaceOptimizationInterface
- 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 interfaceOptimizationInterface
- Returns:
- the total energy
-
getBAR
-
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 interfaceBootstrappableEstimator
- Returns:
- A copy of this Estimator.
-
getFreeEnergyDifferences
public double[] getFreeEnergyDifferences()Description copied from interface:StatisticalEstimator
Gets the free energy difference between each pair of states.- Specified by:
getFreeEnergyDifferences
in interfaceStatisticalEstimator
- Returns:
- Array of free energy differences between states.
-
getMBARFreeEnergies
public double[] getMBARFreeEnergies() -
getReducedPotentials
public double[][] getReducedPotentials() -
getSnaps
public int[] getSnaps() -
getFEDifferenceUncertainties
public double[] getFEDifferenceUncertainties()Description copied from interface:StatisticalEstimator
Gets the uncertainty in free energy difference between each pair of states.- Specified by:
getFEDifferenceUncertainties
in interfaceStatisticalEstimator
- Returns:
- Array of uncertainties in the free energy differences.
-
getObservationEnsembleAverages
public double[] getObservationEnsembleAverages() -
getObservationEnsembleUncertainties
public double[] getObservationEnsembleUncertainties() -
getUncertaintyMatrix
public double[][] getUncertaintyMatrix() -
getTotalFreeEnergyDifference
public double getTotalFreeEnergyDifference()Description copied from interface:StatisticalEstimator
Returns the total free energy difference between the first and last state.- Specified by:
getTotalFreeEnergyDifference
in interfaceStatisticalEstimator
- Returns:
- Total free energy difference estimate.
-
getTotalFEDifferenceUncertainty
public double getTotalFEDifferenceUncertainty()Description copied from interface:StatisticalEstimator
Returns the total uncertainty in the computed free energy difference between the first and last state.- Specified by:
getTotalFEDifferenceUncertainty
in interfaceStatisticalEstimator
- Returns:
- Total uncertainty in the free energy difference.
-
getNumberOfBins
public int getNumberOfBins()Description copied from interface:StatisticalEstimator
Returns the number of windows (BAR, etc), bins (WHAM, etc), or other sub-values used to compute the total free energy difference.- Specified by:
getNumberOfBins
in interfaceStatisticalEstimator
- Returns:
- Total number of windows used to compute the total free energy difference.
-
getEnthalpyDifferences
public double[] getEnthalpyDifferences()Description copied from interface:StatisticalEstimator
Gets the enthalpy change between each pair of states.- Specified by:
getEnthalpyDifferences
in interfaceStatisticalEstimator
- Returns:
- The enthalpy difference between each pair of states.
-
getTotalEnthalpyDifference
public double getTotalEnthalpyDifference()Gets the total enthalpy difference between the first and last state.- Specified by:
getTotalEnthalpyDifference
in interfaceStatisticalEstimator
- Returns:
- The enthalpy difference between each pair of states.
-
getBinEntropies
public double[] getBinEntropies() -
writeFile
-
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
Example MBAR code usage and comparison with analytic answers for Harmonic Oscillators.- Parameters:
args
-
-