| rsb.h(3) | librsb | rsb.h(3) |
librsb - rsb.h - The librsb library interface (rsb.h, optional ones rsb.hpp and rsb.F90)
-
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.
#define RSB_SIZEOF(TYPE) RSB_NUMERICAL_TYPE_SIZE(TYPE)
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().
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)
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
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.
Use RSB_SIZEOF macro to get the size (in bytes) of a type supported by the library (e.g.: when allocating numerical vectors).
Flags for specifying a particular elemental/row-wise operation with rsb_mtx_upd_vals().
Enumerator
Extraction filter flags, to be used with rsb_mtx_get_nrm()/rsb_mtx_get_vec().
Enumerator
Flags for getting matrix information via rsb_mtx_get_info()/rsb_mtx_get_info_str().
Enumerator
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
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
Returns
See also
rsb_coo_sort
Warning
Note
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
Sorts row-major the given COO input arrays representing a sparse matrix $A$.
Parameters
Returns
See also
Note
Reads structural information (dimensions, structural flags) for a matrix file into user specified (and optionally NULL) variables.
Parameters
Returns
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
%%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
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
Returns
Note
%%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
Renders as pixel map the matrix contained in a matrix file.
Parameters
Returns
Note
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
Saves the given matrix to the specified matrix file.
Parameters
Returns
Warning
Note
%%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
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
Returns
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
%%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
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
Returns
Note
%%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
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
Returns
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
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
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..
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
Returns
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
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
Returns
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
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
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:0s).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_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..
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
Returns
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
Dense matrix B is updated by adding scaled sparse matrix ${A}$ to it: $B <- B + alpha {A} $
Parameters
Returns
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
Symmetry is currently not expanded.
Threaded, for large enough matrices.
See also
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
Returns
Warning
See also
Given as input COO arrays VA,IA,JA, allocates and assembles an RSB matrix using separate arrays.
Parameters
Returns
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
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
Returns
Warning
Note
See also
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
Returns
See also
Given input read only CSC format arrays, allocates and assembles an RSB matrix (stored in separate arrays).
Parameters
Returns
See also
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);
Given input read only CSR format arrays, allocates and assembles an RSB matrix (stored in separate arrays).
Parameters
Returns
See also
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
Returns
See also
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
Returns
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
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
Returns
Example freeing a sparse matrix:
rsb_mtx_free(mtxAp);
See also
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
Returns
See also
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
Returns
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
See also
Fills the given arrays with the matrix expressed in the CSR format.
Parameters
Returns
See also
Returns a specified matrix (numerical) property.
Parameters
Returns
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
Returns a specified matrix (numerical) property, via a string form query.
Parameters
Returns
Example snip:
rsb_mtx_get_info_str(mtxAp,"RSB_MIF_MATRIX_INFO__TO__CHAR_P",
ib,sizeof(ib));
printf("%s",ib);
See also
Computes a matrix norm (either infinite-norm or or 2-norm or 1-norm).
Parameters
In case of a complex type, only the real part will be written to Np.
Returns
See also
A function computing a simple preconditioner out of mtxAp.
Parameters
Returns
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
See also
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
Returns
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
Gets the specified matrix elements, if found. Please note that unlike rsb_mtx_set_vals, the matrix has to be fully assembled here.
Parameters
Returns
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
Will overwrite a supplied array with a specific vector quantity.
Parameters
Returns
See also
Renders a matrix to a file. Currently, only Encapsulated Postscript (EPS) is supported.
Parameters
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
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
Returns
See also
Switches a matrix to COO arrays in place.
Parameters
Returns
Note
Warning
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
Switches the matrix to the CSR format, in-place.
Parameters
Returns
Note
Warning
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
$ 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
Returns
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
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
Returns
See also
Translate a PSBLAS transposition value character to a librsb
one.
See the PSBLAS library website/documentation for valid input
values.
Parameters
Returns
Example snip:
See also
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
Returns
Note
See also
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
Returns
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
See also
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
Returns
Warning
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
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
Returns
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
See also
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
Returns
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
Warning
This function is not optimized.
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
Returns
See also
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
Returns
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
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
Returns
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:0s).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
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
See also
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
Returns
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
Todo
Sample matrix sparse block structure before tuning
Sample matrix sparse block structure after tuning
See also
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
Returns
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
Todo
Sample matrix sparse block structure before tuning
Sample matrix sparse block structure after tuning
See also
rsb_tune_spmm
librsb was written by Michele Martone; this documentation has been generated by Doxygen.
rsb-examples rsb-spblas.h rsb.h rsb.hpp
| Sun Jan 1 2023 | Version 1.3.0.2 |