[
https://issues.apache.org/jira/browse/MATH-1201?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jason Sachs updated MATH-1201:
------------------------------
Description:
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:
>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.
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, or is the minimum error
used? (it seems dependent on each of the solver algorithms
- 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?)
was:
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:
>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.
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, or is the minimum error
used? (it seems dependent on each of the solver algorithms
- 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?)
> 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:
> >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.
> 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, or is the minimum error
> used? (it seems dependent on each of the solver algorithms
> - 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)
