commons-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gilles (JIRA)" <>
Subject [jira] [Commented] (MATH-1201) Please clarify tolerance semantics of org.apache.commons.math3.analysis.solvers
Date Wed, 04 Feb 2015 13:21:34 GMT


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:
>             Project: Commons Math
>          Issue Type: Improvement
>            Reporter: Jason Sachs
>            Priority: Minor
> The documentation for [BrentSolver|]
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|;a=blob;f=src/main/java/org/apache/commons/math3/analysis/solvers/],
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|;a=blob;f=src/main/java/org/apache/commons/math3/analysis/solvers/]
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|]
but should be there.
> - the code appears not to use function value accuracy at all. 
> - the [code for BrentSolver|;a=blob;f=src/main/java/org/apache/commons/math3/analysis/solvers/]
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
> - amend the documentation for [BaseUnivariateSolver|]
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
> - 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
> - 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

View raw message