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

  • 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.

    • setCoordinates

      public void setCoordinates(double[] parameters)
      Description copied from interface: OptimizationInterface
      Set the current value of the parameters. If the supplied array is null or not large enough, no action is taken.
      Specified by:
      setCoordinates in interface OptimizationInterface
      Parameters:
      parameters - The array 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.

    • getFreeEnergyDifferences

      public double[] getFreeEnergyDifferences()
      Description copied from interface: StatisticalEstimator
      Gets the free energy difference between each pair of states.
      Specified by:
      getFreeEnergyDifferences in interface StatisticalEstimator
      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 interface StatisticalEstimator
      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 interface StatisticalEstimator
      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 interface StatisticalEstimator
      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 interface StatisticalEstimator
      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 interface StatisticalEstimator
      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 interface StatisticalEstimator
      Returns:
      The enthalpy difference between each pair of states.

    • 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 -