Author: erans Date: Mon Jul 11 12:32:14 2011 New Revision: 1145146 URL: http://svn.apache.org/viewvc?rev=1145146&view=rev Log: 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.
Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/BaseSecantSolver.java commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/BracketedUnivariateRealSolver.java commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/SecantSolver.java commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolverUtils.java commons/proper/math/trunk/src/site/xdoc/userguide/analysis.xml Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/BaseSecantSolver.java URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/BaseSecantSolver.java?rev=1145146&r1=1145145&r2=1145146&view=diff ============================================================================== --- commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/BaseSecantSolver.java (original) +++ commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/BaseSecantSolver.java Mon Jul 11 12:32:14 2011 @@ -25,7 +25,7 @@ import org.apache.commons.math.exception * 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 * 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 Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/BracketedUnivariateRealSolver.java URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/BracketedUnivariateRealSolver.java?rev=1145146&r1=1145145&r2=1145146&view=diff ============================================================================== --- commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/BracketedUnivariateRealSolver.java (original) +++ commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/BracketedUnivariateRealSolver.java Mon Jul 11 12:32:14 2011 @@ -57,9 +57,9 @@ public interface BracketedUnivariateReal * @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 BracketedUnivariateReal * @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 Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/SecantSolver.java URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/SecantSolver.java?rev=1145146&r1=1145145&r2=1145146&view=diff ============================================================================== --- commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/SecantSolver.java (original) +++ commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/SecantSolver.java Mon Jul 11 12:32:14 2011 @@ -97,7 +97,6 @@ public class SecantSolver extends Abstra // Keep finding better approximations. while (true) { - // Calculate the next approximation. final double x = x1 - ((f1 * (x1 - x0)) / (f1 - f0)); final double fx = computeObjectiveValue(x); Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolverUtils.java URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolverUtils.java?rev=1145146&r1=1145145&r2=1145146&view=diff ============================================================================== --- commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolverUtils.java (original) +++ commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolverUtils.java Mon Jul 11 12:32:14 2011 @@ -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. Modified: commons/proper/math/trunk/src/site/xdoc/userguide/analysis.xml URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/userguide/analysis.xml?rev=1145146&r1=1145145&r2=1145146&view=diff ============================================================================== --- commons/proper/math/trunk/src/site/xdoc/userguide/analysis.xml (original) +++ commons/proper/math/trunk/src/site/xdoc/userguide/analysis.xml Mon Jul 11 12:32:14 2011 @@ -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