next up previous contents
Next: 2.3.4 Extracting and setting Up: 2.3 Linear Algebra Objects Previous: 2.3.2 Linear algebra object

2.3.3 Linear algebra object inquiry routines

    As for the template object, we do not permit the data structure that encodes the linear algebra object to be accessed directly. Instead, we provide inquiry routines, which can be used to query information about the linear algebra object. The general rule is that all linear algebra object inquiry routines start with PLA_Obj_ followed by the name of the field required.

General information:

    This category of inquiry routines provides information that is often useful when dealing with a given object at the global level (without specifically addressing local information) as well as when operations specific to the local portion of an object are to be performed.   It includes calls to inquire the object type, the data type, and the template used to create the object.





Valid return values for PLA_Obj_objtype include:


The return value equals PLA_UNDEFINED if the object type is not recognized.

  The object data type is extracted by calling





Any MPI data type is permitted, but typically the data type will be one of


The template used to create the object is extracted by calling




Global information:

    Ideally, code written using PLAPACK deals only with global information about the object, including the global dimensions, the alignment of the object to the template, the dimension of the processing mesh onto which a (multi)vector is projected, and/or the row or column of the node mesh that owns a projected (multi)vector. The following call returns these values for a given object:




The values returned in global_length and global_width reflect those that would have been used to create the object. Thus, for a matrix and multiscalar they reflect the row and column dimension of the object. For (unprojected) vectors and vectors projected onto a column, global_length equals the length of the vector and global_width always equals unity. A vector projected onto a row has length global_width and width global_length gif . For (unprojected) multivectors and multivectors onto a column, global_length equals the length of the vectors and global_width equals the number of vectors (columns) in the multivector. A multivector projected onto a row has width global_length and length global_width since these parameters reflect the length and width after projection.

For projected (multi)vectors, parameter project_onto returns one of values PLA_PROJ_ONTO_ROW or PLA_PROJ_ONTO_COL. Parameters owner_row and owner_col return the index of the row or column of nodes that owns the projected (multi)vector or multiscalar. If the projected (multi)vector or multiscalar is duplicated these may equal PLA_ALL_ROWS and/or PLA_ALL_COLS. Notice that for some of the objects some of the parameters have no meaning, in which case the value PLA_UNDEFINED is returned. The alignment parameters indicate alignment with respect to the template.

As for the template inquiry routines, we also provide calls for extracting specific parameters:


Here we have added the call PLA_Obj_global_size to return the length of a (duplicated) (projected) (multivector) when viewed as a vector, to overcome the already mentioned confusion of what the length of such an object is. Also, the call PLA_Obj_global_numvecs can be used to extract the number of vectors in a (duplicated) (projected) multivector.

Local information:

    Some routines need to gain access to information concerning the part of a linear algebra object assigned to a node. For this, we provide calls that return this information for the part of the object assigned to the node that makes the call.

Before discussing the local information calls, we must discuss how PLAPACK locally stores the data associated with the different linear algebra objects. Let us consider a vector x distributed to a tex2html_wrap_inline13055 mesh of nodes. For simplicity, we will assume that the vector is aligned to the first entry of the template vector, which is partitioned using a distribution blocking size tex2html_wrap_inline13057 . Thus


where tex2html_wrap_inline13059 is of length tex2html_wrap_inline13061 (except perhaps the last sub-vector). Node (i,j) will own the sub-vectors


This vector is locally stored in memory so that the order of the elements is preserved (i.e., elements of tex2html_wrap_inline13065 will precede those of tex2html_wrap_inline13067 ). The   stride in memory between elements will be internally determined, and can be inquired by one of the subsequently described calls.

Next, let us consider a matrix A distributed to the same mesh. For simplicity, we assume that A is aligned with the upper-left element of the template matrix induced by the above mentioned template vector. Then,


and the following sub-matrix is assigned to node (i,j) :


It is this matrix tex2html_wrap_inline13075 that is stored in a local two-dimensional array, using FORTRAN style   column-major order storage, with a   leading dimension determined internal to PLAPACK.

Finally, let us discuss the storage of a projected multivector. Notice that if the vector x discussed above is spread within a column of nodes, or gathered to the i th node in each column, the following sub-vectors will be collected on node (i,j) :


Notice that the sub-vectors from within a column of nodes are interleaved so that the indices of sub-vectors are strictly increasing (the order in the global vector is maintained). It is this vector that is then stored in a local linear array, with a stride determined internal to PLAPACK.

The primary call to extract the local information is given by




The address of where the data is stored is returned in local_buffer. Depending on the object type of the object, the different parameters have different meaning:
Notice that it is entirely possible that the part of a linear algebra object that a given node owns is empty. In this case, local_length and/or local_width will equal zero, and the local_buffer pointer may not have a meaningful value. In particular, local_buffer may equal NULL in this situation.

As for the template and object global inquiry routines, we also provide calls for extracting specific parameters:


next up previous contents
Next: 2.3.4 Extracting and setting Up: 2.3 Linear Algebra Objects Previous: 2.3.2 Linear algebra object