edu.northwestern.at.utils.math.rootfinders

## Class NewtonRaphson

- java.lang.Object
- - edu.northwestern.at.utils.math.rootfinders.NewtonRaphson

- All Implemented Interfaces:
    MonadicFunctionRootFinder

      public class NewtonRaphson
      extends java.lang.Object
      implements MonadicFunctionRootFinder

  Find roots of equations using Newton/Raphson iteration.

  The Method of NewtonRaphson is a root-finding method which requires an initial estimate x0 for a root and that the function be continuous and everywhere differentiable.

  If the derivative of the function whose root is being sought is difficult or expensive to compute, the Method of Secants or Brent's Method is a better choice. If the function is not everywhere differentiable, Bisection is the method to use.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `NewtonRaphson()` Constructor if RootFinder interface used.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `double` | `findRoot(double x0, double x1, double tol, int maxIter, MonadicFunction function, MonadicFunction derivativeFunction, RootFinderConvergenceTest convergenceTest, RootFinderIterationInformation iterationInformation)` Implementation for `MonadicFunctionRootFinder` interface.
    `static double` | `newtonRaphson(double x0, double tol, int maxIter, MonadicFunction function, MonadicFunction derivativeFunction)` Find root using the Method of Newton/Raphson.
    `static double` | `newtonRaphson(double x0, double tol, int maxIter, MonadicFunction function, MonadicFunction derivativeFunction, RootFinderConvergenceTest convergenceTest, RootFinderIterationInformation iterationInformation)` Find root using the Method of Newton/Raphson.
    `static double` | `newtonRaphson(double x0, MonadicFunction function, MonadicFunction derivativeFunction)` Find root using the Method of Newton/Raphson.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### NewtonRaphson

          public NewtonRaphson()

      Constructor if RootFinder interface used.

  - ### Method Detail

    - #### newtonRaphson

          public static double newtonRaphson(double x0,
                             double tol,
                             int maxIter,
                             MonadicFunction function,
                             MonadicFunction derivativeFunction,
                             RootFinderConvergenceTest convergenceTest,
                             RootFinderIterationInformation iterationInformation)
                                      throws java.lang.IllegalArgumentException

      Find root using the Method of Newton/Raphson.
      Parameters:
        `x0` - First approximation to root value.
        `tol` - Desired accuracy for root value.
        `maxIter` - Maximum number of iterations.
        `function` - Class implementing MonadicFunction interface to provide function values.
        `derivativeFunction` - Class implementing MonadicFunction interface to provide function derivative values.
        `convergenceTest` - RootFinderConvergenceTest which tests for convergence of the root-finding process.
        `iterationInformation` - Class implementing RootFinderIterationInformation for retrieving information about each iteration of root finding process. Set to null if you don't want this information.
      Returns:
        Approximation to root.
      Throws:
        `java.lang.IllegalArgumentException` - if function or derivativeFunction is null.

    - #### newtonRaphson

          public static double newtonRaphson(double x0,
                             double tol,
                             int maxIter,
                             MonadicFunction function,
                             MonadicFunction derivativeFunction)
                                      throws java.lang.IllegalArgumentException

      Find root using the Method of Newton/Raphson.
      Parameters:
        `x0` - First approximation to root value.
        `tol` - Desired accuracy for root value.
        `maxIter` - Maximum number of iterations.
        `function` - Class implementing MonadicFunction interface to provide function values.
        `derivativeFunction` - Class implementing MonadicFunction interface to provide function derivative values.
      Returns:
        Approximation to root.
      Throws:
        `java.lang.IllegalArgumentException` - if function or derivativeFunction is null.

    - #### newtonRaphson

          public static double newtonRaphson(double x0,
                             MonadicFunction function,
                             MonadicFunction derivativeFunction)
                                      throws java.lang.IllegalArgumentException

      Find root using the Method of Newton/Raphson.
      Parameters:
        `x0` - First approximation to root value.
        `function` - Class implementing MonadicFunction interface to provide function values.
        `derivativeFunction` - Class implementing MonadicFunction interface to provide function derivative values.
      Returns:
        Approximation to root.
      Throws:
        `java.lang.IllegalArgumentException` - if function or derivativeFunction is null.

        Up to 100 iterations are attempted with the convergence tolerance set to Constants.MACHEPS .

    - #### findRoot

          public double findRoot(double x0,
                        double x1,
                        double tol,
                        int maxIter,
                        MonadicFunction function,
                        MonadicFunction derivativeFunction,
                        RootFinderConvergenceTest convergenceTest,
                        RootFinderIterationInformation iterationInformation)
                          throws java.lang.IllegalArgumentException

      Implementation for `MonadicFunctionRootFinder` interface.
      Specified by:
        `findRoot` in interface `MonadicFunctionRootFinder`
      Parameters:
        `x0` - Left bracket value for root.
        `x1` - Right bracket value for root. Not used by some root-finder (e.g., Newton/Raphson), set to same value as x0 in those cases.
        `tol` - Convergence tolerance.
        `maxIter` - Maximum number of iterations.
        `function` - MonadicFunction computes value for function whose root is being sought.
        `derivativeFunction` - MonadicFunction computes derivative value for function whose root is being sought. Currently used only by Newton/Raphson, set to null for other methods.
        `convergenceTest` - RootFinderConvergenceTest which tests for convergence of the root-finding process.
        `iterationInformation` - Method implementing the RootFinderIterationInformation interace. Allows retrieval of function, function derivative, and iteration number for each iteration in the root-finding process. Can be set to null if you don't want to get that information.
      Throws:
        `java.lang.IllegalArgumentException`