agi.foundation.numericalmethods.advanced

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

Class NewtonFindRoot

java.lang.Object

agi.foundation.numericalmethods.advanced.NewtonFindRoot

public class NewtonFindRoot
extends Object

Locates the root of a function using the Newton-Raphson method.

Constructor Summary

Constructors

Constructor and Description
NewtonFindRoot(RealValuedScalarFunction function, double functionTolerance, RealValuedScalarFunction derivativeFunction, double derivativeTolerance, double lowerBound, double upperBound) Initializes a new instance that can be used to find roots of a specified function.

Method Summary

Modifier and Type	Method and Description
boolean	findRoot(int maxIterations) Attempts the indicated number of iterations to locate the root of the function to within the required convergence criteria.
RealValuedScalarFunction	getDerivativeFunction() Gets the derivative of Function (get).
double	getDerivativeTolerance() Gets the tolerance used to determine whether the derivative is zero for the purposes of aborting the calculation and setting the ResultType (get) to NewtonRootType.SOLVER_FAILED_DUE_TO_HORIZONTAL_SLOPE.
double	getDerivativeValue() Gets the value of the DerivativeFunction (get) at the Root (get).
RealValuedScalarFunction	getFunction() Gets the evaluation function.
double	getFunctionTolerance() Gets the tolerance used to determine whether the function is zero and a root has been found.
double	getFunctionValue() Gets the value of the Function (get) at the Root (get).
int	getIterations() Gets the number of iterations taken.
double	getLowerBound() Gets the lower bound of the range of independent variables to search for the root within.
double	getMaximumStepsize() Gets the maximum size of the step to take during a single iteration.
NewtonRootType	getResultType() Gets the type of result the Root (get) represents.
double	getRoot() Gets the value of the root.
double	getUpperBound() Gets the upper bound of the range of independent variables to search for the root within.
double	getVariableTolerance() Gets the tolerance used to determine whether a root guess is the same as another root guess, used in early detection of non-convergence.
void	setDerivativeTolerance(double value) Sets the tolerance used to determine whether the derivative is zero for the purposes of aborting the calculation and setting the ResultType (get) to NewtonRootType.SOLVER_FAILED_DUE_TO_HORIZONTAL_SLOPE.
void	setFunctionTolerance(double value) Sets the tolerance used to determine whether the function is zero and a root has been found.
void	setInitialGuessOfRootLocation(double guess) Sets the initial guess of the root's location.
void	setLowerBound(double value) Sets the lower bound of the range of independent variables to search for the root within.
void	setMaximumStepsize(double value) Sets the maximum size of the step to take during a single iteration.
void	setUpperBound(double value) Sets the upper bound of the range of independent variables to search for the root within.
void	setVariableTolerance(double value) Sets the tolerance used to determine whether a root guess is the same as another root guess, used in early detection of non-convergence.

Methods inherited from class java.lang.Object

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

Constructor Detail

NewtonFindRoot

public NewtonFindRoot(RealValuedScalarFunction function,
                      double functionTolerance,
                      RealValuedScalarFunction derivativeFunction,
                      double derivativeTolerance,
                      double lowerBound,
                      double upperBound)

Initializes a new instance that can be used to find roots of a specified function. NewtonFindRoot.setInitialGuessOfRootLocation(double) must be called before NewtonFindRoot.findRoot(int). MaximumStepsize (get / set) is set to an initial value of Double.MAX_VALUE, VariableTolerance (get / set) is set to an initial value of zero.

Parameters:

function - The Function (get) to find the root of.

functionTolerance - The FunctionTolerance (get / set) to use to determine whether the Function (get) is zero.

derivativeFunction - The DerivativeFunction (get) of the function.

derivativeTolerance - The DerivativeTolerance (get / set) to use to determine whether the DerivativeFunction (get) is zero.

lowerBound - The lower bound of the region to search for the root within.

upperBound - The upper bound of the region to search for the root within.

Method Detail

findRoot

public final boolean findRoot(int maxIterations)

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

Parameters:

maxIterations - The maximum number of iterations to perform. If a solution has not been found after this number of iterations the Root (get) property is set to the guess of the last iteration and ResultType (get) is set to NewtonRootType.SOLUTION_DID_NOT_CONVERGE.

Returns:

true if the root was found; otherwise false.

getFunctionTolerance

public final double getFunctionTolerance()

Gets the tolerance used to determine whether the function is zero and a root has been found.

setFunctionTolerance

public final void setFunctionTolerance(double value)

Sets the tolerance used to determine whether the function is zero and a root has been found.

getDerivativeTolerance

public final double getDerivativeTolerance()

Gets the tolerance used to determine whether the derivative is zero for the purposes of aborting the calculation and setting the ResultType (get) to NewtonRootType.SOLVER_FAILED_DUE_TO_HORIZONTAL_SLOPE.

setDerivativeTolerance

public final void setDerivativeTolerance(double value)

Sets the tolerance used to determine whether the derivative is zero for the purposes of aborting the calculation and setting the ResultType (get) to NewtonRootType.SOLVER_FAILED_DUE_TO_HORIZONTAL_SLOPE.

getVariableTolerance

public final double getVariableTolerance()

Gets the tolerance used to determine whether a root guess is the same as another root guess, used in early detection of non-convergence.

setVariableTolerance

public final void setVariableTolerance(double value)

Sets the tolerance used to determine whether a root guess is the same as another root guess, used in early detection of non-convergence.

getMaximumStepsize

public final double getMaximumStepsize()

Gets the maximum size of the step to take during a single iteration.

setMaximumStepsize

public final void setMaximumStepsize(double value)

Sets the maximum size of the step to take during a single iteration.

getIterations

public final int getIterations()

Gets the number of iterations taken.

getRoot

public final double getRoot()

Gets the value of the root. Consult the ResultType (get) property for whether the calculated root is the result of a finished calculation, or some other failure condition such as the failure to converge in the allotted number of maximum iterations.

setInitialGuessOfRootLocation

public final void setInitialGuessOfRootLocation(double guess)

Sets the initial guess of the root's location. This sets Root (get) to the provided guess, ResultType (get) to NewtonRootType.INITIAL_GUESS and Iterations (get) is set to 0. If Function (get) and/or DerivativeFunction (get) are non-null the method also assigns assigns FunctionValue (get) and DerivativeValue (get) respectively.

Parameters:

guess - The guess of the roots location.

getFunctionValue

public final double getFunctionValue()

Gets the value of the Function (get) at the Root (get).

getDerivativeValue

public final double getDerivativeValue()

Gets the value of the DerivativeFunction (get) at the Root (get).

getResultType

@Nonnull
public final NewtonRootType getResultType()

Gets the type of result the Root (get) represents.

getLowerBound

public final double getLowerBound()

Gets the lower bound of the range of independent variables to search for the root within.

setLowerBound

public final void setLowerBound(double value)

Sets the lower bound of the range of independent variables to search for the root within.

getUpperBound

public final double getUpperBound()

Gets the upper bound of the range of independent variables to search for the root within.

setUpperBound

public final void setUpperBound(double value)

Sets the upper bound of the range of independent variables to search for the root within.

getFunction

public final RealValuedScalarFunction getFunction()

Gets the evaluation function.

getDerivativeFunction

public final RealValuedScalarFunction getDerivativeFunction()

Gets the derivative of Function (get).