Parallel Engineering and Scientific Subroutine Library for AIX Version 2 Release 3: Guide and Reference

PSPINS--Inserts Local Data into a General Sparse Matrix

This sparse utility subroutine is used by each process to insert all blocks of data it owns into its local part of the general sparse matrix A.

Syntax

Fortran

CALL PSPINS (a, ia, ja, blck, desc_a)

On Entry

a

is the local part of the global general sparse matrix A that is produced on a preceding call to PSPALL or previous call(s) to this subroutine.

Scope: local

Type: required

Specified as: the derived data type D_SPMAT.

ia

is the first global row index of the general sparse matrix A that receives data from the submatrix BLCK.

Scope: local

Type: required

Specified as: a fullword integer; 1 <= ia <= DESC_A%MATRIX_DATA(M).

ja

is the first global column index of the general sparse matrix A that receives data from the submatrix BLCK.

Scope: local

Type: required

Specified as: a fullword integer, where: ja = 1.

blck

is the local part of the submatrix BLCK to be inserted into the global general sparse matrix A. Each call to this subroutine inserts one contiguous block of rows into the local part of the sparse matrix corresponding to the global submatrix A_{ia:ia+BLCK%M-1,
ja:ja+BLCK%N-1}. This subroutine only can insert blocks of data it owns into its local part of the general sparse matrix A. BLCK contains the following components:

BLCK%M is the number of local rows in the submatrix BLCK. Scope: local.
Specified as: a fullword integer; 1 <= BLCK%M <= DESC_A%MATRIX_DATA(N_ROW).
BLCK%N is an upper bound on the number of local columns in the submatrix BLCK. Scope: local.
Specified as: a fullword integer; 1 <= BLCK%N <= n, where n is the order of the global general sparse matrix A.
BLCK%FIDA is the storage mode for the submatrix BLCK, where:
If BLCK%FIDA='CSR', the submatrix BLCK is stored in the storage-by-rows storage mode. Scope: global.
Specified as: a character variable of length 5; BLCK%FIDA='CSR'.

If BLCK%FIDA='CSR', then you must specify the BLCK%AS, BLCK%IA1, and BLCK%IA2 components, as follows:

BLCK%AS is a pointer to the submatrix BLCK that is stored by rows. See "Notes". Scope: local.
Specified as: a pointer to an assumed-shape array with shape (:), containing long-precision real numbers.
BLCK%IA1 is a pointer to the column numbers of each non-zero element in the submatrix BLCK. See "Notes". Scope: local.
Specified as: a pointer to an assumed-shape array with shape (:), containing fullword integers; 1 <= BLCK%IA1(i) <= BLCK%N, where:
i = 1, nz and nz is the actual number of non-zero elements in the submatrix BLCK.
BLCK%IA2 is a pointer to the starting positions of each row of the submatrix BLCK in BLCK%AS and one position past the end of BLCK%AS. See "Notes". Scope: local.
Specified as: a pointer to an assumed-shape array with shape (:), containing fullword integers, where:

BLCK%IA2(1) = 1
BLCK%IA2(BLCK%M+1) = 1+nz and nz is the actual number of non-zero elements in the submatrix BLCK.

Specified as: the derived data type D_SPMAT.

desc_a

is the descriptor vector for a global general sparse matrix A that is produced on a preceding call to PADALL or previous call(s) to this subroutine.

Type: required

Specified as: the derived data type DESC_TYPE.

On Return

a

is the updated local part of the global general sparse matrix A, updated with data from the submatrix BLCK.

Scope: local

Type: required

Returned as: the derived data type D_SPMAT.

desc_a

is the updated array descriptor for the global general sparse matrix A.

Type: required

Returned as: the derived data type DESC_TYPE.

Notes and Coding Rules

Before you call this subroutine, you must have called PADALL and PSPALL.
This subroutine accepts mixed case letters for the BLCK%FIDA component.
Arguments BLCK and A must not have common elements; otherwise, results are unpredictable.
For details about some of the elements stored in DESC_A%MATRIX_DATA, see Derived Data Type DESC_TYPE.
The submatrix BLCK must be stored by rows; that is BLCK%FIDA = 'CSR'. For information about the storage-by-rows storage mode, see the ESSL Version 3 Guide and Reference.
Once you declare BLCK of derived data type D_SPMAT, you must allocate the components of BLCK that point to an array. The following example shows how to code the allocate statement if each row of the submatrix BLCK contains no more than 20 elements:
```
TYPE(D_SPMAT)  ::   BLCK                       !Declare the BLCK variable
        .
        .
        .
ALLOCATE(BLCK%AS(20),BLCK%IA1(20),BLCK%IA2(2)) !Allocate array pointers
```
When you are finished calling PSPINS, you should deallocate BLCK%AS, BLCK%IA1, and BLCK%IA2.
Each process has to call PSPINS as many times as necessary to insert the local rows it owns. It is also possible to call PSPINS multiple times to insert different or duplicate coefficients of the same local row it owns. For information on how duplicate coefficients are handled, see the dupflag argument description in PSPASB. For an example of inserting coefficients of the same local row, see Example.

Error Conditions

Computational Errors

None

Resource Errors

Unable to allocate work space.
Unable to allocate component(s) of A.

Input-Argument and Miscellaneous Errors

Stage 1:

desc_a has not been initialized.

Stage 2:

The BLACS context is invalid.

Stage 3:

This subroutine was called from outside the process grid.

Stage 4:

The process grid is not np × 1.
ia < 1 or ia > DESC_A%MATRIX_DATA(M)
ja <> 1
desc_a component(s) are not valid.
The sparse matrix A is not valid.
BLCK%M < 1 or BLCK%M > DESC_A%MATRIX_DATA(N_ROW)
BLCK%N < 1 or BLCK%N > n
BLCK%FIDA <> 'CSR'
One or more rows to be inserted into submatrix A does not belong to the process.

Example

This piece of an example shows how to insert coefficients into the same GLOB_ROW row by calling PSPINS multiple times. It would be useful in finite element applications, where PSPINS inserts one element at a time into the global matrix, but more than one element may contribute to the same matrix row. In this case, PSPINS is called with the same value of ia by all the elements contributing to that row.

For a complete example, see Example--Using the Fortran 90 Sparse Subroutines.

            .
            .
            .
DO GLOB_ROW = 1, N
 
   ROW_MAT%DESCRA(1) = 'G'
   ROW_MAT%FIDA      = 'CSR'
 
   ROW_MAT%IA2(1) = 1
   ROW_MAT%IA2(2) = 1
 
   IA = GLOB_ROW
 
   !       (x-1,y,z)
   ROW_MAT%AS(1)  = COEFF(X-1,Y,Z,X,Y,Z)
   ROW_MAT%IA1(1) = IDX(X-1,Y,Z)
   CALL PSPINS(A,IA,1,ROW_MAT,DESC_A)
   !       (x,y-1,z)
   ROW_MAT%AS(1)  = COEFF(X,Y-1,Z,X,Y,Z)
   ROW_MAT%IA1(1) = IDX(X,Y-1,Z)
   CALL PSPINS(A,IA,1,ROW_MAT,DESC_A)
   !       (x,y,z-1)
   ROW_MAT%AS(1)  = COEFF(X,Y,Z-1,X,Y,Z)
   ROW_MAT%IA1(1) = IDX(X,Y,Z-1)
   CALL PSPINS(A,IA,1,ROW_MAT,DESC_A)
   !       (x,y,z)
   ROW_MAT%AS(1)  = COEFF(X,Y,Z,X,Y,Z)
   ROW_MAT%IA1(1) = IDX(X,Y,Z)
   CALL PSPINS(A,IA,1,ROW_MAT,DESC_A)
   !       (x,y,z+1)
   ROW_MAT%AS(1)  = COEFF(X,Y,Z+1,X,Y,Z)
   ROW_MAT%IA1(1) = IDX(X,Y,Z+1)
   CALL PSPINS(A,IA,1,ROW_MAT,DESC_A)
   !       (x,y+1,z)
   ROW_MAT%AS(1)  = COEFF(X,Y+1,Z,X,Y,Z)
   ROW_MAT%IA1(1) = IDX(X,Y+1,Z)
   CALL PSPINS(A,IA,1,ROW_MAT,DESC_A)
   !       (x+1,y,z)
   ROW_MAT%AS(1)  = COEFF(X+1,Y,Z,X,Y,Z)
   ROW_MAT%IA1(1) = IDX(X+1,Y,Z)
   CALL PSPINS(A,IA,1,ROW_MAT,DESC_A)
END DO
            .
            .
            .

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]