Elements of an array are identified by their indices along each axis. Let a d-dimensional array A of elemental type T have extent n_j along its j-th axis, j = 0,...,d-1. Then, a valid index i_j along the j-th axis must be greater than or equal to zero and less than n_j. An attempt to reference an element A[i₀,i₁,...,i_d-1] with any invalid index i_j causes an ArrayIndexOutOfBoundsException to be thrown.

Elements of an array are logically ordered with respect to each other according to the following definition. An element A[i₀,i₁,...,i_d-1] of a d-dimensional array A follows an element A[j₀,j₁,...,j_d-1] of the same array if and only if there exists a k greater than or equal to zero and less than d such that i_l=j_l for all l<k and i_k>j_k. In usual nomenclature, this corresponds to row-major (C-style) ordering of the elements. We call this the intrinsic ordering of the array elements. (In a column-major, i.e., Fortran-style, ordering of the elements, an element A[i₀,i₁,...,i_d-1] of a d-dimensional array A follows an element A[j₀,j₁,...,j_d-1] of the same array if and only if there exists a k greater than or equal to zero and less than d such that i_l=j_l for all l>k and i_k>j_k. This concept will be useful when we discuss native interfaces below.)

We propose the development of standard Java classes which implement multidimensional rectangular arrays. The rank and type of an array are defined by its class. That is, for each rank and type there is a different class. (This is necessary for traditional compiler optimizations, since Java does not support templates.) Supported types must include all of Java primitive types (boolean, byte, char, short, int, long, float, and double), one or more complex types (at least the Complex class in the VNI JSR - Add Complex Class to Java), and Object. Supported ranks must include 0- (scalar), 1-, 2-, 3-, 4-, 5-, 6- and 7-dimensional arrays. (Rank 7 is the current standard limit for Fortran.) The class for a d-dimensional array of type would be typeArraydD. As an example, the class for a two-dimensional array of doubles would be named doubleArray2D. Array classes are final classes.

The array classes must fully support the concept of regular array sections. A regular array section corresponds to a subarray of another array, which we call the master array. Each element of an array section corresponds to exactly one element of its master array. The correspondence is one-to-one in the section to master direction. Referencing one element of an array section (for reading or writing) has the effect of referencing the corresponding element of the master array. Regular array sections have the same type as, and rank less than or equal to, their master arrays. Regular array sections behave exactly like regular arrays for all operations, including sectioning. (In fact, there are no separate classes for array sections.)

The array classes provide methods that implement Fortran-like functionality for arrays. In particular, the following operations must be provided:

• Get and set the values of an array element, array regular section, or array irregular section.
• Operations to query the rank and shape of an array.
• Operations to reshape and transpose an array.
• Elemental conversion functions (e.g., the equivalent of Fortran REAL and AIMAG, that convert complex arrays into double arrays).
• Elemental transcendental functions.
• Elemental relational functions (<, >, <=, >=, ==, !=).
• Array reduction functions (sum, minval, etc.).
• Array construction functions (merge, pack, spread, unpack).
• Array manipulation functions (shift, spread).
• Array location functions (maxloc, minloc).
• Array scatter and gather operations.
• Operations that correspond to array expressions (addition, multiplication, etc.)

Quite often, Java code using the Array package will have to interface with native code. The native code can access the elements of a multidimensional array using the following mechanism, explained through an example. Let there be a native static void foo(doubleArray2D). The C code for foo needs to do the following:

    foo(JNIEnv *env, jobject arr)
    {

        /*
         * Find the number of elements in the array.
         */
        jsize len = GetMDArrayLength(env, arr);
        ...

        /*
         * Obtain a pointer to the elements of the array.
	 * The elements are in an order defined by parameter ORDER.
         */
        jdouble *data = GetDoubleMDArrayElements(env, arr, ORDER);

	/*
         * Operate on data as desired.
         */
        ...

        /*
         * Release the array elements when done.
         */
        ReleaseDoubleMDArrayElements(env, arr, data);
        return;
    }
    

Note that the elements extracted by GetDoubleMDArrayElements are ordered according to some enumeration order identified by the last parameter. We propose at least two supported orderings: ROW_MAJOR returns the elements in row major order, while COL_MAJOR returns the elements in column major order. Note that ROW_MAJOR orders the element according to the intrinsic ordering previously specified. COL_MAJOR returns the elements in the same order that a Fortran array would be organized. It is convenient for the development of Java/Fortran interfaces.

The actions performed by GetDoubleMDArrayElements and ReleaseDoubleMDArrayElements are implementation dependent. In some cases it may be possible to just return a pointer to the (pinned) storage of the array elements, if that storage is already in the appropriate order. In other situations it may be necessary to copy the elements to a temporary storage. If the array arr passed as a parameter is a section of another array, then copy is in general the only alternative.

The array classes can be implemented with no changes in Java or JVM. However, it is essential that the get and set methods be implemented as efficiently as array indexing operations are in Fortran or in C. Multidimensional arrays are extremely common in numerical computing, and hence we expect that efficient multidimensional arrays classes will be heavily used.

Access to individual elements of multidimensional arrays is performed only through get and set accessor methods. As an example, consider the following simple implementation of a matrix multiply code, where each matrix is represented by a doubleArray2D class:

void matmul(doubleArray2D a, doubleArray2D b, doubleArray2D c) {

    /*
     * For simplicity, let us consider only the simple case
     * in which the matrices are conforming, that is,
     * a is m x n, b is n x p, and c is m x p.
     */
    int m = a.size(0);
    int n = a.size(1);
    int p = b.size(1);

    for (int i=0; i<m; i++) {
        for (int j=0; j<p; j++) {
            c.set(i,j,0);
            for (int k=0; k<n; k++) 
                c.set(i,j,c.get(i,j)+a.get(i,k)*b.get(k,j));
        }
    }
}
	

The basic syntax proposed uses A[i,j,k] rather than A[i][j][k] to reference elements of multidimensional arrays. This differentiates multidimensional arrays from Java arrays of arrays. References of this form are syntactically mapped to the appropriate get or set method, depending on how they are used. We illustrate these ideas with simple examples showing the respective mappings:

double[*] X = new intArray1D(M);
    --> intArray1D X = new intArray1D(M};

X[i] = Y[i];
    --> X.set(i,Y.get(i));

double[*,*,*] A = new doubleArray3D(M,N,K);
    -->  doubleArray3D A = new doubleArray3D(M,N,K);

A[i,j,k] = B[i,j,k]+s*C[j,k,l];
    --> A.set(i,j,k,B.get(i,j,k)+s*C.get(j,k,l));
	

A good implementation of the Array package will deliver high performance in the execution of aggregate methods. That is, methods that operate on many elements, such as adding two array sections or multiplying two matrices. The techniques for performing efficient aggregate operations on matrices, in particular for linear algebra operations, are well described in the literature.

To deliver good performance on user codes that use elementary operations on array elements, two compiler technologies are of utmost importance:

1. Bounds checking optimization through versioning: This technique creates safe regions of code where all array accesses are guaranteed to be valid. Aggressive optimizations, that reorder code, can be applied in these regions.
2. Semantic expansion: With the array package, each elemental data access (set or get) operation is a method call. The method verifies that all the indices are valid (along each of the array axes) before proceeding to the actual data access. Exposing the semantics of these methods to the compiler is a necessary step for optimization. This is accomplished through the technique of semantic expansion.

The extended array syntax could be accomplished in several ways

1. The official Java language could be extended outright to support this notation. This extension is similar in concept to the "+" notation supported for Strings.
2. A specific pre-processor could be built that translates multidimensional array expressions into their equivalent semantics using the conventional method syntax for the Array package.
3. The Java language could be extended to support a limited form of operator overloading for [i,j,k] and [,,].

There is a relationship between the specification of the Array package and of the Complex class (as being submitted by VNI). Complex arrays in the Array package must support the same elemental type as defined by the Complex class.

The recent proposal to extend generic types to Java could provide a more general solution for building multidimensional arrays of user-defined types.