Sparse Matrix class

3.2 Sparse Matrix class

The psb_Tspmat_type class contains all information about the local portion of the sparse matrix and its storage mode. Its design is based on the STATE design pattern [13] as detailed in [11]; the type declaration is shown in figure 4 where T is a placeholder for the data type and precision variants

S: Single precision real;
D: Double precision real;
C: Single precision complex;
Z: Double precision complex.

The actual data is contained in the polymorphic component a%a of type psb_T_base_sparse_mat; its specific layout can be chosen dynamically among the predefined types, or an entirely new storage layout can be implemented and passed to the library at runtime via the psb_spasb routine.

  type :: psb_Tspmat_type
    class(psb_T_base_sparse_mat), allocatable  :: a
  end type  psb_Tspmat_type

Figure 4: The PSBLAS defined data type that contains a sparse matrix.

The following very common formats are precompiled in PSBLAS and thus are always available:

psb_T_coo_sparse_mat: Coordinate storage;
psb_T_csr_sparse_mat: Compressed storage by rows;
psb_T_csc_sparse_mat: Compressed storage by columns;

The inner sparse matrix has an associated state, which can take the following values:

Build:: State entered after the first allocation, and before the first assembly; in this state it is possible to add nonzero entries.
Assembled:: State entered after the assembly; computations using the sparse matrix, such as matrix-vector products, are only possible in this state;
Update:: State entered after a reinitalization; this is used to handle applications in which the same sparsity pattern is used multiple times with different coefficients. In this state it is only possible to enter coefficients for already existing nonzero entries.

The only storage variant supporting the build state is COO; all other variants are obtained by conversion to/from it.

3.2.1 Sparse Matrix Methods

3.2.2 get_nrows — Get number of rows in a sparse matrix

nr = a%get_nrows()

Type:: Asynchronous.
On Entry
a: the sparse matrix
Scope: local

On Return
Function value: The number of rows of sparse matrix a.

3.2.3 get_ncols — Get number of columns in a sparse matrix

nc = a%get_ncols()

Type:: Asynchronous.
On Entry
a: the sparse matrix
Scope: local

On Return
Function value: The number of columns of sparse matrix a.

3.2.4 get_nnzeros — Get number of nonzero elements in a sparse matrix

nz = a%get_nnzeros()

Type:: Asynchronous.
On Entry
a: the sparse matrix
Scope: local

On Return
Function value: The number of nonzero elements stored in sparse matrix a.

Notes

The function value is specific to the storage format of matrix a; some storage formats employ padding, thus the returned value for the same matrix may be different for different storage choices.

3.2.5 get_size — Get maximum number of nonzero elements in a sparse matrix

maxnz = a%get_size()

Type:: Asynchronous.
On Entry
a: the sparse matrix
Scope: local

On Return
Function value: The maximum number of nonzero elements that can be stored in sparse matrix a using its current memory allocation.

3.2.6 sizeof — Get memory occupation in bytes of a sparse matrix

memory_size = a%sizeof()

Type:: Asynchronous.
On Entry
a: the sparse matrix
Scope: local

On Return
Function value: The memory occupation in bytes.

3.2.7 get_fmt — Short description of the dynamic type

write(*,*) a%get_fmt()

Type:: Asynchronous.
On Entry
a: the sparse matrix
Scope: local

On Return
Function value: A short string describing the dynamic type of the matrix. Predefined values include NULL, COO, CSR and CSC.

3.2.8 is_bld, is_upd, is_asb — Status check

if (a%is_bld()) then
if (a%is_upd()) then
if (a%is_asb()) then

Type:: Asynchronous.
On Entry
a: the sparse matrix
Scope: local

On Return
Function value: A logical value indicating whether the matrix is in the Build, Update or Assembled state, respectively.

3.2.9 is_lower, is_upper, is_triangle, is_unit — Format check

if (a%is_triangle()) then
if (a%is_upper()) then
if (a%is_lower()) then
if (a%is_unit()) then

Type:: Asynchronous.
On Entry
a: the sparse matrix
Scope: local

On Return
Function value: A logical value indicating whether the matrix is triangular; if is_triangle() returns .true. check also if it is lower, upper and with a unit (i.e. assumed) diagonal.

3.2.10 cscnv — Convert to a different storage format

call a%cscnv(b,info [, type, mold, dupl])
call a%cscnv(info [, type, mold, dupl])

Type:: Asynchronous.
On Entry
a: the sparse matrix.
A variable of type psb_Tspmat_type.
Scope: local.
type: a string requesting a new format.
Type: optional.
mold: a variable of class(psb_T_base_sparse_mat) requesting a new format.
Type: optional.
dupl: an integer value specifing how to handle duplicates (see Named Constants below)

On Return
b,a: A copy of a with a new storage format.
A variable of type psb_Tspmat_type.
info: Return code.

The mold arguments may be employed to interface with special devices, such as GPUs and other accelerators.

3.2.11 csclip — Reduce to a submatrix

call a%csclip(b,info[,&
& imin,imax,jmin,jmax,rscale,cscale])

Returns the submatrix A(imin:imax,jmin:jmax), optionally rescaling row/col indices to the range 1:imax-imin+1,1:jmax-jmin+1.

Type:: Asynchronous.
On Entry
a: the sparse matrix.
A variable of type psb_Tspmat_type.
Scope: local.
imin,imax,jmin,jmax: Minimum and maximum row and column indices.
Type: optional.
rscale,cscale: Whether to rescale row/column indices. Type: optional.

On Return
b: A copy of a submatrix of a.
A variable of type psb_Tspmat_type.
info: Return code.

3.2.12 clean_zeros — Eliminate zero coefficients

call a%clean_zeros(info)

Eliminates zero coefficients in the input matrix. Note that depending on the internal storage format, there may still be some amount of zero padding in the output.

Type:: Asynchronous.
On Entry
a: the sparse matrix.
A variable of type psb_Tspmat_type.
Scope: local.

On Return
a: The matrix a without zero coefficients.
A variable of type psb_Tspmat_type.
info: Return code.

3.2.13 get_diag — Get main diagonal

call a%get_diag(d,info)

Returns a copy of the main diagonal.

Type:: Asynchronous.
On Entry
a: the sparse matrix.
A variable of type psb_Tspmat_type.
Scope: local.

On Return
d: A copy of the main diagonal.
A one-dimensional array of the appropriate type.
info: Return code.

3.2.14 clip_diag — Cut out main diagonal

call a%clip_diag(b,info)

Returns a copy of a without the main diagonal.

Type:: Asynchronous.
On Entry
a: the sparse matrix.
A variable of type psb_Tspmat_type.
Scope: local.

On Return
b: A copy of a without the main diagonal.
A variable of type psb_Tspmat_type.
info: Return code.

3.2.15 tril — Return the lower triangle

call a%tril(l,info[,&
& diag,imin,imax,jmin,jmax,rscale,cscale,u])

Returns the lower triangular part of submatrix A(imin:imax,jmin:jmax), optionally rescaling row/col indices to the range 1:imax-imin+1,1:jmax-jmin+1 and returing the complementary upper triangle.

Type:: Asynchronous.
On Entry
a: the sparse matrix.
A variable of type psb_Tspmat_type.
Scope: local.
diag: Include diagonals up to this one; diag=1 means the first superdiagonal, diag=-1 means the first subdiagonal. Default 0.
imin,imax,jmin,jmax: Minimum and maximum row and column indices.
Type: optional.
rscale,cscale: Whether to rescale row/column indices. Type: optional.

On Return
l: A copy of the lower triangle of a.
A variable of type psb_Tspmat_type.
u: (optional) A copy of the upper triangle of a.
A variable of type psb_Tspmat_type.
info: Return code.

3.2.16 triu — Return the upper triangle

call a%triu(u,info[,&
& diag,imin,imax,jmin,jmax,rscale,cscale,l])

Returns the upper triangular part of submatrix A(imin:imax,jmin:jmax), optionally rescaling row/col indices to the range 1:imax-imin+1,1:jmax-jmin+1, and returing the complementary lower triangle.

Type:: Asynchronous.
On Entry
a: the sparse matrix.
A variable of type psb_Tspmat_type.
Scope: local.
diag: Include diagonals up to this one; diag=1 means the first superdiagonal, diag=-1 means the first subdiagonal. Default 0.
imin,imax,jmin,jmax: Minimum and maximum row and column indices.
Type: optional.
rscale,cscale: Whether to rescale row/column indices. Type: optional.

On Return
u: A copy of the upper triangle of a.
A variable of type psb_Tspmat_type.
l: (optional) A copy of the lower triangle of a.
A variable of type psb_Tspmat_type.
info: Return code.

3.2.17 psb_set_mat_default — Set default storage format

call psb_set_mat_default(a)

Type:: Asynchronous.
On Entry
a: a variable of class(psb_T_base_sparse_mat) requesting a new default storage format.
Type: required.

3.2.18 clone — Clone current object

call a%clone(b,info)

Type:: Asynchronous.
On Entry
a: the sparse matrix.
Scope: local.

On Return
b: A copy of the input object.
info: Return code.

3.2.19 Named Constants

psb_dupl_ovwrt_: Duplicate coefficients should be overwritten (i.e. ignore duplications)
psb_dupl_add_: Duplicate coefficients should be added;
psb_dupl_err_: Duplicate coefficients should trigger an error conditino
psb_upd_dflt_: Default update strategy for matrix coefficients;
psb_upd_srch_: Update strategy based on search into the data structure;
psb_upd_perm_: Update strategy based on additional permutation data (see tools routine description).

[next] [prev] [prev-tail] [front] [up]