From 099fdba0750714d65ce21c21618da5379ed885f4 Mon Sep 17 00:00:00 2001
From: Gilles Sadowski <erans@apache.org>
Date: Mon, 11 Jul 2011 12:32:14 +0000
Subject: [PATCH] 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
---
 .../math/analysis/solvers/BaseSecantSolver.java        |  6 +++---
 .../solvers/BracketedUnivariateRealSolver.java         |  8 ++++----
 .../commons/math/analysis/solvers/SecantSolver.java    |  1 -
 .../analysis/solvers/UnivariateRealSolverUtils.java    | 10 ++++++----
 src/site/xdoc/userguide/analysis.xml                   |  6 +++---
 5 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/src/main/java/org/apache/commons/math/analysis/solvers/BaseSecantSolver.java b/src/main/java/org/apache/commons/math/analysis/solvers/BaseSecantSolver.java
index 9dfc6da25..d446869dd 100644
--- a/src/main/java/org/apache/commons/math/analysis/solvers/BaseSecantSolver.java
+++ b/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
- * bracketing method so it is not implemented here. It has a separate
+ * <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
  * implementation.</p>
  *
  * @since 3.0
diff --git a/src/main/java/org/apache/commons/math/analysis/solvers/BracketedUnivariateRealSolver.java b/src/main/java/org/apache/commons/math/analysis/solvers/BracketedUnivariateRealSolver.java
index 0a186359f..0376b93a4 100644
--- a/src/main/java/org/apache/commons/math/analysis/solvers/BracketedUnivariateRealSolver.java
+++ b/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
diff --git a/src/main/java/org/apache/commons/math/analysis/solvers/SecantSolver.java b/src/main/java/org/apache/commons/math/analysis/solvers/SecantSolver.java
index 5f979e267..363a8b3c7 100644
--- a/src/main/java/org/apache/commons/math/analysis/solvers/SecantSolver.java
+++ b/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);
diff --git a/src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolverUtils.java b/src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolverUtils.java
index f18f39604..254966e31 100644
--- a/src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolverUtils.java
+++ b/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
-     * opposite signs at the endpoints.
+     * Check that the endpoints specify an interval and the end points
+     * bracket a root.
      *
      * @param function Function.
      * @param lower Lower endpoint.
diff --git a/src/site/xdoc/userguide/analysis.xml b/src/site/xdoc/userguide/analysis.xml
index 5d7aeeb46..daecf80b0 100644
--- a/src/site/xdoc/userguide/analysis.xml
+++ b/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