Package com.opengamma.strata.math.impl.rootfinding

Class 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 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​(DoubleFunction1D function,
                      Double x1,
                      Double x2)
        Uses the DoubleFunction1D.derivative() method. x1 and x2 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.