MATH-599 (part of the patch provided by D. Hendriks on JIRA, issue MATH-605).

Improved Javadoc.
Allow a bracketing interval to contain the root at its end-points.


git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1145146 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/math/analysis/solvers/BaseSecantSolver.java

@@ -25,7 +25,7 @@ import org.apache.commons.math.exception.MathInternalError;
  * Base class for all bracketing <em>Secant</em>-based methods for root-finding
  * (approximating a zero of a univariate real function).
  *
- * <p>Implementation of the {@link RegulaFalsiSolver <em>Regula Falsi</em>}, and
+ * <p>Implementation of the {@link RegulaFalsiSolver <em>Regula Falsi</em>} and
  * {@link IllinoisSolver <em>Illinois</em>} methods is based on the
  * following article: M. Dowell and P. Jarratt,
  * <em>A modified regula falsi method for computing the root of an
@@ -38,8 +38,8 @@ import org.apache.commons.math.exception.MathInternalError;
  * BIT Numerical Mathematics, volume 12, number 4, pages 503-508, Springer,
  * 1972.</p>
  *
- * <p>The  {@link SecantSolver <em>secant<em>} method is <em>not</emp> a
+ * <p>The {@link SecantSolver <em>Secant</em>} method is <em>not</em> a
- * bracketing method so it is not implemented here. It has a separate
+ * bracketing method, so it is not implemented here. It has a separate
  * implementation.</p>
  *
  * @since 3.0

src/main/java/org/apache/commons/math/analysis/solvers/BracketedUnivariateRealSolver.java

@@ -57,9 +57,9 @@ public interface BracketedUnivariateRealSolver<FUNC extends UnivariateRealFuncti
      * @param f Function to solve.
      * @param min Lower bound for the interval.
      * @param max Upper bound for the interval.
-     * @param allowedSolutions the kind of solutions that the root-finding algorithm may
+     * @param allowedSolutions The kind of solutions that the root-finding algorithm may
      * accept as solutions.
-     * @return a value where the function is zero.
+     * @return A value where the function is zero.
      * @throws org.apache.commons.math.exception.MathIllegalArgumentException
      * if the arguments do not satisfy the requirements specified by the solver.
      * @throws org.apache.commons.math.exception.TooManyEvaluationsException if
@@ -79,9 +79,9 @@ public interface BracketedUnivariateRealSolver<FUNC extends UnivariateRealFuncti
      * @param min Lower bound for the interval.
      * @param max Upper bound for the interval.
      * @param startValue Start value to use.
-     * @param allowedSolutions the kind of solutions that the root-finding algorithm may
+     * @param allowedSolutions The kind of solutions that the root-finding algorithm may
      * accept as solutions.
-     * @return a value where the function is zero.
+     * @return A value where the function is zero.
      * @throws org.apache.commons.math.exception.MathIllegalArgumentException
      * if the arguments do not satisfy the requirements specified by the solver.
      * @throws org.apache.commons.math.exception.TooManyEvaluationsException if

src/main/java/org/apache/commons/math/analysis/solvers/SecantSolver.java

@@ -97,7 +97,6 @@ public class SecantSolver extends AbstractUnivariateRealSolver {
 
         // Keep finding better approximations.
         while (true) {
-
             // Calculate the next approximation.
             final double x = x1 - ((f1 * (x1 - x0)) / (f1 - f0));
             final double fx = computeObjectiveValue(x);

src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolverUtils.java

@@ -289,7 +289,9 @@ public class UnivariateRealSolverUtils {
     }
 
     /**
-     * Check whether the function takes opposite signs at the endpoints.
+     * Check whether the interval bounds bracket a root. That is, if the
+     * values at the endpoints are not equal to zero, then the function takes
+     * opposite signs at the endpoints.
      *
      * @param function Function.
      * @param lower Lower endpoint.
@@ -305,7 +307,7 @@ public class UnivariateRealSolverUtils {
         }
         final double fLo = function.value(lower);
         final double fHi = function.value(upper);
-        return (fLo > 0 && fHi < 0) || (fLo < 0 && fHi > 0);
+        return (fLo >= 0 && fHi <= 0) || (fLo <= 0 && fHi >= 0);
     }
 
     /**
@@ -354,8 +356,8 @@ public class UnivariateRealSolverUtils {
     }
 
     /**
-     * Check that the endpoints specify an interval and the function takes
+     * Check that the endpoints specify an interval and the end points
-     * opposite signs at the endpoints.
+     * bracket a root.
      *
      * @param function Function.
      * @param lower Lower endpoint.

src/site/xdoc/userguide/analysis.xml

@@ -158,7 +158,7 @@
           return bogus values. There will not necessarily be an indication that
           the computed root is way off the true value.  Secondly, the root finding
           problem itself may be inherently ill-conditioned.  There is a
-           "domain of indeterminacy", the interval for which the function has
+          "domain of indeterminacy", the interval for which the function has
           near zero absolute values around the true root,  which may be large.
           Even worse, small problems like roundoff error may cause the function
           value to "numerically oscillate" between negative and positive values.
@@ -178,7 +178,7 @@
           accuracy. Using a solver object, roots of functions
           are easily found using the <code>solve</code> methods.  These methods takes
           a maximum iteration count <code>maxEval</code>, a function <code>f</code>,
-          and either two domain values, <code>min</code> and <code>max</code> or a
+          and either two domain values, <code>min</code> and <code>max</code>, or a
           <code>startValue</code> as parameters. If the maximal number of iterations
           count is exceeded, non-convergence is assumed and a <code>ConvergenceException</code>
           exception is thrown.  A suggested value is 100, which should be plenty, given that a
@@ -187,7 +187,7 @@
           ill-conditioned problems is to be solved, this number can be decreased in order
           to avoid wasting time.
           <a
-          href="../apidocs/org/apache/commons/math/analysis/solvers/BracketedUnivariateRealSolver.html">bracketed
+          href="../apidocs/org/apache/commons/math/analysis/solvers/BracketedUnivariateRealSolver.html">Bracketed
           solvers</a> also take an <a
           href="../apidocs/org/apache/commons/math/analysis/solvers/AllowedSolutions.html">allowedSolutions</a>
           enum parameter to specify which side of the final convergence interval should be