| <?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. |
| --> |
| |
| <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/math4/util/package-summary.html"> |
| org.apache.commons.math4.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/math4/util/DoubleArray.html"> |
| 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/math4/util/ResizableDoubleArray.html"> |
| 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/math4/util/ResizableDoubleArray.html"> |
| ResizableDoubleArray</a> |
| for details. |
| </p> |
| </subsection> |
| |
| <subsection name="6.3 int/double hash map" href="int_double_hash_map"> |
| <p> |
| The <a href="../apidocs/org/apache/commons/math4/util/OpenIntToDoubleHashMap.html"> |
| OpenIntToDoubleHashMap</a> class provides a specialized hash map |
| implementation for int/double. This implementation has a much smaller memory |
| overhead than standard <code>java.util.HashMap</code> class. It uses open addressing |
| and primitive arrays, which greatly reduces the number of intermediate objects and |
| improve data locality. |
| </p> |
| </subsection> |
| |
| <subsection name="6.4 Continued Fractions" href="continued_fractions"> |
| <p> |
| The <a href="../apidocs/org/apache/commons/math4/util/ContinuedFraction.html"> |
| 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 π can be computed using a <a href="http://functions.wolfram.com/Constants/Pi/10/0002/">continued fraction</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 π, simply call any of the <code>evalute</code> methods |
| (Note, the point of evaluation in this example is meaningless since π is a |
| constant). |
| </p> |
| <p> |
| For a more practical use of continued fractions, consider the <a href="http://functions.wolfram.com/ElementaryFunctions/Exp/10/">exponential function</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.5 Binomial coefficients, factorials, Stirling numbers and other common math functions" href="binomial_coefficients_factorials_and_other_common_math_functions"> |
| <p> |
| A collection of reusable math functions is provided in the |
| <a href="../apidocs/org/apache/commons/math4/util/ArithmeticUtils.html">ArithmeticUtils</a> |
| utility class. ArithmeticUtils currently includes methods to compute the following: <ul> |
| <li> |
| Binomial coefficients -- "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> |
| Stirling numbers of the second kind -- S(n,k) as an exact long value |
| <code>stirlingS2(int, int)</code> for small n, k.</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> |
| Least common multiple and greatest common denominator functions. |
| </li> |
| </ul> |
| </p> |
| </subsection> |
| |
| <subsection name="6.6 Fast mathematical functions" href="fast_math"> |
| <p> |
| Apache Commons Math provides a faster, more accurate, portable alternative |
| to the regular <code>Math</code> and <code>StrictMath</code>classes for large |
| scale computation. |
| </p> |
| <p> |
| FastMath is a drop-in replacement for both Math and StrictMath. This |
| means that for any method in Math (say <code>Math.sin(x)</code> or |
| <code>Math.cbrt(y)</code>), user can directly change the class and use the |
| methods as is (using <code>FastMath.sin(x)</code> or <code>FastMath.cbrt(y)</code> |
| in the previous example). |
| </p> |
| <p> |
| FastMath speed is achieved by relying heavily on optimizing compilers to |
| native code present in many JVM todays and use of large tables. Precomputed |
| literal arrays are provided in this class to speed up load time. These |
| precomputed tables are used in the default configuration, to improve speed |
| even at first use of the class. If users prefer to compute the tables |
| automatically at load time, they can change a compile-time constant. This will |
| increase class load time at first use, but this overhead will occur only once |
| per run, regardless of the number of subsequent calls to computation methods. |
| Note that FastMath is extensively used inside Apache Commons Math, so by |
| calling some algorithms, the one-shot overhead when the constant is set to |
| false will occur regardless of the end-user calling FastMath methods directly |
| or not. Performance figures for a specific JVM and hardware can be evaluated by |
| running the FastMathTestPerformance tests in the test directory of the source |
| distribution. |
| </p> |
| <p> |
| FastMath accuracy should be mostly independent of the JVM as it relies only |
| on IEEE-754 basic operations and on embedded tables. Almost all operations |
| are accurate to about 0.5 ulp throughout the domain range. This statement, of |
| course is only a rough global observed behavior, it is <em>not</em> a guarantee |
| for <em>every</em> double numbers input (see William Kahan's <a |
| href="http://en.wikipedia.org/wiki/Rounding#The_table-maker.27s_dilemma">Table |
| Maker's Dilemma</a>). |
| </p> |
| <p> |
| FastMath additionally implements the following methods not found in Math/StrictMath: |
| <ul> |
| <li>asinh(double)</li> |
| <li>acosh(double)</li> |
| <li>atanh(double)</li> |
| <li>pow(double,int)</li> |
| </ul> |
| The following methods are found in Math/StrictMath since 1.6 only, they are |
| provided by FastMath even in 1.5 Java virtual machines |
| <ul> |
| <li>copySign(double, double)</li> |
| <li>getExponent(double)</li> |
| <li>nextAfter(double,double)</li> |
| <li>nextUp(double)</li> |
| <li>scalb(double, int)</li> |
| <li>copySign(float, float)</li> |
| <li>getExponent(float)</li> |
| <li>nextAfter(float,double)</li> |
| <li>nextUp(float)</li> |
| <li>scalb(float, int)</li> |
| </ul> |
| </p> |
| </subsection> |
| |
| <subsection name="6.7 Miscellaneous" href="miscellaneous"> |
| The <a href="../apidocs/org/apache/commons/math4/util/MultidimensionalCounter.html"> |
| MultidimensionalCounter</a> is a utility class that converts a set of indices |
| (identifying points in a multidimensional space) to a single index (e.g. identifying |
| a location in a one-dimensional array. |
| </subsection> |
| |
| </section> |
| |
| </body> |
| </document> |