The reference documentation of the \librsb library comes in both HTML and Unix man pages formats.
The following sections/man pages are available: The librsb library interface (rsb.h, optional ones rsb.hpp and rsb.F90) ; The Sparse BLAS interface to librsb (blas_sparse.h, rsb_blas_sparse.F90) ; Example programs and code. More...

Macros
#define	RSB_SIZEOF(TYPE)

Enumerations
enum	rsb_opt_t { RSB_IO_WANT_VERBOSE_INIT =0x000001 , RSB_IO_WANT_VERBOSE_EXIT =0x000002 , RSB_IO_WANT_OUTPUT_STREAM =0x000003 , RSB_IO_WANT_SORT_METHOD =0x000004 , RSB_IO_WANT_CACHE_BLOCKING_METHOD =0x000005 , RSB_IO_WANT_SUBDIVISION_MULTIPLIER =0x000006 , RSB_IO_WANT_VERBOSE_ERRORS =0x000007 , RSB_IO_WANT_BOUNDED_BOX_COMPUTATION =0x000008 , RSB_IO_WANT_EXECUTING_THREADS =0x000009 , RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE =0x000010 , RSB_IO_WANT_MEMORY_HIERARCHY_INFO_STRING =0x000011 , RSB_IO_WANT_IS_INITIALIZED_MARKER =0x000012 , RSB_IO_WANT_MEM_ALLOC_CNT =0x000013 , RSB_IO_WANT_MEM_ALLOC_TOT =0x000014 , RSB_IO_WANT_LEAF_LEVEL_MULTIVEC =0x000015 , RSB_IO_WANT_MAX_MEMORY_ALLOCATIONS =0x000016 , RSB_IO_WANT_MAX_MEMORY_ALLOCATED =0x000017 , RSB_IO_WANT_LIBRSB_ETIME =0x000018 , RSB_IO_WANT_VERBOSE_TUNING =0x000019 }
	library option values for \see_lib_init_funcs. More...
enum	rsb_extff_t { RSB_EXTF_NORM_ONE =0x00001001 , RSB_EXTF_NORM_TWO =0x00001002 , RSB_EXTF_NORM_INF =0x00001003 , RSB_EXTF_SUMS_ROW =0x00001004 , RSB_EXTF_SUMS_COL =0x00001005 , RSB_EXTF_ASUMS_ROW =0x00001006 , RSB_EXTF_ASUMS_COL =0x00001007 , RSB_EXTF_DIAG =0x00000004 }
	Extraction filter flags, to be used with rsb_mtx_get_nrm()/rsb_mtx_get_vec(). More...
enum	rsb_mif_t { RSB_MIF_INDEX_STORAGE_IN_BYTES__TO__SIZE_T =0x00000001 , RSB_MIF_INDEX_STORAGE_IN_BYTES_PER_NNZ__TO__RSB_REAL_T =0x00000002 , RSB_MIF_MATRIX_ROWS__TO__RSB_COO_INDEX_T =0x00000004 , RSB_MIF_MATRIX_COLS__TO__RSB_COO_INDEX_T =0x00000008 , RSB_MIF_MATRIX_NNZ__TO__RSB_NNZ_INDEX_T =0x00000010 , RSB_MIF_TOTAL_SIZE__TO__SIZE_T =0x00000020 , RSB_MIF_MATRIX_FLAGS__TO__RSB_FLAGS_T =0x00000040 , RSB_MIF_MATRIX_TYPECODE__TO__RSB_TYPE_T =0x00000080 , RSB_MIF_MATRIX_INFO__TO__CHAR_P =0x00000100 , RSB_MIF_LEAVES_COUNT__TO__RSB_BLK_INDEX_T =0x00000200 }
	Flags for getting matrix information via rsb_mtx_get_info()/rsb_mtx_get_info_str(). More...
enum	rsb_elopf_t { RSB_ELOPF_MUL =0x00000001 , RSB_ELOPF_DIV =0x00000002 , RSB_ELOPF_POW =0x00000004 , RSB_ELOPF_NEG =0x00000008 , RSB_ELOPF_SCALE_ROWS =0x00000010 , RSB_ELOPF_SCALE_COLS =0x00000020 , RSB_ELOPF_SCALE_ROWS_REAL =0x00000040 , RSB_ELOPF_SCALE_COLS_REAL =0x00000080 }
	Flags for specifying a particular elemental/row-wise operation with rsb_mtx_upd_vals(). More...

Functions
rsb_err_t	rsb_lib_init (struct rsb_initopts *iop)
rsb_err_t	rsb_lib_set_opt (enum rsb_opt_t iof, const void *iop)
rsb_err_t	rsb_lib_get_opt (enum rsb_opt_t iof, void *iop)
rsb_err_t	rsb_lib_set_opt_str (const rsb_char_t opnp, const rsb_char_t opvp)
rsb_err_t	rsb_lib_reinit (struct rsb_initopts *iop)
rsb_err_t	rsb_lib_exit (struct rsb_initopts *iop)
struct rsb_mtx_t *	rsb_mtx_alloc_from_coo_const (const void VA, const rsb_coo_idx_t IA, const rsb_coo_idx_t JA, rsb_nnz_idx_t nnzA, rsb_type_t typecode, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_blk_idx_t brA, rsb_blk_idx_t bcA, rsb_flags_t flagsA, rsb_err_t errvalp)
struct rsb_mtx_t *	rsb_mtx_alloc_from_coo_inplace (void VA, rsb_coo_idx_t IA, rsb_coo_idx_t JA, rsb_nnz_idx_t nnzA, rsb_type_t typecode, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_blk_idx_t brA, rsb_blk_idx_t bcA, rsb_flags_t flagsA, rsb_err_t errvalp)
struct rsb_mtx_t *	rsb_mtx_free (struct rsb_mtx_t *mtxAp)
rsb_err_t	rsb_mtx_clone (struct rsb_mtx_t *mtxBpp, rsb_type_t typecode, rsb_trans_t transA, const void alphap, const struct rsb_mtx_t *mtxAp, rsb_flags_t flags)
rsb_err_t	rsb_spmv (rsb_trans_t transA, const void alphap, const struct rsb_mtx_t mtxAp, const void Xp, rsb_coo_idx_t incX, const void betap, void *Yp, rsb_coo_idx_t incY)
rsb_err_t	rsb_spsv (rsb_trans_t transT, const void alphap, const struct rsb_mtx_t mtxTp, const void Xp, rsb_coo_idx_t incX, void Yp, rsb_coo_idx_t incY)
rsb_err_t	rsb_spsm (rsb_trans_t transT, const void alphap, const struct rsb_mtx_t mtxTp, rsb_coo_idx_t nrhs, rsb_flags_t order, const void betap, const void Bp, rsb_nnz_idx_t ldB, void *Cp, rsb_nnz_idx_t ldC)
rsb_err_t	rsb_coo_sort (void VA, rsb_coo_idx_t IA, rsb_coo_idx_t *JA, rsb_nnz_idx_t nnzA, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_type_t typecode, rsb_flags_t flagsA)
rsb_err_t	rsb_coo_cleanup (rsb_coo_idx_t nnzp, void VA, rsb_coo_idx_t IA, rsb_coo_idx_t JA, rsb_nnz_idx_t nnzA, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_type_t typecode, rsb_flags_t flagsA)
rsb_err_t	rsb_file_mtx_get_dims (const char filename, rsb_coo_idx_t nrp, rsb_coo_idx_t ncp, rsb_coo_idx_t nzp, rsb_flags_t *flagsp)
rsb_err_t	rsb_perror (void *stream, rsb_err_t errval)
rsb_err_t	rsb_strerror_r (rsb_err_t errval, rsb_char_t *buf, size_t buflen)
rsb_err_t	rsb_mtx_upd_vals (struct rsb_mtx_t mtxAp, enum rsb_elopf_t elop_flags, const void omegap)
rsb_err_t	rsb_mtx_set_vals (struct rsb_mtx_t mtxAp, const void VA, const rsb_coo_idx_t IA, const rsb_coo_idx_t JA, rsb_nnz_idx_t nnz, rsb_flags_t flags)
rsb_err_t	rsb_mtx_get_vals (const struct rsb_mtx_t mtxAp, void VA, const rsb_coo_idx_t IA, const rsb_coo_idx_t JA, rsb_nnz_idx_t nnz, rsb_flags_t flags)
rsb_err_t	rsb_file_mtx_save (const struct rsb_mtx_t mtxAp, const rsb_char_t filename)
rsb_err_t	rsb_file_vec_save (const rsb_char_t filename, rsb_type_t typecode, const void Yp, rsb_coo_idx_t yvl)
rsb_err_t	rsb_file_vec_load (const rsb_char_t filename, rsb_type_t typecode, void Yp, rsb_coo_idx_t *yvlp)
struct rsb_mtx_t *	rsb_file_mtx_load (const rsb_char_t filename, rsb_flags_t flagsA, rsb_type_t typecode, rsb_err_t errvalp)
struct rsb_mtx_t *	rsb_sppsp (rsb_type_t typecode, rsb_trans_t transA, const void alphap, const struct rsb_mtx_t mtxAp, rsb_trans_t transB, const void betap, const struct rsb_mtx_t mtxBp, rsb_err_t *errvalp)
struct rsb_mtx_t *	rsb_spmsp (rsb_type_t typecode, rsb_trans_t transA, const void alphap, const struct rsb_mtx_t mtxAp, rsb_trans_t transB, const void betap, const struct rsb_mtx_t mtxBp, rsb_err_t *errvalp)
rsb_err_t	rsb_mtx_add_to_dense (const void alphap, const struct rsb_mtx_t mtxAp, rsb_nnz_idx_t ldB, rsb_nnz_idx_t nrB, rsb_nnz_idx_t ncB, rsb_bool_t rowmajorB, void *Bp)
rsb_trans_t	rsb_psblas_trans_to_rsb_trans (const char psbtrans)
struct rsb_mtx_t *	rsb_mtx_alloc_from_csr_const (const void VA, const rsb_coo_idx_t RP, const rsb_coo_idx_t JA, rsb_nnz_idx_t nnzA, rsb_type_t typecode, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_blk_idx_t brA, rsb_blk_idx_t bcA, rsb_flags_t flagsA, rsb_err_t errvalp)
struct rsb_mtx_t *	rsb_mtx_alloc_from_csc_const (const void VA, const rsb_coo_idx_t IA, const rsb_coo_idx_t CP, rsb_nnz_idx_t nnzA, rsb_type_t typecode, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_blk_idx_t brA, rsb_blk_idx_t bcA, rsb_flags_t flagsA, rsb_err_t errvalp)
struct rsb_mtx_t *	rsb_mtx_alloc_from_csr_inplace (void VA, rsb_nnz_idx_t RP, rsb_coo_idx_t JA, rsb_nnz_idx_t nnzA, rsb_type_t typecode, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_blk_idx_t brA, rsb_blk_idx_t bcA, rsb_flags_t flagsA, rsb_err_t errvalp)
rsb_err_t	rsb_mtx_switch_to_csr (struct rsb_mtx_t mtxAp, void VAp, rsb_coo_idx_t IAp, rsb_coo_idx_t *JAp, rsb_flags_t flags)
rsb_err_t	rsb_mtx_get_coo (const struct rsb_mtx_t mtxAp, void VA, rsb_coo_idx_t IA, rsb_coo_idx_t JA, rsb_flags_t flags)
rsb_err_t	rsb_mtx_get_csr (rsb_type_t typecode, const struct rsb_mtx_t mtxAp, void VA, rsb_nnz_idx_t RP, rsb_coo_idx_t JA, rsb_flags_t flags)
rsb_err_t	rsb_mtx_get_rows_sparse (rsb_trans_t transA, const void alphap, const struct rsb_mtx_t mtxAp, void VA, rsb_coo_idx_t IA, rsb_coo_idx_t JA, rsb_coo_idx_t frA, rsb_coo_idx_t lrA, rsb_nnz_idx_t rnzp, rsb_flags_t flags)
rsb_err_t	rsb_mtx_get_coo_block (const struct rsb_mtx_t mtxAp, void VA, rsb_coo_idx_t IA, rsb_coo_idx_t JA, rsb_coo_idx_t frA, rsb_coo_idx_t lrA, rsb_coo_idx_t fcA, rsb_coo_idx_t lcA, const rsb_coo_idx_t IREN, const rsb_coo_idx_t JREN, rsb_nnz_idx_t *rnzp, rsb_flags_t flags)
rsb_err_t	rsb_spmm (rsb_trans_t transA, const void alphap, const struct rsb_mtx_t mtxAp, rsb_coo_idx_t nrhs, rsb_flags_t order, const void Bp, rsb_nnz_idx_t ldB, const void betap, void *Cp, rsb_nnz_idx_t ldC)
rsb_err_t	rsb_spmsp_to_dense (rsb_type_t typecode, rsb_trans_t transA, const void alphap, const struct rsb_mtx_t mtxAp, rsb_trans_t transB, const void betap, const struct rsb_mtx_t mtxBp, rsb_nnz_idx_t ldC, rsb_nnz_idx_t nrC, rsb_nnz_idx_t ncC, rsb_bool_t rowmajorC, void *Cp)
rsb_err_t	rsb_mtx_rndr (const char filename, const struct rsb_mtx_t mtxAp, rsb_coo_idx_t pmWidth, rsb_coo_idx_t pmHeight, rsb_marf_t rflags)
rsb_err_t	rsb_file_mtx_rndr (void pmp, const char filename, rsb_coo_idx_t pmlWidth, rsb_coo_idx_t pmWidth, rsb_coo_idx_t pmHeight, rsb_marf_t rflags)
rsb_err_t	rsb_mtx_switch_to_coo (struct rsb_mtx_t mtxAp, void VAp, rsb_coo_idx_t IAp, rsb_coo_idx_t *JAp, rsb_flags_t flags)
rsb_err_t	rsb_mtx_get_prec (void opdp, const struct rsb_mtx_t mtxAp, rsb_precf_t prec_flags, const void *ipdp)
rsb_err_t	rsb_mtx_get_info (const struct rsb_mtx_t mtxAp, enum rsb_mif_t miflags, void minfop)
rsb_err_t	rsb_mtx_get_info_str (const struct rsb_mtx_t mtxAp, const rsb_char_t mis, void *minfop, size_t buflen)
rsb_err_t	rsb_mtx_get_nrm (const struct rsb_mtx_t mtxAp, void Np, enum rsb_extff_t flags)
rsb_err_t	rsb_mtx_get_vec (const struct rsb_mtx_t mtxAp, void Dp, enum rsb_extff_t flags)
rsb_time_t	rsb_time (void)
struct rsb_mtx_t *	rsb_mtx_alloc_from_coo_begin (rsb_nnz_idx_t nnzA, rsb_type_t typecode, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_flags_t flagsA, rsb_err_t *errvalp)
rsb_err_t	rsb_mtx_alloc_from_coo_end (struct rsb_mtx_t **mtxApp)
rsb_err_t	rsb_tune_spmm (struct rsb_mtx_t *mtxOpp, rsb_real_t sfp, rsb_int_t tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const void alphap, const struct rsb_mtx_t mtxAp, rsb_coo_idx_t nrhs, rsb_flags_t order, const void Bp, rsb_nnz_idx_t ldB, const void betap, void Cp, rsb_nnz_idx_t ldC)
rsb_err_t	rsb_tune_spsm (struct rsb_mtx_t *mtxOpp, rsb_real_t sfp, rsb_int_t tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const void alphap, const struct rsb_mtx_t mtxAp, rsb_coo_idx_t nrhs, rsb_flags_t order, const void Bp, rsb_nnz_idx_t ldB, const void betap, void Cp, rsb_nnz_idx_t ldC)

Detailed Description

The reference documentation of the \librsb library comes in both HTML and Unix man pages formats.
The following sections/man pages are available: The librsb library interface (rsb.h, optional ones rsb.hpp and rsb.F90) ; The Sparse BLAS interface to librsb (blas_sparse.h, rsb_blas_sparse.F90) ; Example programs and code.

In general, users of this library are interested in high performance sparse matrix computations on cache based shared memory parallel computers.
For this, \librsb offers a native C interface (here documented) and a Fortran one (in rsb.F90, equivalent to the C declaration headers from rsb.h), in addition to the Sparse BLAS one (both C and Fortran, documented).
Please refer to optional <rsb.hpp> for the C++ API.

Configuration, build, and installation instructions are contained in the README file distributed in the sources archive.

Typical C program structure

initialize \librsb with rsb_lib_init()
(in any order) allocate matrices (e.g.: with rsb_mtx_alloc_from_coo_inplace() or others); do any computation with them (e.g.: rsb_spmv(), rsb_spsv() ); converting matrices (e.g.: with rsb_mtx_switch_to_coo() ); freeing matrices (rsb_mtx_free() )
finalize \librsb with rsb_lib_exit()

Important usage notes

General C program structure Before calling any \librsb function, a program is required to initialize \librsb's internal status. This is done by calling rsb_lib_init() . Afterwards, any \librsb function can be safely used. When \librsb functions are not intended to be called anymore, a program may call rsb_lib_exit() to free any resource. Then, rsb_lib_init() should be called for further usage of \librsb.

Manipulating matrices and vectors In order to use \librsb, the user is not required to use explicitly any of \librsb's data structures: their manipulation is to be performed by \librsb functions. Therefore, knowledge of \librsb's matrix type (rsb_mtx_t) is not necessary at all: this structure is intended to be used as an opaque container.

On the contrary, arrays for numerical vectors (or more generally, dense matrices) are expected to be managed by the user: \librsb does not furnish any specific vector type. Computational functions treat dense vectors/matrices are simple arrays of a specified type; see the Example programs and code .

Computational functions This library can be configured at build time to support a custom subset of numerical types. To keep the programming interface compact, it has been decided to not replicate the computational functions to each numerical type. Instead, the type is expected to be specified by the user via a type flag. For instance, matrix assembly functions (e.g.: rsb_mtx_alloc_from_coo_const() ) accept a type information and keep it stored in the matrix structure. Therefore, computational functions (e.g.: rsb_spmv() ) can fetch this information from their rsb_mtx_t operand, and treat accordingly the other parameters (e.g.: alphap, Xp, ...). Mixed type operations are currently not supported.

Memory management

Matrix structures (rsb_mtx_t) allocated by \librsb shall be freed only via rsb_mtx_free() .

Benchmarking

If you want to benchmark this library, there are different possibilities:

#!/bin/bash
 
set -e
set -x
 
# the benchmark command assumes A.mtx is a file in Matrix Market format
rsbench -oa -Ob --bench --nmb -f pd.mtx
 
# it has many (librsb development-oriented) options
rsbench -oa -Ob --help
 
# this is mostly a development tool so don't rely on much more than the above.

Tuning and Customization

There are different ./configure options you may look at for tuning or customizing the library.

Macro Definition Documentation

◆ RSB_SIZEOF

#define RSB_SIZEOF ( TYPE )

Value:

RSB_NUMERICAL_TYPE_SIZE(TYPE)

Use RSB_SIZEOF macro to get the size (in bytes) of a type supported by the library (e.g.: when allocating numerical vectors).

Enumeration Type Documentation

◆ rsb_elopf_t

enum rsb_elopf_t

Flags for specifying a particular elemental/row-wise operation with rsb_mtx_upd_vals().

Enumerator
RSB_ELOPF_MUL	Elemental multiplication of the matrix by a specified scalar (usable with rsb_mtx_upd_vals(), binary operation).
RSB_ELOPF_DIV	Elemental division by a specified scalar (usable with rsb_mtx_upd_vals(), binary operation).
RSB_ELOPF_POW	Elemental power to a specified scalar (usable with rsb_mtx_upd_vals(), binary operation).
RSB_ELOPF_NEG	Elemental negation (usable with rsb_mtx_upd_vals(), unary operation).
RSB_ELOPF_SCALE_ROWS	Row wise scaling by a specified scaling vector (usable with rsb_mtx_upd_vals(), binary operation).
RSB_ELOPF_SCALE_COLS	Column wise scaling by a specified scaling vector (usable with rsb_mtx_upd_vals(), binary operation).
RSB_ELOPF_SCALE_ROWS_REAL	Row wise scaling by a specified scaling vector. If matrix is of a complex type, the argument is expected to be of the corresponding real type (assumed that that type has been enabled). (usable with rsb_mtx_upd_vals(), binary operation).
RSB_ELOPF_SCALE_COLS_REAL	Column wise scaling by a specified scaling vector. If matrix is of a complex type, the argument is expected to be of the corresponding real type (assumed that that type has been enabled). (usable with rsb_mtx_upd_vals(), binary operation).

◆ rsb_extff_t

enum rsb_extff_t

Extraction filter flags, to be used with rsb_mtx_get_nrm()/rsb_mtx_get_vec().

Enumerator
RSB_EXTF_NORM_ONE	rsb_mtx_get_nrm() flag value for computing the one-norm.
RSB_EXTF_NORM_TWO	rsb_mtx_get_nrm() flag value for computing the two-norm (Frobenius norm).
RSB_EXTF_NORM_INF	rsb_mtx_get_nrm() flag value for computing the infinity-norm.
RSB_EXTF_SUMS_ROW	rsb_mtx_get_vec() flag value for computing the sum along each row.
RSB_EXTF_SUMS_COL	rsb_mtx_get_vec() flag value for computing the sum along each column.
RSB_EXTF_ASUMS_ROW	rsb_mtx_get_vec() flag value for computing the absolute values sum, along each row.
RSB_EXTF_ASUMS_COL	rsb_mtx_get_vec() flag value for computing the absolute values sum, along each column.
RSB_EXTF_DIAG	rsb_mtx_get_vec() flag value for extracting the diagonal submatrix.

◆ rsb_mif_t

enum rsb_mif_t

Flags for getting matrix information via rsb_mtx_get_info()/rsb_mtx_get_info_str().

Enumerator
RSB_MIF_INDEX_STORAGE_IN_BYTES__TO__SIZE_T	Index storage occupation, in bytes. (size_t)
RSB_MIF_INDEX_STORAGE_IN_BYTES_PER_NNZ__TO__RSB_REAL_T	Index storage occupation per nnz, in bytes. (rsb_real_t)
RSB_MIF_MATRIX_ROWS__TO__RSB_COO_INDEX_T	Rows count(rsb_coo_idx_t)
RSB_MIF_MATRIX_COLS__TO__RSB_COO_INDEX_T	Columns count (rsb_coo_idx_t)
RSB_MIF_MATRIX_NNZ__TO__RSB_NNZ_INDEX_T	Nonzeroes count (rsb_nnz_idx_t)
RSB_MIF_TOTAL_SIZE__TO__SIZE_T	Total size, in bytes (size_t)
RSB_MIF_MATRIX_FLAGS__TO__RSB_FLAGS_T	Matrix flags (rsb_flags_t)
RSB_MIF_MATRIX_TYPECODE__TO__RSB_TYPE_T	Matrix type code (rsb_type_t)
RSB_MIF_MATRIX_INFO__TO__CHAR_P	Matrix info string, only for rsb_mtx_get_info_str() (rsb_char_t*)
RSB_MIF_LEAVES_COUNT__TO__RSB_BLK_INDEX_T	Leaf submatrices count (rsb_blk_idx_t)

◆ rsb_opt_t

enum rsb_opt_t

library option values for \see_lib_init_funcs.

Enumerator
RSB_IO_WANT_VERBOSE_INIT	RSB_IO_WANT_VERBOSE_INIT prompts for a verbose initialization of the library: messages will be written to the file descriptor (`FILE*`) pointed by the value pointer when calling rsb_lib_init or rsb_lib_reinit.
RSB_IO_WANT_VERBOSE_EXIT	RSB_IO_WANT_VERBOSE_EXIT prompts for a verbose finalization of the library: messages will be written to the file descriptor (`FILE*`) pointed by the value pointer when calling rsb_lib_exit.
RSB_IO_WANT_OUTPUT_STREAM	Specifies the default output stream. Output (debug info) info will be written to the file descriptor (`FILE*`) pointed by the value pointer.
RSB_IO_WANT_SORT_METHOD	Specifies the default sorting method. Specified as a pointed integer (rsb_int_t) number, in {[0],1}. (internal)
RSB_IO_WANT_CACHE_BLOCKING_METHOD	Specifies the default cache blocking method. Specified as a pointed integer (rsb_int_t) number, in {-1,[0],1}. (internal)
RSB_IO_WANT_SUBDIVISION_MULTIPLIER	Specifies a multiplier for finer (if >1.0) or coarser (if <1.0) subdivisions. Specified as a pointed (rsb_real_t) number, in {..,[1.0],..}. (internal)
RSB_IO_WANT_VERBOSE_ERRORS	Prompts for a verbose error reporting: messages will be written to the file descriptor (`FILE*`) pointed by the value pointer. Only meaningful if an interface error verbosity greater than 0 was set at configure time.
RSB_IO_WANT_BOUNDED_BOX_COMPUTATION	Prompts for bounded box computation, for a smoother submatrices locking; pointed rsb_int_t in {0,[1]}. (internal).
RSB_IO_WANT_EXECUTING_THREADS	Specifies the number of desired executing threads; pointed rsb_int_t in {[0],1,..}.
RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE	Specifies the level of interface verbosity; if setting, pointed rsb_int_t values should be in {[0],1,..}. Support may be enabled or disabled at build time via the `--enable-internals-error-verbosity` configure option. If disabled, only getting is supported and yields -1, but setting is not supported and the RSB_ERR_NO_STREAM_OUTPUT_CONFIGURED_OUT error will be returned.
RSB_IO_WANT_MEMORY_HIERARCHY_INFO_STRING	Specifies a custom memory hierarchy info string; pointed `const` rsb_char_t*; (may point to a NULL string pointer).
RSB_IO_WANT_IS_INITIALIZED_MARKER	Used for getting whether the library has been initialized (RSB_BOOL_TRUE) or not (RSB_BOOL_FALSE) ; pointed `const` rsb_bool_t*; (this is NOT for general users).
RSB_IO_WANT_MEM_ALLOC_CNT	Used for getting the count of memory allocations performed by librsb employing librsb's memory allocation wrapper (if disabled, will return zero); pointed `const` `size_t*`; (this is for debugging purposes).
RSB_IO_WANT_MEM_ALLOC_TOT	Used for getting the total amount of memory allocated by librsb employing librsb's memory allocation wrapper (if disabled, will return zero); pointed `const` `size_t*`; (this is for debugging purposes).
RSB_IO_WANT_LEAF_LEVEL_MULTIVEC	Specifies whether the default multi-vector ops shall act at a leaf level (default value of 0 is yes). Specified as a pointed integer (rsb_int_t) number, in {-1,[0]}. (internal)
RSB_IO_WANT_MAX_MEMORY_ALLOCATIONS	Specifies an upper limit to the count of allocated memory areas (default value of 0 means no limit). Specified as a pointed `size_t`. \rsb_configure_memwrap
RSB_IO_WANT_MAX_MEMORY_ALLOCATED	Specifies an upper limit to the amount of allocated memory (default value of 0 means no limit). Specified as a pointed `size_t`. \rsb_configure_memwrap
RSB_IO_WANT_LIBRSB_ETIME	Represents time spent in librsb. Specified as a pointed rsb_time_t. Only works if statistics collection (`--enable-librsb-stats`) was specified at configure time.
RSB_IO_WANT_VERBOSE_TUNING	Auto tuning verbosity level for rsb_tune_spmm/rsb_tune_spsm. If 0, no verbosity; if 1, verbose; if 2, verbose with trace files being dumped.

Function Documentation

◆ rsb_coo_cleanup()

rsb_err_t rsb_coo_cleanup	(	rsb_coo_idx_t *	nnzp,
		void *	VA,
		rsb_coo_idx_t *	IA,
		rsb_coo_idx_t *	JA,
		rsb_nnz_idx_t	nnzA,
		rsb_coo_idx_t	nrA,
		rsb_coo_idx_t	ncA,
		rsb_type_t	typecode,
		rsb_flags_t	flagsA )

Compacts the given COO input arrays representing a sparse matrix . Will either sum together duplicates or use the last one, depending on whether RSB_FLAG_DUPLICATES_KEEP_LAST or RSB_FLAG_DUPLICATES_SUM is present in flagsA.

It is important that the input is sorted and flagsA shall contain RSB_FLAG_SORTED_INPUT, otherwise the algorithm's complexity will be quadratic.

Parameters

nnzp	Pointer to the number of nonzeroes after the cleanup.
VA,IA,JA	Output numerical values (`VA`) array; output row (`IA`) and column (`JA`) indices arrays.
nnzA	The number of nonzeroes in the input arrays representing matrix .
nrA,ncA	The number of rows and columns of the sparse matrix .
typecode	A valid type code for the given (numerical array) input pointer (see matrix_type_symbols_section).
flagsA	A valid combination of matrix storage flags. If unsure, use RSB_FLAG_NOFLAGS.

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.

See also: rsb_time, rsb_coo_sort; rsb_coo_sort

Warning: This is an experimental librsb-1.3 function.

Note: By invoking with swapped IA and JA (and swapping nrA and ncA as well) one can obtain column major order.

Examples:

        rsb_err_t errval = RSB_ERR_NO_ERROR;
        rsb_nnz_idx_t nnzA = 4;
        const rsb_coo_idx_t  nrA = 4;
        const rsb_coo_idx_t  ncA = 4;
        rsb_coo_idx_t    IA[] = { 1, 1, 1, 2 };
        rsb_coo_idx_t    JA[] = { 1, 1, 3, 2 };
        RSB_DEFAULT_TYPE VA[] = { 1, 10, 13, 22 };
        const rsb_type_t typecode = RSB_NUMERICAL_TYPE_DEFAULT;
        rsb_flags_t flagsA = RSB_FLAG_DUPLICATES_SUM | RSB_FLAG_SORTED_INPUT;
        // IA={1,1,1,2} JA={1,1,3,2} VA={1,10,13,22} nnzA=4 nrA=4 nca=4
 
        if((errval = rsb_lib_init(RSB_NULL_INIT_OPTIONS))
                        != RSB_ERR_NO_ERROR) goto err;
 
        errval = rsb_coo_cleanup(&nnzA, VA, IA, JA,
                 nnzA, nrA, ncA, typecode, flagsA );
        if(errval != RSB_ERR_NO_ERROR )
        {
                printf("Error calling rsb_coo_cleanup!\n");
                goto err;
        }
        // IA={1,1,2} JA={1,3,2} VA={11,13,22} nnzA=3 nrA=4 nca=4

        rsb_err_t errval = RSB_ERR_NO_ERROR;
        rsb_nnz_idx_t nnzA = 3;
        const rsb_coo_idx_t  nrA = 2;
        const rsb_coo_idx_t  ncA = 2;
        rsb_coo_idx_t    IA[] = { 1, 1, 1 };
        rsb_coo_idx_t    JA[] = { 2, 1, 1 };
        RSB_DEFAULT_TYPE VA[] = { 1, 2, 3 };
        const rsb_type_t typecode = RSB_NUMERICAL_TYPE_DEFAULT;
        const rsb_flags_t flagsA = RSB_FLAG_DUPLICATES_SUM 
                        | RSB_FLAG_SORTED_INPUT
                        | RSB_FLAG_FORTRAN_INDICES_INTERFACE;
 
        // IA={1,1,1} JA={2,1,1} VA={1,2,3} nnzA=3 nrA=2 nca=2
        errval =rsb_coo_sort(VA, IA, JA, nnzA, nrA, ncA,  typecode, flagsA);
        if(errval != RSB_ERR_NO_ERROR )
        {
                printf("Error calling rsb_coo_cleanup!\n");
                goto err;
        }
        // IA={1,1,1} JA={1,1,2} VA={2,3,1} nnzA=3 nrA=2 nca=2
 
        errval = rsb_coo_cleanup(&nnzA, VA, IA, JA, nnzA,
                 nrA, ncA, typecode, flagsA );
        if(errval != RSB_ERR_NO_ERROR )
        {
                printf("Error calling rsb_coo_cleanup!\n");
                goto err;
        }
        // IA={1,1} JA={1,2} VA={5,1} nnzA=2 nrA=2 nca=2

◆ rsb_coo_sort()

rsb_err_t rsb_coo_sort	(	void *	VA,
		rsb_coo_idx_t *	IA,
		rsb_coo_idx_t *	JA,
		rsb_nnz_idx_t	nnzA,
		rsb_coo_idx_t	nrA,
		rsb_coo_idx_t	ncA,
		rsb_type_t	typecode,
		rsb_flags_t	flagsA )

Sorts row-major the given COO input arrays representing a sparse matrix .

Parameters

VA,IA,JA	Output numerical values (`VA`) array; output row (`IA`) and column (`JA`) indices arrays.
nnzA	The number of nonzeroes in the input arrays representing matrix .
nrA,ncA	The number of rows and columns of the sparse matrix . If any of nrA or ncA is zero, no sort occurs.
typecode	A valid type code for the given (numerical array) input pointer (see matrix_type_symbols_section).
flagsA	A valid combination of matrix storage flags. If unsure, use RSB_FLAG_NOFLAGS.

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.

See also: rsb_time, rsb_coo_sort

Note: By invoking with swapped IA and JA (and swapping nrA and ncA as well) one can obtain column major order.

◆ rsb_file_mtx_get_dims()

rsb_err_t rsb_file_mtx_get_dims	(	const char *	filename,
		rsb_coo_idx_t *	nrp,
		rsb_coo_idx_t *	ncp,
		rsb_coo_idx_t *	nzp,
		rsb_flags_t *	flagsp )

Reads structural information (dimensions, structural flags) for a matrix file into user specified (and optionally NULL) variables.

Parameters

filename	The specified matrix file name (cannot be `NULL`).
nrp,ncp	Output pointers to rows and columns count variables (can be `NULL`).
nzp	Output pointer to the nonzeroes count variable (can be `NULL`).
flagsp	Output pointer to the detected structural flags variable. Will be a combination of RSB_FLAG_LOWER, RSB_FLAG_UPPER, RSB_FLAG_SYMMETRIC, RSB_FLAG_HERMITIAN.

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error. If read dimensions are illegal (see rsb_coo_idx_t,rsb_nnz_idx_t), RSB_ERR_LIMITS will be returned.

Example getting dimensions of a sparse matrix stored in a Matrix Market file:

        if(RSB_ERR_NO_ERROR!=(errval =
                rsb_file_mtx_get_dims("pd.mtx",&nrA,&ncA,&nnzA,NULL)))
        {
                if(errval != RSB_ERR_UNSUPPORTED_FEATURE)
                        goto err; /* may have not configured what needed */
        }

Note

The only sparse matrix file format currently supported is Matrix Market. E.g.:

%%MatrixMarket matrix coordinate real symmetric
%
% A Hilbert Matrix of order 3, so with 3 rows, 3 columns, and 6 nonzeroes.
%
3 3 6
1 1 1.0
2 1 0.5
2 2 0.33
3 1 0.33
3 2 0.25
3 3 0.2

In the above example header on the first line, you can specify either real or complex or pattern for the numerical type. Either general, symmetric, hermitian can be specified for the structure. In case of pattern matrices, only coordinate indices will be loaded (saving pattern matrices is not yet supported); in case of real matrices, also one coefficient value will be saved/loaded; in the case of complex matrices, both the real and imaginary parts will be saved/loaded in addition to the indices.

Upper/lower flags will not be reported; hermitiannes do.

See also: rsb_mtx_get_coo, rsb_mtx_get_csr, rsb_mtx_get_rows_sparse, rsb_mtx_get_coo_block, rsb_mtx_get_prec, rsb_mtx_get_nrm, rsb_mtx_get_vec, rsb_file_mtx_get_dims, rsb_mtx_get_vals

◆ rsb_file_mtx_load()

struct rsb_mtx_t * rsb_file_mtx_load	(	const rsb_char_t *	filename,
		rsb_flags_t	flagsA,
		rsb_type_t	typecode,
		rsb_err_t *	errvalp )

Loads a sparse matrix from the specified matrix file, assembling it in the format specified by flags, using the numerical type representation as specified by the user. Extra input errors or warnings verbosity can be enabled via the ./configure --enable-internals-error-verbosity option.

Parameters

filename	The specified matrix file name (cannot be `NULL`).
flagsA	A valid combination of matrix storage flags.
typecode	A valid type code for the given (numerical array) input pointer (see matrix_type_symbols_section).
errvalp	An optional (can be `NULL`) pointer to rsb_err_t where the error status will be written to.

Returns: On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error, NULL.

Note

The only sparse matrix file format currently supported is Matrix Market. E.g.:

%%MatrixMarket matrix coordinate real symmetric
%
% A Hilbert Matrix of order 3, so with 3 rows, 3 columns, and 6 nonzeroes.
%
3 3 6
1 1 1.0
2 1 0.5
2 2 0.33
3 1 0.33
3 2 0.25
3 3 0.2

In the above example header on the first line, you can specify either real or complex or pattern for the numerical type. Either general, symmetric, hermitian can be specified for the structure. In case of pattern matrices, only coordinate indices will be loaded (saving pattern matrices is not yet supported); in case of real matrices, also one coefficient value will be saved/loaded; in the case of complex matrices, both the real and imaginary parts will be saved/loaded in addition to the indices.

Example loading a matrix from a Matrix Market file:

        mtxAp = rsb_file_mtx_load("pd.mtx",
                RSB_FLAG_NOFLAGS,typecode,NULL);
        if(!mtxAp)
        {
                return EXIT_FAILURE;
        }

See also: rsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_load

◆ rsb_file_mtx_rndr()

rsb_err_t rsb_file_mtx_rndr	(	void *	pmp,
		const char *	filename,
		rsb_coo_idx_t	pmlWidth,
		rsb_coo_idx_t	pmWidth,
		rsb_coo_idx_t	pmHeight,
		rsb_marf_t	rflags )

Renders as pixel map the matrix contained in a matrix file.

Parameters

pmp	Pixel map array pointer.
filename	The specified matrix file name (cannot be `NULL`).
pmlWidth	stride between lines (in pixels; no less than `pmWidth`).
pmWidth	Pixel map width (in pixels or points).
pmHeight	Pixel map height (in pixels or points).
rflags	The color mode; only RSB_MARF_RGB is supported for now (1 byte per channel, 3 channels — red, green, blue): this requires array `pmp` to be at least (3`pmlWidthpmHeight)` bytes large.

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.

Note: At the time being, pmlWidth is required to be equal to pmWidth.

Example rendering a matrix from a Matrix Market file to a pixelmap in memory:

        /* matrices can be rendered from file to a pixelmap as well */
        {
                unsigned char pixmap[3*2*2];
 
                if(RSB_ERR_NO_ERROR!=(errval =
                rsb_file_mtx_rndr(pixmap,"pd.mtx",2,2,2,RSB_MARF_RGB)))
                        goto err;
        }

See also: rsb_mtx_rndr, rsb_file_mtx_rndr

◆ rsb_file_mtx_save()

rsb_err_t rsb_file_mtx_save	(	const struct rsb_mtx_t *	mtxAp,
		const rsb_char_t *	filename )

Saves the given matrix to the specified matrix file.

Parameters

mtxAp	Valid `rsb_mtx_t` pointer to matrix representation.
filename	The specified output file name (if `NULL` or '' (the empty string), will write to standard output).

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.

Warning: Some structural info contained in the matrix structural flags may be lost in the output data.

Note

The only sparse matrix file format currently supported is Matrix Market. E.g.:

%%MatrixMarket matrix coordinate real symmetric
%
% A Hilbert Matrix of order 3, so with 3 rows, 3 columns, and 6 nonzeroes.
%
3 3 6
1 1 1.0
2 1 0.5
2 2 0.33
3 1 0.33
3 2 0.25
3 3 0.2

In the above example header on the first line, you can specify either real or complex or pattern for the numerical type. Either general, symmetric, hermitian can be specified for the structure. In case of pattern matrices, only coordinate indices will be loaded (saving pattern matrices is not yet supported); in case of real matrices, also one coefficient value will be saved/loaded; in the case of complex matrices, both the real and imaginary parts will be saved/loaded in addition to the indices.

Example, printing a matrix to standard output:

        if(RSB_ERR_NO_ERROR!=(errval = rsb_file_mtx_save(mtxAp,NULL)))
        {
                if(errval != RSB_ERR_UNSUPPORTED_FEATURE)
                        goto err;
        }

See also: rsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_load

◆ rsb_file_vec_load()

rsb_err_t rsb_file_vec_load	(	const rsb_char_t *	filename,
		rsb_type_t	typecode,
		void *	Yp,
		rsb_coo_idx_t *	yvlp )

Loads a dense vector from the specified file, using the numerical type representation as specified by the user. This function is intended to be called in two steps: first with Yp=NULL, in order to write the vector length to *yvlp ; then, with yvlp=NULL, to get Yp written.

Parameters

filename	The specified vector file name (cannot be `NULL`).
typecode	A valid type code for the given (numerical array) input pointer (see matrix_type_symbols_section).
Yp	The input array vector.
yvlp	An optional pointer (can be `NULL`). If supplied, vector length will be written here, and no vector will be read.

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.

Example loading vector matrix from file

        /* also vectors can be loaded */
        if(RSB_ERR_NO_ERROR!=(errval = 
                rsb_file_vec_load("vf.mtx",typecode,NULL,&vl )))
                goto err;
        /* we expect vf.mtx to be 6 rows long */
        if( vl != 6 )
        {
                goto err;
        }
 
        if(RSB_ERR_NO_ERROR!=(errval = 
                rsb_file_vec_load("vf.mtx",typecode,XV, NULL )))
                goto err;

Note

The only dense vector file format currently supported is Matrix Market. E.g.:

%%MatrixMarket matrix array complex general
% Test MatrixMarket file with a complex vector.
% Note: a blank line like the following is OK.

6           1
11.000000000000000E+000 12.000000000000000E+000 
21.000000000000000E+000 22.000000000000000E+000 
31.000000000000000E+000 32.000000000000000E+000 
41.000000000000000E+000 42.000000000000000E+000 
51.000000000000000E+000 52.000000000000000E+000 
61.000000000000000E+000 62.000000000000000E+000

In the above example header on the first line, you can specify either real or complex or pattern for the numerical type.

See also: rsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_load

◆ rsb_file_vec_save()

rsb_err_t rsb_file_vec_save	(	const rsb_char_t *	filename,
		rsb_type_t	typecode,
		const void *	Yp,
		rsb_coo_idx_t	yvl )

Saves a dense vector to the specified file, using the numerical type representation as specified by the user. This function assumes Yp!=NULL and yvl>0.

Parameters

filename	The specified vector file name (cannot be `NULL`).
typecode	A valid type code for the given (numerical array) input pointer (see matrix_type_symbols_section).
Yp	The output array vector.
yvl	Output vector length.

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.

Note

The only dense vector file format currently supported is Matrix Market. E.g.:

%%MatrixMarket matrix array complex general
% Test MatrixMarket file with a complex vector.
% Note: a blank line like the following is OK.

6           1
11.000000000000000E+000 12.000000000000000E+000 
21.000000000000000E+000 22.000000000000000E+000 
31.000000000000000E+000 32.000000000000000E+000 
41.000000000000000E+000 42.000000000000000E+000 
51.000000000000000E+000 52.000000000000000E+000 
61.000000000000000E+000 62.000000000000000E+000

In the above example header on the first line, you can specify either real or complex or pattern for the numerical type.

Example printing to standard output:

        errval = rsb_file_vec_save(NULL, typecode, X, nrA);
        if(errval != RSB_ERR_NO_ERROR )
        {
                printf("Error printing vector!\n");
                goto err;
        }

See also: rsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_load

◆ rsb_lib_exit()

rsb_err_t rsb_lib_exit ( struct rsb_initopts * iop )

Finalize librsb.
rsb_lib_exit should be called after having freed all matrices.
If not all of the data structures were properly deallocated before, this function may still attempt finalizing the library and return the RSB_ERR_MEMORY_LEAK error code (this depends on the --enable-allocator-wrapper configure time option). Any allocated memory will be lost (librsb does not keep track of allocated matrices).
Internal library state will be cleared. After this call, it is legal to initialize the library again, by calling rsb_lib_init().
On an error, the library state may be inconsistent, so it is advisable to either terminate program execution (rather than forcing a new initialization with rsb_lib_init()).
Parameter iop is reserved for future use; for now it is safe to pass RSB_NULL_EXIT_OPTIONS.
It should be safe to call rsb_lib_exit() more than once.

Parameters

iop	A pointer to a rsb_initopts structure with library options. It may be `NULL` (or better, RSB_NULL_INIT_OPTIONS/RSB_NULL_EXIT_OPTIONS) for specifying default options.

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.

An example snippet declaring an error variable accumulator at program's beginning:

rsb_err_t errval = RSB_ERR_NO_ERROR;

and finalizing the library at program's end:

        if((errval = rsb_lib_exit(RSB_NULL_EXIT_OPTIONS))
                        != RSB_ERR_NO_ERROR)
        {
                printf("Error finalizing the library!\n");
                goto err;
        }

See also: rsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or (deprecated) macros RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..

◆ rsb_lib_get_opt()

rsb_err_t rsb_lib_get_opt	(	enum rsb_opt_t	iof,
		void *	iop )

Gets value of a library option.
A value specified by the request flag iof will be fetched from the library internal state and *iop will be updated accordingly.

Parameters

iof	library options flags. See rsb_opt_t for a list of valid options.
iop	library options value output pointer (pointed location will be updated).

See also: RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP; rsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or (deprecated) macros RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..

◆ rsb_lib_init()

rsb_err_t rsb_lib_init ( struct rsb_initopts * iop )

This is the library initialization function.
It must be called only once before using any other library function.
It is allowed to call it again after rsb_lib_exit().
To fine-tune the library behaviour, one may specify a number of options via the iop parameter.
Options may be specified also after rsb_lib_init() by calling rsb_lib_reinit().
One may call RSB_REINIT_SINGLE_VALUE_GET with flag RSB_IO_WANT_IS_INITIALIZED_MARKER to verify whether the library has been initialized or not.
If the RSB_NUM_THREADS environment variable is set, rsb_lib_init() uses it and sets the number of active threads, thus overriding what detected by the OpenMP runtime (e.g. OMP_NUM_THREADS).

Parameters

iop	A pointer to a rsb_initopts structure with library options. It may be `NULL` (or better, RSB_NULL_INIT_OPTIONS/RSB_NULL_EXIT_OPTIONS) for specifying default options.

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.

An example snippet declaring an error variable accumulator at program's beginning:

rsb_err_t errval = RSB_ERR_NO_ERROR;

and initializing the library soon thereafter:

        if((errval = rsb_lib_init(RSB_NULL_INIT_OPTIONS)) != 
                        RSB_ERR_NO_ERROR)
        {
                printf("Error initializing the library!\n");
                goto err;
        }

See also: rsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or (deprecated) macros RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..

◆ rsb_lib_reinit()

rsb_err_t rsb_lib_reinit ( struct rsb_initopts * iop )

Changes the library operation options which were set at initialization time either by a user or as defaults.
Not all options may be supported, depending on build time library settings.
If an unsupported option was specified, an appropriate error (e.g.: RSB_ERR_UNSUPPORTED_OPERATION) will be returned.

On the first error, option processing is interrupted and the remaining options (if any) are not processed.
Program execution may continue safely even if an error code is returned (that is, library status should be consistent).

Parameters

iop	A pointer to a rsb_initopts structure with library options. It may be `NULL` (or better, RSB_NULL_INIT_OPTIONS/RSB_NULL_EXIT_OPTIONS) for specifying default options.

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.

        rsb_err_t errval = RSB_ERR_NO_ERROR;
        struct rsb_initopts io;
 
        rsb_int_t ione={1};
        enum rsb_opt_t keys[]={RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE};
        void*values[]={&ione};
        io.action=RSB_IO_SPECIFIER_SET;
        io.keys=keys;
        io.values=values;
        io.n_pairs=1;
 
        if((errval = rsb_lib_init(RSB_NULL_INIT_OPTIONS))
                        != RSB_ERR_NO_ERROR) goto err;
 
        // won't print anything
        if((errval = rsb_lib_reinit(&io))
                        != RSB_ERR_NO_ERROR) goto err;
 
        // may print verbose message (depends on configure)
        if((errval = rsb_lib_reinit(NULL))
                        != RSB_ERR_NO_ERROR) goto err;
 
        // may print verbose message (depends on configure)
        if((errval = rsb_lib_set_opt_str(
                "RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE","0"))
                        != RSB_ERR_NO_ERROR) goto err;
 
        // won't print anything anymore
        if((errval = rsb_lib_exit(&io))
                        != RSB_ERR_NO_ERROR) goto err;

See also: rsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or (deprecated) macros RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..

◆ rsb_lib_set_opt()

rsb_err_t rsb_lib_set_opt	(	enum rsb_opt_t	iof,
		const void *	iop )

Sets value of a library option.
A value specified by the request flag iof will be fetched from *iop and will be used to update the selected option in the library internal state.

Parameters

iof	library options flags. See rsb_opt_t for a list of valid options.
iop	library options value output pointer (pointed location will be updated).

Example snip:

                rsb_int_t evi=1; 
 
                /* Setting a single optional library parameter. */
                errval = rsb_lib_set_opt(
                        RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE, &evi);
                if(errval != RSB_ERR_NO_ERROR)
                {
                       /*! [Copy error message to string] */
                        char errbuf[256];
                        rsb_strerror_r(errval,&errbuf[0],sizeof(errbuf));
                        printf("Failed setting the"
                        " RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE"
                        " library option (reason string:\n%s).\n",errbuf);
                       /*! [Copy error message to string] */
                        if(errval&RSB_ERRS_UNSUPPORTED_FEATURES)
                        {
                          printf("This error may be safely ignored.\n");
                        }
                        else
                        {
                          printf("Some unexpected error occurred!\n");
                          goto err;
                        }
                }
                else
                {
                        printf("Setting back the "
                                "RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE"
                                " library option.\n");
                        evi = 0;
                        errval = rsb_lib_set_opt(RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE,
                                        &evi);
                        errval = RSB_ERR_NO_ERROR;
                }

See also: RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP; rsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or (deprecated) macros RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..

◆ rsb_lib_set_opt_str()

rsb_err_t rsb_lib_set_opt_str	(	const rsb_char_t *	opnp,
		const rsb_char_t *	opvp )

Specifies individual library options in order to fine-tune the library behaviour.
Both the option name and the value shall be expressed as strings, identical to their preprocessor identifiers (see rsb_opt_t ). The opnp string will be translated internally to the corresponding request flag values, and the passed value will be parsed out of the opvp string.

Parameters

opnp	A pointer to a library option input name string (may not be `NULL`).
opvp	A pointer to a library option input value string (may not be `NULL`).

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.

        rsb_err_t errval = RSB_ERR_NO_ERROR;
        struct rsb_initopts io;
 
        rsb_int_t ione={1};
        enum rsb_opt_t keys[]={RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE};
        void*values[]={&ione};
        io.action=RSB_IO_SPECIFIER_SET;
        io.keys=keys;
        io.values=values;
        io.n_pairs=1;
 
        if((errval = rsb_lib_init(RSB_NULL_INIT_OPTIONS))
                        != RSB_ERR_NO_ERROR) goto err;
 
        // won't print anything
        if((errval = rsb_lib_reinit(&io))
                        != RSB_ERR_NO_ERROR) goto err;
 
        // may print verbose message (depends on configure)
        if((errval = rsb_lib_reinit(NULL))
                        != RSB_ERR_NO_ERROR) goto err;
 
        // may print verbose message (depends on configure)
        if((errval = rsb_lib_set_opt_str(
                "RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE","0"))
                        != RSB_ERR_NO_ERROR) goto err;
 
        // won't print anything anymore
        if((errval = rsb_lib_exit(&io))
                        != RSB_ERR_NO_ERROR) goto err;

See also: rsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or (deprecated) macros RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..

◆ rsb_mtx_add_to_dense()

rsb_err_t rsb_mtx_add_to_dense	(	const void *	alphap,
		const struct rsb_mtx_t *	mtxAp,
		rsb_nnz_idx_t	ldB,
		rsb_nnz_idx_t	nrB,
		rsb_nnz_idx_t	ncB,
		rsb_bool_t	rowmajorB,
		void *	Bp )

Dense matrix B is updated by adding scaled sparse matrix to it: $B \leftarrow B + \alpha {A}$

Parameters

alphap	Optional pointer (if `NULL`, will default to 1) to a numerical value (of the same type as matrix).
mtxAp	Valid `rsb_mtx_t` pointer to matrix representation.
ldB	Leading dimension of `Bp` array.
nrB,ncB	The number of rows and columns for the dense matrix .
rowmajorB	RSB_BOOL_TRUE if the dense matrix is considered stored as row major, or RSB_BOOL_FALSE if as column major.
Bp	Array representing the dense matrix .

Returns: RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.

Example snip:

        const rsb_nnz_idx_t ldB = 4, nrB = 3, ncB = 3;
        const rsb_bool_t rowmajorB = RSB_BOOL_TRUE;
        RSB_DEFAULT_TYPE Bp[ /*ldB*nrB*/ ] = {
                -1, -1, -1, -1,
                -1, -1, -1, -1,
                -1, -1, -1, -1
        };
        RSB_DEFAULT_TYPE *alphap = NULL;
 
        errval = rsb_mtx_add_to_dense(alphap, mtxAp, ldB,
                 nrB, ncB, rowmajorB, Bp);
        if(errval != RSB_ERR_NO_ERROR )
        {
                printf("Error calling rsb_mtx_add_to_dense!\n");
                goto err;
        }
 

Note: Please note that it suffices to 'transpose' Bp's description parameters to get transposed summed in.; Symmetry is currently not expanded.; Threaded, for large enough matrices.

See also: rsb_spmsp_to_dense, rsb_sppsp, rsb_spmsp, rsb_mtx_add_to_dense

◆ rsb_mtx_alloc_from_coo_begin()

struct rsb_mtx_t * rsb_mtx_alloc_from_coo_begin	(	rsb_nnz_idx_t	nnzA,
		rsb_type_t	typecode,
		rsb_coo_idx_t	nrA,
		rsb_coo_idx_t	ncA,
		rsb_flags_t	flagsA,
		rsb_err_t *	errvalp )

Creates an empty matrix structure in assembly state. The user then populates it using rsb_mtx_set_vals() repeatedly; then assembles it with rsb_mtx_alloc_from_coo_end().

Parameters

nnzA	A rough estimate of the number of nonzeroes matrix will host (used for optimizing arrays allocation). If you do not know yet, you can specify zero.
typecode	A valid type code for the given (numerical array) input pointer (see matrix_type_symbols_section).
nrA,ncA	The number of rows and columns of the sparse matrix .
flagsA	A valid combination of index conversion and matrix storage flags and other meaningful flags. The encouraged base choice here is RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS. If Fortran (1 based) indices are being used for the IA, JA arrays, then the RSB_FLAG_FORTRAN_INDICES_INTERFACE flag should be added. If symmetric storage is desired, then RSB_FLAG_SYMMETRIC (or RSB_FLAG_HERMITIAN, for Hermitian matrices) is necessary, in combination with either RSB_FLAG_LOWER or RSB_FLAG_UPPER. If you intend to use this matrix for triangular solution (e.g.: rsb_spsv()/rsb_spsm()), it needs to be triangular and specified with either RSB_FLAG_LOWER_TRIANGULAR or RSB_FLAG_UPPER_TRIANGULAR, and not have RSB_FLAG_LOWER_SYMMETRIC or RSB_FLAG_LOWER_HERMITIAN. Nonzeroes non complying with the specified flags will be ignored. If a matrix is both RSB_FLAG_LOWER_TRIANGULAR and RSB_FLAG_UPPER_TRIANGULAR at the same time, then it's diagonal, for which shorthand: RSB_FLAG_DIAGONAL can be used. If RSB_FLAG_UNIT_DIAG_IMPLICIT is present, diagonal entries will be not represented but assumed to be unitary. If RSB_FLAG_DUPLICATES_SUM is present, duplicate entries will be summed together. If RSB_FLAG_DISCARD_ZEROS is present, zeroes will be discarded.
errvalp	An optional (can be `NULL`) pointer to rsb_err_t where the error status will be written to.

Returns: Pointer to a rsb_mtx_t matrix structure in assembly state, or NULL (on error).

Warning: This function has not been thoroughly tested.

See also: rsb_mtx_alloc_from_coo_const, rsb_mtx_alloc_from_coo_inplace, rsb_mtx_free, rsb_mtx_clone, rsb_mtx_alloc_from_csr_const, rsb_mtx_alloc_from_csc_const, rsb_mtx_alloc_from_csr_inplace, rsb_mtx_switch_to_csr, rsb_mtx_alloc_from_coo_begin, rsb_mtx_alloc_from_coo_end

◆ rsb_mtx_alloc_from_coo_const()

struct rsb_mtx_t * rsb_mtx_alloc_from_coo_const	(	const void *	VA,
		const rsb_coo_idx_t *	IA,
		const rsb_coo_idx_t *	JA,
		rsb_nnz_idx_t	nnzA,
		rsb_type_t	typecode,
		rsb_coo_idx_t	nrA,
		rsb_coo_idx_t	ncA,
		rsb_blk_idx_t	brA,
		rsb_blk_idx_t	bcA,
		rsb_flags_t	flagsA,
		rsb_err_t *	errvalp )

Given as input COO arrays VA,IA,JA, allocates and assembles an RSB matrix using separate arrays.

Parameters

VA,IA,JA	Input numerical values (`VA`) array; row (`IA`) and column (`JA`) input indices arrays.
nnzA	The number of nonzeroes in the input arrays representing matrix .
typecode	A valid type code for the given (numerical array) input pointer (see matrix_type_symbols_section).
nrA,ncA	The number of rows and columns of the sparse matrix . If any of nrA or ncA is zero, it will be detected on the basis of the `IA` and `JA` arrays and flagsA.
brA,bcA	Blocking parameters: `brA` should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused, reserved for future use); `bcA` should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused, reserved for future use).
flagsA	A valid combination of index conversion and matrix storage flags and other meaningful flags. The encouraged base choice here is RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS. If Fortran (1 based) indices are being used for the IA, JA arrays, then the RSB_FLAG_FORTRAN_INDICES_INTERFACE flag should be added. If symmetric storage is desired, then RSB_FLAG_SYMMETRIC (or RSB_FLAG_HERMITIAN, for Hermitian matrices) is necessary, in combination with either RSB_FLAG_LOWER or

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ RSB_SIZEOF

Enumeration Type Documentation

◆ rsb_elopf_t

◆ rsb_extff_t

◆ rsb_mif_t

◆ rsb_opt_t

Function Documentation

◆ rsb_coo_cleanup()

◆ rsb_coo_sort()

◆ rsb_file_mtx_get_dims()

◆ rsb_file_mtx_load()

◆ rsb_file_mtx_rndr()

◆ rsb_file_mtx_save()

◆ rsb_file_vec_load()

◆ rsb_file_vec_save()

◆ rsb_lib_exit()

◆ rsb_lib_get_opt()

◆ rsb_lib_init()

◆ rsb_lib_reinit()

◆ rsb_lib_set_opt()

◆ rsb_lib_set_opt_str()

◆ rsb_mtx_add_to_dense()

◆ rsb_mtx_alloc_from_coo_begin()

◆ rsb_mtx_alloc_from_coo_const()