JSR 83: Multiarray package

Java Multiarray package

Summary:

This JSR proposes a package implementing true rectangular multidimensional arrays for Java.

Section 1. Identification

Submitting Member: International Business Machines Corporation

Name of Contact Person: Jose E. Moreira

E-Mail Address: jmoreira@us.ibm.com

Telephone Number: 1-914-945-3987

Fax Number: 1-914-945-4425

Specification Lead: Jose E. Moreira, IBM Corporation

E-Mail Address: jmoreira@us.ibm.com

Telephone Number: 1-914-945-3987

Fax Number: 1-914-945-4425

Initial Expert Group Membership:

• International Business Machines Corporation
• Sun Microsystems, Inc

Additional endorsers of this JSR include individuals from:

• University of North Carolina
• National Institute of Standards and Technology
• NAG
• The Mathworks, Inc.
• University of Tennessee
• UCAR

Section 2: Request

2.1 Please describe the proposed Specification:

Elements of a multiarray 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 a multiarray 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 multiarray A follows an element A[j₀,j₁,...,j_d-1] of the same multiarray 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 multiarray 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 multiarray A follows an element A[j₀,j₁,...,j_d-1] of the same multiarray 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 and mapping to conventional Java arrays below.)

We propose the development of standard Java classes which implement multiarrays. The rank and type of a multiarray are defined by its class. That is, for each rank and type there is a different concrete class. 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 a Complex class that implements double precision complex numbers), 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 typeMultiarraydD. As an example, the class for a two-dimensional multiarray of doubles would be named doubleMultiarray2D. Multiarray classes are final classes.

All concrete classes of the same type (e.g., doubleMultiarray1D, doubleMultiarray2D, ..., doubleMultiarray7D) are derived from an abstract class with the same type (e.g., doubleMultiarray). All type-specific abstract classes (e.g., floatMultiarray, ComplexMultiarray, charMultiarray) are derived from the abstract class Multiarray. This class hierarchy supports type- and rank-generic programming (through the abstract classes), as well as type- and rank-specific programming (as would normally be done in C and Fortran). We expect that programming with the concrete final classes will be important for performance. Programs that use the type- and rank-specific concrete final classes can be optimized using mature compiler techniques developed for Fortran, C, and C++. The optimization of type- and rank-generic programs is still a research topic.

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

A d_B-dimensional multiarray section B of a d_A-dimensional master multiarray A is defined by specifying, for each axis k of A, either (i) a specific element index along that axis or (ii) a range of element indices. A range of indices consists of an arithmetic progression of indices, defined by its first element, the incremental step, and the number of elements. The single index or the range of indices serve as a selector of the elements of A that are present in section B. The number of axes of A for which a single index is specified is equal to the rank difference between A and B, d_A - d_B. The shape of B is defined by the length (number of elements) in the range selectors.

In addition to regular multiarray sections, the Multiarray package must provide some support for irregular multiarray sections. In specifying an irregular multiarray section, the selector for an axis of a master multiarray A can be an arbitrary list of indices, as opposed to just an arithmetic progression. Irregular multiarray sections are never instantiated as objects, and there is no explicit representation for them. The concept is only present during certain operations on multiarrays.

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

• Get and set the values of a multiarray element or regular multiarray section.
• Get and set the values of the elements in an irregular multiarray section.
• Operations to query the rank and shape of a multiarray.
• Operations to reshape and transpose a multiarray.
• Elemental conversion functions (e.g., the equivalent of Fortran REAL and AIMAG, that convert complex arrays into double arrays).
• Elemental transcendental functions (e.g., sin and cos applied to each element of a multiarray).
• Elemental relational functions (<, >, <=, >=, ==, !=), applied to corresponding elements of conforming (i.e., same shape) multiarrays.
• Fortran-like array reduction functions (sum, minval, etc.).
• Fortran-like array construction functions (merge, pack, spread, unpack).
• Fortran-like array manipulation functions (shift, spread).
• Fortran-like array location functions (maxloc, minloc).
• Operations that correspond to Fortran-like array expressions (addition, multiplication, etc.)

Quite often, Java code using the Array package will have to interface with native code. Although native code can use the JNI procedure for accessing elements of a multiarray through the set and get accessor methods, we envision that most invocations will be to methods that expect a Java single-dimensional array as a parameter. For example, if a Java programmer wants to invoke a native method native static void foo(double[]), passing as parameter a doubleMultiarray2D, it is first necessary to extract the elements into a Java single-dimensional array (using an unravel operation), then invoke method foo, and then propagate the effect back to the original doubleMultiarray2D (using a ravel operation):

        doubleMultiarray2D A = new doubleMuliarray2D(m,n);
        ...
        double[] B = A.unravel();
        foo(B);
        A.ravel(B);
        

Access to individual elements of multiarrays 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));
        }
    }
}