edu.northwestern.at.utils.math.rootfinders

## Class Bisection

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

- All Implemented Interfaces:
    MonadicFunctionRootFinder

      public class Bisection
      extends java.lang.Object
      implements MonadicFunctionRootFinder

  Find roots of equations using Bisection.

  The Method of Bisection is a root-finding method which requires an initial interval [x0,x1] bracketing a root and that the function be continuous in that interval.

  An updated estimate of the root value is computed by using the midpoint of the two previous values. Depending upon the sign of the function at the interval midpoint, the midpoint replaces either the lower interval value (if f(midpoint) < 0) or the upper interval value (if f(midpoint) > 0). This bisection process halves the search interval on each iteration

  If the function whose root is being sought has a derivative at each point in the interval, the Method of Secants or Brent's Method is a better choice.

- - ### Constructor Summary

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

  - ### Method Summary

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

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

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

- - ### Constructor Detail

    - #### Bisection

          public Bisection()

      Constructor if RootFinder interface used.

  - ### Method Detail

    - #### bisection

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

      Find root using the Method of Bisection.
      Parameters:
        `x0` - First approximation to root value.
        `x1` - Second approximation to root value.
        `tol` - Desired accuracy for root value.
        `maxIter` - Maximum number of iterations.
        `function` - Class implementing MonadicFunction interface to provide function 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 of function.
      Throws:
        `java.lang.IllegalArgumentException` - if [x0,x1] cannot be expanded to bracket a root or function is null.

        This implementation always starts by attempting to expand the root bracketing interval to enclose a root.

    - #### bisection

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

      Find root using the Method of Bisection.
      Parameters:
        `x0` - First approximation to root value.
        `x1` - Second approximation to root value.
        `tol` - Desired accuracy for root value.
        `maxIter` - Maximum number of iterations.
        `function` - Class implementing MonadicFunction interface to provide function values.
      Returns:
        Approximation to root of function.
      Throws:
        `java.lang.IllegalArgumentException` - if [x0,x1] cannot be expanded to bracket a root or function is null.

        This implementation always starts by attempting to expand the root bracketing interval to enclose a root.

    - #### bisection

          public static double bisection(double x0,
                         double x1,
                         MonadicFunction function)
                                  throws java.lang.IllegalArgumentException

      Find root using the Method of Bisection.
      Parameters:
        `x0` - First approximation to root value.
        `x1` - Second approximation to root value.
        `function` - Class implementing MonadicFunction interface to provide function values.
      Returns:
        Approximation to root of function.
      Throws:
        `java.lang.IllegalArgumentException` - if [x0,x1] cannot be expanded to bracket a root or function is null.

        This implementation always starts by attempting to expand the root bracketing interval to enclose a root. Up to 250 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`