Commons Math example source code file (analysis.xml)
The Commons Math analysis.xml source code
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
<!-- $Revision: 927009 $ $Date: 2010-03-24 07:14:07 -0400 (Wed, 24 Mar 2010) $ -->
<document url="analysis.html">
<properties>
<title>The Commons Math User Guide - Numerical Analysis
</properties>
<body>
<section name="4 Numerical Analysis">
<subsection name="4.1 Overview" href="overview">
<p>
The analysis package is the parent package for algorithms dealing with
real-valued functions of one real variable. It contains dedicated sub-packages
providing numerical root-finding, integration, and interpolation. It also
contains a polynomials sub-package that considers polynomials with real
coefficients as differentiable real functions.
</p>
<p>
Functions interfaces are intended to be implemented by user code to represent
their domain problems. The algorithms provided by the library will then operate
on these function to find their roots, or integrate them, or ... Functions can
be multivariate or univariate, real vectorial or matrix valued, and they can be
differentiable or not.
</p>
<p>
Possible future additions may include numerical differentiation.
</p>
</subsection>
<subsection name="4.2 Root-finding" href="rootfinding">
<p>
A <a href="../apidocs/org/apache/commons/math/analysis/solvers/UnivariateRealSolver.html">
org.apache.commons.math.analysis.solvers.UnivariateRealSolver.</a>
provides the means to find roots of <a href="../apidocs/org/apache/commons/math/analysis/UnivariateRealFunction.html">univariate real-valued functions.
A root is the value where the function takes the value 0. Commons-Math
includes implementations of the following root-finding algorithms: <ul>
<li>
Bisection</a>
<li>
Brent-Dekker</a>
<li>
Newton's Method</a>
<li>
Secant Method</a>
<li>
Muller's Method</a>
<li>
Laguerre's Method</a>
<li>
Ridder's Method</a>
</ul>
</p>
<p>
There are numerous non-obvious traps and pitfalls in root finding.
First, the usual disclaimers due to the way real world computers
calculate values apply. If the computation of the function provides
numerical instabilities, for example due to bit cancellation, the root
finding algorithms may behave badly and fail to converge or even
return bogus values. There will not necessarily be an indication that
the computed root is way off the true value. Secondly, the root finding
problem itself may be inherently ill-conditioned. There is a
"domain of indeterminacy", the interval for which the function has
near zero absolute values around the true root, which may be large.
Even worse, small problems like roundoff error may cause the function
value to "numerically oscillate" between negative and positive values.
This may again result in roots way off the true value, without
indication. There is not much a generic algorithm can do if
ill-conditioned problems are met. A way around this is to transform
the problem in order to get a better conditioned function. Proper
selection of a root-finding algorithm and its configuration parameters
requires knowledge of the analytical properties of the function under
analysis and numerical analysis techniques. Users are encouraged
to consult a numerical analysis text (or a numerical analyst) when
selecting and configuring a solver.
</p>
<p>
In order to use the root-finding features, first a solver object must
be created. It is encouraged that all solver object creation occurs
via the <code>org.apache.commons.math.analysis.solvers.UnivariateRealSolverFactory
class. <code>UnivariateRealSolverFactory is a simple factory
used to create all of the solver objects supported by Commons-Math.
The typical usage of <code>UnivariateRealSolverFactory
to create a solver object would be:</p>
<source>UnivariateRealSolverFactory factory = UnivariateRealSolverFactory.newInstance();
UnivariateRealSolver solver = factory.newDefaultSolver();</source>
<p>
The solvers that can be instantiated via the
<code>UnivariateRealSolverFactory are detailed below:
<table>
<tr> | Bisection | newBisectionSolver | Root must be bracketted. Linear, guaranteed convergence |
<tr>Brent | newBrentSolver | Root must be bracketted. Super-linear, guaranteed convergence |
<tr>Newton | newNewtonSolver | Uses single value for initialization. Super-linear, non-guaranteed convergence Function must be differentiable |
<tr>Secant | newSecantSolver | Root must be bracketted. Super-linear, non-guaranteed convergence |
<tr>Muller | newMullerSolver | Root must be bracketted. We restrict ourselves to real valued functions, not complex ones |
<tr>Laguerre | newLaguerreSolver | Root must be bracketted. Function must be a polynomial |
<tr>Ridder | newRidderSolver | Root must be bracketted. |
</table>
</p>
<p>
Using a solver object, roots of functions are easily found using the <code>solve
methods. For a function <code>f, and two domain values, Property | Methods | Purpose | <tr> <td>Absolute accuracy <td> <div>getAbsoluteAccuracy <div>resetAbsoluteAccuracy <div>setAbsoluteAccuracy </td> <td> The Absolute Accuracy is (estimated) maximal difference between the computed root and the true root of the function. This is what most people think of as "accuracy" intuitively. The default value is chosen as a sane value for most real world problems, for roots in the range from -100 to +100. For accurate computation of roots near zero, in the range form -0.0001 to +0.0001, the value may be decreased. For computing roots much larger in absolute value than 100, the default absolute accuracy may never be reached because the given relative accuracy is reached first. </td> </tr> <tr> <td>Relative accuracy <td> <div>getRelativeAccuracy <div>resetRelativeAccuracy <div>setRelativeAccuracy </td> <td> The Relative Accuracy is the maximal difference between the computed root and the true root, divided by the maximum of the absolute values of the numbers. This accuracy measurement is better suited for numerical calculations with computers, due to the way floating point numbers are represented. The default value is chosen so that algorithms will get a result even for roots with large absolute values, even while it may be impossible to reach the given absolute accuracy. </td> </tr> <tr> <td>Function value accuracy <td> <div>getFunctionValueAccuracy <div>resetFunctionValueAccuracy <div>setFunctionValueAccuracy </td> <td> This value is used by some algorithms in order to prevent numerical instabilities. If the function is evaluated to an absolute value smaller than the Function Value Accuracy, the algorithms assume they hit a root and return the value immediately. The default value is a "very small value". If the goal is to get a near zero function value rather than an accurate root, computation may be sped up by setting this value appropriately. </td> </tr> <tr> <td>Maximum iteration count <td> <div>getMaximumIterationCount <div>resetMaximumIterationCount <div>setMaximumIterationCount </td> <td> This is the maximal number of iterations the algorithm will try. If this number is exceeded, non-convergence is assumed and a <code>ConvergenceException exception is thrown. The default value is 100, which should be plenty, given that a bisection algorithm can't get any more accurate after 52 iterations because of the number of mantissa bits in a double precision floating point number. If a number of ill-conditioned problems is to be solved, this number can be decreased in order to avoid wasting time. </td> </tr> </table> </p> </subsection> <subsection name="4.3 Interpolation" href="interpolation"> <p> A <a href="../apidocs/org/apache/commons/math/analysis/interpolation/UnivariateRealInterpolator.html"> org.apache.commons.math.analysis.interpolation.UnivariateRealInterpolator</a> is used to find a univariate real-valued function <code>f which for a given set of ordered pairs (<code>xi,
|---|
The search page
Other Commons Math source code examples at this package level
Click here to learn more about this project
