librsb

SYNOPSIS

Data Structures

class RsbLib
Class initializing/finalizing librsb state.

#define RSBP_DEPRECATED
Internal attribute specifier for deprecated member functions. #define RSBP_NODISCARD
Internal attribute. #define RSBP_WANT_REV 0
If this is defined to 1 before including <rsb.hpp>, rsb_err_t is the default return type. Otherwise the default is void. #define RSBP_RVT template <typename Err_t=void>
No return type. #define RSBP_MSLVRV 10201
Minimal supported librsb version (value of RSB_LIBRSB_VER, defined via rsb.h).

Enumerations

enum RsbSym { IsGen = RSB_FLAG_NOFLAGS, IsHer = RSB_FLAG_HERMITIAN, IsSym = RSB_FLAG_SYMMETRIC, IsTri = RSB_FLAG_TRIANGULAR }
enum RsbOp { Sum }

Functions

RsbMatrix (rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, const RsbSym sym=IsGen)
RsbMatrix (rsb_coo_idx_t nrA, const rsb_coo_idx_t *RP, const rsb_coo_idx_t *JA, const NT *VA, const RsbSym sym=IsGen)
RsbMatrix (const rsb_coo_idx_t *IA, const rsb_coo_idx_t *JA, const NT *VA, rsb_nnz_idx_t nnzA, const rsb_flags_t flagsA=RSB_FLAG_NOFLAGS)
RsbMatrix (const rsb_char_t *filename, const RsbSym sym=IsGen)
RsbMatrix (const RsbMatrix &A_Rsb, bool do_trans=false, rsb_flags_t flagsA=RSB_FLAG_NOFLAGS)
RsbMatrix (RsbMatrix &&other)
~RsbMatrix (void)
RSBP_RVT RSBP_DEPRECATED Err_t _add (rsb_coo_idx_t i, rsb_coo_idx_t j, NT val)
RSBP_RVT Err_t close (void)
RSBP_RVT RSBP_DEPRECATED Err_t _close (void)
RSBP_RVT RSBP_DEPRECATED Err_t spmv (rsb_trans_t transA, const NT *alphap, const NT *Xp, rsb_coo_idx_t incX, const NT *betap, NT *Yp, rsb_coo_idx_t incY) const
RSBP_RVT Err_t spmv (rsb_trans_t transA, const NT alpha, const NT *Xp, rsb_coo_idx_t incX, const NT beta, NT *Yp, rsb_coo_idx_t incY) const
RSBP_RVT Err_t spmv (rsb_trans_t transA, const NT alpha, const NT *Xp, const NT beta, NT *Yp) const
RSBP_RVT Err_t spmv (NT *y, const NT *x, bool do_trans=false) const
RSBP_RVT RSBP_DEPRECATED Err_t spmm (rsb_trans_t transA, const NT *alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT *Bp, rsb_nnz_idx_t ldB, const NT *betap, NT *Cp, rsb_nnz_idx_t ldC) const
RSBP_RVT Err_t spmm (rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT *Bp, rsb_nnz_idx_t ldB, const NT beta, NT *Cp, rsb_nnz_idx_t ldC) const
RSBP_RVT Err_t spmm (rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT *Bp, const NT beta, NT *Cp) const
RSBP_RVT RSBP_DEPRECATED Err_t spsm (rsb_trans_t transT, const NT *alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT *betap, const NT *Bp, rsb_nnz_idx_t ldB, NT *Cp, rsb_nnz_idx_t ldC) const
RSBP_RVT Err_t spsm (rsb_trans_t transT, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT beta, const NT *Bp, rsb_nnz_idx_t ldB, NT *Cp, rsb_nnz_idx_t ldC) const
RSBP_RVT Err_t spsm (rsb_trans_t transT, const NT alpha, rsb_coo_idx_t nrhs, const NT *Bp, NT *Cp) const
RSBP_RVT Err_t spsm (NT *y, const NT *x, rsb_coo_idx_t nrhs, bool do_trans=false) const
RSBP_RVT Err_t spsm (NT *y, rsb_coo_idx_t nrhs, bool do_trans=false) const
RSBP_RVT RSBP_DEPRECATED Err_t spsv (rsb_trans_t transT, const NT *alphap, const NT *Xp, rsb_coo_idx_t incX, NT *Yp, rsb_coo_idx_t incY) const
RSBP_RVT Err_t spsv (rsb_trans_t transT, const NT alpha, const NT *Xp, NT *Yp) const
RSBP_RVT Err_t spsv (NT *y, const NT *x, bool do_trans=false) const
RSBP_RVT Err_t spsv (NT *y, bool do_trans=false) const
size_t get_info_size_t (enum rsb_mif_t mif) const
rsb_flags_t get_info_rsb_flags_t (enum rsb_mif_t mif) const
rsb_blk_idx_t get_info_blk_t (enum rsb_mif_t mif) const
rsb_nnz_idx_t get_info_nnz_t (enum rsb_mif_t mif) const
rsb_flags_t get_flags_t (enum rsb_mif_t mif) const
rsb_type_t get_type_t (enum rsb_mif_t mif) const
rsb_coo_idx_t get_info_coo_t (enum rsb_mif_t mif) const
size_t _get_index_storage_bytes (void) const
size_t _get_storage_bytes (void) const
rsb_nnz_idx_t nnz (void) const
rsb_blk_idx_t blocks (void) const
rsb_coo_idx_t rows (void) const
rsb_coo_idx_t cols (void) const
RSBP_RVT Err_t get_vals (NT *VA, const rsb_coo_idx_t *IA, const rsb_coo_idx_t *JA, rsb_nnz_idx_t nnz, rsb_flags_t flags) const
NT get_val (const rsb_coo_idx_t i, const rsb_coo_idx_t j, rsb_flags_t flags=RSB_FLAG_NOFLAGS) const
RSBP_RVT Err_t set_val (const NT val, const rsb_coo_idx_t i, const rsb_coo_idx_t j, rsb_flags_t flags=RSB_FLAG_NOFLAGS)
RSBP_RVT Err_t set_vals (const NT *VA, const rsb_coo_idx_t *IA, const rsb_coo_idx_t *JA, rsb_nnz_idx_t nnz, rsb_flags_t flags)
RSBP_RVT Err_t get_vec (NT *Dp, enum rsb_extff_t flags) const
RSBP_RVT RSBP_DEPRECATED Err_t get_coo (rsb_trans_t transA, NT *VA, rsb_coo_idx_t *IA, rsb_coo_idx_t *JA, rsb_flags_t flags) const
RSBP_RVT RSBP_DEPRECATED Err_t get_csr (rsb_trans_t transA, NT *VA, rsb_coo_idx_t *RP, rsb_coo_idx_t *JA, rsb_flags_t flags) const
RSBP_RVT RSBP_DEPRECATED Err_t get_rows_sparse (rsb_trans_t transA, const NT *alphap, NT *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) const
RSBP_RVT Err_t upd_vals (enum rsb_elopf_t elop_flags, const NT &omega)
RSBP_RVT Err_t upd_vals (enum rsb_elopf_t elop_flags, const NT *omegap)
RSBP_RVT Err_t get_nrm (NT *Np, enum rsb_extff_t flags) const
rsb_type_t rsbtype (void) const
rsb_flags_t rsbflags (void) const
rsb_string_t get_info_str (const char *key) const
RSBP_RVT Err_t get_info (enum rsb_mif_t miflags, void *minfop) const
rsb_string_t _info (void) const
RSBP_RVT RSBP_DEPRECATED Err_t tune_spsm_threads (rsb_real_t *sfp=RSBP_NULL, rsb_int_t *tnp=RSBP_NULL, rsb_int_t maxr=0, rsb_time_t maxt=0, rsb_trans_t transA=RSB_TRANSPOSITION_N, const NT *alphap=RSBP_NULL, rsb_coo_idx_t nrhs=1, rsb_flags_t order=RSB_FLAG_WANT_COLUMN_MAJOR_ORDER, const NT *Bp=RSBP_NULL, rsb_nnz_idx_t ldB=0, const NT *betap=RSBP_NULL, NT *Cp=RSBP_NULL, rsb_nnz_idx_t ldC=0) const
RSBP_RVT RSBP_DEPRECATED Err_t tune_spmm_threads (rsb_real_t *sfp=RSBP_NULL, rsb_int_t *tnp=RSBP_NULL, rsb_int_t maxr=0, rsb_time_t maxt=0, rsb_trans_t transA=RSB_TRANSPOSITION_N, const NT *alphap=RSBP_NULL, rsb_coo_idx_t nrhs=1, rsb_flags_t order=RSB_FLAG_WANT_COLUMN_MAJOR_ORDER, const NT *Bp=RSBP_NULL, rsb_nnz_idx_t ldB=0, const NT *betap=RSBP_NULL, NT *Cp=RSBP_NULL, rsb_nnz_idx_t ldC=0) const
RSBP_RVT RSBP_DEPRECATED Err_t tune_spmm (rsb_real_t *sfp, rsb_int_t *tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const NT *alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT *Bp, rsb_nnz_idx_t ldB, const NT *betap, NT *Cp, rsb_nnz_idx_t ldC)
RSBP_RVT RSBP_DEPRECATED Err_t tune_spmm (rsb_real_t *sfp, rsb_int_t *tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT *Bp, rsb_nnz_idx_t ldB, const NT beta, NT *Cp, rsb_nnz_idx_t ldC)
RSBP_RVT Err_t tune_spmm (rsb_real_t &sf, rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT *Bp, const NT beta, NT *Cp)
RSBP_RVT RSBP_DEPRECATED Err_t tune_spsm (rsb_real_t *sfp, rsb_int_t *tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const NT *alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT *Bp, rsb_nnz_idx_t ldB, const NT *betap, NT *Cp, rsb_nnz_idx_t ldC)
RSBP_RVT Err_t file_save (const rsb_char_t *filename=RSBP_NULL) const
RsbMatrix & operator= (const RsbMatrix &A_Rsb)
bool _is_complex (void) const
bool operator== (const RsbMatrix &B_Rsb) const
bool operator!= (const RsbMatrix &B_Rsb) const
NT normOne (void) const
NT normInf (void) const
RSBP_RVT Err_t rndr (const rsb_char_t *filename=RSBP_NULL, rsb_coo_idx_t pmWidth=512, rsb_coo_idx_t pmHeight=512, rsb_marf_t rflags=RSB_MARF_EPS) const
RsbMatrix (rsb_trans_t transA, NT alpha, const RsbMatrix &mtxA, rsb_trans_t transB, NT beta, const RsbMatrix &mtxB, RsbOp op)
RsbMatrix (const RsbMatrix &mtxA, const RsbMatrix &mtxB, RsbOp op)

Variables

rsb_mtx_t * mtxAp_ {RSBP_NULL}
Represent a sparse matrix in RSB format by means of librsb.

Detailed Description

Classes RsbLib and RsbMatrix provide native C++ access to librsb.

Most of the librsb functionality is available via C++ classes RsbLib and RsbMatrix.
These classes are defined in header file <rsb.hpp>, which wraps functionality of librsb's C interface <rsb.h>.
The RsbMatrix class can manipulate sparse matrices of several numerical types (same ones as librsb: matrix_supported_numerical_types_section).
Before using RsbMatrix, the library must be initialized by having a RsbLib object.
To avoid problems when including this header, don't define preprocessor macros prefixed with RSB_ or RSBP_.

For a quick start, check out examples/example.cpp or other examples in its directory.

/*
Copyright (C) 2020-2022 Michele Martone
This file is part of librsb.
librsb is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
librsb is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
License for more details.
You should have received a copy of the GNU Lesser General Public
License along with librsb; see the file COPYING.
If not, see <https://www.gnu.org/licenses/>.
*/
/*!
 \ingroup rsb::examples
  @author Michele Martone
 @brief C++ example based on <rsb.hpp> using RsbMatrix.spmm().
 Using a a sblib does not differ conceptually much 
 Errors caught by ced and trigger an exception instead.
 Memory management of matrices and the library state itself follow the usual C++ RAII rules:
 the \c mtx object is freed first via RsbMatrix's destructor;
 then s finalized via RsbLib()'s destructor .
 \include example.cpp
 */
#include <rsb.hpp>
using namespace rsb;
#ifdef RSB_NUMERICAL_TYPE_DOUBLE
#if RSBP_WANT_CPP20
#include <vector>
#include <array>
/* If your compiler is C++20 compatible, the std::span-based interface is available like: */
auto main() -> int {
  RsbLib rsblib;
  const rsb_nnz_idx_t nnzA { 7 };
  const rsb_coo_idx_t nrA { 6 }, ncA { 6 }, nrhs { 2 };
  const rsb_coo_idx_t IA [nnzA] {0,1,2,3,4,5,1};
  std::array<rsb_coo_idx_t,7> JA {0,1,2,3,4,5,0};
  std::vector<double> VA {1,1,1,1,1,1,2}, X(nrhs*ncA,1);
  std::vector<double> Y(nrhs*nrA,0);
  const double alpha {2}, beta {1};
  rsb_int_t tn {0};
  rsb_real_t sf {0}; // speedup factor (tune_spmm output)
  const rsb_flags_t order {RSB_FLAG_WANT_COLUMN_MAJOR_ORDER};
  // IA,JA,VA are respectively from a C array, std::vector, std::array;
  // here using the C++20's std::span interface:
  RsbMatrix<double> mtx(IA,JA,VA);
  mtx.file_save(); // rsb_file_mtx_save
  mtx.tune_spmm(sf,RSB_TRANSPOSITION_N,alpha,nrhs,order,X,beta,Y); // rsb_tune_spmm
  mtx.spmm(RSB_TRANSPOSITION_N,alpha,nrhs,order,X,beta,Y); // rsb_spmv
}
#else
#include <vector>
/* The pointer-based interface is available as well: */
auto main() -> int {
  RsbLib rsblib;
  const rsb_nnz_idx_t nnzA { 7 };
  const rsb_coo_idx_t nrA { 6 }, ncA { 6 }, nrhs { 1 };
  const std::vector<rsb_coo_idx_t> IA {0,1,2,3,4,5,1}, JA {0,1,2,3,4,5,0};
  const std::vector<double> VA {1,1,1,1,1,1,2}, X(ncA,1);
  std::vector<double> Y(nrA,0);
  const double alpha {2}, beta {1};
  rsb_int_t tn {0};
  rsb_real_t sf {0}; // speedup factor (tune_spmm output)
  RsbMatrix<double> mtx(IA.data(),JA.data(),VA.data(),nnzA);
  mtx.file_save(nullptr); // rsb_file_mtx_save
  mtx.tune_spmm(&sf,&tn,0,0.0,RSB_TRANSPOSITION_N,alpha,nrhs,RSB_FLAG_WANT_COLUMN_MAJOR_ORDER,X.data(),ncA,beta,Y.data(),nrA); // rsb_tune_spmm
  mtx.spmv(RSB_TRANSPOSITION_N, alpha, X.data(), beta, Y.data()); // rsb_spmv
}
#endif
#else
auto main() { }
#endif

Author

Michele Martone

Macro Definition Documentation

#define RSBP_DEPRECATED

Internal attribute specifier for deprecated member functions. Header-only (rsb.hpp) wrapper classes for librsb (http://librsb.sf.net).

#define RSBP_MSLVRV 10201

Minimal supported librsb version (value of RSB_LIBRSB_VER, defined via rsb.h).

#define RSBP_NODISCARD

Internal attribute.

#define RSBP_RVT template <typename Err_t=void>

No return type.

#define RSBP_WANT_REV 0

If this is defined to 1 before including <rsb.hpp>, rsb_err_t is the default return type. Otherwise the default is void.

Enumeration Type Documentation

enum RsbOp

Enumerator

Sum

enum RsbSym

Matrix structure: either general, symmetric, hermitian, or triangular (also see rsb_flags_t).

Enumerator

IsGen: General matrix, no triangle structure or symmetry assumed.
IsHer: Hermitian ( $ A == A^H $). Please pass only lower/upper triangle.
IsSym: Symmetric ( $ A == A^T $). Please pass only lower/upper triangle.
IsTri: Triangular (required for spsv/ spsm).

Function Documentation

RSBP_RVT RSBP_DEPRECATED Err_t _add (rsb_coo_idx_t i, rsb_coo_idx_t j, NT val)

Deprecated

Use set_val() and set_vals() instead.

RSBP_RVT RSBP_DEPRECATED Err_t _close (void )

Deprecated

Use close() instead.

size_t _get_index_storage_bytes (void ) const

\rl_name_to_be_changed

size_t _get_storage_bytes (void ) const

\rl_name_to_be_changed

rsb_string_t _info (void ) const

\rl_name_to_be_changed

bool _is_complex (void ) const

\rl_name_to_be_changed

RSBP_RVT Err_t close (void )

Terminate assembly of a previously started and populated matrix.
Shall be called once.

sblib_asm_snip

See also

RsbMatrix::RsbMatrix(rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, const RsbSym sym = IsGen ); sblib_based_on_pred rsb_mtx_alloc_from_coo_end() sblib_based_on_post

rsb_coo_idx_t cols (void ) const

sblib_dims_snip

RSBP_RVT Err_t file_save (const rsb_char_t * filename = RSBP_NULL) const

sblib_based_on_pred rsb_file_mtx_save() sblib_based_on_post

Example snip from examples/misc.cpp:

    mtx.file_save(); // print to stdout

RSBP_RVT RSBP_DEPRECATED Err_t get_coo (rsb_trans_t transA, NT * VA, rsb_coo_idx_t * IA, rsb_coo_idx_t * JA, rsb_flags_t flags) const

sblib_based_on_pred rsb_mtx_get_coo() sblib_based_on_post

\rl_no_transa \rl_deprecate

RSBP_RVT RSBP_DEPRECATED Err_t get_csr (rsb_trans_t transA, NT * VA, rsb_coo_idx_t * RP, rsb_coo_idx_t * JA, rsb_flags_t flags) const

sblib_based_on_pred rsb_mtx_get_csr() sblib_based_on_post

\rl_no_transa \rl_deprecate

rsb_flags_t get_flags_t (enum rsb_mif_t mif) const

sblib_based_on_pred rsb_mtx_get_info() sblib_based_on_post

RSBP_RVT Err_t get_info (enum rsb_mif_t miflags, void * minfop) const

sblib_based_on_pred rsb_mtx_get_info() sblib_based_on_post

rsb_blk_idx_t get_info_blk_t (enum rsb_mif_t mif) const

sblib_based_on_pred rsb_mtx_get_info() sblib_based_on_post

rsb_coo_idx_t get_info_coo_t (enum rsb_mif_t mif) const

sblib_based_on_pred rsb_mtx_get_info() sblib_based_on_post

rsb_nnz_idx_t get_info_nnz_t (enum rsb_mif_t mif) const

sblib_based_on_pred rsb_mtx_get_info() sblib_based_on_post

rsb_flags_t get_info_rsb_flags_t (enum rsb_mif_t mif) const

sblib_based_on_pred rsb_mtx_get_info() sblib_based_on_post

size_t get_info_size_t (enum rsb_mif_t mif) const

sblib_based_on_pred rsb_mtx_get_info() sblib_based_on_post

rsb_string_t get_info_str (const char * key) const

sblib_based_on_pred rsb_mtx_get_info_str() sblib_based_on_post

RSBP_RVT Err_t get_nrm (NT * Np, enum rsb_extff_t flags) const

sblib_based_on_pred rsb_mtx_get_nrm() sblib_based_on_post

RSBP_RVT RSBP_DEPRECATED Err_t get_rows_sparse (rsb_trans_t transA, const NT * alphap, NT * 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) const

sblib_based_on_pred rsb_mtx_get_rows_sparse() sblib_based_on_post

\rl_deprecate

rsb_type_t get_type_t (enum rsb_mif_t mif) const

sblib_based_on_pred rsb_mtx_get_info() sblib_based_on_post

NT get_val (const rsb_coo_idx_t i, const rsb_coo_idx_t j, rsb_flags_t flags = RSB_FLAG_NOFLAGS) const

sblib_based_on_pred rsb_mtx_get_vals() sblib_based_on_post

RSBP_RVT Err_t get_vals (NT * VA, const rsb_coo_idx_t * IA, const rsb_coo_idx_t * JA, rsb_nnz_idx_t nnz, rsb_flags_t flags) const

sblib_based_on_pred rsb_mtx_get_vals() sblib_based_on_post

RSBP_RVT Err_t get_vec (NT * Dp, enum rsb_extff_t flags) const

sblib_based_on_pred rsb_mtx_get_vec() sblib_based_on_post

bool operator!= (const RsbMatrix & B_Rsb) const

sblib__cmp_snip

See also

RsbMatrix::operator==(const RsbMatrix & B_Rsb) const;

RsbMatrix & operator= (const RsbMatrix & A_Rsb)

A copy constructor. Will clone the input matrix contents.

bool operator== (const RsbMatrix & B_Rsb) const

Deep comparison: compare if the two matrices have same dimensions, nonzeroes count, nonzeroes pattern and value. Meant for very sporadic use. Inefficient: it can involve matrices copying.

sblib__cmp_snip

RSBP_RVT Err_t rndr (const rsb_char_t * filename = RSBP_NULL, rsb_coo_idx_t pmWidth = 512, rsb_coo_idx_t pmHeight = 512, rsb_marf_t rflags = RSB_MARF_EPS) const

sblib_based_on_pred rsb_mtx_rndr() sblib_based_on_post

sblib_rndr_snip

rsb_coo_idx_t rows (void ) const

sblib_dims_snip

RsbMatrix (const rsb_char_t * filename, const RsbSym sym = IsGen)

Assemble a sparse matrix given filename input.
sblib_based_on_pred rsb_file_mtx_load() sblib_based_on_post

RsbMatrix (const rsb_coo_idx_t * IA, const rsb_coo_idx_t * JA, const NT * VA, rsb_nnz_idx_t nnzA, const rsb_flags_t flagsA = RSB_FLAG_NOFLAGS)

Assemble a sparse matrix given COO input.
sblib__asm_coo_snip
sblib_based_on_pred rsb_mtx_alloc_from_coo_const() sblib_based_on_post

RsbMatrix (const RsbMatrix & A_Rsb, bool do_trans = false, rsb_flags_t flagsA = RSB_FLAG_NOFLAGS)

Copy a sparse matrix given example input.
Can either clone it, or transpose it or change flags (structure) in the process.

RsbMatrix (rsb_coo_idx_t nrA, const rsb_coo_idx_t * RP, const rsb_coo_idx_t * JA, const NT * VA, const RsbSym sym = IsGen)

Assemble a sparse matrix given CSR input.
sblib_based_on_pred rsb_mtx_alloc_from_csr_const() sblib_based_on_post

RsbMatrix (rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, const RsbSym sym = IsGen)

Begin assembling a sparse matrix of given dimensions and type.
Then you can use set_val() or set_vals() repeatedly to populate the matrix.
After populating the matrix, use close() to terminate its assembly.
sblib_asm_snip

sblib_based_on_pred rsb_mtx_alloc_from_coo_begin() sblib_based_on_post

RsbMatrix (rsb_trans_t transA, NT alpha, const RsbMatrix & mtxA, rsb_trans_t transB, NT beta, const RsbMatrix & mtxB, RsbOp op)

sblib_based_on_pred rsb_sppsp() sblib_based_on_post

RsbMatrix (RsbMatrix && other)

Move constructor.
The moved matrix object will be invalid afterwards.
Example snip from examples/misc.cpp:

  assert( mtx1.nnz() == nnzA );
  RsbMatrix<double> mtx3 { std::move(mtx1) };
  assert( mtx3.nnz() == nnzA );

rsb_type_t rsbtype (void ) const

sblib_rsbtype_snip

RSBP_RVT Err_t set_val (const NT val, const rsb_coo_idx_t i, const rsb_coo_idx_t j, rsb_flags_t flags = RSB_FLAG_NOFLAGS)

sblib_based_on_pred rsb_mtx_set_vals() sblib_based_on_post

sblib_asm_snip

See also

set_vals().

RSBP_RVT Err_t set_vals (const NT * VA, const rsb_coo_idx_t * IA, const rsb_coo_idx_t * JA, rsb_nnz_idx_t nnz, rsb_flags_t flags)

Add a single entry during the assembly of a matrix created empty.
Use close() to terminate matrix assembly.

sblib_asm_snip

sblib_based_on_pred rsb_mtx_set_vals() sblib_based_on_post

RSBP_RVT RSBP_DEPRECATED Err_t spmm (rsb_trans_t transA, const NT * alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, rsb_nnz_idx_t ldB, const NT * betap, NT * Cp, rsb_nnz_idx_t ldC) const

sblib_based_on_pred rsb_spmm() sblib_based_on_post \rl_deprecate

RSBP_RVT Err_t spmm (rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, const NT beta, NT * Cp) const

sblib_based_on_prei rsb_spmm() sblib_based_on_post

RSBP_RVT Err_t spmm (rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, rsb_nnz_idx_t ldB, const NT beta, NT * Cp, rsb_nnz_idx_t ldC) const

sblib_spmm_snip

sblib_based_on_prei rsb_spmm() sblib_based_on_post

RSBP_RVT Err_t spmv (NT * y, const NT * x, bool do_trans = false) const

sblib_based_on_prei rsb_spmv() sblib_based_on_post

sblib_spmv_snip

RSBP_RVT RSBP_DEPRECATED Err_t spmv (rsb_trans_t transA, const NT * alphap, const NT * Xp, rsb_coo_idx_t incX, const NT * betap, NT * Yp, rsb_coo_idx_t incY) const

sblib_based_on_pred rsb_spmv() sblib_based_on_post \rl_deprecate

RSBP_RVT Err_t spmv (rsb_trans_t transA, const NT alpha, const NT * Xp, const NT beta, NT * Yp) const

sblib_based_on_prei rsb_spmv() sblib_based_on_post

sblib_spmv_snip

RSBP_RVT Err_t spmv (rsb_trans_t transA, const NT alpha, const NT * Xp, rsb_coo_idx_t incX, const NT beta, NT * Yp, rsb_coo_idx_t incY) const

sblib_based_on_prei rsb_spmv() sblib_based_on_post

sblib_spmv_snip

RSBP_RVT Err_t spsm (NT * y, const NT * x, rsb_coo_idx_t nrhs, bool do_trans = false) const

sblib_based_on_prei rsb_spsm() sblib_based_on_post

RSBP_RVT Err_t spsm (NT * y, rsb_coo_idx_t nrhs, bool do_trans = false) const

sblib_based_on_prei rsb_spsm() sblib_based_on_post

RSBP_RVT RSBP_DEPRECATED Err_t spsm (rsb_trans_t transT, const NT * alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * betap, const NT * Bp, rsb_nnz_idx_t ldB, NT * Cp, rsb_nnz_idx_t ldC) const

sblib_based_on_pred rsb_spsm() sblib_based_on_post \rl_deprecate

RSBP_RVT Err_t spsm (rsb_trans_t transT, const NT alpha, rsb_coo_idx_t nrhs, const NT * Bp, NT * Cp) const

sblib_based_on_prei rsb_spsm() sblib_based_on_post

RSBP_RVT Err_t spsm (rsb_trans_t transT, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT beta, const NT * Bp, rsb_nnz_idx_t ldB, NT * Cp, rsb_nnz_idx_t ldC) const

sblib_based_on_prei rsb_spsm() sblib_based_on_post

RSBP_RVT Err_t spsv (NT * y, bool do_trans = false) const

sblib_based_on_prei rsb_spsv() sblib_based_on_post

RSBP_RVT Err_t spsv (NT * y, const NT * x, bool do_trans = false) const

sblib_based_on_prei rsb_spsv() sblib_based_on_post

RSBP_RVT RSBP_DEPRECATED Err_t spsv (rsb_trans_t transT, const NT * alphap, const NT * Xp, rsb_coo_idx_t incX, NT * Yp, rsb_coo_idx_t incY) const

sblib_based_on_pred rsb_spsv() sblib_based_on_post \rl_deprecate

RSBP_RVT Err_t spsv (rsb_trans_t transT, const NT alpha, const NT * Xp, NT * Yp) const

sblib_based_on_prei rsb_spsv() sblib_based_on_post

RSBP_RVT Err_t tune_spmm (rsb_real_t & sf, rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, const NT beta, NT * Cp)

sblib_based_on_prei rsb_tune_spmm() sblib_based_on_post

sblib_autotune_snip

RSBP_RVT RSBP_DEPRECATED Err_t tune_spmm (rsb_real_t * sfp, rsb_int_t * tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const NT * alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, rsb_nnz_idx_t ldB, const NT * betap, NT * Cp, rsb_nnz_idx_t ldC)

sblib_based_on_pred rsb_tune_spmm() sblib_based_on_post

sblib_autotune_snip

\rl_deprecate

RSBP_RVT RSBP_DEPRECATED Err_t tune_spmm (rsb_real_t * sfp, rsb_int_t * tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, rsb_nnz_idx_t ldB, const NT beta, NT * Cp, rsb_nnz_idx_t ldC)

sblib_based_on_prei rsb_tune_spmm() sblib_based_on_post

sblib_autotune_snip

RSBP_RVT RSBP_DEPRECATED Err_t tune_spmm_threads (rsb_real_t * sfp = RSBP_NULL, rsb_int_t * tnp = RSBP_NULL, rsb_int_t maxr = 0, rsb_time_t maxt = 0, rsb_trans_t transA = **RSB_TRANSPOSITION_N, const NT * alphap = RSBP_NULL, rsb_coo_idx_t nrhs = 1, rsb_flags_t order = RSB_FLAG_WANT_COLUMN_MAJOR_ORDER, const NT * Bp = RSBP_NULL, rsb_nnz_idx_t ldB =** 0, const NT * betap = RSBP_NULL, NT * Cp = RSBP_NULL, rsb_nnz_idx_t ldC = 0) const

sblib_based_on_pred rsb_tune_spmm() sblib_based_on_post

sblib_autotune_snip \rl_deprecate

RSBP_RVT RSBP_DEPRECATED Err_t tune_spsm (rsb_real_t * sfp, rsb_int_t * tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const NT * alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, rsb_nnz_idx_t ldB, const NT * betap, NT * Cp, rsb_nnz_idx_t ldC)

sblib_based_on_pred rsb_tune_spsm() sblib_based_on_post

\rl_deprecate

RSBP_RVT RSBP_DEPRECATED Err_t tune_spsm_threads (rsb_real_t * sfp = RSBP_NULL, rsb_int_t * tnp = RSBP_NULL, rsb_int_t maxr = 0, rsb_time_t maxt = 0, rsb_trans_t transA = **RSB_TRANSPOSITION_N, const NT * alphap = RSBP_NULL, rsb_coo_idx_t nrhs = 1, rsb_flags_t order = RSB_FLAG_WANT_COLUMN_MAJOR_ORDER, const NT * Bp = RSBP_NULL, rsb_nnz_idx_t ldB =** 0, const NT * betap = RSBP_NULL, NT * Cp = RSBP_NULL, rsb_nnz_idx_t ldC = 0) const

sblib_based_on_pred rsb_tune_spsm() sblib_based_on_post

\rl_deprecate

RSBP_RVT Err_t upd_vals (enum rsb_elopf_t elop_flags, const NT & omega)

sblib_based_on_pred rsb_mtx_upd_vals() sblib_based_on_post

sblib_upd_vals_snip

RSBP_RVT Err_t upd_vals (enum rsb_elopf_t elop_flags, const NT * omegap)

sblib_based_on_pred rsb_mtx_upd_vals() sblib_based_on_post

\rl_deprecate

~RsbMatrix (void )

Destructor.
Frees matrix object memory.
sblib_based_on_pred rsb_mtx_free() sblib_based_on_post

Variable Documentation

rsb_mtx_t* mtxAp_ {RSBP_NULL}

Represent a sparse matrix in RSB format by means of librsb. Manage construction, destruction, and std::move of numerical matrices.
Most of the member functions here translate directly to a single function call to librsb (rsb.h), and pass the parameters as they are, so the error checking is done by librsb.
While most of librsb C functions use void* pointers instead of numerical data, RsbMatrix is templated by a type parameter. This introduces type safety at compile time.

Users of member functions can choose among several overloads. So in additional to the more direct overloads passing e.g. $ alpha $ and $ beta $ by reference, here a user can pass them by value.

Parameters

NT the numerical type, at least for the four canonical ones (float, double, std::complex<float>, std::complex<double>); see matrix_supported_numerical_types_section and rsb_type_t for more.

Note

Default error propagation is by exception throw for all constructors and most member functions.
Functions declared to return Err_t can be specialized in rsb_err_t so not to throw exceptions, but to return an error code instead.
Exceptions thrown by member functions (not constructors) can be deactivated at build time by defining RSBP_NOTHROW before including <rsb.hpp>.

One may turn on return error value as default at build time by defining RSBP_WANT_REV=1 .

Warning

The error model is work in progress and subject to change.

Todo

While the rsb.h interface is stable, the rsb.hpp interface is neither stable, nor complete: early users' feedback is very welcome.
Shall all $ alpha $ and $ beta $ be passed by values only? This is natural and fits C++. But rsb_tune_spmm() / rsb_tune_spsm() have more parameters with a nullptr-like `default' value: how to deal with them in RsbMatrix::tune_spmm() / RsbMatrix::tune_spsm() without introducing too many special cases ?
Similarly for the consistency of RsbMatrix::get_flags_t(), RsbMatrix::get_type_t(), RsbMatrix::get_info_coo_t(), and similar: shall they throw an exception if given a flag not matching the return type ?
Or maybe keeping only RsbMatrix::get_info(), with per-type reference overloads ?
Furthermore: if working under C++20, shall sblib avoid pointer-based interfaces completely (using std::span only)? */ template<RSBP_Scalar_t NT> class RsbMatrix { private:

/* RSBP_TESTING_ONLY

Author

librsb was written by Michele Martone; this documentation has been generated by Doxygen.

Ubuntu Manpages

librsb

enum RsbOp

enum RsbSym

RSBP_RVT RSBP_DEPRECATED Err_t _add (rsb_coo_idx_t i, rsb_coo_idx_t j, NT val)

RSBP_RVT RSBP_DEPRECATED Err_t _close (void )

RSBP_RVT Err_t close (void )

rsb_coo_idx_t cols (void ) const

RSBP_RVT Err_t file_save (const rsb_char_t * filename = RSBP_NULL) const

RSBP_RVT RSBP_DEPRECATED Err_t get_coo (rsb_trans_t transA, NT * VA, rsb_coo_idx_t * IA, rsb_coo_idx_t * JA, rsb_flags_t flags) const

RSBP_RVT RSBP_DEPRECATED Err_t get_csr (rsb_trans_t transA, NT * VA, rsb_coo_idx_t * RP, rsb_coo_idx_t * JA, rsb_flags_t flags) const

rsb_flags_t get_flags_t (enum rsb_mif_t mif) const

RSBP_RVT Err_t get_info (enum rsb_mif_t miflags, void * minfop) const

rsb_blk_idx_t get_info_blk_t (enum rsb_mif_t mif) const

rsb_coo_idx_t get_info_coo_t (enum rsb_mif_t mif) const

rsb_nnz_idx_t get_info_nnz_t (enum rsb_mif_t mif) const

rsb_flags_t get_info_rsb_flags_t (enum rsb_mif_t mif) const

RSBP_RVT Err_t get_nrm (NT * Np, enum rsb_extff_t flags) const

RSBP_RVT RSBP_DEPRECATED Err_t get_rows_sparse (rsb_trans_t transA, const NT * alphap, NT * 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) const

rsb_type_t get_type_t (enum rsb_mif_t mif) const

RSBP_RVT Err_t get_vals (NT * VA, const rsb_coo_idx_t * IA, const rsb_coo_idx_t * JA, rsb_nnz_idx_t nnz, rsb_flags_t flags) const

RSBP_RVT Err_t get_vec (NT * Dp, enum rsb_extff_t flags) const

RsbMatrix & operator= (const RsbMatrix & A_Rsb)

RSBP_RVT Err_t rndr (const rsb_char_t * filename = RSBP_NULL, rsb_coo_idx_t pmWidth = 512, rsb_coo_idx_t pmHeight = 512, rsb_marf_t rflags = RSB_MARF_EPS) const

rsb_coo_idx_t rows (void ) const

RsbMatrix (const rsb_char_t * filename, const RsbSym sym = IsGen)

RsbMatrix (const rsb_coo_idx_t * IA, const rsb_coo_idx_t * JA, const NT * VA, rsb_nnz_idx_t nnzA, const rsb_flags_t flagsA = RSB_FLAG_NOFLAGS)

RsbMatrix (rsb_coo_idx_t nrA, const rsb_coo_idx_t * RP, const rsb_coo_idx_t * JA, const NT * VA, const RsbSym sym = IsGen)

RsbMatrix (rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, const RsbSym sym = IsGen)

RsbMatrix (rsb_trans_t transA, NT alpha, const RsbMatrix & mtxA, rsb_trans_t transB, NT beta, const RsbMatrix & mtxB, RsbOp op)

rsb_type_t rsbtype (void ) const

RSBP_RVT Err_t set_val (const NT val, const rsb_coo_idx_t i, const rsb_coo_idx_t j, rsb_flags_t flags = RSB_FLAG_NOFLAGS)

RSBP_RVT Err_t set_vals (const NT * VA, const rsb_coo_idx_t * IA, const rsb_coo_idx_t * JA, rsb_nnz_idx_t nnz, rsb_flags_t flags)

RSBP_RVT RSBP_DEPRECATED Err_t spmm (rsb_trans_t transA, const NT * alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, rsb_nnz_idx_t ldB, const NT * betap, NT * Cp, rsb_nnz_idx_t ldC) const

RSBP_RVT Err_t spmm (rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, const NT beta, NT * Cp) const

RSBP_RVT Err_t spmm (rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, rsb_nnz_idx_t ldB, const NT beta, NT * Cp, rsb_nnz_idx_t ldC) const

RSBP_RVT Err_t spmv (NT * y, const NT * x, bool do_trans = false) const

RSBP_RVT RSBP_DEPRECATED Err_t spmv (rsb_trans_t transA, const NT * alphap, const NT * Xp, rsb_coo_idx_t incX, const NT * betap, NT * Yp, rsb_coo_idx_t incY) const

RSBP_RVT Err_t spmv (rsb_trans_t transA, const NT alpha, const NT * Xp, const NT beta, NT * Yp) const

RSBP_RVT Err_t spmv (rsb_trans_t transA, const NT alpha, const NT * Xp, rsb_coo_idx_t incX, const NT beta, NT * Yp, rsb_coo_idx_t incY) const

RSBP_RVT Err_t spsm (NT * y, const NT * x, rsb_coo_idx_t nrhs, bool do_trans = false) const

RSBP_RVT Err_t spsm (NT * y, rsb_coo_idx_t nrhs, bool do_trans = false) const

RSBP_RVT RSBP_DEPRECATED Err_t spsm (rsb_trans_t transT, const NT * alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * betap, const NT * Bp, rsb_nnz_idx_t ldB, NT * Cp, rsb_nnz_idx_t ldC) const

RSBP_RVT Err_t spsm (rsb_trans_t transT, const NT alpha, rsb_coo_idx_t nrhs, const NT * Bp, NT * Cp) const

RSBP_RVT Err_t spsm (rsb_trans_t transT, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT beta, const NT * Bp, rsb_nnz_idx_t ldB, NT * Cp, rsb_nnz_idx_t ldC) const

RSBP_RVT Err_t spsv (NT * y, bool do_trans = false) const

RSBP_RVT Err_t spsv (NT * y, const NT * x, bool do_trans = false) const

RSBP_RVT RSBP_DEPRECATED Err_t spsv (rsb_trans_t transT, const NT * alphap, const NT * Xp, rsb_coo_idx_t incX, NT * Yp, rsb_coo_idx_t incY) const

RSBP_RVT Err_t spsv (rsb_trans_t transT, const NT alpha, const NT * Xp, NT * Yp) const

RSBP_RVT Err_t tune_spmm (rsb_real_t & sf, rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, const NT beta, NT * Cp)

RSBP_RVT RSBP_DEPRECATED Err_t tune_spmm (rsb_real_t * sfp, rsb_int_t * tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const NT * alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, rsb_nnz_idx_t ldB, const NT * betap, NT * Cp, rsb_nnz_idx_t ldC)

RSBP_RVT RSBP_DEPRECATED Err_t tune_spmm (rsb_real_t * sfp, rsb_int_t * tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const NT alpha, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, rsb_nnz_idx_t ldB, const NT beta, NT * Cp, rsb_nnz_idx_t ldC)

RSBP_RVT RSBP_DEPRECATED Err_t tune_spsm (rsb_real_t * sfp, rsb_int_t * tnp, rsb_int_t maxr, rsb_time_t maxt, rsb_trans_t transA, const NT * alphap, rsb_coo_idx_t nrhs, rsb_flags_t order, const NT * Bp, rsb_nnz_idx_t ldB, const NT * betap, NT * Cp, rsb_nnz_idx_t ldC)

RSBP_RVT Err_t upd_vals (enum rsb_elopf_t elop_flags, const NT & omega)

RSBP_RVT Err_t upd_vals (enum rsb_elopf_t elop_flags, const NT * omegap)