rsb.h(3)
The librsb library interface (rsb.h, optional ones rsb.hpp and rsb.F90)
Description
rsb.h
NAME
librsb - rsb.h - The librsb library interface (rsb.h, optional ones rsb.hpp and rsb.F90)
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.
SYNOPSIS
Macros
#define RSB_SIZEOF(TYPE) RSB_NUMERICAL_TYPE_SIZE(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 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..
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().
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().
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().
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
#define RSB_SIZEOF(TYPE) 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
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).
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.
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)
enum rsb_opt_t
library option values for
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..
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. Only works if the memory wrapper (--enable-allocator-wrapper) has been specified at configure time.
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. Only works if the memory wrapper (--enable-allocator-wrapper) has been specified at configure time.
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_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 $A$. 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 $A$.
nrA,ncA The number of rows and columns of the sparse
matrix $A$.
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!0);
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!0);
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!0);
goto err;
}
// IA={1,1} JA={1,2} VA={5,1} nnzA=2 nrA=2 nca=2
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_ttypecode, rsb_flags_t flagsA)
Sorts row-major the given COO
input arrays representing a sparse matrix $A$.
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 $A$.
nrA,ncA The number of rows and columns of the sparse
matrix $A$. 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_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
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_err_t rsb_file_mtx_rndr (void * pmp, const char * filename, rsb_coo_idx_tpmlWidth, 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*pmlWidth*pmHeight) 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_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 $A$ 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_err_t rsb_file_vec_load (const rsb_char_t * filename, rsb_type_ttypecode, 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_err_t rsb_file_vec_save (const rsb_char_t * filename, rsb_type_ttypecode, 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!0);
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_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!0);
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_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_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!0);
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_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_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:1s).0,errbuf);
/*! [Copy error message to string] */
if(errval&RSB_ERRS_UNSUPPORTED_FEATURES)
{
printf("This error may be safely ignored.0);
}
else
{
printf("Some unexpected error occurred!0);
goto err;
}
}
else
{
printf("Setting back the "
"RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE"
" library option.0);
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_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_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_trowmajorB, void * Bp)
Dense matrix B is updated by
adding scaled sparse matrix ${A}$ to it: $B <- 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 $A$
representation.
ldB Leading dimension of Bp array.
nrB,ncB The number of rows and columns for the dense
matrix $B$.
rowmajorB RSB_BOOL_TRUE if the dense matrix $B$
is considered stored as row major, or RSB_BOOL_FALSE
if as column major.
Bp Array representing the dense matrix $B$.
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!0);
goto err;
}
Note
Please note that it suffices to
’transpose’ Bp’s description parameters to
get $A$ 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
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_tflagsA, 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 $A$ 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 $A$.
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
struct rsb_mtx_t * rsb_mtx_alloc_from_coo_const (const void * VA, constrsb_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_tbrA, 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 $A$.
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 $A$. 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 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
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error, NULL.
Example snip:
mtxAp = rsb_mtx_alloc_from_coo_const(
VA,IA,JA,nnzA,typecode,nrA,ncA,
brA,bcA,RSB_FLAG_NOFLAGS,NULL);
if(!mtxAp)
{
return EXIT_FAILURE;
}
And another,
with duplicate sum flags:
mtxAp = rsb_mtx_alloc_from_coo_const(
VA,IA,JA,nnzA,typecode,nrA,ncA,brA,bcA,
RSB_FLAG_NOFLAGS /* default format will be chosen */
|RSB_FLAG_DUPLICATES_SUM/* duplicates will be summed */
,&errval);
if((!mtxAp) || (errval != RSB_ERR_NO_ERROR))
{
printf("Error while allocating the matrix!0);
goto err;
}
And yet another,
allocating a triangular matrix:
mtxAp = rsb_mtx_alloc_from_coo_const(
VA,IA,JA,nnzA,typecode,nrA,ncA,brA,bcA,
RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS /* force rsb */
| RSB_FLAG_DUPLICATES_SUM/* sum dups */
| RSB_FLAG_UNIT_DIAG_IMPLICIT/* ask diagonal implicit */
| RSB_FLAG_TRIANGULAR /* need triangle for spsv */
, &errval);
if((!mtxAp) || (errval != RSB_ERR_NO_ERROR))
{
printf("Error while allocating the matrix!0);
goto err;
}
printf("Correctly allocated a matrix with %ld
nonzeroes.0,
(long int)nnzA);
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_err_t rsb_mtx_alloc_from_coo_end (struct rsb_mtx_t ** mtxApp)
Assembles RSB arrays for a
matrix in build state created with
rsb_mtx_alloc_from_coo_begin() and populated with
rsb_mtx_set_vals().
After assembly, any operation on the matrix is allowed.
Parameters
mtxApp rsb_mtx_t pointer to an unassembled matrix address.
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
This function has not been thoroughly tested.
Note
Note that the memory location of the matrix will be changed by this call, and the (old) *mtxApp address value will be not valid anymore.
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
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)
Given as input COO arrays
VA,IA,JA, allocates and assembles an RSB matrix reusing
input arrays.
Assumes all three VA,IA,JA arrays are at least
max(nnzA,nrA+1,ncA+1) sized. The user is expected NOT to use
these arrays until the matrix has been destroyed with
rsb_mtx_free(). Then, it is possible to use these
arrays again.
Parameters
VA,IA,JA Input/output
numerical values array (VA); row (IA) and column (JA)
indices arrays.
nnzA The number of nonzeroes in the input arrays
representing matrix $A$.
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 $A$.
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 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
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error, NULL.
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
struct rsb_mtx_t * rsb_mtx_alloc_from_csc_const (const void * VA, constrsb_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_tbrA, rsb_blk_idx_t bcA, rsb_flags_t flagsA, rsb_err_t * errvalp)
Given input read only CSC format
arrays, allocates and assembles an RSB matrix (stored in
separate arrays).
Parameters
VA,IA,CP Input numerical
values (VA) array, input row indices (IA) and compressed
column (CP) indices arrays.
nnzA The number of nonzeroes in the input arrays
representing matrix $A$.
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 $A$.
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 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
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error, NULL.
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
Example:
rsb_err_t errval = RSB_ERR_NO_ERROR;
struct rsb_mtx_t *mtxAp = NULL;
const rsb_blk_idx_t brA = RSB_DEFAULT_BLOCKING,
bcA = RSB_DEFAULT_BLOCKING;
const rsb_nnz_idx_t nnzA = 4;
const rsb_coo_idx_t nrA = 3;
const rsb_coo_idx_t ncA = 3;
const rsb_coo_idx_t IA[] = { 0, 2, 1, 2 };
const rsb_coo_idx_t CP[] = { 0, 2, 3, 4 };
const RSB_DEFAULT_TYPE VA[] = { 11, 31, 22, 33 };
const rsb_type_t typecode = RSB_NUMERICAL_TYPE_DEFAULT;
if(rsb_lib_init(RSB_NULL_INIT_OPTIONS)!=RSB_ERR_NO_ERROR)
{
return EXIT_FAILURE;
}
mtxAp =
rsb_mtx_alloc_from_csc_const(
VA,IA,CP,nnzA,typecode,nrA,ncA,
brA,bcA,RSB_FLAG_NOFLAGS,NULL);
if(!mtxAp)
{
return EXIT_FAILURE;
}
rsb_file_mtx_save(mtxAp, NULL);
struct rsb_mtx_t * rsb_mtx_alloc_from_csr_const (const void * VA, constrsb_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_tbrA, rsb_blk_idx_t bcA, rsb_flags_t flagsA, rsb_err_t * errvalp)
Given input read
only CSR format arrays, allocates and assembles an RSB
matrix (stored in separate arrays).
Parameters
VA,RP,JA Input numerical
values (VA) array; compressed rows (RP) and column (JA)
input indices arrays.
nnzA The number of nonzeroes in the input arrays
representing matrix $A$.
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 $A$.
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 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
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error, NULL.
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
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)
Given as input CSR arrays
VA,RP,JA , allocates and assembles an RSB matrix reusing
input arrays.
Assumes all three VA,IA,JA arrays are at least
max(nnzA,nrA+1,ncA+1) sized. The user is expected NOT to use
these arrays until the matrix has been destroyed with
rsb_mtx_free(). Then, it is possible to use these
arrays again.
Parameters
VA,RP,JA Input numerical
values (VA) array; compressed rows (RP) and column (JA)
input indices arrays. Will not be freed by
rsb_mtx_free().
nnzA The number of nonzeroes in the input arrays
representing matrix $A$.
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 $A$.
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 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
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error, NULL.
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_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)
This function clones a given
matrix, allocating a fresh data structure or overwriting an
existing one.
Target type (specified by typecode) can be different from
that in the matrix. If alphap=NULL, the cloned matrix will
not be scaled.
This new structure will be completely separated and
independent from the original one.
Examples:
// will clone the matrix exactly
errval =
rsb_mtx_clone(&mtxBp,RSB_NUMERICAL_TYPE_SAME_TYPE,RSB_TRANSPOSITION_N,NULL,mtxAp,RSB_FLAG_IDENTICAL_FLAGS);
// will clone the transpose of the matrix
errval =
rsb_mtx_clone(&mtxBp,RSB_NUMERICAL_TYPE_SAME_TYPE,RSB_TRANSPOSITION_T,NULL,mtxAp,RSB_FLAG_IDENTICAL_FLAGS);
// will clone the lower triangle of the matrix
errval =
rsb_mtx_clone(&mtxBp,RSB_NUMERICAL_TYPE_SAME_TYPE,RSB_TRANSPOSITION_N,NULL,mtxAp,RSB_FLAG_TRIANGULAR|RSB_FLAG_LOWER);
Parameters
mtxBpp Valid rsb_mtx_t
pointer to an address for matrix $B$. If *mtxBpp==NULL, a
fresh clone will be assigned there; if not, the existing
matrix structure will be freed and allocated to host the new
one. The case *mtxBpp==mtxAp is supported.
typecode A valid type code for the desired output matrix
(see matrix_type_symbols_section).
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to
a numerical value for scaling the output. Of the type code
of mtxAp.
mtxAp Valid rsb_mtx_t pointer to matrix $A$
representation.
flags Either RSB_FLAG_IDENTICAL_FLAGS or a
combination of other flags, e.g.:
RSB_FLAG_C_INDICES_INTERFACE,
RSB_FLAG_SYMMETRIC, RSB_FLAG_HERMITIAN,
RSB_FLAG_TRIANGULAR, RSB_FLAG_UPPER,
RSB_FLAG_LOWER, RSB_FLAG_UNIT_DIAG_IMPLICIT,
RSB_FLAG_DISCARD_ZEROS. Flag
RSB_FLAG_EXTERNALLY_ALLOCATED_ARRAYS is forbidden.
Flag RSB_FLAG_FORTRAN_INDICES_INTERFACE is
ignored.
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:
if( RSB_ERR_NO_ERROR != (errval =
rsb_mtx_clone(&mtxAp,RSB_NUMERICAL_TYPE_SAME_TYPE,
RSB_TRANSPOSITION_T,NULL,mtxAp,RSB_FLAG_IDENTICAL_FLAGS)))
{
goto err;
}
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
struct rsb_mtx_t * rsb_mtx_free (struct rsb_mtx_t * mtxAp)
Frees a previously allocated
sparse matrix structure.
In the case the matrix has the
RSB_FLAG_EXTERNALLY_ALLOCATED_ARRAYS flag, the main
three data arrays VA,IA,JA will not be freed by
rsb_mtx_free (see
rsb_mtx_alloc_from_coo_inplace,rsb_mtx_alloc_from_csr_inplace).
Parameters
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
Returns
Always NULL.
Example freeing a sparse matrix:
rsb_mtx_free(mtxAp);
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_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)
Returns the matrix converted in
a coordinate storage format.
Elements will be stored in no particular order.
If there are structural or fill-in zero elements, these will
be skipped.
Writes as many entries as there are nonzeroes (use
rsb_mtx_get_info(mtxAp,RSB_MIF_MATRIX_NNZ__TO__RSB_NNZ_INDEX_T,&nnz))
to find out how many in order to allocate the arrays
correctly.
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
VA,IA,JA Output numerical values (VA) array; output row
(IA) and column (JA) indices arrays.
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE
or RSB_FLAG_C_INDICES_INTERFACE (see
flags_section flags section).
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_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_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_tlrA, 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)
Writes in COO format the
specified submatrix.
Works in two stages: first the user invokes it with VA,IA,JA
set to NULL to get *rnzp. Then the VA,IA,JA arrays can be
allocated, and the function called again, this time with
rnzp=NULL but the VA,IA,JA arrays pointers non NULL (or at
least, one of them).
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
VA,IA,JA Output numerical values (VA) array; output row
(IA) and column (JA) indices arrays.
frA,lrA First and last row indices.
fcA,lcA First and last column indices.
IREN,JREN Renumbering arrays for IA and JA (respectively
rows count and columns count sized). If NULL, no renumbering
will be used.
rnzp A pointer where the number of relevant nonzero
elements will be written to.
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE
or RSB_FLAG_C_INDICES_INTERFACE (see
flags_section flags section).
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.
Examples:
rsb_coo_idx_t nzi;
rsb_coo_idx_t *IA = NULL;
rsb_coo_idx_t *JA = NULL;
const rsb_coo_idx_t IREN[]={0,1,2,3};
const rsb_coo_idx_t JREN[]={3,2,1,0};
RSB_DEFAULT_TYPE *VA = NULL;
const size_t so = sizeof(RSB_DEFAULT_TYPE);
const size_t si = sizeof(rsb_coo_idx_t);
rsb_err_t errval;
rsb_flags_t flagsA = RSB_FLAG_NOFLAGS;
rsb_nnz_idx_t rnz = 0;
rsb_coo_idx_t frA=0,lrA=1; // first two rows
rsb_coo_idx_t fcA=0,lcA=4; // 5 (all) columns
// get the nnz
count only
errval=rsb_mtx_get_coo_block
(mtxAp,NULL,NULL,NULL,frA,lrA,fcA,lcA,NULL,NULL,&rnz,flagsA);
if(errval != RSB_ERR_NO_ERROR )
goto err;
// allocate VA,
IA, JA to rnz elements
IA = calloc(rnz, si);
JA = calloc(rnz, si);
VA = calloc(rnz, so);
// get the rnz
values then
errval=rsb_mtx_get_coo_block
(mtxAp, VA, IA, JA,frA,lrA,fcA,lcA,NULL,NULL,NULL,flagsA);
if(errval != RSB_ERR_NO_ERROR )
goto err;
for(nzi=0;nzi<rnz;++nzi)
printf("%d/%d %d %d -> %d0,(int)nzi,(int)rnz,
(int)IA[nzi],(int)JA[nzi],(int)VA[nzi]);
// get the rnz
values again, renumbered
errval=rsb_mtx_get_coo_block
(mtxAp, VA, IA, JA,frA,lrA,fcA,lcA,IREN,JREN,NULL,flagsA);
if(errval != RSB_ERR_NO_ERROR )
goto err;
for(nzi=0;nzi<rnz;++nzi)
printf("%d/%d %d %d -> %d0,(int)nzi,(int)rnz,
(int)IA[nzi],(int)JA[nzi],(int)VA[nzi]);
free(VA);
free(IA);
free(JA);
And other
examples:
// get nnz count first
errval=rsb_mtx_get_coo_block(mtxAp,NULL,NULL,NULL,frA,lrA,fcA,lcA,NULL,NULL,&rnz,flags
)
// allocate VA, IA, JA to rnz elements
...
// get the rnz values then
errval=rsb_mtx_get_coo_block(mtxAp, VA, IA,
JA,frA,lrA,fcA,lcA,NULL,NULL,NULL,flags )
Warning
Expect this function to change soon (e.g.: have scaling parameters, etc.). Contact the author if you intend to use it.
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_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_tflags)
Fills the given arrays with the
matrix expressed in the CSR format.
Parameters
typecode A valid type
code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
mtxAp Valid rsb_mtx_t pointer to matrix $A$
representation.
VA,RP,JA Output numerical values (VA) array, compressed
row indices (RP) and column indices (JA) arrays.
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE
or RSB_FLAG_C_INDICES_INTERFACE (see
flags_section flags section).
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_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_err_t rsb_mtx_get_info (const struct rsb_mtx_t * mtxAp, enum rsb_mif_tmiflags, void * minfop)
Returns a specified matrix
(numerical) property.
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
miflags A valid value of matrix info flags (see
rsb_mif_t for valid values).
minfop Pointer to a variable of the right type,
according to the matrix info flag specification (see
rsb_mif_t).
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:
rsb_real_t isopnnz;
const enum rsb_mif_t miflags =
RSB_MIF_INDEX_STORAGE_IN_BYTES_PER_NNZ__TO__RSB_REAL_T;
errval = rsb_mtx_get_info(mtxAp, miflags, &isopnnz);
if(errval !=
RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_get_info!0);
goto err;
}
printf("RSB matrix uses %lf bytes per
nnz.0,(double)isopnnz);
See also
rsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_load
rsb_err_t rsb_mtx_get_info_str (const struct rsb_mtx_t * mtxAp, constrsb_char_t * mis, void * minfop, size_t buflen)
Returns a specified matrix
(numerical) property, via a string form query.
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
mis A string specifying any identifier among the matrix
info ones. See rsb_mif_t for a list of valid
identifiers that can be supplied in string form.
minfop Pointer to a variable of the right type,
according to the matrix info flag specification (see
rsb_mif_t).
buflen If greater than 0, minfop will be treated as a
string of length buflen and filled with the desired value
via the standard snprintf() function.
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:
rsb_mtx_get_info_str(mtxAp,"RSB_MIF_MATRIX_INFO__TO__CHAR_P",
ib,sizeof(ib));
printf("%s",ib);
See also
rsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_load
rsb_err_t rsb_mtx_get_nrm (const struct rsb_mtx_t * mtxAp, void * Np, enumrsb_extff_t flags)
Computes a matrix norm (either
infinite-norm or or 2-norm or 1-norm).
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
Np Points to a scalar value which will be overwritten
with the selected norm.
flags Either RSB_EXTF_NORM_ONE or
RSB_EXTF_NORM_TWO or RSB_EXTF_NORM_INF.
In case of a complex type, only
the real part will be written to Np.
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_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_err_t rsb_mtx_get_prec (void * opdp, const struct rsb_mtx_t * mtxAp,rsb_precf_t prec_flags, const void * ipdp)
A function computing a simple
preconditioner out of mtxAp.
Parameters
opdp Preconditioner data
pointer (output).
mtxAp Valid rsb_mtx_t pointer to matrix $A$
representation.
prec_flags Valid preconditioner request flags
(currently, only RSB_PRECF_ILU0 is supported; for it,
*opdp will be overwritten with two rsb_mtx_t pointers,
respectively a lower and an upper matrix.).
ipdp Preconditioner data pointer (input) (ignored at the
moment).
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:
struct rsb_mtx_t *mtxAp = NULL; /* matrix structure pointer
*/
struct rsb_mtx_t *mtxLUp [2]; /* matrix structure pointer */
rsb_precf_t prec_flags = RSB_PRECF_ILU0;
if((errval =
rsb_lib_init(RSB_NULL_INIT_OPTIONS)) !=
RSB_ERR_NO_ERROR)
{
printf("Error initializing the library!0);
goto err;
}
mtxAp =
rsb_mtx_alloc_from_coo_const(
VA,IA,JA,nnzA,typecode,nrA,ncA,brA,bcA,
RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS /* force rsb */
| RSB_FLAG_DUPLICATES_SUM /* sum dups */
| RSB_FLAG_TRIANGULAR /* need triangle for spsv */
, &errval);
if((!mtxAp) ||
(errval != RSB_ERR_NO_ERROR))
{
printf("Error while allocating the matrix!0);
goto err;
}
errval =
rsb_mtx_get_prec(mtxLUp,mtxAp, prec_flags, NULL);
if( errval != RSB_ERR_NO_ERROR )
{
printf("Error while calling rsb_mtx_get_prec!0);
goto err;
}
// ...
rsb_mtx_free(mtxLUp[0]);
rsb_mtx_free(mtxLUp[1]);
rsb_mtx_free(mtxAp );
Note
Matrix should be square, have at least two rows, and have at least one nonzero.
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_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)
Writes to the given COO arrays
the specified submatrix.
Invoke with VA,IA,JA set to NULL in order to get the
nonzeroes count written to *rnzp, and know how large the
arrays should be.
IA can be NULL (in this case it will be ignored). The
written rows are ordered.
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
VA,IA,JA Output numerical values (VA) array; input row
(IA) and column (JA) indices arrays.
frA,lrA First and last row indices.
rnzp A pointer where the number of relevant nonzero
elements will be written to.
alphap Optional pointer (if NULL, will default to 1) to
a numerical value (of the same type as matrix).
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE
or RSB_FLAG_C_INDICES_INTERFACE (see
flags_section flags section).
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:
rsb_coo_idx_t IA[] = { 0, 0, 0, 0 };
rsb_coo_idx_t JA[] = { 0, 0, 0, 0 };
RSB_DEFAULT_TYPE VA[] = { -1, -1, -1, -1 };
rsb_trans_t transA = RSB_TRANSPOSITION_N;
const rsb_coo_idx_t frA = 2, lrA = 2;
rsb_nnz_idx_t rnz;
RSB_DEFAULT_TYPE *alphap = NULL;
errval =
rsb_mtx_get_rows_sparse(transA, NULL, mtxAp, NULL,
NULL, NULL, frA, lrA, &rnz, RSB_FLAG_NOFLAGS);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_get_rows_sparse!0);
goto err;
}
printf("Rows
between %d and %d have %d nnz0,
(int)frA,(int)lrA,(int)rnz);
errval =
rsb_mtx_get_rows_sparse(transA, alphap, mtxAp,
VA, IA, JA, frA, lrA, &rnz, RSB_FLAG_NOFLAGS);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_get_vals!0);
goto err;
}
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_err_t rsb_mtx_get_vals (const struct rsb_mtx_t * mtxAp, void * VA, constrsb_coo_idx_t * IA, const rsb_coo_idx_t * JA, rsb_nnz_idx_t nnz,rsb_flags_t flags)
Gets the specified matrix
elements, if found. Please note that unlike
rsb_mtx_set_vals, the matrix has to be fully
assembled here.
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
VA,IA,JA Output numerical values (VA) array; input row
(IA) and column (JA) indices arrays.
nnz The number of nonzeroes in the input arrays.
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE
or RSB_FLAG_C_INDICES_INTERFACE (see
flags_section flags section).
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_coo_idx_t IA[] = { 2, 0, 2, 0 };
const rsb_coo_idx_t JA[] = { 2, 0, 0, 0 };
RSB_DEFAULT_TYPE VA[] = { -1, -1, -1, -1 };
errval =
rsb_mtx_get_vals(mtxAp, VA, IA, JA, nnzA, RSB_FLAG_NOFLAGS);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_get_vals!0);
goto err;
}
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_err_t rsb_mtx_get_vec (const struct rsb_mtx_t * mtxAp, void * Dp, enumrsb_extff_t flags)
Will overwrite a supplied array
with a specific vector quantity.
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
Dp A valid pointer to a numerical vector array $D$.
flags Either one of the different extraction filter
flags (e.g.: RSB_EXTF_DIAG, RSB_EXTF_SUMS_ROW,
...) .
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_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_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)
Renders a matrix to a file.
Currently, only Encapsulated Postscript (EPS) is supported.
Parameters
filename The specified
output file name (if NULL or ’’ (the empty
string), will write to standard output).
mtxAp Valid rsb_mtx_t pointer to matrix $A$
representation.
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*pmlWidth*pmHeight) bytes large.
Example rendering a sparse
matrix to Postscript:
if(RSB_ERR_NO_ERROR!=(errval =
rsb_mtx_rndr("pd.eps",mtxAp,512,512,RSB_MARF_EPS_B)))
goto err;
Setting
environment variable RSB_USE_HOSTNAME=0 prevents hostname
being in the EPS plot internal comments.
See also
rsb_mtx_rndr, rsb_file_mtx_rndr
rsb_err_t rsb_mtx_set_vals (struct rsb_mtx_t * mtxAp, const void * VA, constrsb_coo_idx_t * IA, const rsb_coo_idx_t * JA, rsb_nnz_idx_t nnz,rsb_flags_t flags)
Updates the specified matrix
elements, if found in the nonzero pattern.
In the special case of a matrix in assembly state (that is,
one that has been created as empty with
rsb_mtx_alloc_from_coo_begin() and not yet assembled
with rsb_mtx_alloc_from_coo_end() ) all the supplied
matrix elements will be accepted: whether already present or
not.
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
VA,IA,JA Input numerical values (VA) array; row (IA) and
column (JA) input indices arrays.
nnz The number of nonzeroes in the input arrays.
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE
or RSB_FLAG_C_INDICES_INTERFACE plus either
RSB_FLAG_DUPLICATES_SUM (to sum into) or
RSB_FLAG_DUPLICATES_KEEP_LAST (to overwrite entries)
(see flags_section flags section).
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_mtx_upd_vals, rsb_mtx_set_vals
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)
Switches a matrix to COO arrays
in place.
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
VAp,IAp,JAp Output numerical values (VAp) array pointer;
output row (IAp) and column (JAp) indices arrays pointers.
flags A combination of
RSB_FLAG_C_INDICES_INTERFACE,
RSB_FLAG_FORTRAN_INDICES_INTERFACE,
RSB_FLAG_FORTRAN_INDICES_INTERFACE. (see
flags_section flags section).
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
This function is only valid if mtxAp has been assembled in place (that is, in the arrays that are being reclaimed), so with e.g.: rsb_mtx_alloc_from_coo_inplace(). Please also note that the matrix will get freed internally and so mtxAp will not be usable in any way afterwards.
Warning
This function has not been thoroughly tested.
Example:
rsb_coo_idx_t *RP = NULL;
rsb_coo_idx_t *JA = NULL;
RSB_DEFAULT_TYPE *VA = NULL;
errval =
rsb_mtx_switch_to_coo(mtxAp, (void**)&VA,
&RP, &JA, RSB_FLAG_NOFLAGS);
// NOTE: no rsb_mtx_free() necessary now..
See also
rsb_mtx_switch_to_coo,rsb_mtx_switch_to_coo
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)
Switches the matrix to the CSR
format, in-place.
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
VAp,IAp,JAp Output numerical values (VAp) array pointer;
output row (IAp) and column (JAp) indices arrays pointers.
flags A valid combination of index conversion flags
(that is, RSB_FLAG_C_INDICES_INTERFACE and
RSB_FLAG_FORTRAN_INDICES_INTERFACE) and other
meaningful flags. Symmetry flags shall be the same as in the
matrix in use, because symmetry expansion may happen
otherwise. Flags RSB_FLAG_EXTERNALLY_ALLOCATED_ARRAYS
are forbidden.
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
This function is only valid if mtxAp has been assembled in place (that is, in the arrays that are being reclaimed), so with e.g.: rsb_mtx_alloc_from_coo_inplace(). Please also note that the matrix will get freed internally and so mtxAp will not be usable in any way afterwards.
Warning
This function has not been thoroughly tested.
Example:
rsb_coo_idx_t *IA = NULL;
rsb_coo_idx_t *JA = NULL;
RSB_DEFAULT_TYPE *VA = NULL;
errval =
rsb_mtx_switch_to_csr(mtxAp, (void**)&VA,
&IA, &JA, RSB_FLAG_NOFLAGS);
// NOTE: no rsb_mtx_free() necessary now..
See also
rsb_mtx_switch_to_coo,rsb_mtx_switch_to_coo
rsb_err_t rsb_mtx_upd_vals (struct rsb_mtx_t * mtxAp, enum rsb_elopf_telop_flags, const void * omegap)
$ A <- op (A,Omega) $ Updates
the matrix $A$ by applying either a row-wise or an elemental
operation $op$, which is determined by elop_flags. If an
unary operation is selected, omegap can be NULL.
Parameters
mtxAp Valid rsb_mtx_t
pointer to matrix $A$ representation.
elop_flags Elemental operation specification flags (see
rsb_elopf_t for valid choices).
omegap Pointer to a numerical location(s) (of the same
type as 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:
enum rsb_elopf_t elop_flags = RSB_ELOPF_NEG;
const RSB_DEFAULT_TYPE omegap[] = {10};
errval =
rsb_mtx_upd_vals(mtxAp, elop_flags, NULL);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_upd_vals!0);
goto err;
}
elop_flags =
RSB_ELOPF_MUL;
errval = rsb_mtx_upd_vals(mtxAp, elop_flags, omegap);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_upd_vals!0);
goto err;
}
See also
rsb_mtx_upd_vals, rsb_mtx_set_vals
rsb_err_t rsb_perror (void * stream, rsb_err_t errval)
Prints out to the specified
stream a string corresponding to the error code (using
<stdio.h>’s fprintf). If stream==NULL, will
print out to the default output stream; see
RSB_IO_WANT_OUTPUT_STREAM .
Parameters
stream A (FILE*)
pointer, as declared in <stdio.h>; can be NULL.
errval A valid error flag value (see
rsb_err_t).
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_perror, rsb_strerror_r
rsb_trans_t rsb_psblas_trans_to_rsb_trans (const char psbtrans)
Translate a PSBLAS transposition
value character to a librsb one.
See the PSBLAS library website/documentation for valid input
values.
Parameters
psbtrans Transposition parameter value valid in the PSBLAS library.
Returns
A valid transposition code; that is RSB_TRANSPOSITION_N for ’N’, RSB_TRANSPOSITION_T for ’T’, RSB_TRANSPOSITION_C for ’C’, (See matrix_transposition_flags_section).
Example snip:
See also
rsb_psblas_trans_to_rsb_trans
rsb_err_t rsb_spmm (rsb_trans_t transA, const void * alphap, const structrsb_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)
Updates a dense matrix with the
product of sparse matrix by dense matrix; that is, computes
$ C <- beta* C + alpha* opa(A) * B $.
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;
$opa( A )= A ˆT$ if transA=RSB_TRANSPOSITION_T; $opa( A )=
A ˆH$ if transA=RSB_TRANSPOSITION_C; If
--enable-rsb-num-threads has been specified at configure
time, the RSB_NUM_THREADS environment variable will override
the number of executing threads specified by
OMP_NUM_THREADS. (See also RSB_IO_WANT_EXECUTING_THREADS).
Setting order=RSB_FLAG_WANT_COLUMN_MAJOR_ORDER with ldC=0
and ldB=0 implies ’compact’ defaults, that is no
extra stride between the columns.
Parameters
transA Transposition
parameter for $A$ (see
matrix_transposition_flags_section).
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 $A$
representation.
nrhs The number of right hand side vectors (cannot be
<1).
order A flag among
RSB_FLAG_WANT_COLUMN_MAJOR_ORDER and
RSB_FLAG_WANT_ROW_MAJOR_ORDER. For contiguous vector
arrays, you probably want
RSB_FLAG_WANT_COLUMN_MAJOR_ORDER.
Bp The input vector array.
ldB Leading dimension of Bp array.
betap Optional pointer (if NULL, will default to 1) to a
numerical value.
Cp The output vector array.
ldC Leading dimension of Cp array.
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
Starting from version 1.3, librsb uses C++ kernels for rsb_spmv/rsb_spmm. Assuming you configured --enable-debug-getenvs, you may set environment variable RSB_WANT_RSBPP=0 to turn use the old C kernels.
See also
rsb_spmv, rsb_spmm, rsb_spata, rsb_tune_spmm
struct rsb_mtx_t * rsb_spmsp (rsb_type_t typecode, rsb_trans_t transA, constvoid * alphap, const struct rsb_mtx_t * mtxAp, rsb_trans_t transB, constvoid * betap, const struct rsb_mtx_t * mtxBp, rsb_err_t * errvalp)
Computes the weighted product of
two sparse matrices in a new sparse matrix (also known as
SpGEMM operation): $C <- alpha * opa(A) * beta * opb(B) $
Symmetry/Hermitian flags are ignored by this operation.
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;
$opa( A )= A ˆT$ if transA=RSB_TRANSPOSITION_T; $opa( A )=
A ˆH$ if transA=RSB_TRANSPOSITION_C; $opb( B )=B$ if
transB=RSB_TRANSPOSITION_N;
$opb( B )= B ˆT$ if transB=RSB_TRANSPOSITION_T; $opb( B )=
B ˆH$ if transB=RSB_TRANSPOSITION_C;
Parameters
typecode A valid type
code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
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 $A$
representation.
transB Transposition parameter for $B$ (see
matrix_transposition_flags_section).
betap Optional pointer (if NULL, will default to 1) to a
numerical value.
mtxBp Valid rsb_mtx_t pointer to matrix $B$
representation.
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.
Example snip:
const rsb_trans_t transA = RSB_TRANSPOSITION_N;
const rsb_trans_t transB = RSB_TRANSPOSITION_N;
RSB_DEFAULT_TYPE *alphap = NULL;
RSB_DEFAULT_TYPE *betap = NULL;
struct rsb_mtx_t * mtxCp = NULL;
mtxCp =
rsb_spmsp(typecode, transA, alphap, mtxAp,
transB, betap, mtxAp, &errval);
if( !mtxCp )
{
printf("Error calling rsb_spmsp!0);
goto err;
}
if(errval !=
RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_spmsp!0);
goto err;
}
Warning
Parameters alphap,betap,transA,transB are not yet taken in consideration. The following defaults are valid: $alpha=1.0$ and $beta=1.0$, and transA=transB=RSB_TRANSPOSITION_N.
See also
rsb_spmsp_to_dense, rsb_sppsp, rsb_spmsp, rsb_mtx_add_to_dense
rsb_err_t rsb_spmsp_to_dense (rsb_type_t typecode, rsb_trans_t transA, constvoid * alphap, const struct rsb_mtx_t * mtxAp, rsb_trans_t transB, constvoid * 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)
Computes the product of sparse
matrices and adds it to a dense matrix: $C <- alpha
opa(A) * beta * opb(B) $.
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;
$opa( A )= A ˆT$ if transA=RSB_TRANSPOSITION_T; $opa( A )=
A ˆH$ if transA=RSB_TRANSPOSITION_C; $opb( B )=B$ if
transB=RSB_TRANSPOSITION_N;
$opb( B )= B ˆT$ if transB=RSB_TRANSPOSITION_T; $opb( B )=
B ˆH$ if transB=RSB_TRANSPOSITION_C;
Parameters
typecode A valid type
code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
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 $A$
representation.
transB Transposition parameter for $B$ (see
matrix_transposition_flags_section).
betap Optional pointer (if NULL, will default to 1) to a
numerical value.
mtxBp Valid rsb_mtx_t pointer to matrix $B$
representation.
ldC Leading dimension of Cp array.
nrC,ncC The number of rows and columns for the dense
matrix $C$.
rowmajorC RSB_BOOL_TRUE if the dense matrix $C$
is considered stored as row major, or RSB_BOOL_FALSE
if as column major.
Cp Array representing the dense matrix $C$.
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
Parameters alphap,betap,transA,transB are not yet taken in consideration. The following defaults are valid: $alpha=1.0$ and $beta=1.0$, and transA=transB=RSB_TRANSPOSITION_N.
Example snip:
const rsb_nnz_idx_t ldC = 4, nrC = 3, ncC = 3;
const rsb_bool_t rowmajorC = RSB_BOOL_TRUE;
RSB_DEFAULT_TYPE Cp[ /*ldC*nrC*/ ] = {
0, 0, 0, -99,
0, 0, 0, -99,
0, 0, 0, -99
};
const rsb_trans_t transA = RSB_TRANSPOSITION_N;
const rsb_trans_t transB = RSB_TRANSPOSITION_N;
RSB_DEFAULT_TYPE *alphap = NULL;
RSB_DEFAULT_TYPE *betap = NULL;
errval =
rsb_spmsp_to_dense(typecode, transA, alphap, mtxAp,
transB, betap, mtxAp , ldC, nrC, ncC, rowmajorC, Cp);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_spmsp_to_dense!0);
goto err;
}
See also
rsb_spmsp_to_dense, rsb_sppsp, rsb_spmsp, rsb_mtx_add_to_dense
rsb_err_t rsb_spmv (rsb_trans_t transA, const void * alphap, const structrsb_mtx_t * mtxAp, const void * Xp, rsb_coo_idx_t incX, const void * betap,void * Yp, rsb_coo_idx_t incY)
Multiplies a sparse matrix
$opa(A)$ by a vector $X$, updating vector $Y$.
Computes $Y <- beta Y + alpha * opa(A) * X $.
It is not allowed to supply same Xp and Yp (that is,
Xp==Yp).
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;
$opa( A )= A ˆT$ if transA=RSB_TRANSPOSITION_T; $opa( A )=
A ˆH$ if transA=RSB_TRANSPOSITION_C; If
--enable-rsb-num-threads has been specified at configure
time, the RSB_NUM_THREADS environment variable will override
the number of executing threads specified by
OMP_NUM_THREADS. (See also RSB_IO_WANT_EXECUTING_THREADS).
Parameters
transA Transposition
parameter for $A$ (see
matrix_transposition_flags_section).
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 $A$
representation.
Xp The input vector array.
incX Spacing of vector elements in each input vector
array (>=1).
betap Optional pointer (if NULL, will default to 1) to a
numerical value.
Yp The output array vector.
incY Spacing of vector elements in each output vector
array (>=1).
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:
if((errval =
rsb_spmv(RSB_TRANSPOSITION_N,&one,mtxAp,B,1,&one,X,1))
!= RSB_ERR_NO_ERROR )
{
printf("Error performing a multiplication!0);
goto err;
}
Note
Starting from version 1.3, librsb uses C++ kernels for rsb_spmv/rsb_spmm. Assuming you configured --enable-debug-getenvs, you may set environment variable RSB_WANT_RSBPP=0 to turn use the old C kernels.
See also
rsb_spmv, rsb_spmm, rsb_spata, rsb_tune_spmm
struct rsb_mtx_t * rsb_sppsp (rsb_type_t typecode, rsb_trans_t transA, constvoid * alphap, const struct rsb_mtx_t * mtxAp, rsb_trans_t transB, constvoid * betap, const struct rsb_mtx_t * mtxBp, rsb_err_t * errvalp)
Computes the weighted sum of two
sparse matrices, returning a new matrix: $C <- alpha*
transA(A) + beta* transB{B} $ Symmetry flags are ignored in
this operation.
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;
$opa( A )= A ˆT$ if transA=RSB_TRANSPOSITION_T; $opa( A )=
A ˆH$ if transA=RSB_TRANSPOSITION_C; $opb( B )=B$ if
transB=RSB_TRANSPOSITION_N;
$opb( B )= B ˆT$ if transB=RSB_TRANSPOSITION_T; $opb( B )=
B ˆH$ if transB=RSB_TRANSPOSITION_C;
Parameters
typecode A valid type
code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
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 $A$
representation.
transB Transposition parameter for $B$ (see
matrix_transposition_flags_section).
betap Optional pointer (if NULL, will default to 1) to a
numerical value.
mtxBp Valid rsb_mtx_t pointer to matrix $B$
representation.
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.
Example snip:
const rsb_trans_t transA = RSB_TRANSPOSITION_N;
const rsb_trans_t transB = RSB_TRANSPOSITION_N;
RSB_DEFAULT_TYPE *alphap = NULL;
RSB_DEFAULT_TYPE *betap = NULL;
struct rsb_mtx_t * mtxCp = NULL;
mtxCp =
rsb_sppsp(typecode, transA, alphap, mtxAp,
transB, betap, mtxAp, &errval);
if( !mtxCp )
{
printf("Error calling rsb_sppsp!0);
goto err;
}
if(errval !=
RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_sppsp!0);
goto err;
}
See also
rsb_spmsp_to_dense, rsb_sppsp, rsb_spmsp, rsb_mtx_add_to_dense
Warning
This function has not been
thoroughly tested.
This function is not optimized.
rsb_err_t rsb_spsm (rsb_trans_t transT, const void * alphap, const structrsb_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)
Computes $Y <- alpha * opt( T
)ˆ{-1} * B $, with upper or lower triangular $T$.
$opt( T )=T$ if transT=RSB_TRANSPOSITION_N;
$opt( T )= T ˆT$ if transT=RSB_TRANSPOSITION_T; $opt( T )=
T ˆH$ if transT=RSB_TRANSPOSITION_C;
Parameters
transT Transposition
parameter for $T$ (see
matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to
a numerical value (of the same type as matrix).
mtxTp Valid rsb_mtx_t pointer to matrix $T$
representation. The matrix must be triangular; that is, it
must have been allocated with either
RSB_FLAG_LOWER_TRIANGULAR or
RSB_FLAG_UPPER_TRIANGULAR flags.
nrhs The number of right hand side vectors (cannot be
<1).
order A flag among
RSB_FLAG_WANT_COLUMN_MAJOR_ORDER and
RSB_FLAG_WANT_ROW_MAJOR_ORDER. For contiguous vector
arrays, you probably want
RSB_FLAG_WANT_COLUMN_MAJOR_ORDER.
betap Optional pointer (if NULL, will default to 1) to a
numerical value.
Bp The input vector array.
ldB Leading dimension of Bp array.
Cp The output vector array.
ldC Leading dimension of Cp array.
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_spsm, rsb_spsv, rsb_tune_spsm
rsb_err_t rsb_spsv (rsb_trans_t transT, const void * alphap, const structrsb_mtx_t * mtxTp, const void * Xp, rsb_coo_idx_t incX, void * Yp,rsb_coo_idx_t incY)
Computes $Y <- alpha * opt( T
)ˆ{-1} * X $, with upper or lower triangular $T$. It is
allowed to supply same Xp and Yp (that is, Xp==Yp).
$opt( T )=T$ if transT=RSB_TRANSPOSITION_N;
$opt( T )= T ˆT$ if transT=RSB_TRANSPOSITION_T; $opt( T )=
T ˆH$ if transT=RSB_TRANSPOSITION_C;
Parameters
transT Transposition
parameter for $T$ (see
matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to
a numerical value (of the same type as matrix).
mtxTp Valid rsb_mtx_t pointer to matrix $T$
representation. The matrix must be triangular; that is, it
must have been allocated with either
RSB_FLAG_LOWER_TRIANGULAR or
RSB_FLAG_UPPER_TRIANGULAR flags.
Xp The input vector array.
incX Spacing of vector elements in each input vector
array (>=1).
Yp The output array vector.
incY Spacing of vector elements in each output vector
array (>=1).
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 --enable-zero-division-checks-on-solve was specified at configure time, attempts to solve a triangular matrix with zeroes on a diagonal will fail.
Example backsolving a triangular
system:
if((errval =
rsb_spsv(RSB_TRANSPOSITION_N,&one,mtxAp,X,1,X,1))
!= RSB_ERR_NO_ERROR )
{
printf("Error performing triangular solve!0);
goto err;
}
See also
rsb_spsm, rsb_spsv, rsb_tune_spsm
rsb_err_t rsb_strerror_r (rsb_err_t errval, rsb_char_t * buf, size_t buflen)
Writes a textual description of
an error code in the specified string buffer. No more than
buflen characters will be written (comprehensive of the
terminating NUL character). No action will be performed on
RSB_ERR_NO_ERROR. Notice too that error flags cannot be
added in the way flags are (e.g.
(RSB_ERR_GENERIC_ERROR|RSB_ERR_BADARGS) evaluates to
RSB_ERR_GENERIC_ERROR).
Parameters
errval A valid error
flag value (see rsb_err_t).
buf A valid string buffer pointer where to write to.
buflen The string buffer 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.
Examples:
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:1s).0,errbuf);
or
rsb_err_t errval = RSB_ERR_INTERNAL_ERROR;
// ...
if(errval !=
RSB_ERR_NO_ERROR)
{
char errbuf[256];
rsb_strerror_r(errval,&errbuf[0],sizeof(errbuf));
// error handling ...
See also
rsb_perror, rsb_strerror_r
rsb_time_t rsb_time (void)
Returns the current time in
seconds. This function is meant to be used for computing
wall clock time intervals (e.g.: for benchmarking purposes).
The user should not rely on this function for absolute time
computations.
Returns
A value for the current time, in seconds.
See also
rsb_time, rsb_coo_sort
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, constvoid * 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)
An auto-tuner: optimizes either
the matrix instance, the thread count or both for the
rsb_spmm operation.
The tuner works by evaluating different instances and
working threads variants. The instance leading to faster
operation time will be retained and given back to the user
in *mtxOpp. If nrhs==1 and
order==RSB_FLAG_WANT_COLUMN_MAJOR_ORDER, unitary stride
vectors are assumed. In case of error, the original input
matrix shall be unaffected. It is possible to specify the
leading dimensions of Bp,Cp implicitly, with ldB=0 and
ldC=0: in this case, their values will be computed
internally and if Bp!=NULL,Cp!=NULL, they will be assumed of
being sufficiently sized. Values of nrhs<1 will be
treated as 1. Bp, Cp can be NULL: temporary vectors will be
allocated, used, and deallocated within the tuner. If
mtxOpp=NULL and *tnp!=NULL the best thread count will be
probed for the matrix given in mtxAp. Please note that if
threads-only tuning is requested and matrix has too few
leaves (see RSB_MIF_LEAVES_COUNT__TO__RSB_BLK_INDEX_T),
tuning will not work. If mtxAp==NULL, then the *mtxOpp
instance will be used; however in this case, if a better
instance is found, the original will be destroyed as with
rsb_mtx_free(). The case mtxAp!=NULL&&*mtxOpp!=NULL
is illegal and will cause error code RSB_ERR_BADARGS to be
returned.
Parameters
mtxOpp Optimal matrix
structure pointer will be assigned to *mtxOpp (it may occur
that *mtxOpp==mtxAp on output). If mtxOpp is NULL then no
data structure optimization will be attempted; rather, only
optimal threads search will occur (tnp must be not NULL
then).
sfp Achieved speedup factor will be written to *sfp
(unless sfp==NULL).
tnp If tnp==NULL on input, the current thread count will
be utilized. Otherwise, if *tnp>0, then *tnp will be used
as first suggestion in optimal thread count searching. If
tnp!=NULL ,on output *tnp will be set to contain the optimal
number of threads. Then, the user is expected to set this
number of threads using e.g.:
RSB_REINIT_SINGLE_VALUE_SET(RSB_IO_WANT_EXECUTING_THREADS,tnp,errval).
Please note that this will affect the whole library
operation, not only this matrix.
maxr Optimizer rounds max count. If <1, will be
treated as 1; if 0 will be decided automatically. Max is
RSB_CONST_MAX_TUNING_ROUNDS.
maxt Maximum time (in seconds) per optimization round
(does not take in account conversion time). If maxt<0.0
is provided, -ceil(maxt) will be interpreted as number of
iterations to check for each operation time sample. If
maxt==0.0 is provided, a default choice will be made
instead.
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
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 $A$
representation.
nrhs The number of right hand side vectors (cannot be
<1).
order A flag among RSB_FLAG_WANT_COLUMN_MAJOR_ORDER
and RSB_FLAG_WANT_ROW_MAJOR_ORDER. For contiguous vector
arrays, you probably want
RSB_FLAG_WANT_COLUMN_MAJOR_ORDER.
Bp The input vector array. If NULL, a temporary,
internally allocated copy will be used.
ldB Leading dimension of Bp array.
betap Optional pointer (if NULL, will default to 1)
to a numerical value.
Cp The output vector array. If NULL, a temporary,
internally allocated copy will be used.
ldC Leading dimension of Cp array.
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.
Examples:
// obtain best thread count for mtxAp:
errval = rsb_tune_spmm(NULL ,&sf,&tn
,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);
// obtain best
thread count for mtxAp; Bp and Cp will be allocated by the
tuner:
errval = rsb_tune_spmm(NULL ,&sf,&tn
,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,NULL,0,&beta,NULL,0);
// obtain best
clone of mtxAp (for current thread count):
assert(mtxOp == NULL && mtxAp != NULL);
errval =
rsb_tune_spmm(&mtxOp,&sf,NULL,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);
// obtain best
clone of mtxAp and best thread count:
assert(mtxOp == NULL && mtxAp != NULL);
errval = rsb_tune_spmm(&mtxOp,&sf,&tn
,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);
// replace mtxAp
with best clone (if any):
errval =
rsb_tune_spmm(&mtxAp,&sf,NULL,maxr,maxt,transA,&alpha,NULL
,nrhs,order,Bp,ldB,&beta,Cp,ldC);
// replace mtxAp
with best clone (if any) and obtain best thread count:
errval = rsb_tune_spmm(&mtxAp,&sf,&tn
,maxr,maxt,transA,&alpha,NULL
,nrhs,order,Bp,ldB,&beta,Cp,ldC);
// illegal call:
assert(mtxOp != NULL && mtxAp != NULL);
errval = rsb_tune_spmm(&mtxOp,&sf,&tn
,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);
Warning
This function is still experimental. In case of error, although the matrix shall be unaffected, the library status may be affected (e.g.: execution thread count, default matrix subdivision).
Todo
Autotuning functionality is still object of much research. Need support for lightweight, threads-only optimization.
Sample matrix sparse block
structure before tuning
Sample matrix sparse block structure after tuning
See also
rsb_spmv, rsb_spmm, rsb_spata, rsb_tune_spmm
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, constvoid * 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)
An auto-tuner: optimizes either
the matrix instance, the thread count or both for the
rsb_spsm operation.
The tuner works by evaluating different instances and
working threads variants. The instance leading to faster
operation time will be retained and given back to the user
in *mtxOpp. If nrhs==1 and
order==RSB_FLAG_WANT_COLUMN_MAJOR_ORDER, unitary stride
vectors are assumed. In case of error, the original input
matrix shall be unaffected. It is possible to specify the
leading dimensions of Bp,Cp implicitly, with ldB=0 and
ldC=0: in this case, their values will be computed
internally and if Bp!=NULL,Cp!=NULL, they will be assumed of
being sufficiently sized. Values of nrhs<1 will be
treated as 1. Bp, Cp can be NULL: temporary vectors will be
allocated, used, and deallocated within the tuner. If
mtxOpp=NULL and *tnp!=NULL the best thread count will be
probed for the matrix given in mtxAp. Please note that if
threads-only tuning is requested and matrix has too few
leaves (see RSB_MIF_LEAVES_COUNT__TO__RSB_BLK_INDEX_T),
tuning will not work. If mtxAp==NULL, then the *mtxOpp
instance will be used; however in this case, if a better
instance is found, the original will be destroyed as with
rsb_mtx_free(). The case mtxAp!=NULL&&*mtxOpp!=NULL
is illegal and will cause error code RSB_ERR_BADARGS to be
returned.
Parameters
mtxOpp Optimal matrix
structure pointer will be assigned to *mtxOpp (it may occur
that *mtxOpp==mtxAp on output). If mtxOpp is NULL then no
data structure optimization will be attempted; rather, only
optimal threads search will occur (tnp must be not NULL
then).
sfp Achieved speedup factor will be written to *sfp
(unless sfp==NULL).
tnp If tnp==NULL on input, the current thread count will
be utilized. Otherwise, if *tnp>0, then *tnp will be used
as first suggestion in optimal thread count searching. If
tnp!=NULL ,on output *tnp will be set to contain the optimal
number of threads. Then, the user is expected to set this
number of threads using e.g.:
RSB_REINIT_SINGLE_VALUE_SET(RSB_IO_WANT_EXECUTING_THREADS,tnp,errval).
Please note that this will affect the whole library
operation, not only this matrix.
maxr Optimizer rounds max count. If <1, will be
treated as 1; if 0 will be decided automatically. Max is
RSB_CONST_MAX_TUNING_ROUNDS.
maxt Maximum time (in seconds) per optimization round
(does not take in account conversion time). If maxt<0.0
is provided, -ceil(maxt) will be interpreted as number of
iterations to check for each operation time sample. If
maxt==0.0 is provided, a default choice will be made
instead.
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
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 $A$
representation.
nrhs The number of right hand side vectors (cannot be
<1).
order A flag among RSB_FLAG_WANT_COLUMN_MAJOR_ORDER
and RSB_FLAG_WANT_ROW_MAJOR_ORDER. For contiguous vector
arrays, you probably want
RSB_FLAG_WANT_COLUMN_MAJOR_ORDER.
Bp The input vector array. If NULL, a temporary,
internally allocated copy will be used.
ldB Leading dimension of Bp array.
betap Optional pointer (if NULL, will default to 1)
to a numerical value.
Cp The output vector array. If NULL, a temporary,
internally allocated copy will be used.
ldC Leading dimension of Cp array.
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
--enable-zero-division-checks-on-solve was specified at
configure time, attempts to solve a triangular matrix with
zeroes on a diagonal will fail.
Warning
This function is still experimental. In case of error, although the matrix shall be unaffected, the library status may be affected (e.g.: execution thread count, default matrix subdivision).
Todo
Autotuning functionality is still object of much research. Need support for lightweight, threads-only optimization.
Sample matrix sparse block
structure before tuning
Sample matrix sparse block structure after tuning
See also
rsb_spsm,
rsb_spsv, rsb_tune_spsm
rsb_tune_spmm
Author
librsb was written by Michele Martone; this documentation has been generated by Doxygen.
SEE ALSO
rsb-examples rsb-spblas.h rsb.h rsb.hpp