#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_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_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_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_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)
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
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 \leftarrow B + \alpha {A} $
Parameters
alphap Optional pointer (if NULL, will default
to 1) to a numerical value (of the same type as matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $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
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
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
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
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
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
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_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 \leftarrow 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
psbtrans Transposition parameter value valid in
the PSBLAS library.
Returns
A valid transposition code; that is
RSB_TRANSPOSITION_N for 'N', RSB_TRANSPOSITION_T for 'T',
RSB_TRANSPOSITION_C for 'C', (See
matrix_transposition_flags_section).
See also
rsb_psblas_trans_to_rsb_trans
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)
Updates a dense matrix with the product of sparse matrix by dense
matrix; that is, computes $ C \leftarrow
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;
$opa( A )= A ^T$ if transA=RSB_TRANSPOSITION_T; $opa(
A )= A ^H$ if transA=RSB_TRANSPOSITION_C; If
--enable-rsb-num-threads has been specified at configure time, the
RSB_NUM_THREADS environment variable will override the number of
executing threads specified by OMP_NUM_THREADS. (See also
RSB_IO_WANT_EXECUTING_THREADS). Setting
order=RSB_FLAG_WANT_COLUMN_MAJOR_ORDER with
ldC=0 and ldB=0 implies 'compact' defaults, that is no extra
stride between the columns.
Parameters
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical
value (of the same type as matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
nrhs The number of right hand side vectors (cannot be <1).
order A flag among RSB_FLAG_WANT_COLUMN_MAJOR_ORDER and
RSB_FLAG_WANT_ROW_MAJOR_ORDER. For contiguous vector arrays, you
probably want RSB_FLAG_WANT_COLUMN_MAJOR_ORDER.
Bp The input vector array.
ldB Leading dimension of Bp array.
betap Optional pointer (if NULL, will default to 1) to a numerical
value.
Cp The output vector array.
ldC Leading dimension of Cp array.
Returns
RSB_ERR_NO_ERROR on correct operation, an error
code otherwise. You can use rsb_strerror_r() or rsb_perror() to
get more information about the error.
See also
rsb_spmv, rsb_spmm,
rsb_tune_spmm
Computes the weighted product of two sparse matrices in a new
sparse matrix (also known as SpGEMM operation): $C \leftarrow \alpha dot
opa(A) dot try/Hermitian flags are ignored by this operation.
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;
$opa( A )= A ^T$ if transA=RSB_TRANSPOSITION_T; $opa(
A )= A ^H$ if transA=RSB_TRANSPOSITION_C; $opb( B )=B$
if transB=RSB_TRANSPOSITION_N;
$opb( B )= B ^T$ if transB=RSB_TRANSPOSITION_T; $opb(
B )= B ^H$ if transB=RSB_TRANSPOSITION_C;
Parameters
typecode A valid type code for the given
(numerical array) input pointer (see matrix_type_symbols_section).
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical
value (of the same type as matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
transB Transposition parameter for $B$ (see
matrix_transposition_flags_section).
betap Optional pointer (if NULL, will default to 1) to a numerical
value.
mtxBp Valid rsb_mtx_t pointer to matrix $B$ representation.
errvalp An optional (can be NULL) pointer to rsb_err_t
where the error status will be written to.
Returns
On success, a valid pointer (struct rsb_mtx_t*) to
the newly allocated matrix structure; on error, NULL.
Warning
Parameters alphap,betap,transA,transB are not yet
taken in consideration. The following defaults are valid: $\alpha=1.0$ and
$transA=transB=RSB_TRANSPOSITION_N.
See also
rsb_spmsp_to_dense, rsb_sppsp,
rsb_spmsp, rsb_mtx_add_to_dense
rsb_err_t rsb_spmsp_to_dense (rsb_type_t typecode,
rsb_trans_t transA, 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)
Computes the product of sparse matrices and adds it to a dense
matrix: $C \leftarrow \alpha opa(A) dot
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;
$opa( A )= A ^T$ if transA=RSB_TRANSPOSITION_T; $opa(
A )= A ^H$ if transA=RSB_TRANSPOSITION_C; $opb( B )=B$
if transB=RSB_TRANSPOSITION_N;
$opb( B )= B ^T$ if transB=RSB_TRANSPOSITION_T; $opb(
B )= B ^H$ if transB=RSB_TRANSPOSITION_C;
Parameters
typecode A valid type code for the given
(numerical array) input pointer (see matrix_type_symbols_section).
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical
value (of the same type as matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
transB Transposition parameter for $B$ (see
matrix_transposition_flags_section).
betap Optional pointer (if NULL, will default to 1) to a numerical
value.
mtxBp Valid rsb_mtx_t pointer to matrix $B$ representation.
ldC Leading dimension of Cp array.
nrC,ncC The number of rows and columns for the dense matrix $C$.
rowmajorC RSB_BOOL_TRUE if the dense matrix $C$ is considered
stored as row major, or RSB_BOOL_FALSE if as column major.
Cp Array representing the dense matrix $C$.
Returns
RSB_ERR_NO_ERROR on correct operation, an error
code otherwise. You can use rsb_strerror_r() or rsb_perror() to
get more information about the error.
Warning
Parameters alphap,betap,transA,transB are not yet
taken in consideration. The following defaults are valid: $\alpha=1.0$ and
$transA=transB=RSB_TRANSPOSITION_N.
See also
rsb_spmsp_to_dense, rsb_sppsp,
rsb_spmsp, rsb_mtx_add_to_dense
rsb_err_t rsb_spmv (rsb_trans_t transA, const void
* alphap, const struct rsb_mtx_t * mtxAp, const void * Xp,
rsb_coo_idx_t incX, const void * betap, void * Yp, rsb_coo_idx_t
incY)
Multiplies a sparse matrix $opa(A)$ by a vector $X$, updating
vector $Y$.
Computes $Y \leftarrow
It is not allowed to supply same Xp and Yp (that is, Xp==Yp).
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;
$opa( A )= A ^T$ if transA=RSB_TRANSPOSITION_T; $opa(
A )= A ^H$ if transA=RSB_TRANSPOSITION_C; If
--enable-rsb-num-threads has been specified at configure time, the
RSB_NUM_THREADS environment variable will override the number of
executing threads specified by OMP_NUM_THREADS. (See also
RSB_IO_WANT_EXECUTING_THREADS).
Parameters
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical
value (of the same type as matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
Xp The input vector array.
incX Spacing of vector elements in each input vector array (>=1).
betap Optional pointer (if NULL, will default to 1) to a numerical
value.
Yp The output array vector.
incY Spacing of vector elements in each output vector array
(>=1).
Returns
RSB_ERR_NO_ERROR on correct operation, an error
code otherwise. You can use rsb_strerror_r() or rsb_perror() to
get more information about the error.
See also
rsb_spmv, rsb_spmm,
rsb_tune_spmm
Computes the weighted sum of two sparse matrices, returning a new
matrix: $C \leftarrow \alphadot transA(A) + try flags are ignored in this
operation.
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;
$opa( A )= A ^T$ if transA=RSB_TRANSPOSITION_T; $opa(
A )= A ^H$ if transA=RSB_TRANSPOSITION_C; $opb( B )=B$
if transB=RSB_TRANSPOSITION_N;
$opb( B )= B ^T$ if transB=RSB_TRANSPOSITION_T; $opb(
B )= B ^H$ if transB=RSB_TRANSPOSITION_C;
Parameters
typecode A valid type code for the given
(numerical array) input pointer (see matrix_type_symbols_section).
transA Transposition parameter for $A$ (see
matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical
value (of the same type as matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
transB Transposition parameter for $B$ (see
matrix_transposition_flags_section).
betap Optional pointer (if NULL, will default to 1) to a numerical
value.
mtxBp Valid rsb_mtx_t pointer to matrix $B$ representation.
errvalp An optional (can be NULL) pointer to rsb_err_t
where the error status will be written to.
Returns
On success, a valid pointer (struct rsb_mtx_t*) to
the newly allocated matrix structure; on error, NULL.
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 \leftarrow \alpha dot opt( T )^{-1} dot B $, with
upper or lower triangular $T$.
$opt( T )=T$ if transT=RSB_TRANSPOSITION_N;
$opt( T )= T ^T$ if transT=RSB_TRANSPOSITION_T; $opt(
T )= T ^H$ if transT=RSB_TRANSPOSITION_C;
Parameters
transT Transposition parameter for $T$ (see
matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical
value (of the same type as matrix).
mtxTp Valid rsb_mtx_t pointer to matrix $T$ representation. The matrix
must be triangular; that is, it must have been allocated with either
RSB_FLAG_LOWER_TRIANGULAR or
RSB_FLAG_UPPER_TRIANGULAR flags.
nrhs The number of right hand side vectors (cannot be <1).
order A flag among RSB_FLAG_WANT_COLUMN_MAJOR_ORDER and
RSB_FLAG_WANT_ROW_MAJOR_ORDER. For contiguous vector arrays, you
probably want RSB_FLAG_WANT_COLUMN_MAJOR_ORDER.
betap Optional pointer (if NULL, will default to 1) to a numerical
value.
Bp The input vector array.
ldB Leading dimension of Bp array.
Cp The output vector array.
ldC Leading dimension of Cp array.
Returns
RSB_ERR_NO_ERROR on correct operation, an error
code otherwise. You can use rsb_strerror_r() or rsb_perror() to
get more information about the error.
See also
rsb_spsm, rsb_spsv,
rsb_tune_spsm
rsb_err_t rsb_spsv (rsb_trans_t transT, const void
* alphap, const struct rsb_mtx_t * mtxTp, const void * Xp,
rsb_coo_idx_t incX, void * Yp, rsb_coo_idx_t incY)
Computes $Y \leftarrow \alpha dot opt( T )^{-1} dot X $, with
upper or lower triangular $T$. It is allowed to supply same Xp and Yp
(that is, Xp==Yp).
$opt( T )=T$ if transT=RSB_TRANSPOSITION_N;
$opt( T )= T ^T$ if transT=RSB_TRANSPOSITION_T; $opt(
T )= T ^H$ if transT=RSB_TRANSPOSITION_C;
Parameters
transT Transposition parameter for $T$ (see
matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical
value (of the same type as matrix).
mtxTp Valid rsb_mtx_t pointer to matrix $T$ representation. The matrix
must be triangular; that is, it must have been allocated with either
RSB_FLAG_LOWER_TRIANGULAR or
RSB_FLAG_UPPER_TRIANGULAR flags.
Xp The input vector array.
incX Spacing of vector elements in each input vector array (>=1).
Yp The output array vector.
incY Spacing of vector elements in each output vector array
(>=1).
Returns
RSB_ERR_NO_ERROR on correct operation, an error
code otherwise. You can use rsb_strerror_r() or rsb_perror() to
get more information about the error. If
--enable-zero-division-checks-on-solve was specified at configure time,
attempts to solve a triangular matrix with zeroes on a diagonal will
fail.
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_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