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

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 2 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;
LS,LD,LC,LZ
Same numeric type as above, but with psb_lpk_ integer indices.

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


Listing 2: 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

  1. 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]