agi.foundation.numericalmethods.advanced

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

Class BrentFindRoot

java.lang.Object

agi.foundation.numericalmethods.advanced.BrentFindRoot

public class BrentFindRoot
extends Object

Locates the root of a function using the Van Wijngaarden, Dekker, Brent algorithm.

Constructor Summary

Constructors

Constructor and Description
BrentFindRoot(RealValuedScalarFunction function, double variableTolerance, double functionTolerance, BrentSolutionType solutionType, ConvergenceCriteria criteria) Initializes a new instance that can be used to find roots of a specified function.
BrentFindRoot(RealValuedScalarFunction function, double variableTolerance, double functionTolerance, BrentSolutionType solutionType, ConvergenceCriteria criteria, BracketToward bracketToward) Initializes a new instance that can be used to find roots of a specified function.

Method Summary

Modifier and Type	Method and Description
boolean	checkInitialBracketingPoints(double a, double c) Checks whether the given variable values will produce a valid initial bracketing interval.
boolean	checkInitialBracketingPoints(double a, double fa, double c, double fc) Checks whether the given variable and function values will produce a valid initial bracketing interval.
boolean	findRoot(int maximumIterations) Attempts the indicated number of iterations to locate the root of the function to within the required convergence criteria.
BracketToward	getBracketToward() Gets the behavior of the root finder when a sampled function value exactly equals zero and ConvergenceCriteria (get) requires convergence on the independent variable.
ConvergenceCriteria	getConvergenceCriteria() Gets the criteria used in determining convergence.
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	getRoot() Gets the current best estimate of independent variable value at which the root occurs.
double	getValue() Gets the function value at the current best estimate of the Root (get).
double	getVariableTolerance() Gets the convergence tolerance on the value of the independent variable.
boolean	isFunctionValueWithinTolerance() Indicates whether the function value has converged to within the specified tolerance.
void	setInitialBracketingPoints(double a, double c) Defines the initial bracketing interval using the provided variable values.
void	setInitialBracketingPoints(double a, double fa, 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

BrentFindRoot

public BrentFindRoot(@Nonnull
                     RealValuedScalarFunction function,
                     double variableTolerance,
                     double functionTolerance,
                     @Nonnull
                     BrentSolutionType solutionType,
                     @Nonnull
                     ConvergenceCriteria criteria)

Initializes a new instance that can be used to find roots of a specified function. The BracketToward (get) property is set based on the value of the solutionType parameter as follows:

• BrentSolutionType.ON_OR_ABOVE_ZERO => BracketToward.NEGATIVE
• BrentSolutionType.ON_OR_BELOW_ZERO => BracketToward.POSITIVE
• BrentSolutionType.ABOVE_OR_BELOW_ZERO => BracketToward.EARLIEST

Parameters:

function - The function to be called in order to evaluate intermediate variable values.

variableTolerance - The convergence tolerance in the variable value.

functionTolerance - The convergence tolerance in the function value.

solutionType - Indicates on which side of zero a solution must be found.

criteria - Specifies the criteria to be used in determining convergence.

Throws:

ArgumentNullException - Thrown when the parameter function is null.

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

BrentFindRoot

public BrentFindRoot(@Nonnull
                     RealValuedScalarFunction function,
                     double variableTolerance,
                     double functionTolerance,
                     @Nonnull
                     BrentSolutionType solutionType,
                     @Nonnull
                     ConvergenceCriteria criteria,
                     @Nonnull
                     BracketToward bracketToward)

Initializes a new instance that can be used to find roots of a specified function.

Parameters:

function - The function to be called in order to evaluate intermediate variable values.

variableTolerance - The convergence tolerance in the variable value.

functionTolerance - The convergence tolerance in the function value.

solutionType - Indicates on which side of zero a solution must be found.

criteria - Specifies the criteria to be used in determining convergence.

bracketToward - Specifies the bracketing behavior when a sampled function value exactly equals zero. This parameter only has an effect when the criteria is ConvergenceCriteria.Variable or ConvergenceCriteria.Both. See BracketToward (get) for more information.

Throws:

ArgumentNullException - Thrown when function is null.

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

Method Detail

getRoot

public final double getRoot()

Gets the current best estimate of independent variable value at which the root occurs. If HasConverged (get) is true, this is the actual root according to the convergence criteria defined when this instance was constructed.

getValue

public final double getValue()

Gets the function value at the current best estimate of the Root (get). If HasConverged (get) is true, this is the actual root according to the convergence criteria defined when this instance was constructed.

getVariableTolerance

public final double getVariableTolerance()

Gets the convergence tolerance on the value of the independent 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.

getBracketToward

@Nonnull
public final BracketToward getBracketToward()

Gets the behavior of the root finder when a sampled function value exactly equals zero and ConvergenceCriteria (get) requires convergence on the independent variable.

getIterations

public final int getIterations()

Gets the number of iterations taken.

getHasConverged

public final boolean getHasConverged()

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

getFunction

public final RealValuedScalarFunction getFunction()

Gets the evaluation function.

checkInitialBracketingPoints

public final boolean checkInitialBracketingPoints(double a,
                                                  double c)

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

Parameters:

a - The first bracketing value of the variable.

c - The second bracketing value of the variable

Returns:

true if the values will produce a valid interval; otherwise false. If the value is false, it may be caused by either a or c already representing a root.

checkInitialBracketingPoints

public final boolean checkInitialBracketingPoints(double a,
                                                  double fa,
                                                  double c,
                                                  double fc)

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

Parameters:

a - The first bracketing value of the variable.

fa - The corresponding function value at the first bracketing value of the variable.

c - The second bracketing value of the variable

fc - The corresponding function value at the second bracketing value of the variable.

Returns:

true if the values will produce a valid interval; otherwise false. If the value is false, one of the parameters is not-a-number (NaN) or a and c do not bracket a root.

setInitialBracketingPoints

public final void setInitialBracketingPoints(double a,
                                             double c)

Defines the initial bracketing interval using the provided variable values.

Parameters:

a - The first bracketing value of the variable.

c - The second bracketing value of the variable

setInitialBracketingPoints

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

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

Parameters:

a - The first bracketing c.

fa - The corresponding function value at the first bracketing value of the variable.

c - The second bracketing value of the variable

fc - The corresponding function value at the second bracketing value of the variable.

Throws:

ArithmeticException - Thrown when the function value at either or both of the end points is Double.NaN.

ArithmeticException - Thrown when the two points do not bracket a root (or when there is a singularity).

ArithmeticException - Thrown when the two points are already within the desired tolerance of zero.

ArithmeticException - Thrown when the two points are already within the desired tolerance of each other.

isFunctionValueWithinTolerance

public final boolean isFunctionValueWithinTolerance()

Indicates whether the function value has converged to within the specified tolerance.

Returns:

true if the value is within tolerance; otherwise false.

findRoot

public final boolean findRoot(int maximumIterations)

Attempts the indicated number of iterations to locate the root of the function to within the required convergence criteria.

Parameters:

maximumIterations - The allowed number of iterations.

Returns:

true if the root was found; otherwise false.