Package com.irurueta.numerical.optimization

Class BracketedSingleOptimizer

java.lang.Object
com.irurueta.numerical.optimization.Optimizer
com.irurueta.numerical.optimization.SingleOptimizer
com.irurueta.numerical.optimization.BracketedSingleOptimizer
Direct Known Subclasses:
BrentSingleOptimizer, DerivativeBrentSingleOptimizer, GoldenSingleOptimizer
public abstract class BracketedSingleOptimizer extends SingleOptimizer
This class searches for brackets of values containing a minimum in a single dimension function. A bracket is a set of points: "a" a minimum evaluation point, "b" a middle evaluation point and "c" a maximum evaluation where a <= b <= c, and where f(b) <= f(a) and f(b) <= f(c). This class uses a downhill algorithm that is better suited to continuous functions. Other functions might not obtain reliable results when using this algorithm to obtain a bracket of points. Some subclasses of this class will implement algorithms to refine the solution obtained in a bracket in order to find an accurate estimation of a minimum. Some algorithms might not need to previously compute a bracket and will simply search for a minimum in all the range of possible values, whereas other algorithms will require first the computation of a bracket. In either case, computing a bracket prior estimating a minimum will always ensure that a more reliable solution will be found. Besides, bracket computation is required when a function contains several minima and search of an accurate minimum estimation is desired to be restricted to a certain range of values.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected double
    ax
    Minimum evaluation point inside the bracket.
    private boolean
    bracketAvailable
    Boolean indicating whether a bracket has been provided or computed.
    private boolean
    bracketEvaluationAvailable
    Boolean indicating whether function evaluation at bracket limits and middle point are available or not.
    protected double
    bx
    Middle evaluation point inside the bracket.
    protected double
    cx
    Maximum evaluation point inside the bracket.
    static final double
    DEFAULT_MAX_EVAL_POINT
    Default maximum evaluation point where the bracket is supposed to start By default, if no bracket is computed, the whole range of values is used for minimum estimation.
    static final double
    DEFAULT_MIDDLE_EVAL_POINT
    Default middle evaluation point where the bracket is supposed to start By default, if no bracket is computed, the whole range of values is used for minimum estimation.
    static final double
    DEFAULT_MIN_EVAL_POINT
    Default minimum evaluation point where the bracket is supposed to start By default, if no bracket is computed, the whole range of values is used for minimum estimation.
    private double
    fa
    Function evaluation value at minimum evaluation point inside the bracket.
    private double
    fb
    Function evaluation value at middle evaluation point inside the bracket.
    private double
    fc
    Function evaluation value at maximum evaluation point inside the bracket.
    static final double
    GLIMIT
    The maximum magnification allowed for a parabolic-fit step.
    static final double
    GOLD
    The default ratio by which intervals are magnified and.
    static final double
    TINY
    Small value representing machine precision.

    Fields inherited from class com.irurueta.numerical.optimization.SingleOptimizer

    fmin, listener, resultAvailable, xmin

    Fields inherited from class com.irurueta.numerical.optimization.Optimizer

    iterationCompletedListener, locked

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    BracketedSingleOptimizer()
    Empty Constructor.
    protected
    BracketedSingleOptimizer(double minEvalPoint, double middleEvalPoint, double maxEvalPoint)
    Constructor.
    protected
    BracketedSingleOptimizer(SingleDimensionFunctionEvaluatorListener listener, double minEvalPoint, double middleEvalPoint, double maxEvalPoint)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    areBracketEvaluationsAvailable()
    Returns boolean indicating whether bracket evaluations are available for retrieval.
    void
    computeBracket()
    Computes a bracket of values using the whole range of possible values as an initial guess.
    void
    computeBracket(double minEvalPoint)
    Computes a bracket of values using provided value as a starting point, and assuming that bracket finishes at Double.MAX_VALUE.
    void
    computeBracket(double minEvalPoint, double middleEvalPoint)
    Computes a bracket of values using provided values as a starting point.
    void
    evaluateBracket()
    Computes function evaluations at provided or estimated bracket locations.
    double
    getEvaluationAtMax()
    Returns single dimension function evaluation at provided or computed maximum evaluation point where the bracket finishes.
    double
    getEvaluationAtMiddle()
    Returns single dimension function evaluation at provided or computed middle evaluation point within the bracket.
    double
    getEvaluationAtMin()
    Returns single dimension function evaluation at provided or computed minimum evaluation point where the bracket starts.
    double
    getMaxEvaluationPoint()
    Returns maximum evaluation point whether the bracket finishes.
    double
    getMiddleEvaluationPoint()
    Returns middle evaluation point within the bracket.
    double
    getMinEvaluationPoint()
    Returns minimum evaluation point where the bracket starts
    private void
    internalSetBracket(double minEvalPoint, double middleEvalPoint, double maxEvalPoint)
    Internal method to set a bracket of values.
    boolean
    isBracketAvailable()
    Returns boolean indicating whether a bracket has been provided or computed and is available for retrieval.
    protected void
    mov3(double[] a, double[] b, double[] c, double d, double e, double f)
    Moves d, e and f into a[0], b[0] and c[0].
    void
    setBracket(double minEvalPoint, double middleEvalPoint, double maxEvalPoint)
    Sets a bracket of values to later search for a minimum.
    protected void
    shift2(double[] a, double[] b, double c)
    Pushes "b" value into "a", and "c" value into "b".
    protected void
    shift3(double[] a, double[] b, double[] c, double d)
    Pushes "b" value into "a", and "c" value into "b" and "d" value into "c".
    protected double
    sign(double a, double b)
    Internal method to determine whether a and b have the same sign.
    private void
    swap(double[] a, double[] b)
    Internal method to swap two values.

    Methods inherited from class com.irurueta.numerical.optimization.SingleOptimizer

    getEvaluationAtResult, getListener, getResult, isListenerAvailable, isReady, isResultAvailable, setListener

    Methods inherited from class com.irurueta.numerical.optimization.Optimizer

    getOnIterationCompletedListener, isLocked, minimize, setOnIterationCompletedListener

    Methods inherited from class java.lang.Object

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

  • Field Details

    • GOLD

      public static final double GOLD
      The default ratio by which intervals are magnified and.
      See Also:

    • GLIMIT

      public static final double GLIMIT
      The maximum magnification allowed for a parabolic-fit step.
      See Also:

    • TINY

      public static final double TINY
      Small value representing machine precision.
      See Also:

    • DEFAULT_MIN_EVAL_POINT

      public static final double DEFAULT_MIN_EVAL_POINT
      Default minimum evaluation point where the bracket is supposed to start By default, if no bracket is computed, the whole range of values is used for minimum estimation.
      See Also:

    • DEFAULT_MIDDLE_EVAL_POINT

      public static final double DEFAULT_MIDDLE_EVAL_POINT
      Default middle evaluation point where the bracket is supposed to start By default, if no bracket is computed, the whole range of values is used for minimum estimation.
      See Also:

    • DEFAULT_MAX_EVAL_POINT

      public static final double DEFAULT_MAX_EVAL_POINT
      Default maximum evaluation point where the bracket is supposed to start By default, if no bracket is computed, the whole range of values is used for minimum estimation.
      See Also:

    • ax

      protected double ax
      Minimum evaluation point inside the bracket.

    • bx

      protected double bx
      Middle evaluation point inside the bracket.

    • cx

      protected double cx
      Maximum evaluation point inside the bracket.

    • bracketAvailable

      private boolean bracketAvailable
      Boolean indicating whether a bracket has been provided or computed.

    • fa

      private double fa
      Function evaluation value at minimum evaluation point inside the bracket.

    • fb

      private double fb
      Function evaluation value at middle evaluation point inside the bracket.

    • fc

      private double fc
      Function evaluation value at maximum evaluation point inside the bracket.

    • bracketEvaluationAvailable

      private boolean bracketEvaluationAvailable
      Boolean indicating whether function evaluation at bracket limits and middle point are available or not.

  • Constructor Details

    • BracketedSingleOptimizer

      protected BracketedSingleOptimizer(double minEvalPoint, double middleEvalPoint, double maxEvalPoint) throws InvalidBracketRangeException
      Constructor. Creates an instance with provided bracket of values.
      Parameters:
      minEvalPoint - Minimum bracket evaluation point.
      middleEvalPoint - Middle bracket evaluation point.
      maxEvalPoint - Maximum bracket evaluation point.
      Throws:
      InvalidBracketRangeException - Raised if the following condition is not met: minEvalPoint <= middleEvalPoint <= maxEvalPoint.

    • BracketedSingleOptimizer

      protected BracketedSingleOptimizer()
      Empty Constructor. Creates an instance using default bracket values.

    • BracketedSingleOptimizer

      protected BracketedSingleOptimizer(SingleDimensionFunctionEvaluatorListener listener, double minEvalPoint, double middleEvalPoint, double maxEvalPoint) throws InvalidBracketRangeException
      Constructor. Creates an instance with provided bracket of values and a listener to get single dimension function evaluations.
      Parameters:
      listener - Listener to evaluate a function.
      minEvalPoint - Minimum bracket evaluation point.
      middleEvalPoint - Middle bracket evaluation point.
      maxEvalPoint - Maximum bracket evaluation point.
      Throws:
      InvalidBracketRangeException - Raised if the following condition is not met: minEvalPoint <= middleEvalPoint <= maxEvalPoint.

  • Method Details

    • setBracket

      public void setBracket(double minEvalPoint, double middleEvalPoint, double maxEvalPoint) throws LockedException, InvalidBracketRangeException
      Sets a bracket of values to later search for a minimum. A local minimum will only be search within the minimum and maximum evaluation points of a given bracket. If bracket is not provided, it can also be computed from a default or coarse set of points in order to obtain a more refined bracket so that a minimum search can be estimated more precisely.
      Parameters:
      minEvalPoint - Minimum bracket evaluation point.
      middleEvalPoint - Middle bracket evaluation point.
      maxEvalPoint - Maximum bracket evaluation point.
      Throws:
      InvalidBracketRangeException - Raised if the following condition is not met: minEvalPoint <= middleEvalPoint <= maxEvalPoint.
      LockedException - Raised if this instance is locked. This instance will be locked while doing some operations. Attempting to change any parameter while being locked will raise this exception.

    • isBracketAvailable

      public boolean isBracketAvailable()
      Returns boolean indicating whether a bracket has been provided or computed and is available for retrieval.
      Returns:
      true if a bracket has been provided, false otherwise.

    • getMinEvaluationPoint

      public double getMinEvaluationPoint() throws NotAvailableException
      Returns minimum evaluation point where the bracket starts
      Returns:
      Minimum evaluation point.
      Throws:
      NotAvailableException - Raised if not provided or computed.

    • getMiddleEvaluationPoint

      public double getMiddleEvaluationPoint() throws NotAvailableException
      Returns middle evaluation point within the bracket.
      Returns:
      Middle evaluation point.
      Throws:
      NotAvailableException - Raised if not provided or computed.

    • getMaxEvaluationPoint

      public double getMaxEvaluationPoint() throws NotAvailableException
      Returns maximum evaluation point whether the bracket finishes.
      Returns:
      Maximum evaluation point.
      Throws:
      NotAvailableException - Raised if not provided or computed.

    • getEvaluationAtMin

      public double getEvaluationAtMin() throws NotAvailableException
      Returns single dimension function evaluation at provided or computed minimum evaluation point where the bracket starts.
      Returns:
      Function evaluation at bracket's minimum evaluation point.
      Throws:
      NotAvailableException - Raised if bracket evaluations are not available.

    • getEvaluationAtMiddle

      public double getEvaluationAtMiddle() throws NotAvailableException
      Returns single dimension function evaluation at provided or computed middle evaluation point within the bracket.
      Returns:
      Function evaluation at bracket's middle evaluation point.
      Throws:
      NotAvailableException - Raised if bracket evaluations are not available.

    • getEvaluationAtMax

      public double getEvaluationAtMax() throws NotAvailableException
      Returns single dimension function evaluation at provided or computed maximum evaluation point where the bracket finishes.
      Returns:
      Function evaluation at bracket's maximum evaluation point.
      Throws:
      NotAvailableException - Raised if bracket evaluations are not available.

    • computeBracket

      public void computeBracket(double minEvalPoint, double middleEvalPoint) throws LockedException, NotReadyException, InvalidBracketRangeException, OptimizationException
      Computes a bracket of values using provided values as a starting point. Given a function f, and given distinct initial points ax and bx, this routine searches in the downhill direction (defined by the function as evaluated at the initial points) and returns. ax (minimum evaluation point), bx (middle evaluation point), cx (maximum evaluation point) that bracket a minimum of the function. Also returned are the function values at the three points fa, fb, and fc, which are the function evaluations at minimum, middle and maximum bracket points.
      Parameters:
      minEvalPoint - Initial minimum evaluation point of bracket.
      middleEvalPoint - Initial middle evaluation point of bracket.
      Throws:
      LockedException - Raised if this instance is locked. This instance will be locked while doing some operations. Attempting to change any parameter while being locked will raise this exception.
      NotReadyException - Raised if this instance is not ready because a listener has not yet been provided.
      InvalidBracketRangeException - Raised if minEvalPoint < middleEvalPoint.
      OptimizationException - Raised if a bracket couldn't be found . because convergence was not achieved or function evaluation failed.

    • computeBracket

      public void computeBracket(double minEvalPoint) throws LockedException, NotReadyException, OptimizationException, InvalidBracketRangeException
      Computes a bracket of values using provided value as a starting point, and assuming that bracket finishes at Double.MAX_VALUE. Given a function f, and given distinct initial points ax and bx = 0.0, this routine searches in the downhill direction (defined by the function as evaluated at the initial points) and returns ax (minimum evaluation point), bx (middle evaluation point), cx (maximum evaluation point) that bracket a minimum of the function. Also returned are the function values at the three points fa, fb, and fc, which are the function evaluations at minimum, middle and maximum bracket points.
      Parameters:
      minEvalPoint - Initial minimum evaluation point of bracket.
      Throws:
      LockedException - Raised if this instance is locked. This instance will be locked while doing some operations. Attempting to change any parameter while being locked will raise this exception.
      NotReadyException - Raised if this instance is not ready because a listener has not yet been provided.
      InvalidBracketRangeException - Raised if minEvalPoint < 0.0.
      OptimizationException - Raised if a bracket couldn't be found because convergence was not achieved or function evaluation failed.

    • computeBracket

      public void computeBracket() throws LockedException, NotReadyException, OptimizationException
      Computes a bracket of values using the whole range of possible values as an initial guess. Given a function f, and given distinct initial points ax = -Double.MAX_VALUE and bx = 0.0, this routine searches in the downhill direction (defined by the function as evaluated at the initial points) and returns ax (minimum evaluation point), bx (middle evaluation point), cx (maximum evaluation point) that bracket a minimum of the function. Also returned are the function values at the three points fa, fb, and fc, which are the function evaluations at minimum, middle and maximum bracket points
      Throws:
      LockedException - Raised if this instance is locked. This instance will be locked while doing some operations. Attempting to change any parameter while being locked will raise this exception.
      NotReadyException - Raised if this instance is not ready because a listener has not yet been provided.
      OptimizationException - Raised if a bracket couldn't be found because convergence was not achieved or function evaluation failed.

    • evaluateBracket

      public void evaluateBracket() throws LockedException, NotReadyException, OptimizationException
      Computes function evaluations at provided or estimated bracket locations. After calling this method bracket evaluations will be available.
      Throws:
      LockedException - Raised if this instance is locked. This instance will be locked while doing some operations. Attempting to change any parameter while being locked will raise this exception.
      NotReadyException - Raised if this instance is not ready because a listener has not yet been provided.
      OptimizationException - Raised if function evaluation failed.

    • areBracketEvaluationsAvailable

      public boolean areBracketEvaluationsAvailable()
      Returns boolean indicating whether bracket evaluations are available for retrieval.
      Returns:
      True if bracket evaluations are available, false otherwise.

    • sign

      protected double sign(double a, double b)
      Internal method to determine whether a and b have the same sign.
      Parameters:
      a - Value to be compared.
      b - Value to be compared.
      Returns:
      Returns "a" if "a" and "b" have the same sign or "-a" otherwise.

    • shift2

      protected void shift2(double[] a, double[] b, double c)
      Pushes "b" value into "a", and "c" value into "b". "a" and "b" are in/out parameters. Results will be available at a[0] and b[0] after executing this method.
      Parameters:
      a - a value to be lost.
      b - a value to be shifted into "a".
      c - a value to be shifted into "b".

    • shift3

      protected void shift3(double[] a, double[] b, double[] c, double d)
      Pushes "b" value into "a", and "c" value into "b" and "d" value into "c". "a", "b" and "c" are in/out parameters. Results will be available at a[0], b[0] and c[0] after executing this method.
      Parameters:
      a - a value to be lost.
      b - a value to be shifted into "a".
      c - a value to be shifted into "b".
      d - a value to be shifted into "c".

    • mov3

      protected void mov3(double[] a, double[] b, double[] c, double d, double e, double f)
      Moves d, e and f into a[0], b[0] and c[0]. Previously existing values into a, b, c will be lost after executing this method.
      Parameters:
      a - a value to be set.
      b - a value to be set.
      c - a value to be set.
      d - a value to be copied.
      e - a value to be copied.
      f - a value to be copied.

    • swap

      private void swap(double[] a, double[] b)
      Internal method to swap two values. Value inside a[0] will be swapped with value provided in b[0].
      Parameters:
      a - Value to be swapped.
      b - Value to be swapped.

    • internalSetBracket

      private void internalSetBracket(double minEvalPoint, double middleEvalPoint, double maxEvalPoint) throws InvalidBracketRangeException
      Internal method to set a bracket of values. This method does not check whether this instance is locked.
      Parameters:
      minEvalPoint - Minimum bracket evaluation point.
      middleEvalPoint - Middle bracket evaluation point.
      maxEvalPoint - Maximum bracket evaluation point.
      Throws:
      InvalidBracketRangeException - Raised if the following condition is not met: minEvalPoint <= middleEvalPoint <= maxEvalPoint.