iadesc.inc
c* Description of the storage description array "ia".
c*
c* The first element, storage, is required. Other parameters
c* required for specific storage formats are identified below.
c*
c* ia(1):
c* storage - storage format
c*
c* 0 ==> unknown
c*
c* In this case, the storage format is unknown, and
c* storage format-dependent operations such as
c* matrix-vector multiplication must be performed by
c* the host code via reverse communication.
c*
c* Other storage parameters required: nunk
c*
c* 1 ==> full storage
c*
c* In this option, the coefficient is stored in the
c* conventional manner, as an nrows x ncols array.
c*
c* Other storage parameters required: ncols
c* idim
c*
c* 2 ==> full-band column storage (NOT IMPLEMENTED)
c*
c* In this option, each column of the reduced matrix
c* corresponds to a diagonal of the original matrix.
c* This storage scheme is also used in EISPACK.
c*
c* Example: 11 12 0 0 0 0
c* 21 22 23 0 0 0
c* 0 32 33 34 0 0
c* 41 0 43 44 45 0
c* 0 52 0 54 55 56
c* 0 0 63 0 65 66
c*
c* would be represented in full-band column storage as
c* the following nunk x (lbw + ubw + 1) array, where
c* lbw and ubw are the lower and upper bandwidths,
c* respectively:
c*
c* 0 0 0 11 12
c* 0 0 21 22 23
c* 0 0 32 33 34
c* 41 0 43 44 45
c* 52 0 54 55 56
c* 63 0 65 66 0
c*
c* Other storage parameters required: nrows
c* idim
c* lbw
c* ubw
c*
c* 3 ==> full-band row storage (NOT IMPLEMENTED)
c*
c* In this option, each *row* of the reduced matrix
c* corresponds to a diagonal of the original matrix.
c* This storage scheme is also used in LAPACK.
c*
c* Example: 11 12 0 0 0
c* 21 22 23 0 0
c* 0 32 33 34 0
c* 41 0 43 44 45
c* 0 52 0 54 55
c*
c* would be represented in full-band row storage as
c* the following (lbw + ubw + 1) x nunk array, where
c* lbw and ubw are the lower and upper bandwidths,
c* respectively:
c*
c* 0 0 0 41 52 63
c* 0 0 0 0 0 0
c* 0 21 32 43 54 65
c* 11 22 33 44 55 66
c* 12 23 34 45 56 0
c*
c* Other storage parameters required: nrows
c* idim
c* lbw
c* ubw
c*
c* 4 ==> general block-tridiagonal storage (NOT IMPLEMENTED)
c*
c* Example: A1 C1
c* B1 A2 C2
c* . . .
c* . . Cn-1
c* Bn-1 An
c*
c* would be stored as:
c*
c* a = A1 A2 ... An B1 B2 ... Bn-1 C1 C2 ... Cn-1
c*
c* Note that nunk = blksize*nblks, where blksize is the
c* block size and nblks is the number of blocks.
c*
c* Other storage parameters required: nrows
c* idim
c* blksize
c* nblks
c*
c* 5 ==> symmetric block-tridiagonal storage (NOT IMPLEMENTED)
c*
c* Example: A1 B1
c* B1 A2 B2
c* . . .
c* . . Bn-1
c* Bn-1 An
c*
c* would be stored as:
c*
c* a = A1 A2 ... An B1 B2 ... Bn-1
c*
c* Note that nunk = blksize*nblks, where blksize is the
c* block size and nblks is the number of blocks.
c*
c* Other storage parameters required: nrows
c* idim
c* blksize
c* nblks
c*
c* 6 ==> block-tridiagonal with diagonal off-diagonal blocks
c* (NOT IMPLEMENTED)
c*
c* In this case the B's and C's in format 4 are diagonal
c* matrices, so they are stored as n-1 columns (each) after
c* An.
c*
c* Note that nunk = blksize*nblks, where blksize is the
c* block size and nblks is the number of blocks.
c*
c* Other storage parameters required: nrows
c* idim
c* blksize
c* nblks
c*
c* 7 ==> symmetric block-tridiagonal with diagonal off-
c* diagonal blocks (NOT IMPLEMENTED)
c*
c* In this case the B's in format 5 are diagonal matrices,
c* so they are stored as n-1 columns after An.
c*
c* Note that nunk = blksize*nblks, where blksize is the
c* block size and nblks is the number of blocks.
c*
c* Other storage parameters required: nrows
c* idim
c* blksize
c* nblks
c*
c* 8 ==> ELLPACK-ITPACK, or row-packed format
c*
c* In this format, all zeros are removed from each row, so
c* that the matrix is essentially left-justified, and the
c* main diagonal elements are stored in the first column.
c* Thus the coefficient is stored in an nunk x maxnz array,
c* where maxnz is the maximum number of non-zero elements
c* on any row.
c*
c* A companion nunk x maxnz array maps the column in the
c* reduced matrix to the column in the original matrix for
c* each element.
c*
c* NSPCG calls this primary format, but does not require
c* the main diagonal elements to be in the first column.
c*
c* Example: 11 0 0 14 15
c* 0 22 0 0 0
c* 0 0 33 0 0
c* 41 0 0 44 45
c* 51 0 0 54 55
c*
c* would be represented in ELL format by the arrays "a" and
c* "ja" as follows:
c*
c* 11 14 15 1 4 5
c* 22 0 0 2 0 0
c* a = 33 0 0 ja = 3 0 0
c* 44 41 45 4 1 5
c* 55 51 54 5 1 4
c*
c* Note that the main diagonal elements *must* be in the
c* first column of array "a".
c*
c* Other storage parameters required: nrows
c* idim
c* maxnz
c*
c* 9 ==> ELLPACK-ITPACK transpose (NOT IMPLEMENTED)
c*
c* This is the transpose of ELL storage. Here the main
c* diagonal elements are stored in the first row, and the
c* coefficient is stored in an maxnz x nunk array, where
c* again maxnz is the maximum number of non-zero elements
c* on any row.
c*
c* A companion maxnz x nunk array maps the column in the
c* reduced matrix to the column in the original matrix for
c* each element.
c*
c* Example: 11 0 0 14 15
c* 0 22 0 0 0
c* 0 0 33 0 0
c* 41 0 0 44 45
c* 51 0 0 54 55
c*
c* would be represented in ELLT format by the arrays "a" and
c* "ja" as follows:
c*
c* 11 22 33 44 55 1 2 3 4 5
c* a = 14 0 0 41 51 ja = 4 0 0 1 1
c* 15 0 0 45 54 5 0 0 5 4
c*
c* Note that the main diagonal elements *must* be in the
c* first row of array "a".
c*
c* Other storage parameters required: nunk
c* idim
c* maxnz
c*
c* 10 ==> Coordinate format (COO)
c*
c* In this format, a is a vector
c* of length nelem containing all the elements of A. The
c* first n elements of a must contain the main diagonal
c* elements of A, but the remaining elements can be in
c* any order. The map array ja is a vector of length
c* 2*nelem. Then the first nelem elements of ja contain
c* the row indices of A, and the next nelem elements
c* contain the column indices of A.
c*
c* Advantages:
c* - stores no extra zero elements (unless you want to)
c* - elements can be in any order (except for main
c* diagonal)
c* - matrix-vector multiply implemented as single loop,
c* so longer vector length
c* Disadvantage:
c* - two indirect references in matrix-vector multiply
c*
c* Example: 11 0 0 14 15
c* 0 22 0 0 0
c* 0 0 33 0 0
c* 41 0 0 44 45
c* 51 0 0 54 55
c*
c* could be represented in COO format by the arrays "a" and
c* "ja" as:
c*
c* a = 11 22 33 44 55 41 51 14 54 15 45
c*
c* ja = 1 2 3 4 5 4 5 1 5 1 5 1 2 3 4 5 1 1 4 4 5 5
c*
c* or as:
c*
c* a = 11 22 33 44 55 14 15 41 45 51 54
c*
c* ja = 1 2 3 4 5 1 1 4 4 5 5 1 2 3 4 5 4 5 1 5 1 5
c*
c* Other storage parameters required: nunk
c* nelem
c*
c* 11 ==> Row sequential storage (RSS)
c*
c* RSS format is essentially a variation of COO format.
c*
c* In this format the positions in the full matrix are
c* numbered from 1 to nrows*nrows, starting with element
c* (1,1), and proceeding across each row in succession to
c* element (nrows,nrows). For example, the elements of a
c* 3x3 matrix would be numbered as follows:
c*
c* Example: 1,1 1,2 1,3 1 2 3
c* 2,1 2,2 2,3 ==> 4 5 6
c* 3,1 3,2 3,3 7 8 9
c*
c* So again a is a vector of length nelem containing the
c* active elements of A. The map array ja is again a
c* vector of length nelem containing the sequence number
c* of the corresponding element of a, that is:
c*
c* (i-1)*nrows + j
c*
c* The elements of a can be in any order, except that the
c* main diagonal elements must be in the first nrows
c* elements.
c*
c* Advantages:
c* - stores no extra zero elements (unless you want to)
c* - matrix-vector multiply implemented as single loop,
c* so longer vector length
c* - ja is half as long as with COO format
c* Disadvantages:
c* - indirect references plus significant integer
c* arithmetic (including integer division) required
c* - requires use of large integers (up to nrows*nrows),
c* which can lead to integer overflow for even
c* moderate problem sizes (>~46,000 unknowns for
c* 4-byte integers)
c*
c* Example: 11 0 0 14 15
c* 0 22 0 0 0
c* 0 0 33 0 0
c* 41 0 0 44 45
c* 51 0 0 54 55
c*
c* could be represented in row sequential format by the
c* arrays "a" and "ja" as:
c*
c* a = 11 22 33 44 55 41 51 14 54 15 45
c*
c* ja = 1 7 13 19 25 16 21 4 24 5 20
c*
c* Other storage parameters required: nunk
c* nelem
c*
c* 12 ==> Column sequential storage (CSS)
c*
c* CSS format is another variation of COO format, similar
c* to RSS.
c*
c* In this format the positions in the full matrix are
c* numbered from 1 to nrows*nrows, starting with element
c* (1,1), and proceeding down each column in succession to
c* element (nrows,nrows). For example, the elements of a
c* 3x3 matrix would be numbered as follows:
c*
c* Example: 1,1 1,2 1,3 1 4 7
c* 2,1 2,2 2,3 ==> 2 5 8
c* 3,1 3,2 3,3 3 6 9
c*
c* So again a is a vector of length nelem containing the
c* active elements of A. The map array ja is again a
c* vector of length nelem containing the sequence number
c* of the corresponding element of a, that is:
c*
c* (j-1)*nrows + i
c*
c* The elements of a can be in any order, except that the
c* main diagonal elements must be in the first nrows
c* elements.
c*
c* Advantages:
c* - stores no extra zero elements (unless you want to)
c* - matrix-vector multiply implemented as single loop,
c* so longer vector length
c* - ja is half as long as with COO format
c* Disadvantages:
c* - indirect references plus significant integer
c* arithmetic (including integer division) required
c* - requires use of large integers (up to nrows*nrows),
c* which can lead to integer overflow for even
c* moderate problem sizes (>~46,000 unknowns for
c* 4-byte integers)
c*
c* Example: 11 0 0 14 15
c* 0 22 0 0 0
c* 0 0 33 0 0
c* 41 0 0 44 45
c* 51 0 0 54 55
c*
c* could be represented in column sequential format by the
c* arrays "a" and "ja" as:
c*
c* a = 11 22 33 44 55 41 51 14 54 15 45
c*
c* ja = 1 7 13 19 25 4 5 16 20 21 24
c*
c* Other storage parameters required: nunk
c* nelem
c*
c* ia(2):
c* nrows - number of active rows
c* also referred to as:
c* nunk - number of unknowns
c* or:
c* ntot - total number of unknowns
c* when A is the coefficient matrix of a linear system of equations
c* ia(3):
c* idim - leading dimension of A for storage = 1-9
c* or:
c* nelem - total number of elements in vector containing A for
c* storage = 10-12
c* ia(4):
c* maxnz - maximum number of active elements in any row
c* For storage = 1, maxnz would be equal to nrows, and is
c* also referred to as ncols.
c* For storage = 8-9, maxnz would be the maximum number
c* of non-zero elements in any row.
c* ia(5), ia(6):
c* lbw - lower bandwidth
c* ubw - upper bandwidth
c* ia(7), ia(8):
c* blksize - block size
c* nblks - number of blocks