In the following, we use the unadorned term "array" to mean the Java language construct, and the term "multidimensional array" for the mathematical abstraction modeled by the MultiArray class in this package.

A multidimensional array is a collection of elements that are accessed by index. The elements may be objects or primitives. The index is a one dimensional array of integers. The number of dimensions of a multidimensional array is called its rank. Each of the dimensions has a length, which determines the possible values of the corresponding index element. A multidimensional array of rank 1 is often referred to as a vector. A multidimensional array of rank 0 is referred to as a scalar.

Like C and C++, the Java programming language provides an array primitive which is actually a (fixed length) vector. Also like C and C++, this primitive is used in the language to build up multidimensional arrays as vectors of vectors. For example, a two dimensional M by N array would be constructed as a vector of M references to M vectors each of length N. This strategy wastes some storage, and the waste increases for higher dimensioned arrays. In random access patterns, the added level of indirection for each dimension incurs a performance penalty as well. Numerical programs in C or C++ often avoid direct use of the language construct for multidimensional arrays. The availability of pointers and pointer arithmetic can be used to trade off against the costs, but these features are not available in Java. This suggests a need for Java library classes that abstract the notion of multidimensional array and implement commonly used array operations. These are included in this package.

The MultiArray API consists of:

• MultiArrayInfo Interface - A reflection or introspection interface for multidimensional arrays. Methods to discover the rank, shape and component type.
• Accessor Interface - Methods to set and get single values of a multidimensional array. Also methods for aggregate copy in and out of the array.
• MultiArray Interface - The union of MultiArrayInfo and Accessor interfaces. This is the interface that client code should use. The artificial factorization into MultiArrayInfo and Accessor interfaces is only needed for the convenience of some implementations, notably ucar.netcdf.Variable.
• MultiArray Implementations- Wrappers for Java arrays (ArrayMultiArray) and scalar objects (ScalarMultiArray), as well as a space efficient implementation (MultiArrayImpl).
• IndexIterator utility class - Used to step through the possible index values.
• MultiArrayProxy / IndexMap Interface Framework - MultiArrayProxy uses an IndexMap to provide a different view of some MultiArray. The new view typically has a different structure than the backing MultiArray. For example, we may wish to reduce the rank by one, fixing the index for a given dimension at a specific value.
• Concrete IndexMap classes - Concrete IndexMap primitives that are used with MultiArrayProxy to slice, clip, subsample, flip, transpose, or flatten a MultiArray. These may be functionally composed to form complex operations by using nested construction.
• AbstractAccessor abstract class - A partial implementation of the Accessor Interface that handles primitive type conversions.
• StringCharAdapter class - An adapter for MultiArray of char component type that presents a MultiArray of String interface.

The MultiArray methods to get() and set() values operate on single values. To grab a slice, clipped region or some other aggregate out of a MultiArray, use MultiArrayProxy and the appropriate concrete IndexMaps to create that view of the MultiArray. The concrete MultiArrayImpl provides a copy constructor for which the view can be used as initializer. The copyin() and copyout() methods of MultiArray may also be used for simple clippings.

There is an example program, DemoMultiArrays.java, which shows some ways to use the interface.