src/site/xdoc/userguide/utilities.xml - commons-math - Git at Google

 <?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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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 &pi; 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 &pi;, simply call any of the <code>evalute</code> methods
     (Note, the point of evaluation in this example is meaningless since &pi; 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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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>
	<?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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/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>