The MultiArray API provides an abstraction for multidimensional array access and some concrete implementations. By use of the MultiArrayProxy and IndexMaps, it also provides techniques by which a MultiArray can be viewed as if it had different structure.

This discussion is made somewhat confusing by imprecise usage in our field. When we say "array", or "vector", it isn't clear whether we are talking about constructs in a given programming language or mathematical abstractions. In the following discussion, we will use the unadorned term "array" to mean the Java language construct, The term "multidimensional array" for a mathematical abstraction which is modeled by the MultiArray class in this package.

A multidimensional array is a collection of elements which 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.

The Java language, like C and C++, provides an array primitive which is actually a vector. Also like C and C++, this primitive is used in the language to build up multidimensional arrays as vectors of vectors. Numerical programs in C and C++ rarely use the higher dimensional array construct for several reasons. (TODO: more detail on why?) One purpose of this API is to codify that practice into a clear object framework.

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 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 IndexMapping 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 IndexMapping primitives which are used with MultiArrayProxy to slice, clip, subsample, transpose, or flatten a MultArray. These may be functionally composed to form complex operations by using nested construction.
• AbstractAccessor abstract class - A partial implementation of the Accessor Interface which handles primitive type conversions.

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 IndexMappings 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.