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
