Package com.irurueta.numerical.roots

Class BisectionSingleRootEstimator

java.lang.Object
com.irurueta.numerical.roots.RootEstimator
com.irurueta.numerical.roots.SingleRootEstimator
com.irurueta.numerical.roots.BracketedSingleRootEstimator
com.irurueta.numerical.roots.BisectionSingleRootEstimator
public class BisectionSingleRootEstimator extends BracketedSingleRootEstimator
This class searches for a single REAL root on a single dimension function (i.e. f(x) ). The root to be found must be inside a given or computed bracket of values.

This class uses the bisection method, which is one of the slowest but most reliable existing methods (i.e. the method doubles the accuracy on each iteration, so in 64 iterations the highest accuracy provided by a double value can be obtained).

In comparison to other methods, the Bisection one can find roots even in situations where isn't a zero crossing. In other words, bracket estimation might fail for this class, but even then a root might be obtained.

In order to find a root around a given range of values, a bracket of values can be provided. Otherwise, a bracket can be computed by attempting to find a zero-crossing while expanding an initial range of values.

Bracket computation estimates a larger range of values, which can later be refined in order to estimate a given root.

This class is based on the implementation of Numerical Recipes 3rd ed. Section 9.1.1 page 447.

  • Field Details

    • JMAX

      public static final int JMAX
      Constant defining maximum number of iterations to estimate a root.
      See Also:

    • DEFAULT_TOLERANCE

      public static final double DEFAULT_TOLERANCE
      Constant defining default tolerance to find a root.
      See Also:

    • MIN_TOLERANCE

      public static final double MIN_TOLERANCE
      Minimum allowed tolerance that can be set.
      See Also:

    • tolerance

      private double tolerance
      Tolerance to find a root. Whenever the variation of the estimated root is smaller than the provided tolerance, then the algorithm is assumed to be converged.

  • Constructor Details

    • BisectionSingleRootEstimator

      public BisectionSingleRootEstimator()
      Empty constructor.

    • BisectionSingleRootEstimator

      public BisectionSingleRootEstimator(SingleDimensionFunctionEvaluatorListener listener, double minEvalPoint, double maxEvalPoint, double tolerance) throws InvalidBracketRangeException
      Constructor.
      Parameters:
      listener - Listener to evaluate a single dimension function f(x) to find its roots.
      minEvalPoint - Smallest value inside the bracket of values where the root will be searched.
      maxEvalPoint - Largest value inside the bracket of values where the root will be searched.
      tolerance - Tolerance to find a root. During the estimation of a root, if the variation of the estimated root is smaller than the provided tolerance, then the algorithm is assumed to be converged, and the root is ensured to have an accuracy that equals tolerance.
      Throws:
      InvalidBracketRangeException - Raised if minEvalPoint < maxEvalPoint.
      IllegalArgumentException - Raised if provided tolerance is negative.

  • Method Details

    • getTolerance

      public double getTolerance()
      Returns tolerance to find a root. Whenever the variation of the estimated root is smaller than returned tolerance, then the algorithm is assumed to be converged, and the estimated root is ensured to have an accuracy that equals the returned tolerance.
      Returns:
      Tolerance to find a root.

    • setTolerance

      public void setTolerance(double tolerance) throws LockedException
      Sets tolerance to find a root. Whenever the variation of the estimated root is smaller than provided tolerance, then the algorithm is assumed to be converged, and the estimated root is ensured to have an accuracy that equals provided tolerance.
      Parameters:
      tolerance - Tolerance to find a root.
      Throws:
      LockedException - Raised if this instance is locked while doing some computations.
      IllegalArgumentException - Raised if provided tolerance is negative.

    • internalSetTolerance

      private void internalSetTolerance(double tolerance)
      Internal method to set tolerance to find a root. This method does not check whether this instance is locked. Whenever the variation of the estimated root is smaller than provided tolerance, then the algorithm is assumed to be converged, and the estimated root is ensured to have an accuracy that equals provided tolerance.
      Parameters:
      tolerance - Tolerance to find a root.
      Throws:
      IllegalArgumentException - Raised if provided tolerance is negative.

    • estimate

      public void estimate() throws LockedException, NotReadyException, RootEstimationException
      Estimates a single root of the provided single dimension function contained within a given bracket of values.
      Overrides:
      estimate in class RootEstimator
      Throws:
      LockedException - Exception raised if this instance is already locked.
      NotReadyException - Exception raised if not enough parameters have been provided in order to start the estimation.
      RootEstimationException - Raised if the root estimation failed for some other reason (usually inability to evaluate the function, numerical instability or convergence problems, or no roots are found).

    • isReady

      public boolean isReady()
      Returns boolean indicating whether this instance is ready to compute a root. This instance is ready as soon as a listener is provided and a bracket is provided or computed.
      Overrides:
      isReady in class SingleRootEstimator
      Returns:
      True if instance is ready, false otherwise