com.opengamma.strata.math.impl.rootfinding

Class NewtonRaphsonSingleRootFinder

java.lang.Object

com.opengamma.strata.math.impl.rootfinding.RealSingleRootFinder

com.opengamma.strata.math.impl.rootfinding.NewtonRaphsonSingleRootFinder

All Implemented Interfaces:

SingleRootFinder<Double,Double>

public class NewtonRaphsonSingleRootFinder
extends RealSingleRootFinder

Class for finding the real root of a function within a range of $x$-values using the one-dimensional version of Newton's method.

For a function $f(x)$, the Taylor series expansion is given by: $$ \begin{align*} f(x + \delta) \approx f(x) + f'(x)\delta + \frac{f''(x)}{2}\delta^2 + \cdots \end{align*} $$ As delta approaches zero (and if the function is well-behaved), this gives $$ \begin{align*} \delta = -\frac{f(x)}{f'(x)} \end{align*} $$ when $f(x + \delta) = 0$.

There are several well-known problems with Newton's method, in particular when the range of values given includes a local maximum or minimum. In this situation, the next iterative step can shoot off to $\pm\infty$. This implementation currently does not attempt to correct for this: if the value of $x$ goes beyond the initial range of values $x_{low}$ and $x_{high}$, an exception is thrown.

If the function that is provided does not override the DoubleFunction1D.derivative() method, then the derivative is approximated using finite difference. This is undesirable for several reasons: (i) the extra function evaluations will lead to slower convergence; and (ii) the choice of shift size is very important (too small and the result will be dominated by rounding errors, too large and convergence will be even slower). Use of another root-finder is recommended in this case.

Constructor Summary

Constructors

Constructor and Description
NewtonRaphsonSingleRootFinder() Default constructor.
NewtonRaphsonSingleRootFinder(double accuracy) Takes the accuracy of the root as a parameter - this is the maximum difference between the true root and the returned value that is allowed.

Method Summary

Modifier and Type	Method and Description
Double	getRoot(DoubleFunction1D function, Double x) Uses the DoubleFunction1D.derivative() method.
Double	getRoot(DoubleFunction1D function, Double x1, Double x2) Uses the DoubleFunction1D.derivative() method.
Double	getRoot(DoubleFunction1D function, DoubleFunction1D derivative, Double x) Uses the function and its derivative.
Double	getRoot(DoubleFunction1D function, DoubleFunction1D derivative, Double x1, Double x2) Uses the function and its derivative.
Double	getRoot(Function<Double,Double> function, Double x)
Double	getRoot(Function<Double,Double> function, Double x1, Double x2)
Double	getRoot(Function<Double,Double> function, Function<Double,Double> derivative, Double x) Uses the function and its derivative.
Double	getRoot(Function<Double,Double> function, Function<Double,Double> derivative, Double x1, Double x2) Uses the function and its derivative.

Methods inherited from class com.opengamma.strata.math.impl.rootfinding.RealSingleRootFinder

checkInputs, checkInputs, getRoot

Methods inherited from class java.lang.Object

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

Constructor Detail

NewtonRaphsonSingleRootFinder

public NewtonRaphsonSingleRootFinder()

Default constructor. Sets accuracy to 1e-12.

NewtonRaphsonSingleRootFinder

public NewtonRaphsonSingleRootFinder(double accuracy)

Takes the accuracy of the root as a parameter - this is the maximum difference between the true root and the returned value that is allowed. If this is negative, then the absolute value is used.

Parameters:

accuracy - The accuracy

Method Detail

getRoot

public Double getRoot(Function<Double,Double> function,
                      Double x1,
                      Double x2)

Specified by:

getRoot in class RealSingleRootFinder

Throws:

MathException - If the root is not found in 1000 attempts; if the Newton step takes the estimate for the root outside the original bounds.

getRoot

public Double getRoot(Function<Double,Double> function,
                      Double x)

getRoot

public Double getRoot(DoubleFunction1D function,
                      Double x1,
                      Double x2)

Uses the DoubleFunction1D.derivative() method. x₁ and x₂ do not have to be increasing.

Parameters:

function - The function, not null

x1 - The first bound of the root, not null

x2 - The second bound of the root, not null

Returns:

The root

Throws:

MathException - If the root is not found in 1000 attempts; if the Newton step takes the estimate for the root outside the original bounds.

getRoot

public Double getRoot(DoubleFunction1D function,
                      Double x)

Uses the DoubleFunction1D.derivative() method. This method uses an initial guess for the root, rather than bounds.

Parameters:

function - The function, not null

x - The initial guess for the root, not null

Returns:

The root

Throws:

MathException - If the root is not found in 1000 attempts.

getRoot

public Double getRoot(Function<Double,Double> function,
                      Function<Double,Double> derivative,
                      Double x1,
                      Double x2)

Uses the function and its derivative.

Parameters:

function - The function, not null

derivative - The derivative, not null

x1 - The first bound of the root, not null

x2 - The second bound of the root, not null

Returns:

The root

Throws:

MathException - If the root is not found in 1000 attempts; if the Newton step takes the estimate for the root outside the original bounds.

getRoot

public Double getRoot(Function<Double,Double> function,
                      Function<Double,Double> derivative,
                      Double x)

Uses the function and its derivative. This method uses an initial guess for the root, rather than bounds.

Parameters:

function - The function, not null

derivative - The derivative, not null

x - The initial guess for the root, not null

Returns:

The root

Throws:

MathException - If the root is not found in 1000 attempts.

getRoot

public Double getRoot(DoubleFunction1D function,
                      DoubleFunction1D derivative,
                      Double x1,
                      Double x2)

Uses the function and its derivative.

Parameters:

function - The function, not null

derivative - The derivative, not null

x1 - The first bound of the root, not null

x2 - The second bound of the root, not null

Returns:

The root

Throws:

MathException - If the root is not found in 1000 attempts; if the Newton step takes the estimate for the root outside the original bounds.

getRoot

public Double getRoot(DoubleFunction1D function,
                      DoubleFunction1D derivative,
                      Double x)

Uses the function and its derivative. This method uses an initial guess for the root, rather than bounds.

Parameters:

function - The function, not null

derivative - The derivative, not null

x - The initial guess for the root, not null

Returns:

The root

Throws:

MathException - If the root is not found in 1000 attempts.