agi.foundation.numericalmethods.advanced

(agi.foundation.core-2024r3.jar)

Class BrentFindExtremum

java.lang.Object

agi.foundation.numericalmethods.advanced.BrentFindExtremum

public class BrentFindExtremum
extends Object

Locates a local extremum (minimum or maximum) of a function using the Brent algorithm.

Constructor Summary

Constructors

Constructor and Description
BrentFindExtremum(RealValuedScalarFunction function, double variableTolerance, double functionTolerance, ConvergenceCriteria criteria) Initializes the extremum finding algorithm.

Method Summary

Modifier and Type	Method and Description
ExtremumKind	checkInitialBracketingPoints(double a, double b, double c) Checks whether the given values will produce a valid initial bracketing interval.
static ExtremumKind	checkInitialBracketingPoints(double a, double fa, double b, double fb, double c, double fc, double tolerance) Checks whether the given values and function values will produce a valid initial bracketing interval.
boolean	findExtremum(int iterations) Attempts to locate a local extremum in the provided number of iterations.
ConvergenceCriteria	getConvergenceCriteria() Gets the criteria used in determining convergence.
double	getError() Gets the error at this estimate in the quadratic approximation relative to the real function.
double	getExtremum() Gets the current estimate of the extremum.
ExtremumKind	getExtremumKind() Gets whether this extremum is a minimum or maximum.
RealValuedScalarFunction	getFunction() Gets the evaluation function.
double	getFunctionTolerance() Gets the convergence tolerance on the value of the function.
boolean	getHasConverged() Gets a value indicating whether the algorithm is in the converged state.
int	getIterations() Gets the number of iterations taken.
double	getValue() Gets the function value at the current estimate of the extremum.
double	getVariableTolerance() Gets the convergence tolerance on the value of the variable.
void	setInitialBracketingPoints(double a, double b, double c) Defines the initial bracketing interval using the provided variable values.
void	setInitialBracketingPoints(double a, double fa, double b, double fb, double c, double fc) Defines the initial bracketing interval using the provided variable values and corresponding function values.

Methods inherited from class java.lang.Object

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

Constructor Detail

BrentFindExtremum

public BrentFindExtremum(@Nonnull
                         RealValuedScalarFunction function,
                         double variableTolerance,
                         double functionTolerance,
                         @Nonnull
                         ConvergenceCriteria criteria)

Initializes the extremum finding algorithm.

Parameters:

function - The function to evaluate.

variableTolerance - The convergence tolerance in the independent variable.

functionTolerance - The convergence tolerance in the function value.

criteria - The ConvergenceCriteria (get) to be used.

Throws:

ArgumentNullException - Thrown when the function is null.

ArgumentOutOfRangeException - Thrown when the variableTolerance or functionTolerance is less than or equal to zero.

Method Detail

getExtremum

public final double getExtremum()

Gets the current estimate of the extremum.

getValue

public final double getValue()

Gets the function value at the current estimate of the extremum.

getIterations

public final int getIterations()

Gets the number of iterations taken.

getVariableTolerance

public final double getVariableTolerance()

Gets the convergence tolerance on the value of the variable.

getFunctionTolerance

public final double getFunctionTolerance()

Gets the convergence tolerance on the value of the function.

getConvergenceCriteria

@Nonnull
public final ConvergenceCriteria getConvergenceCriteria()

Gets the criteria used in determining convergence.

getHasConverged

public final boolean getHasConverged()

Gets a value indicating whether the algorithm is in the converged state.

getError

public final double getError()

Gets the error at this estimate in the quadratic approximation relative to the real function. This is the value checked against the FunctionTolerance (get) to determine convergence.

getExtremumKind

@Nonnull
public final ExtremumKind getExtremumKind()

Gets whether this extremum is a minimum or maximum.

getFunction

public final RealValuedScalarFunction getFunction()

Gets the evaluation function.

checkInitialBracketingPoints

@Nonnull
public final ExtremumKind checkInitialBracketingPoints(double a,
                                                                 double b,
                                                                 double c)

Checks whether the given values will produce a valid initial bracketing interval.

Parameters:

a - The value of the independent variable at one of the limits of the bracketing interval.

b - The value of the independent variable between the limits of the bracketing interval.

c - The value of the independent variable at one of the limits of the bracketing interval.

Returns:

The type of extremum if the values will produce a valid interval; otherwise ExtremumKind.INVALID.

checkInitialBracketingPoints

@Nonnull
public static ExtremumKind checkInitialBracketingPoints(double a,
                                                                  double fa,
                                                                  double b,
                                                                  double fb,
                                                                  double c,
                                                                  double fc,
                                                                  double tolerance)

Checks whether the given values and function values will produce a valid initial bracketing interval.

Parameters:

a - The value of the independent variable at one of the limits of the bracketing interval.

fa - The function value when evaluated at a.

b - The value of the independent variable between the limits of the bracketing interval.

fb - The function value when evaluated at b.

c - The value of the independent variable at one of the limits of the bracketing interval.

fc - The function value when evaluated at c.

tolerance - The convergence tolerance in the value.

Returns:

The type of extremum if the values will produce a valid interval; otherwise ExtremumKind.INVALID.

setInitialBracketingPoints

public final void setInitialBracketingPoints(double a,
                                             double b,
                                             double c)

Defines the initial bracketing interval using the provided variable values.

When evaluated at the three values of the independent variable provided, a, b, and c, the function must indicate a local extremum such that at least one of the evaluated values is not equal to the other two, and Function (get)(b) is either greater than or equal to or less than or equal to both Function (get)(a) and Function (get)(c).

Parameters:

a - The value of the independent variable at one of the limits of the bracketing interval.

b - The value of the independent variable between the limits of the bracketing interval.

c - The value of the independent variable at one of the limits of the bracketing interval.

Throws:

ArgumentOutOfRangeException - The two end points must bracket the middle point.

ArgumentOutOfRangeException - The middle point does not indicate a local extremum.

setInitialBracketingPoints

public final void setInitialBracketingPoints(double a,
                                             double fa,
                                             double b,
                                             double fb,
                                             double c,
                                             double fc)

Defines the initial bracketing interval using the provided variable values and corresponding function values.

The function values fa, fb, and fc must indicate a local extremum such that at least one of them is not equal to the other two, and fb is either greater than or equal to or less than or equal to both fa and fc.

Parameters:

a - The value of the independent variable at one of the limits of the bracketing interval.

fa - The function value when evaluated at a.

b - The value of the independent variable between the limits of the bracketing interval.

fb - The function value when evaluated at b.

c - The value of the independent variable at one of the limits of the bracketing interval.

fc - The function value when evaluated at c.

Throws:

ArgumentOutOfRangeException - Thrown when the two end points do not bracket the middle point.

ArgumentOutOfRangeException - Thrown when the middle point does not indicate a local extremum.

findExtremum

public final boolean findExtremum(int iterations)

Attempts to locate a local extremum in the provided number of iterations.

Using an iterations value of one in successive calls allows the algorithm to be iterated manually.

Parameters:

iterations - The allowed number of iterations.

Returns:

true if the algorithm converged on an extremum; otherwise false.