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 samples 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 at: https://github.com/choderalab/pymbar/tree/master

Since:
1.0
Author:
Matthew J. Speranza

  • 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

  • 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)
      Implementation of MBAR solved with self-consistent iteration and L-BFGS optimization.
      Specified by:
      estimateDG in interface BootstrappableEstimator
      Parameters:
      randomSamples - Whether to draw random samples with replacement (one bootstrap trial).

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

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

    • getDiffMatrix

      public double[][] getDiffMatrix()

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

    • writeFile

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

    • main

      public static void main(String[] args)