181 lines
7.1 KiB
XML
181 lines
7.1 KiB
XML
<?xml version="1.0"?>
|
|
|
|
<!--
|
|
Copyright 2003-2004 The Apache Software Foundation
|
|
|
|
Licensed 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$ $Date$ -->
|
|
<document url="utilities.html">
|
|
|
|
<properties>
|
|
<title>The Commons Math User Guide - Utilites</title>
|
|
</properties>
|
|
|
|
<body>
|
|
|
|
<section name="6 Utilities">
|
|
|
|
<subsection name="6.1 Overview" href="overview">
|
|
<p>
|
|
The <a href="../apidocs/org/apache/commons/math/util/package-summary.html">
|
|
org.apache.commons.math.util</a> package collects a group of array utilities,
|
|
value transformers, and numerical routines used by implementation classes in
|
|
commons-math.
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="6.2 Double array utilities" href="arrays">
|
|
<p>
|
|
To maintain statistics based on a "rolling" window of values, a resizable
|
|
array implementation was developed and is provided for reuse in the
|
|
<code>util</code> package. The core functionality provided is described in
|
|
the documentation for the interface,
|
|
<a href="../apidocs/org/apache/commons/math/util/DoubleArray.html">
|
|
org.apache.commons.math.util.DoubleArray.</a> This interface adds one
|
|
method, <code>addElementRolling(double)</code> to basic list accessors.
|
|
The <code>addElementRolling</code> method adds an element
|
|
(the actual parameter) to the end of the list and removes the first element
|
|
in the list.
|
|
</p>
|
|
<p>
|
|
The <a href="../apidocs/org/apache/commons/math/util/ResizableDoubleArray.html">
|
|
org.apache.commons.math.util.ResizableDoubleArray</a> class provides a
|
|
configurable, array-backed implementation of the <code>DoubleArray</code>
|
|
interface. When <code>addElementRolling</code> is invoked, the underlying
|
|
array is expanded if necessary, the new element is added to the end of the
|
|
array and the "usable window" of the array is moved forward, so that
|
|
the first element is effectively discarded, what was the second becomes the
|
|
first, and so on. To efficiently manage storage, two maintenance
|
|
operations need to be periodically performed -- orphaned elements at the
|
|
beginning of the array need to be reclaimed and space for new elements at
|
|
the end needs to be created. Both of these operations are handled
|
|
automatically, with frequency / effect driven by the configuration
|
|
properties <code>expansionMode</code>, <code>expansionFactor</code> and
|
|
<code>contractionCriteria.</code> See
|
|
<a href="../apidocs/org/apache/commons/math/util/ResizableDoubleArray.html">
|
|
ResizableDoubleArray</a>
|
|
for details.
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="6.3 Continued Fractions" href="continued_fractions">
|
|
<p>
|
|
The <a href="../apidocs/org/apache/commons/math/util/ContinuedFraction.html">
|
|
org.apache.commons.math.util.ContinuedFraction</a> class provides a generic
|
|
way to create and evaluate continued fractions. The easiest way to create a
|
|
continued fraction is to subclass <code>ContinuedFraction</code> and
|
|
override the <code>getA</code> and <code>getB</code> methods which return
|
|
the continued fraction terms. The precise definition of these terms is
|
|
explained in <a href="http://mathworld.wolfram.com/ContinuedFraction.html">
|
|
Continued Fraction, equation (1)</a> from MathWorld.
|
|
</p>
|
|
<p>
|
|
As an example, the constant Pi could be computed using the continued fraction
|
|
defined at <a href="http://functions.wolfram.com/Constants/Pi/10/0002/">
|
|
http://functions.wolfram.com/Constants/Pi/10/0002/</a>. The following
|
|
anonymous class provides the implementation:
|
|
<source>ContinuedFraction c = new ContinuedFraction() {
|
|
public double getA(int n, double x) {
|
|
switch(n) {
|
|
case 0: return 3.0;
|
|
default: return 6.0;
|
|
}
|
|
}
|
|
|
|
public double getB(int n, double x) {
|
|
double y = (2.0 * n) - 1.0;
|
|
return y * y;
|
|
}
|
|
}</source>
|
|
</p>
|
|
<p>
|
|
Then, to evalute Pi, simply call any of the <code>evalute</code> methods
|
|
(Note, the point of evalution in this example is meaningless since Pi is a
|
|
constant).
|
|
</p>
|
|
<p>
|
|
For a more practical use of continued fractions, consider the exponential
|
|
function with the continued fraction definition of
|
|
<a href="http://functions.wolfram.com/ElementaryFunctions/Exp/10/">
|
|
http://functions.wolfram.com/ElementaryFunctions/Exp/10/</a>. The
|
|
following anonymous class provides its implementation:
|
|
<source>ContinuedFraction c = new ContinuedFraction() {
|
|
public double getA(int n, double x) {
|
|
if (n % 2 == 0) {
|
|
switch(n) {
|
|
case 0: return 1.0;
|
|
default: return 2.0;
|
|
}
|
|
} else {
|
|
return n;
|
|
}
|
|
}
|
|
|
|
public double getB(int n, double x) {
|
|
if (n % 2 == 0) {
|
|
return -x;
|
|
} else {
|
|
return x;
|
|
}
|
|
}
|
|
}</source>
|
|
</p>
|
|
<p>
|
|
Then, to evalute <i>e</i><sup>x</sup> for any value x, simply call any of the
|
|
<code>evalute</code> methods.
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="6.4 binomial coefficients, factorials and other common math functions" href="math_utils">
|
|
<p>
|
|
A collection of reusable math functions is provided in the
|
|
<a href="../apidocs/org/apache/commons/math/util/MathUtils.html">MathUtils</a>
|
|
utility class. MathUtils currently includes methods to compute the following: <ul>
|
|
<li>
|
|
Binomial coeffiecients -- "n choose k" available as an (exact) long value,
|
|
<code>binomialCoefficient(int, int)</code> for small n, k; as a double,
|
|
<code>binomialCoefficientDouble(int, int)</code> for larger values; and in
|
|
a "super-sized" version, <code>binomialCoefficientLog(int, int)</code>
|
|
that returns the natural logarithm of the value.</li>
|
|
<li>
|
|
Factorials -- like binomial coefficients, these are available as exact long
|
|
values, <code>factorial(int)</code>; doubles,
|
|
<code>factorialDouble(int)</code>; or logs, <code>factorialLog(int)</code>. </li>
|
|
<li>
|
|
Hyperbolic sine and cosine functions --
|
|
<code>cosh(double), sinh(double)</code></li>
|
|
<li>
|
|
sign (+1 if argument > 0, 0 if x = 0, and -1 if x < 0) and
|
|
indicator (+1.0 if argument >= 0 and -1.0 if argument < 0) functions
|
|
for variables of all primitive numeric types.</li>
|
|
<li>
|
|
a hash function, <code>hash(double),</code> returning a long-valued
|
|
hash code for a double value.
|
|
</li>
|
|
<li>
|
|
Convience methods to round floating-point number to arbitrary precision.
|
|
</li>
|
|
<li>
|
|
Least common multiple and greatest common denominator functions.
|
|
</li>
|
|
</ul>
|
|
</p>
|
|
</subsection>
|
|
|
|
</section>
|
|
|
|
</body>
|
|
</document> |