commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From l..@apache.org
Subject svn commit: r1165810 - in /commons/proper/math/trunk/src/site/xdoc/userguide: analysis.xml index.xml
Date Tue, 06 Sep 2011 20:01:07 GMT
Author: luc
Date: Tue Sep  6 20:01:07 2011
New Revision: 1165810

URL: http://svn.apache.org/viewvc?rev=1165810&view=rev
Log:
added documentation about error handling in user functions in the userguide

Modified:
    commons/proper/math/trunk/src/site/xdoc/userguide/analysis.xml
    commons/proper/math/trunk/src/site/xdoc/userguide/index.xml

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=1165810&r1=1165809&r2=1165810&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/analysis.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/analysis.xml Tue Sep  6 20:01:07 2011
@@ -44,7 +44,54 @@
           Possible future additions may include numerical differentiation.
         </p>
       </subsection>
-      <subsection name="4.2 Root-finding" href="rootfinding">
+      <subsection name="4.2 Error handling" href="errorhandling">
+        <p>
+          For user-defined functions, when the method encounters an error
+          during evaluation, users must use their <em>own</em> unchecked exceptions.
+          The following example shows the recommended way to do that, using root
+          solving as the example (the same construct should be used for ODE
+          integrators or for optimizations).
+        </p>
+        <source>private static class LocalException extends RuntimeException {
+
+   // the x value that caused the problem
+   private final double x;
+
+   public LocalException(double x) {
+     this.x = x;
+   }
+
+   public double getX() {
+     return x;
+   }
+
+ }
+
+ private static class MyFunction implements UnivariateRealFunction {
+   public double value(double x) {
+     double y = hugeFormula(x);
+     if (somethingBadHappens) {
+       throw new LocalException(x);
+     }
+     return y;
+   }
+ }
+
+ public void compute() {
+   try {
+     solver.solve(maxEval, new MyFunction(a, b, c), min, max);
+   } catch (LocalException le) {
+     // retrieve the x value
+   }
+ }
+ </source>
+      <p>
+        As shown in this example the exception is really something local to user code
+        and there is a guarantee Apache Commons Math will not mess with it.
+        The user is safe.
+      </p>
+      </subsection>
+      <subsection name="4.3 Root-finding" href="rootfinding">
         <p>
           <a href="../apidocs/org/apache/commons/math/analysis/solvers/UnivariateRealSolver.html">
           UnivariateRealSolver</a>, <a href="../apidocs/org/apache/commons/math/analysis/solvers/DifferentiableUnivariateRealSolver.html">
@@ -327,7 +374,7 @@ double c = UnivariateRealSolverUtils.for
           </table>
         </p>
       </subsection>
-      <subsection name="4.3 Interpolation" href="interpolation">
+      <subsection name="4.4 Interpolation" href="interpolation">
         <p>
           A <a href="../apidocs/org/apache/commons/math/analysis/interpolation/UnivariateRealInterpolator.html">
           UnivariateRealInterpolator</a> is used to find a univariate real-valued
@@ -445,7 +492,7 @@ System.out println("f(" + interpolationX
           tricubic interpolating function</a>.
         </p>
       </subsection>
-      <subsection name="4.4 Integration" href="integration">
+      <subsection name="4.5 Integration" href="integration">
         <p>
           A <a href="../apidocs/org/apache/commons/math/analysis/integration/UnivariateRealIntegrator.html">
           UnivariateRealIntegrator</a> provides the means to numerically integrate
@@ -463,7 +510,7 @@ System.out println("f(" + interpolationX
           </ul>      
         </p>
       </subsection>
-      <subsection name="4.5 Polynomials" href="polynomials">
+      <subsection name="4.6 Polynomials" href="polynomials">
         <p>
           The <a href="../apidocs/org/apache/commons/math/analysis/polynomials/package-summary.html">
           org.apache.commons.math.analysis.polynomials</a> package provides real

Modified: commons/proper/math/trunk/src/site/xdoc/userguide/index.xml
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/userguide/index.xml?rev=1165810&r1=1165809&r2=1165810&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/index.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/index.xml Tue Sep  6 20:01:07 2011
@@ -70,10 +70,11 @@
             <li><a href="analysis.html">4. Numerical Analysis</a>
                 <ul>
                 <li><a href="analysis.html#a4.1_Overview">4.1 Overview</a></li>
-                <li><a href="analysis.html#a4.2_Root-finding">4.2 Root-finding</a></li>
               
-                <li><a href="analysis.html#a4.3_Interpolation">4.3 Interpolation</a></li>
-                <li><a href="analysis.html#a4.4_Integration">4.4 Integration</a></li>
-                <li><a href="analysis.html#a4.5_Polynomials">4.5 Polynomials</a></li>
+                <li><a href="analysis.html#a4.2_Error-handling">4.2 Error handling</a></li>
               
+                <li><a href="analysis.html#a4.3_Root-finding">4.3 Root-finding</a></li>
               
+                <li><a href="analysis.html#a4.4_Interpolation">4.4 Interpolation</a></li>
+                <li><a href="analysis.html#a4.5_Integration">4.5 Integration</a></li>
+                <li><a href="analysis.html#a4.6_Polynomials">4.6 Polynomials</a></li>
                 </ul></li>     
             <li><a href="special.html">5. Special Functions</a>
                 <ul>



Mime
View raw message