xdocs/userguide/utilities.xml - commons-math - Git at Google

 <?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 &gt; 0, 0 if x = 0, and -1 if x &lt; 0) and
     indicator (+1.0 if argument  &gt;= 0 and -1.0 if argument &lt; 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>
	<?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>