From 1490873b330c60ad465f63c19a75cd24f18f6f33 Mon Sep 17 00:00:00 2001 From: Luc Maisonobe Date: Tue, 6 Sep 2011 20:01:07 +0000 Subject: [PATCH] added documentation about error handling in user functions in the userguide git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1165810 13f79535-47bb-0310-9956-ffa450edef68 --- src/site/xdoc/userguide/analysis.xml | 55 ++++++++++++++++++++++++++-- src/site/xdoc/userguide/index.xml | 9 +++-- 2 files changed, 56 insertions(+), 8 deletions(-) diff --git a/src/site/xdoc/userguide/analysis.xml b/src/site/xdoc/userguide/analysis.xml index f8fc84b2f..c267b0c71 100644 --- a/src/site/xdoc/userguide/analysis.xml +++ b/src/site/xdoc/userguide/analysis.xml @@ -44,7 +44,54 @@ Possible future additions may include numerical differentiation.

- + +

+ For user-defined functions, when the method encounters an error + during evaluation, users must use their own 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). +

+ 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 + } + } + +

+ 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. +

+ +

UnivariateRealSolver, @@ -327,7 +374,7 @@ double c = UnivariateRealSolverUtils.forceSide(100, function,

- +

A UnivariateRealInterpolator is used to find a univariate real-valued @@ -445,7 +492,7 @@ System.out println("f(" + interpolationX + ") = " + interpolatedY); tricubic interpolating function.

- +

A UnivariateRealIntegrator provides the means to numerically integrate @@ -463,7 +510,7 @@ System.out println("f(" + interpolationX + ") = " + interpolatedY);

- +

The org.apache.commons.math.analysis.polynomials package provides real diff --git a/src/site/xdoc/userguide/index.xml b/src/site/xdoc/userguide/index.xml index ce592ca2d..893a7fb83 100644 --- a/src/site/xdoc/userguide/index.xml +++ b/src/site/xdoc/userguide/index.xml @@ -70,10 +70,11 @@

  • 4. Numerical Analysis
  • 5. Special Functions