[
https://issues.apache.org/jira/browse/MATH-1201?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14305062#comment-14305062
]
Gilles commented on MATH-1201:
------------------------------
Javadoc was improved in commit c7fcb448c99ae5fe9db9b217bea1233df3ee6e57
The "2" vs "6" was a typo.
Regarding the tolerance settings, the problem is more "technical": the
hierarchy was intended to avoid code duplication.
The design is not yet satisfactory anyway; we intended to refactor into a
"fluent API"...
>From the user's point-of-view, one should not rely on the defaults (as I
>indicated in the javadoc now), unless one does not care, in which case a
>complete documentation is not necessary either. :)
> Please clarify tolerance semantics of
> org.apache.commons.math3.analysis.solvers
> --------------------------------------------------------------------------------
>
> Key: MATH-1201
> URL: https://issues.apache.org/jira/browse/MATH-1201
> Project: Commons Math
> Issue Type: Improvement
> Reporter: Jason Sachs
> Priority: Minor
>
> The documentation for
> [BrentSolver|http://commons.apache.org/proper/commons-math/apidocs/org/apache/commons/math3/analysis/solvers/BrentSolver.html]
> is somewhat vague and doesn't seem to agree with the source code:
> {quote}The {{solve}} method returns a zero {{x}} of the function f in the
> given interval {{[a, b]}} to within a tolerance {{6 eps abs \(x\) + t}}
> where {{eps}} is the relative accuracy and {{t}} is the absolute accuracy.
> The given interval must bracket the root.{quote}
> A couple of issues:
> - the default tolerance values are not clearly specified. The documentation
> says "default accuracy (1e-6)" but does not state whether it's absolute,
> relative, or function value accuracy. If I dig into the [source
> code|https://git-wip-us.apache.org/repos/asf?p=commons-math.git;a=blob;f=src/main/java/org/apache/commons/math3/analysis/solvers/BrentSolver.java],
> it is the default absolute accuracy. It is unclear what the default values
> for relative and function value accuracy are. I have to dig into the class
> tree and find
> [BaseAbstractUnivariateSolver|https://git-wip-us.apache.org/repos/asf?p=commons-math.git;a=blob;f=src/main/java/org/apache/commons/math3/analysis/solvers/BaseAbstractUnivariateSolver.java]
> to find out that the default relative accuracy is 10^-14 and the default
> function value accuracy is 10^-15. These constants in the code are never
> mentioned in the documentation for
> [BaseAbstractUnivariateSolver|https://commons.apache.org/proper/commons-math/javadocs/api-3.1/org/apache/commons/math3/analysis/solvers/BaseAbstractUnivariateSolver.html]
> but should be there.
> - the code appears not to use function value accuracy at all.
> - the [code for
> BrentSolver|https://git-wip-us.apache.org/repos/asf?p=commons-math.git;a=blob;f=src/main/java/org/apache/commons/math3/analysis/solvers/BrentSolver.java#l165]
> has the expression {{tol = 2*eps * abs(b) + t}}, not {{tol = 6*eps * abs(b)
> + t}} as would be implied by the documentation. Is this an error, or is there
> a magic feature of Brent's algorithm that effectively turns the 2 into a 6?
> ----
> Suggest you:
> - include the default relative and function value tolerances in the
> documentation for BaseAbstractUnivariateSolver
> - amend the documentation for
> [BaseUnivariateSolver|https://commons.apache.org/proper/commons-math/javadocs/api-3.1/org/apache/commons/math3/analysis/solvers/BaseUnivariateSolver.html]
> to expand upon the three tolerances: Are they always used by each of the
> solver implementations? (no they aren't) Do they add together, or is the
> minimum error of the three used? (it seems dependent on each of the solver
> algorithms; in BrentSolver the relative and absolute tolerances add)
> - amend the documentation for BrentSolver to state clearly that the default
> absolute accuracy is 10^-6 and the other default tolerances are defined in
> the documentation for BaseAbstractUnivariateSolver (with a link)
> - amend the documentation for BrentSolver to state that it does not use
> function value accuracy
> - address the discrepancy in the total tolerance formula between the
> documentation and the code: is the relevant constant 2 or 6?)
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
