The linear algebra object creation routines create the object that stores the information required to describe the object. This includes parameters like the data type, the template with which the object is aligned, the alignment itself, as well as the global dimensions of the object. We will describe the calls required to create the different linear objects next.
The data type of an object can equal any MPI data type, but will typically equal one of MPI_INT, MPI_FLOAT, MPI_DOUBLE, MPI_COMPLEX and MPI_DOUBLE_COMPLEX. Notice that neither MPI_COMPLEX nor MPI_DOUBLE_COMPLEX are standard MPI data types for the C programming language. However, they are frequently used in linear algebra packages. On architectures where MPI does not define these, the PLAPACK infrastructure itself does upon initialization of the environment, to reflect the FORTRAN language conventions for storing complex and double precision complex numbers.
To create a vector, we indicate the data type, the global length, the template to be used, and the alignment of the vector to the template (see Figure 2.1). Often, it will be convenient to work with a group of vectors simultaneously, which we call a multivector. All vectors in a multivector are of equal length and are identically aligned. Thus, one can think of a multivector as a matrix with a few columns, where all columns are identically distributed, like vectors. A multivector object is created by indicating the data type, global length (length of each vector in the multivector), global width (number of vectors comprising the multivector), template, and the alignment to the template. This alignment holds for all vectors in the multivector, as illustrated in Figure 2.1.
PLA_ALIGN_FIRST can be used to indicate the first element in the template.
Matrices require a data type, global length, global width, template, and both a row and column alignment. The call becomes
We have the notion of a multiscalar, which is a linear algebra object that exists as a unit entirely within one node (i.e., it is NOT distributed). This multiscalar may or may not be duplicated within one row, one columns, or all nodes, as indicated in the creating call. In general, the multiscalar is an non-distributed matrix, with row and column dimension.
As part of a parallel implementation of an algorithm, we may need a row vector or column vector to exist within one or all row(s) or column(s) of nodes. To create such an object, one uses the rojected vector create routine. Together with the calling sequence for creating a projected vector, we also give the calling sequence for creating a projected multivector, which is the natural extension of the concept to multivectors:
When creating a projected (multi)vector, global_proj_length and global_proj_width warrant special attention. Notice that a projected (multi)vector is much like a matrix of similar length and width. However, depending on whether the (multi)vector is projected against a column or row, the roles of the global length and width of the multivector may be reversed. To avoid confusion, we dictate that the global length and width given for a projected multivector reflect the global length and width of the multivector after projection.
Note: All nodes that should be aware of the existence of an object need to make identical calls to the creation routine. Thus, it is possible that the call is made by one node, by one column of nodes, by one row of nodes, or by all nodes. It is not necessarily the case that only a node that owns actually data that is encoded in the object must make the call. For example, if one wishes to copy a sub-matrix from a global matrix to a multiscalar owned by one node, all nodes must be aware of the existence of the multiscalar, and thus all nodes must have created the multiscalar. Enforcing consistency is the responsibility of the calling routine, not the creation routine.