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

@@ -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