documentation.md

Brief documentation

Overview

The Modern Fortran library libsparse is a library that provides objects to create and handle rectangular and square sparse matrices using different formats:

• Linked List (LL);

• COOrdinate storage (COO) (with elements stored using a hashing function);

• Compressed Row Storage (CRS).

The library is written following an object-oriented approach.

Compilation

To build the libsparse you need (at least):

• at least a Fortran 2008 compliant compiler (GCC Fortran 11 and Intel Fortran classic compilers have been tested successfully);
• Intel MKL library;
• Make or fpm.

The library relies on different libraries, such as BLAS/LAPACK libraries (currently Intel MKL library), and optionally on PARDISO (at this stage, Intel MKL PARDISO), and METIS 5.

Building with Make

To compile with GCC Fortran compiler gfortran:

make FC=gfortran

or to compile with Intel Fortran classic compiler ifort

make FC=ifort

By default, it will not be compiled against METIS 5. To compile against METIS 5:

make FC=ifort METISENABLE=1

Compilation with debug options is possible by adding the argument DEBUGENABLE=1.

Compilation for single precision is possible by adding the argument DPENABLE=0.

Build with CMake

Configure the build with, e.g.,

export FFLAGS="-O3"
cmake -B build -DCMAKE_VERBOSE_MAKEFILE=On -DCMAKE_BUILD_TYPE=Debug -DCMAKE_METIS_LIB=$(pwd)/../metis-5.1.0/build/Linux-x86_64/libmetis/libmetis.a

To build the project, run

cmake --build build

To test your build, run the test suite after the build has finished with

cmake --build build --target test

Building with fpm

To compile with GCC Fortran compiler gfortran:

fpm @build_gfortran
fpm @test_gfortran

or to compile with Intel Fortran classic compiler ifort

fpm @build_ifort
fpm @test_ifort

Note that the file fpm.toml must be modified for supporting the compilation with ifort.

Methods

Below the term mat refers to one of the three available sparse objects (i.e., llsparse, coosparse, or crssparse), except if it is mentioned otherwise. For more details, please refer to the documentation generated by Doxygen.

To construct (initiate) a sparse matrix, the constructor of the same name as the object, must be used, e.g.:

integer :: dim1         !number of rows     
type(coosparse) :: mat  

dim1 = 100
mat = coosparse(dim1)  

Other options are possible for the constructor (see details in the module pages). For sparse matrices with upper storage (default: fulled storage), it must be mentioned as:

mat = coosparse(dim1,lupper=.true.)  

This option can also be used to load a matrix from a binary stream file.

To add a value val at the position (row,col) of a sparse matrix, the method add must be used, e.g.:

call mat%add(row, col, val)  

To convert a sparse matrix from a format to another format, the assignment = can be used. E.g., to convert from COO to CSR:

type(coosparse) :: coomat  
type(crssparse) :: crsmat  
  
csrmat = coomat  

To copy a sparse matrix, the assignment = can be used. E.g.,:

type(crssparse) :: crsmat  
type(crssparse) :: crsmatcopy  
  
csrmatcopy = crsmat  

To deallocate a sparse matrix, the method destroy can be used, e.g.:

call mat%destroy()  

To extract the diagonal elements of a sparse matrix into a array, the method diag must be used:

array = mat%diag()  

To extract the diagonal elements and off-diagonals of a sparse matrix into a array, the method diag must be used:

extractedmat = mat%diag(x)  

where x is the number of off-diagonals (next to the diagonal) that must be extraced. If x is equal to 0, only the diagonal will be extracted and stored into a sparse matrix.

To get a value val at the position (row,col) of a sparse matrix, the method get must be used, e.g.:

val = mat%get(row, col)  

To get one of the dimensions of a sparse matrix, the method getdim must be used:

val = mat%getdim(x)  

where x is 1 (=number of rows) or 2 (=number of columns).

To get a permutation vector from the METIS 5 fill-reducing ordering approach, the method getordering can be used:

permarray = mat%getordering()  

Options for METIS 5 can be changed through optional arguments of this method.

To approximate the diagonal elements of the inverse of a sparse matrix using Harville (1999):

call crsmat%harville(ngibbs, nburn, diaginv)

To create a CRS matrix from existing arrays, the method external must be used:

call crsmat%external(ia, ja, a)  

where the arrays ia, ja, and a must have the same size as the ones of the sparse matrix crsmat.

To multiply a sparse matrix by a vector as, y = alpha * mat(trans) * v + val * y , the method multbyv must be used:

call mat%multbyv(alpha, trans, v, val, y)  

where alpha and val are double-precision real values, v and y are vectors, and trans (= 'n' or 't') relates to the transposition of the matrix.
The method multbyv is based on the MKL Sparse BLAS library.

To get the number of non-zero elements of a sparse matrix, the method nonzero must be used, e.g.:

nonzeros = mat%nonzero()  

To print a sparse matrix as stored to default output (screen), the method print must be used, e.g.:

call mat%print()  

To print a sparse matrix as stored to a file called file.dat, the method printtofile must be used, e.g.:

call mat%printtofile('file.dat')  

To save a matrix in the internal format, the method save can be used:

call mat%save('file.stream')  

To set an entry to a specified value (even 0), the method set can be used:

call mat%set(row, col, val)  

To set a permutation vector,the method setpermutation can be used:

 call mat%setpermutation(array)  

It is possible to get and set a permutation vector in one call as follows:

 call mat%setpermutation(mat%getordering())  

To solve a linear system of equations of the form mat * x = y, the method solve must be used:

call mat%solve(x,y)  

The method solve is based on Intel MKL Pardiso. If a permutation vector was provided with the method setpermutation, this permutation vector will be used by Intel MKL Pardiso (instead of determining it internally).

To sort a column (in an ascending order) within a row of a CRS sparse matrix, the method sort must be used:

call crsmat%sort()  

To check if the sparse matrix is sorted (columns within rows), the method issorted must be used:

sorted = mat%issorted()  

where the variable sorted is a logical.

To check if the sparse matrix is a square matrix, the method issquare must be used:

square = mat%issquare()  

where the variable square is a logical.

To extract a submatrix from a sparse matrix, the method submatrix must be used, e.g.:

submatrix = mat%submatrix(startrow, endrow, startrow, endrow, lupper = log)  

where log is a logical to extract the full matrix (lupper = .false.) or the upper triangular matrix (lupper = .true.).