rsb.h(3)
NAME
librsb - rsb.h - The librsb library interface (rsb.h, 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, rsb.F90) ; The Sparse
BLAS interface to librsb (blas_sparse.h, rsb_blas_sparse.F90) ; Example
programs and code.
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 informations 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_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_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,
rsb_coo_idx_t *IREN, 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)
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, 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 a the Sparse BLAS one
(both C and Fortran, documented).
Configuration, build, and installation instructions are contained in
the README file distributed in the sources archive.
Typical 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 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/sh
# systematic comparative benchmark, mostly for dense matrices
# (with Intel MKL, if linked) benchmark comparing
# produces a number of plots systematically
bench/dense.sh
# the benchmark command; assumes A.mtx is a file in Matrix Market format
./rsbench -oa -Ob -f A.mtx -qH -R -n1 -t100 --verbose -TD --compare-competitors
# rsbench is very flexible tool; see the help for it:
./rsbench -oa -Ob --help
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 informations 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.
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_sort (void * VA, rsb_coo_idx_t * IA, rsb_coo_idx_t * JA,
rsb_nnz_idx_t nnzA, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_type_t
typecode, rsb_flags_t flagsA)
Sorts row-major the given COO input arrays representing a sparse matrix
$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$.
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.
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.
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.
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.
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_t pmlWidth, rsb_coo_idx_t pmWidth, rsb_coo_idx_t pmHeight,
rsb_marf_t rflags)
Renders as pixel map the matrix contained in a matrix file.
Parameters:
pmp Pixel map array pointer.
filename The specified matrix file name (cannot be NULL).
pmlWidth stride between lines (in pixels; no less than pmWidth).
pmWidth Pixel map width (in pixels or points).
pmHeight Pixel map height (in pixels or points).
rflags The color mode; only RSB_MARF_RGB is supported for now (1
byte per channel, 3 channels --- red, green, blue): this requires
array pmp to be at least (3*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.
Warning:
This function has not been thoroughly tested.
Note:
At the time being, pmlWidth is required to be equal to pmWidth.
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, 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.
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_t
typecode, void * Yp, rsb_coo_idx_t * yvlp)
Loads a dense vector from the specified file, using the numerical type
representation as specified by the user. This function is intended to
be called in two steps: first with Yp=NULL, in order to write the
vector length to *yvlp ; then, with yvlp=NULL, to get Yp written.
Parameters:
filename The specified vector file name (cannot be NULL).
typecode A valid type code for the given (numerical array) input
pointer (see matrix_type_symbols_section).
Yp The input array vector.
yvlp An optional pointer (can be NULL). If supplied, vector length
will be written here, and no vector will be read.
Returns:
RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You
can use rsb_strerror_r() or rsb_perror() to get more information
about the error.
Note:
The only dense vector file format currently supported is Matrix
Market. E.g.:
%%MatrixMarket matrix array complex general
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_t
typecode, const void * Yp, rsb_coo_idx_t yvl)
Saves a dense vector to the specified file, using the numerical type
representation as specified by the user. This function assumes Yp!=NULL
and yvl>0.
Parameters:
filename The specified vector file name (cannot be NULL).
typecode A valid type code for the given (numerical array) input
pointer (see matrix_type_symbols_section).
Yp The output array vector.
yvl Output vector length.
Returns:
RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You
can use rsb_strerror_r() or rsb_perror() to get more information
about the error.
Note:
The only dense vector file format currently supported is Matrix
Market. E.g.:
%%MatrixMarket matrix array complex general
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_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.
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.
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_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.
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.
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.
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_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.
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_t rowmajorB, void * Bp)
Dense matrix B is updated by adding scaled sparse matrix ${A}$ to it:
$B tarrow B + lpha {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.
Warning:
This function has not been thoroughly tested.
Note:
Please note that it suffices to 'transpose' Bp's description
parameters to get $A$ transposed summed in.
See also:
rsb_spmsp_to_dense, rsb_sppsp, rsb_spmsp, rsb_mtx_add_to_dense
struct rsb_mtx_t* rsb_mtx_alloc_from_coo_const (const void * VA, const
rsb_coo_idx_t * IA, const rsb_coo_idx_t * JA, rsb_nnz_idx_t nnzA,
rsb_type_t typecode, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA,
rsb_blk_idx_t brA, rsb_blk_idx_t bcA, rsb_flags_t flagsA, rsb_err_t *
errvalp)
Given as input COO arrays VA,IA,JA, allocates and assembles an RSB
matrix using separate arrays.
Parameters:
VA,IA,JA Input numerical values (VA) array; row (IA) and column
(JA) input indices arrays.
nnzA The number of nonzeroes in the input arrays representing
matrix $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 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_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 min(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 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, 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)
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 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_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)
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 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 min(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 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 If
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.
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.
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_t lrA, rsb_coo_idx_t fcA, rsb_coo_idx_t lcA, rsb_coo_idx_t
* IREN, 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 Then the the
aram mtxAp Valid aram VA,IA,JA Output numerical values ( aram frA,lrA First and last row indices.
aram fcA,lcA First and last column indices.
aram IREN,JREN Renumbering arrays for aram rnzp A pointer where the number of relevant nonzero elemeftflagslsectiontflagsosection).
eturnf#RSB_ERRhNO_ERRORFonGcorrectNoperation,NanRerrorocodeSotherwise.NYouEcanNuseF#rsb_strerror_r()(ore#rsb_perror() to get more information about the error.
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_t
flags)
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_t
miflags, 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.
Warning:
This function has not been thoroughly tested.
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, const
rsb_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.
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, enum
rsb_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).
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:
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.
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,
const rsb_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.
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, enum
rsb_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, 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.
See also:
rsb_mtx_rndr, rsb_file_mtx_rndr
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)
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.
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.
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_t
elop_flags, const void * omegap)
$ A tarrow op (A,ega) $ Updates the matrix $A$ by applying either a
rowwise 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.
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)
See the PSBLAS library website/documentation for valid input values.
Parameters: t
psbtrans Transposition parameter aalue valid in the PSBLAS library.
Returns: d
A valid transposition code; that os RSB_TRANSPOSITION_N for 'N',
RSB_TRANSPOSITION_T for 'T', RSB_tRANSPOSITION_C for 'C', (See
matrix_transposition_flags_sectionSee also: +
rsb_psblas_trans_to_rsb_trans l
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) d
Updates a dense matrix with the produot of sparse matrix by dense
matrix; that is, computes $ C tarrow t
$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 executingAthreads specified by
OMP_NUM_THREADS. (See also RSB_IO_WANT_EXECUTING_THREADS).
Parameters: d
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
alphap Optional pointer (if NULL,Bwill 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.
See also:
rsb_spmv, rsb_spmm, rsb_tune_spmm
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)
Computes the weighted product of two sparse matrices in a new sparse
matrix (also known as SpGEMM operation): $C tarrow lpha
$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 0
matrix_transposition_flags_section). $
alphap Optional pointer (if NULL, will default to 1) to a numeric,l
value (of the same type as matrix). a
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation. n
transB Transposition parameter for $B$ (see d
matrix_transposition_flags_section). t
betap Optional pointer (if NULL, will default to 1) to a numericar
value. a
mtxBp Valid rsb_mtx_t pointer to matrix $B$ representation. n
errvalp An optional (can be NULL) pointer to rsb_err_t where the s
error status will be written to. A
Returns: =
On success, a valid pointer (struct rsb_mtx_t*) to the newly t
allocated matrix structure; on error, NULL. r
Warning: a
Parameters alphap,betap,transA,transB are not yet taken in n
consideration. The following defaults are valid: $lpha=1.0$ and $s
See also: B
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, R
const void * alphap, const struct rsb_mtx_t * mtxAp, rsb_trans_t S
transB, const void * betap, const struct rsb_mtx_t * mtxBp, B
rsb_nnz_idx_t ldC, rsb_nnz_idx_t nrC, rsb_nnz_idx_t ncC, rsb_bool_t _
rowmajorC, void * Cp) T
Computes the product of sparse matrices and adds it to a dense matrixRA
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N; $opa( A )= A ^T$ if N
transA=RSB_TRANSPOSITION_T; $opa( A )= A ^H$ if S
transA=RSB_TRANSPOSITION_C; $opb( B )=B$ if transB=RSB_TRANSPOSITION_PN;
$opb( B )= B ^T$ if transB=RSB_TRANSPOSITION_T; $opb( B )= B ^H$ if O
transB=RSB_TRANSPOSITION_C; S
Parameters: I
typecode A valid type code for the given (numerical array) input T
pointer (see matrix_type_symbols_section). ItransA Transposition parameter for $A$ (see Omatrix_transposition_flags_section). Nalphap Optional pointer (if NULL, will default to 1) to a numeric_NmtxAp 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 numericaa
value. n
mtxBp Valid rsb_mtx_t pointer to matrix $B$ representation. d
ldC Leading dimension of Cp array. t
nrC,ncC The number of rows and columns for the dense matrix $C$. r
rowmajorC RSB_BOOL_TRUE if the dense matrix $C$ is considered a
stored as row major, or RSB_BOOL_FALSE if as column major. n
Cp Array representing the dense matrix $C$. s
Returns: A
RSB_ERR_NO_ERROR on correct operation, an error code otherwise. Y=u
can use rsb_strerror_r() or rsb_perror() to get more information t
about the errort r
Warning: a a
Parameters alphYp,betap,transA,transB are not yet taken in n
consideration. +he following defaults are valid: $lpha=1.0$ and $s
See also: l B
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 structR
rsb_mtx_t * mtxAp, const void * Xp, rsb_coo_idx_t incX, const void * S
betap, void * Yp, rsb_coo_idx_t incY) B
Multiplies a sparseomatrix $opa(A)$ by a vector $X$, updating vector _
$Y$. t T
Computes $Y tarrow o R
It is not allowed to supply same Xp and Yp (that is, Xp==Yp). A
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N; $opa( A )= A ^T$ if N
transA=RSB_TRANSPOSITION_T; $opa( A )= A ^H$ if S
transA=RSB_TRANSPOSITION_C; If --enable-rsb-num-threads has been P
specified at configure time, the RSB_NUM_THREADS environment variableO
will override the number of executing threads specified by S
OMP_NUM_THREADS. (See also RSB_IO_WANT_EXECUTING_THREADS). I
Parameters: t T
transA Transposition parameter for $A$ (see I
matrix_transposition_flags_section). O
. N
_
N
.
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.
See also:
rsb_spmv, rsb_spmm, rsb_tune_spmm
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)
Computes the weighted sum of two sparse matrices, returning a new
matrix: $C tarrow lpha
$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.
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 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)
Computes $Y tarrow lpha
$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 struct
rsb_mtx_t * mtxTp, const void * Xp, rsb_coo_idx_t incX, void * Yp,
rsb_coo_idx_t incY)
Computes $Y tarrow lpha
$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.
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 terminting NUL character).
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.
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,
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)
An auto-tuner: optimizes either the matrix instance, the thread count or both for the #rsb_spmm operation.
ef matrix_transposition_flags_section).
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 aram mtxOpp Optimal matrix structure pointer will be assigned to aram sfp Achieved speedup factor will be written to aram tnp If aram maxr Optimizer rounds max count. If aram maxt Maximum time (in seconds) per optimization round (does not take in account conversion time). If aram transA Transposition parameter for rm#21 (see
aram alphap Optional pointer (if aram mtxAp Valid aram nrhs The number of right hand side vectors (cannot be aram order A flag among #RSB_FLAG_WANT_COLUMN_MAJOR_ORDER aneturnB#RSBGERRNNORERRORJon_correctFoperation,oan errorrcodeaotherwise.oYoulcanause##rsbFstrerror_r()Uor_#rsbRperror() to get more information about the error.
aram Bp The input vector array. If aram ldB Leading dimension of aram betap Optional pointer (if aram Cp The output vector array. If aram ldC Leading dimension of
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
In the future, autotuning functionality shall improve considerably.
Need support for lightweight, threads-only optimization. May
support strided vectors in the future.
See also:
rsb_spmv, rsb_spmm, 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,
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)
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 an error.
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
In the future, autotuning functionality shall improve considerably.
Need support for lightweight, threads-only optimization. May
support strided vectors in the future.
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
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
