librsb  1.2.0.9
Macros | Functions
rsb_rsb.c File Reference

Implementation of the library user interface. More...

Macros

#define RSB_INTERFACE_RETURN_MTX_ERRP(MTXAP, ERRVAL, ERRVALP)
 
#define RSB_INTERFACE_RETURN_MTX(MTXAP)   RSB_INTERFACE_ENDCMD return MTXAP;
 
#define RSB_INTERFACE_RETURN_ERR(ERRVAL)   RSB_INTERFACE_ENDCMD RSB_DO_ERR_RETURN_INTERFACE(ERRVAL)
 
#define RSB_INTERFACE_RETURN_VAL(VAL)   RSB_INTERFACE_ENDCMD {return (VAL);}
 
#define RSB_EXPOSE_NEW_GENERAL_INTERFACE   1 /* temporary (internals) to delimit the new interface which supersedes the deprecated one */
 

Functions

rsb_err_t rsb_lib_init (struct rsb_initopts *iop)
 
rsb_err_t rsb_lib_set_opt (enum rsb_opt_t iof, const void *iop)
 
rsb_err_t rsb_lib_get_opt (enum rsb_opt_t iof, void *iop)
 
rsb_err_t rsb_lib_set_opt_str (const rsb_char_t *opnp, const rsb_char_t *opvp)
 
rsb_err_t rsb_lib_reinit (struct rsb_initopts *iop)
 
rsb_err_t rsb_lib_exit (struct rsb_initopts *iop)
 
struct rsb_mtx_t * rsb_mtx_alloc_from_coo_const (const void *VA, const rsb_coo_idx_t *IA, const rsb_coo_idx_t *JA, rsb_nnz_idx_t nnzA, rsb_type_t typecode, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_blk_idx_t brA, rsb_blk_idx_t bcA, rsb_flags_t flagsA, rsb_err_t *errvalp)
 
struct rsb_mtx_t * rsb_mtx_alloc_from_coo_inplace (void *VA, rsb_coo_idx_t *IA, rsb_coo_idx_t *JA, rsb_nnz_idx_t nnzA, rsb_type_t typecode, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_blk_idx_t brA, rsb_blk_idx_t bcA, rsb_flags_t flagsA, rsb_err_t *errvalp)
 
struct rsb_mtx_t * rsb_mtx_free (struct rsb_mtx_t *mtxAp)
 
rsb_err_t rsb_mtx_clone (struct rsb_mtx_t **mtxBpp, rsb_type_t typecode, rsb_trans_t transA, const void *alphap, const struct rsb_mtx_t *mtxAp, rsb_flags_t flags)
 
rsb_err_t rsb_spmv (rsb_trans_t transA, const void *alphap, const struct rsb_mtx_t *mtxAp, const void *Xp, rsb_coo_idx_t incX, const void *betap, void *Yp, rsb_coo_idx_t incY)
 
rsb_err_t rsb_spsv (rsb_trans_t transT, const void *alphap, const struct rsb_mtx_t *mtxTp, const void *Xp, rsb_coo_idx_t incX, void *Yp, rsb_coo_idx_t incY)
 
rsb_err_t rsb_spsm (rsb_trans_t transT, const void *alphap, const struct rsb_mtx_t *mtxTp, rsb_coo_idx_t nrhs, rsb_flags_t order, const void *betap, const void *Bp, rsb_nnz_idx_t ldB, void *Cp, rsb_nnz_idx_t ldC)
 
rsb_err_t rsb_coo_sort (void *VA, rsb_coo_idx_t *IA, rsb_coo_idx_t *JA, rsb_nnz_idx_t nnzA, rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, rsb_type_t typecode, rsb_flags_t flagsA)
 
rsb_err_t rsb_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)
 
rsb_err_t rsb_tune_spmm (struct rsb_mtx_t **mtxOpp, rsb_real_t *sfp, rsb_int_t *tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const void *alphap, const struct rsb_mtx_t *mtxAp, rsb_coo_idx_t nrhs, rsb_flags_t order, const void *Bp, rsb_nnz_idx_t ldB, const void *betap, void *Cp, rsb_nnz_idx_t ldC)
 
rsb_err_t rsb_tune_spsm (struct rsb_mtx_t **mtxOpp, rsb_real_t *sfp, rsb_int_t *tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const void *alphap, const struct rsb_mtx_t *mtxAp, rsb_coo_idx_t nrhs, rsb_flags_t order, const void *Bp, rsb_nnz_idx_t ldB, const void *betap, void *Cp, rsb_nnz_idx_t ldC)
 

Detailed Description

Implementation of the library user interface.

Author
Michele Martone

Macro Definition Documentation

◆ RSB_EXPOSE_NEW_GENERAL_INTERFACE

#define RSB_EXPOSE_NEW_GENERAL_INTERFACE   1 /* temporary (internals) to delimit the new interface which supersedes the deprecated one */

◆ RSB_INTERFACE_RETURN_ERR

#define RSB_INTERFACE_RETURN_ERR (   ERRVAL)    RSB_INTERFACE_ENDCMD RSB_DO_ERR_RETURN_INTERFACE(ERRVAL)

◆ RSB_INTERFACE_RETURN_MTX

#define RSB_INTERFACE_RETURN_MTX (   MTXAP)    RSB_INTERFACE_ENDCMD return MTXAP;

◆ RSB_INTERFACE_RETURN_MTX_ERRP

#define RSB_INTERFACE_RETURN_MTX_ERRP (   MTXAP,
  ERRVAL,
  ERRVALP 
)
Value:
RSB_INTERFACE_ENDCMD \
RSB_CONDITIONAL_ERRPSET(ERRVALP,ERRVAL) RSB_DO_MTX_RETURN_INTERFACE(MTXAP,ERRVAL);

◆ RSB_INTERFACE_RETURN_VAL

#define RSB_INTERFACE_RETURN_VAL (   VAL)    RSB_INTERFACE_ENDCMD {return (VAL);}

Function Documentation

◆ rsb_lib_get_opt()

rsb_err_t rsb_lib_get_opt ( enum rsb_opt_t  iof,
void *  iop 
)

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

Parameters
ioflibrary options flags. See rsb_opt_t for a list of valid options.
ioplibrary options value output pointer (pointed location will be updated).
See also
RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP
rsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or (deprecated) macros RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..

◆ rsb_lib_set_opt()

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

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

Parameters
ioflibrary options flags. See rsb_opt_t for a list of valid options.
ioplibrary options value output pointer (pointed location will be updated).
See also
RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP
rsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or (deprecated) macros RSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..

◆ rsb_mtx_clone()

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 
)
       \ingroup rsb_doc_matrix_assembly rsb_doc_rsb

       This function clones a given matrix, allocating a fresh data structure or overwriting an existing one.
       \n
       Target type (specified by \c typecode) can be different from that in the matrix.
       \c
       If \c alphap=NULL, the cloned matrix will not be scaled.
       \n
       This new structure will be completely separated and independent from the original one.
       \n
       Examples:
       \code

// 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
mtxBppValid rsb_mtx_t pointer to an address for matrix $B$. If *mtxBpp==NULL, a fresh clone will be assigned there; if not, the existing matrix structure will be freed and allocated to host the new one. The case *mtxBpp==mtxAp is supported.
typecodeA valid type code for the desired output matrix (see matrix_type_symbols_section).
transATransposition parameter for $A$ (see matrix_transposition_flags_section).
alphapOptional pointer (if NULL, will default to 1) to a numerical value for scaling the output. Of the type code of mtxAp.
mtxApValid rsb_mtx_t pointer to matrix $A$ representation.
flagsEither RSB_FLAG_IDENTICAL_FLAGS or a combination of other flags, e.g.: RSB_FLAG_C_INDICES_INTERFACE, RSB_FLAG_SYMMETRIC, RSB_FLAG_HERMITIAN, RSB_FLAG_TRIANGULAR, RSB_FLAG_UPPER, RSB_FLAG_LOWER, RSB_FLAG_UNIT_DIAG_IMPLICIT, RSB_FLAG_DISCARD_ZEROS. Flag RSB_FLAG_EXTERNALLY_ALLOCATED_ARRAYS is forbidden. Flag RSB_FLAG_FORTRAN_INDICES_INTERFACE is ignored.
Returns
RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or rsb_perror() to get more information about the error.
See also
rsb_mtx_alloc_from_coo_const, rsb_mtx_alloc_from_coo_inplace, rsb_mtx_free, rsb_mtx_clone, rsb_mtx_alloc_from_csr_const, rsb_mtx_alloc_from_csc_const, rsb_mtx_alloc_from_csr_inplace, rsb_mtx_switch_to_csr, rsb_mtx_alloc_from_coo_begin, rsb_mtx_alloc_from_coo_end

◆ rsb_mtx_get_coo_block()

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 
)
       \ingroup rsb_doc_matrix_conversion rsb_doc_rsb

       Writes in COO format the specified submatrix.
       Works in two stages: first the user invokes it with \c VA,IA,JA set to \c NULL  to get \c *rnzp.
       Then the \c VA,IA,JA arrays can be allocated, and the function called again, this time with \c rnzp=NULL but the \c VA,IA,JA arrays pointers non \c NULL (or at least, one of them).

       \param mtxAp Valid \c rsb_mtx_t pointer to matrix \f$A\f$ representation.
       \param VA,IA,JA Output numerical values (\c VA) array; output row (\c IA) and column (\c JA) indices arrays.
       \param frA,lrA First and last row indices.
       \param fcA,lcA First and last column indices.
       \param IREN,JREN Renumbering arrays for \c IA and \c JA (respectively rows count and columns count sized). If \c NULL, no renumbering will be used.
       \param rnzp A pointer where the number of relevant nonzero elements will be written to.
       \param flags Either #RSB_FLAG_FORTRAN_INDICES_INTERFACE or #RSB_FLAG_C_INDICES_INTERFACE              (see \ref flags_section flags section).
       \return #RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use #rsb_strerror_r() or #rsb_perror() to get more information about the error.
       Examples:
       \code

// get nnz count first errval=rsb_mtx_get_coo_block(mtxAp,NULL,NULL,NULL,frA,lrA,fcA,lcA,NULL,NULL,&rnz,flags ) // allocate VA, IA, JA to rnz elements ... // get the rnz values then errval=rsb_mtx_get_coo_block(mtxAp, VA, IA, JA,frA,lrA,fcA,lcA,NULL,NULL,NULL,flags )

Warning
Expect this function to change soon (e.g.: have scaling parameters, etc.). Contact the author if you intend to use it.
See also
rsb_mtx_get_coo, rsb_mtx_get_csr, rsb_mtx_get_rows_sparse, rsb_mtx_get_coo_block, rsb_mtx_get_prec, rsb_mtx_get_nrm, rsb_mtx_get_vec, rsb_file_mtx_get_dims, rsb_mtx_get_vals

◆ rsb_tune_spmm()

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 
)
    \ingroup rsb_doc_matrix_assembly rsb_doc_rsb

    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 \c *mtxOpp.  If \c nrhs==1 and \c 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 \c Bp,Cp implicitly, with  \c ldB=0  and \c ldC=0: in this case, their values will be computed internally and if \c Bp!=NULL,Cp!=NULL, they will be assumed of being sufficiently sized.  Values of \c nrhs<1 will be treated as 1.  \c Bp, \c Cp can be \c NULL: temporary vectors will be allocated, used, and deallocated within the tuner. If \c mtxOpp=NULL and \c *tnp!=NULL the best thread count will be probed for the matrix given in \c 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 \c mtxAp==NULL, then the \c *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 \c mtxAp!=NULL&&*mtxOpp!=NULL is illegal and will cause an error.
    \param mtxOpp           Optimal matrix structure pointer will be assigned to \c *mtxOpp (it may occur that *mtxOpp==mtxAp on output). If \c mtxOpp  is \c NULL then no data structure optimization will be attempted; rather, only optimal threads search will occur (\c tnp must be not \c NULL  then).
    \param sfp              Achieved speedup factor will be written to \c *sfp  (unless \c sfp==NULL).
    \param tnp              If \c tnp==NULL on input, the current thread count will be utilized. Otherwise, if \c *tnp>0, then *tnp will be used as first suggestion in optimal thread count searching. If \c tnp!=NULL ,on output \c *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.: \c 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.
    \param maxr             Optimizer rounds max count. If \c <1, will be treated as 1; if 0 will be decided automatically. Max is #RSB_CONST_MAX_TUNING_ROUNDS.
    \param maxt             Maximum time (in seconds) per optimization round (does not take in account conversion time). If \c maxt<0.0 is provided, \c -ceil(maxt) will be interpreted as number of iterations to check for each operation time sample. If \c maxt==0.0 is provided, a default choice will be made instead.
    \param transA Transposition parameter for \f$A\f$ (see \ref matrix_transposition_flags_section).
    \param alphap Optional pointer (if \c NULL, will default to 1) to a numerical value (of the same type as matrix).
    \param mtxAp Valid \c rsb_mtx_t pointer to matrix \f$A\f$ representation.
    \param nrhs The number of right hand side vectors (cannot be \c <1).
    \param 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.
    \param Bp The input vector array. If \c NULL, a temporary, internally allocated copy will be used.
    \param ldB Leading dimension of \c Bp array.
    \param betap Optional pointer (if \c NULL, will default to 1) to a numerical value.
    \param Cp The output vector array. If \c NULL, a temporary, internally allocated copy will be used.
    \param ldC Leading dimension of \c Cp array.
    \return #RSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use #rsb_strerror_r() or #rsb_perror() to get more information about the error.

       Examples:
       \code

// obtain best thread count for mtxAp: errval = rsb_tune_spmm(NULL ,&sf,&tn ,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);

// obtain best thread count for mtxAp; Bp and Cp will be allocated by the tuner: errval = rsb_tune_spmm(NULL ,&sf,&tn ,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,NULL,0,&beta,NULL,0);

// obtain best clone of mtxAp (for current thread count): assert(mtxOp == NULL && mtxAp != NULL); errval = rsb_tune_spmm(&mtxOp,&sf,NULL,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);

// obtain best clone of mtxAp and best thread count: assert(mtxOp == NULL && mtxAp != NULL); errval = rsb_tune_spmm(&mtxOp,&sf,&tn ,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);

// replace mtxAp with best clone (if any): errval = rsb_tune_spmm(&mtxAp,&sf,NULL,maxr,maxt,transA,&alpha,NULL ,nrhs,order,Bp,ldB,&beta,Cp,ldC);

// replace mtxAp with best clone (if any) and obtain best thread count: errval = rsb_tune_spmm(&mtxAp,&sf,&tn ,maxr,maxt,transA,&alpha,NULL ,nrhs,order,Bp,ldB,&beta,Cp,ldC);

// illegal call: assert(mtxOp != NULL && mtxAp != NULL); errval = rsb_tune_spmm(&mtxOp,&sf,&tn ,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);

Warning
This function is still experimental. In case of error, although the matrix shall be unaffected, the library status may be affected (e.g.: execution thread count, default matrix subdivision).
Todo:
In the future, autotuning functionality shall improve considerably. Need support for lightweight, threads-only optimization. May support strided vectors in the future.
See also
rsb_spmv, rsb_spmm, rsb_tune_spmm