Return-Path: X-Original-To: apmail-commons-issues-archive@minotaur.apache.org Delivered-To: apmail-commons-issues-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 2233D17C0F for ; Tue, 3 Feb 2015 21:27:34 +0000 (UTC) Received: (qmail 20265 invoked by uid 500); 3 Feb 2015 21:27:34 -0000 Delivered-To: apmail-commons-issues-archive@commons.apache.org Received: (qmail 20161 invoked by uid 500); 3 Feb 2015 21:27:34 -0000 Mailing-List: contact issues-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: issues@commons.apache.org Delivered-To: mailing list issues@commons.apache.org Received: (qmail 20149 invoked by uid 99); 3 Feb 2015 21:27:34 -0000 Received: from arcas.apache.org (HELO arcas.apache.org) (140.211.11.28) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 03 Feb 2015 21:27:34 +0000 Date: Tue, 3 Feb 2015 21:27:34 +0000 (UTC) From: "Jason Sachs (JIRA)" To: issues@commons.apache.org Message-ID: In-Reply-To: References: Subject: [jira] [Updated] (MATH-1201) Please clarify tolerance semantics of org.apache.commons.math3.analysis.solvers MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-JIRA-FingerPrint: 30527f35849b9dde25b450d4833f0394 [ https://issues.apache.org/jira/browse/MATH-1201?page=3Dcom.atlassian= .jira.plugin.system.issuetabpanels:all-tabpanel ] Jason Sachs updated MATH-1201: ------------------------------ Description:=20 The documentation for [BrentSolver|http://commons.apache.org/proper/commons= -math/apidocs/org/apache/commons/math3/analysis/solvers/BrentSolver.html] i= s 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 g= iven interval {{[a, b]}} to within a tolerance {{6 eps abs \(x\) + t}} whe= re {{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, r= elative, or function value accuracy. If I dig into the [source code|https:/= /git-wip-us.apache.org/repos/asf?p=3Dcommons-math.git;a=3Dblob;f=3Dsrc/main= /java/org/apache/commons/math3/analysis/solvers/BrentSolver.java], it is th= e default absolute accuracy. It is unclear what the default values for rela= tive 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=3Dcommons-math.git;a=3Dblob;f=3Dsrc/main/java/org/apache/commons/math3/a= nalysis/solvers/BaseAbstractUnivariateSolver.java] to find out that the def= ault relative accuracy is 10^-14 and the default function value accuracy is= 10^-15. These constants in the code are never mentioned in the documentati= on for [BaseAbstractUnivariateSolver|https://commons.apache.org/proper/comm= ons-math/javadocs/api-3.1/org/apache/commons/math3/analysis/solvers/BaseAbs= tractUnivariateSolver.html] but should be there. - the code appears not to use function value accuracy at all.=20 - the [code for BrentSolver|https://git-wip-us.apache.org/repos/asf?p=3Dcom= mons-math.git;a=3Dblob;f=3Dsrc/main/java/org/apache/commons/math3/analysis/= solvers/BrentSolver.java#l165] has the expression {{tol =3D 2*eps * abs(b) = + t}}, not {{tol =3D 6*eps * abs(b) + t}} as would be implied by the docume= ntation. 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 documen= tation 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) D= o they add together, or is the minimum error of the three used? (it seems d= ependent 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 fun= ction value accuracy - address the discrepancy in the total tolerance formula between the docume= ntation 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] i= s 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 i= nterval {{[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 int= erval 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, r= elative, or function value accuracy. If I dig into the [source code|https:/= /git-wip-us.apache.org/repos/asf?p=3Dcommons-math.git;a=3Dblob;f=3Dsrc/main= /java/org/apache/commons/math3/analysis/solvers/BrentSolver.java], it is th= e default absolute accuracy. It is unclear what the default values for rela= tive 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=3Dcommons-math.git;a=3Dblob;f=3Dsrc/main/java/org/apache/commons/math3/a= nalysis/solvers/BaseAbstractUnivariateSolver.java] to find out that the def= ault relative accuracy is 10^-14 and the default function value accuracy is= 10^-15. These constants in the code are never mentioned in the documentati= on for [BaseAbstractUnivariateSolver|https://commons.apache.org/proper/comm= ons-math/javadocs/api-3.1/org/apache/commons/math3/analysis/solvers/BaseAbs= tractUnivariateSolver.html] but should be there. - the code appears not to use function value accuracy at all.=20 - the [code for BrentSolver|https://git-wip-us.apache.org/repos/asf?p=3Dcom= mons-math.git;a=3Dblob;f=3Dsrc/main/java/org/apache/commons/math3/analysis/= solvers/BrentSolver.java#l165] has the expression {{tol =3D 2*eps * abs(b) = + t}}, not {{tol =3D 6*eps * abs(b) + t}} as would be implied by the docume= ntation. 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 documen= tation 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) D= o they add together, or is the minimum error of the three used? (it seems d= ependent 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 fun= ction value accuracy - address the discrepancy in the total tolerance formula between the docume= ntation and the code: is the relevant constant 2 or 6?) > Please clarify tolerance semantics of org.apache.commons.math3.analysis.s= olvers=20 > -------------------------------------------------------------------------= ------- > > 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/commo= ns-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}} w= here {{eps}} is the relative accuracy and {{t}} is the absolute accuracy. T= he given interval must bracket the root.{quote} > A couple of issues: > - the default tolerance values are not clearly specified. The documentati= on 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=3Dcommons-math.git;a=3Dblob;f=3Dsrc/ma= in/java/org/apache/commons/math3/analysis/solvers/BrentSolver.java], it is = the default absolute accuracy. It is unclear what the default values for re= lative and function value accuracy are. I have to dig into the class tree a= nd find [BaseAbstractUnivariateSolver|https://git-wip-us.apache.org/repos/a= sf?p=3Dcommons-math.git;a=3Dblob;f=3Dsrc/main/java/org/apache/commons/math3= /analysis/solvers/BaseAbstractUnivariateSolver.java] to find out that the d= efault relative accuracy is 10^-14 and the default function value accuracy = is 10^-15. These constants in the code are never mentioned in the documenta= tion for [BaseAbstractUnivariateSolver|https://commons.apache.org/proper/co= mmons-math/javadocs/api-3.1/org/apache/commons/math3/analysis/solvers/BaseA= bstractUnivariateSolver.html] but should be there. > - the code appears not to use function value accuracy at all.=20 > - the [code for BrentSolver|https://git-wip-us.apache.org/repos/asf?p=3Dc= ommons-math.git;a=3Dblob;f=3Dsrc/main/java/org/apache/commons/math3/analysi= s/solvers/BrentSolver.java#l165] has the expression {{tol =3D 2*eps * abs(b= ) + t}}, not {{tol =3D 6*eps * abs(b) + t}} as would be implied by the docu= mentation. Is this an error, or is there a magic feature of Brent's algorit= hm that effectively turns the 2 into a 6? > ---- > Suggest you: > - include the default relative and function value tolerances in the docum= entation for BaseAbstractUnivariateSolver > - amend the documentation for [BaseUnivariateSolver|https://commons.apach= e.org/proper/commons-math/javadocs/api-3.1/org/apache/commons/math3/analysi= s/solvers/BaseUnivariateSolver.html] to expand upon the three tolerances: A= re 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 an= d absolute tolerances add) > - amend the documentation for BrentSolver to state clearly that the defau= lt 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 f= unction value accuracy > - address the discrepancy in the total tolerance formula between the docu= mentation and the code: is the relevant constant 2 or 6?) -- This message was sent by Atlassian JIRA (v6.3.4#6332)