Commons Math User Guide

##### User Guide

- Contents
- Overview
- Statistics
- Data Generation
- Linear Algebra
- Numerical Analysis
- Special Functions
- Utilities
- Complex Numbers
- Distributions
- Fractions
- Transform Methods
- 3D Geometry
- Optimization
- Ordinary Differential Equations
- Genetic Algorithms

## 6 Utilities

### 6.1 Overview

The org.apache.commons.math.util package collects a group of array utilities, value transformers, and numerical routines used by implementation classes in commons-math.

### 6.2 Double array utilities

To maintain statistics based on a "rolling" window of values, a resizable array implementation was developed and is provided for reuse in the `util` package. The core functionality provided is described in the documentation for the interface, DoubleArray. This interface adds one method, `addElementRolling(double)` to basic list accessors. The `addElementRolling` method adds an element (the actual parameter) to the end of the list and removes the first element in the list.

The ResizableDoubleArray class provides a configurable, array-backed implementation of the `DoubleArray` interface. When `addElementRolling` 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 `expansionMode`, `expansionFactor` and `contractionCriteria.` See ResizableDoubleArray for details.

### 6.3 int/double hash map

The OpenIntToDoubleHashMap class provides a specialized hash map implementation for int/double. This implementation has a much smaller memory overhead than standard `java.util.HashMap` class. It uses open addressing and primitive arrays, which greatly reduces the number of intermediate objects and improve data locality.

### 6.4 Continued Fractions

The ContinuedFraction class provides a generic way to create and evaluate continued fractions. The easiest way to create a continued fraction is to subclass `ContinuedFraction` and override the `getA` and `getB` methods which return the continued fraction terms. The precise definition of these terms is explained in Continued Fraction, equation (1) from MathWorld.

As an example, the constant Pi can be computed using a continued fraction. The following anonymous class provides the implementation:

    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;
        }
    }

Then, to evalute Pi, simply call any of the `evalute` methods (Note, the point of evalution in this example is meaningless since Pi is a constant).

For a more practical use of continued fractions, consider the exponential function. The following anonymous class provides its implementation:

    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;
            }
        }
    }

Then, to evalute ex for any value x, simply call any of the `evalute` methods.

### 6.5 binomial coefficients, factorials and other common math functions

A collection of reusable math functions is provided in the MathUtils utility class. MathUtils currently includes methods to compute the following:

- Binomial coefficients -- "n choose k" available as an (exact) long value, `binomialCoefficient(int, int)` for small n, k; as a double, `binomialCoefficientDouble(int, int)` for larger values; and in a "super-sized" version, `binomialCoefficientLog(int, int)` that returns the natural logarithm of the value.
- Factorials -- like binomial coefficients, these are available as exact long values, `factorial(int)`; doubles, `factorialDouble(int)`; or logs, `factorialLog(int)`.
- Hyperbolic sine and cosine functions -- `cosh(double), sinh(double)`
- 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.
- a hash function, `hash(double),` returning a long-valued hash code for a double value.
- Convience methods to round floating-point number to arbitrary precision.
- Least common multiple and greatest common denominator functions.

### 6.7 Miscellaneous

The MultidimensionalCounter 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.