rsb.hpp File Reference

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

## Data Structures

class | RsbLib
| Class initializing/finalizing `librsb` state. More...

## Macros

#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_doc_examples
\file
@author Michele Martone
@brief C++ example based on <rsb.hpp> using RsbMatrix.spmm().
Using a \librsb program via \rsblib does not differ conceptually much \librsb.
Errors caught by \librsb shall not go unnoticed 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 \librsb is 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
main
auto main() -> int
Definition assemble.cpp:38
RsbLib
Class initializing/finalizing librsb state.
Definition rsb.hpp:277
rsb
Definition rsb.F90:11
rsb_nnz_idx_t
signed int rsb_nnz_idx_t
Definition rsb.h:362
rsb_coo_idx_t
signed int rsb_coo_idx_t
Definition rsb.h:349
rsb_flags_t
signed int rsb_flags_t
Definition rsb.h:373
RSB_FLAG_WANT_COLUMN_MAJOR_ORDER
#define RSB_FLAG_WANT_COLUMN_MAJOR_ORDER
Definition rsb.h:496
rsb_real_t
double rsb_real_t
Definition rsb.h:403
rsb_int_t
signed int rsb_int_t
Definition rsb.h:392
rsb.hpp
Classes RsbLib and RsbMatrix provide native C++ access to librsb.
RsbMatrix
RsbMatrix(rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, const RsbSym sym=IsGen)
Definition rsb.hpp:603
RSB_TRANSPOSITION_N
#define RSB_TRANSPOSITION_N
N: Non transposed flag, valid for rsb_trans_t typed variables.
Definition rsb_types.h:138

Author
  Michele Martone

## Macro Definition Documentation

## RSBP_DEPRECATED

#define RSBP_DEPRECATED

Internal attribute specifier for deprecated member functions.

Header-only (`rsb.hpp`) wrapper classes for librsb (http://librsb.sf.net).

## RSBP_MSLVRV

#define RSBP_MSLVRV 10201

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

## RSBP_NODISCARD

#define RSBP_NODISCARD

Internal attribute.

## RSBP_RVT

#define RSBP_RVT template <typename Err_t=void>

No return type.

## RSBP_WANT_REV

#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

## RsbOp

enum RsbOp

Enumerator
Sum |

## RsbSym

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 ( ). Please pass only lower/upper triangle.
IsSym | Symmetric ( ). Please pass only lower/upper triangle.
IsTri | Triangular (required for spsv/ spsm).

## Function Documentation

## _add()

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.

## _close()

RSBP_RVT RSBP_DEPRECATED Err_t _close | ( | void |  | ) |

Deprecated
  Use close() instead.

## _get_index_storage_bytes()

size_t _get_index_storage_bytes | ( | void |  | ) | const

\rl_name_to_be_changed

## _get_storage_bytes()

size_t _get_storage_bytes | ( | void |  | ) | const

\rl_name_to_be_changed

## _info()

rsb_string_t _info | ( | void |  | ) | const

\rl_name_to_be_changed

## _is_complex()

bool _is_complex | ( | void |  | ) | const

\rl_name_to_be_changed

## blocks()

rsb_blk_idx_t blocks | ( | void |  | ) | const

## close()

RSBP_RVT Err_t close | ( | void |  | ) |

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

\rsblib_asm_snip

See also
  RsbMatrix::RsbMatrix(rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, const RsbSym sym = IsGen ); \rsblib_based_on_pred rsb_mtx_alloc_from_coo_end() \rsblib_based_on_post

## cols()

rsb_coo_idx_t cols | ( | void |  | ) | const

\rsblib_dims_snip

## file_save()

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

\rsblib_based_on_pred rsb_file_mtx_save() \rsblib_based_on_post

Example snip from examples/misc.cpp:

mtx.file_save(); // print to stdout

## get_coo()

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

\rsblib_based_on_pred rsb_mtx_get_coo() \rsblib_based_on_post

\rl_no_transa \rl_deprecate

## get_csr()

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

\rsblib_based_on_pred rsb_mtx_get_csr() \rsblib_based_on_post

\rl_no_transa \rl_deprecate

## get_flags_t()

rsb_flags_t get_flags_t | ( | enum rsb_mif_t | mif | ) | const

\rsblib_based_on_pred rsb_mtx_get_info() \rsblib_based_on_post

## get_info()

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

\rsblib_based_on_pred rsb_mtx_get_info() \rsblib_based_on_post

## get_info_blk_t()

rsb_blk_idx_t get_info_blk_t | ( | enum rsb_mif_t | mif | ) | const

\rsblib_based_on_pred rsb_mtx_get_info() \rsblib_based_on_post

## get_info_coo_t()

rsb_coo_idx_t get_info_coo_t | ( | enum rsb_mif_t | mif | ) | const

\rsblib_based_on_pred rsb_mtx_get_info() \rsblib_based_on_post

## get_info_nnz_t()

rsb_nnz_idx_t get_info_nnz_t | ( | enum rsb_mif_t | mif | ) | const

\rsblib_based_on_pred rsb_mtx_get_info() \rsblib_based_on_post

## get_info_rsb_flags_t()

rsb_flags_t get_info_rsb_flags_t | ( | enum rsb_mif_t | mif | ) | const

\rsblib_based_on_pred rsb_mtx_get_info() \rsblib_based_on_post

## get_info_size_t()

size_t get_info_size_t | ( | enum rsb_mif_t | mif | ) | const

\rsblib_based_on_pred rsb_mtx_get_info() \rsblib_based_on_post

## get_info_str()

rsb_string_t get_info_str | ( | const char * | key | ) | const

\rsblib_based_on_pred rsb_mtx_get_info_str() \rsblib_based_on_post

## get_nrm()

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

\rsblib_based_on_pred rsb_mtx_get_nrm() \rsblib_based_on_post

## get_rows_sparse()

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

\rsblib_based_on_pred rsb_mtx_get_rows_sparse() \rsblib_based_on_post

\rl_deprecate

## get_type_t()

rsb_type_t get_type_t | ( | enum rsb_mif_t | mif | ) | const

\rsblib_based_on_pred rsb_mtx_get_info() \rsblib_based_on_post

## get_val()

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

\rsblib_based_on_pred rsb_mtx_get_vals() \rsblib_based_on_post

## get_vals()

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

\rsblib_based_on_pred rsb_mtx_get_vals() \rsblib_based_on_post

## get_vec()

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

\rsblib_based_on_pred rsb_mtx_get_vec() \rsblib_based_on_post

## nnz()

rsb_nnz_idx_t nnz | ( | void |  | ) | const

## normInf()

NT normInf | ( | void |  | ) | const

## normOne()

NT normOne | ( | void |  | ) | const

## operator!=()

bool operator!= | ( | const RsbMatrix & | B_Rsb | ) | const

\rsblib__cmp_snip

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

## operator=()

RsbMatrix & operator= | ( | const RsbMatrix & | A_Rsb | ) |

A copy constructor. Will clone the input matrix contents.

## operator==()

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.

\rsblib__cmp_snip

## rndr()

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

\rsblib_based_on_pred rsb_mtx_rndr() \rsblib_based_on_post

\rsblib_rndr_snip

## rows()

rsb_coo_idx_t rows | ( | void |  | ) | const

\rsblib_dims_snip

## rsbflags()

rsb_flags_t rsbflags | ( | void |  | ) | const

## RsbMatrix() [1/8]

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

Assemble a sparse matrix given filename input.
\rsblib_based_on_pred rsb_file_mtx_load() \rsblib_based_on_post

## RsbMatrix() [2/8]

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.
\rsblib__asm_coo_snip
\rsblib_based_on_pred rsb_mtx_alloc_from_coo_const() \rsblib_based_on_post

## RsbMatrix() [3/8]

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() [4/8]

RsbMatrix | ( | const RsbMatrix & | mtxA,
|  | const RsbMatrix & | mtxB,
|  | RsbOp | op )

## RsbMatrix() [5/8]

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.
\rsblib_based_on_pred rsb_mtx_alloc_from_csr_const() \rsblib_based_on_post

## RsbMatrix() [6/8]

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.
\rsblib_asm_snip

\rsblib_based_on_pred rsb_mtx_alloc_from_coo_begin() \rsblib_based_on_post

## RsbMatrix() [7/8]

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

\rsblib_based_on_pred rsb_sppsp() \rsblib_based_on_post

## RsbMatrix() [8/8]

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 );

## rsbtype()

rsb_type_t rsbtype | ( | void |  | ) | const

\rsblib_rsbtype_snip

## set_val()

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 )

\rsblib_based_on_pred rsb_mtx_set_vals() \rsblib_based_on_post

\rsblib_asm_snip

See also
  set_vals().

## 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.

\rsblib_asm_snip

\rsblib_based_on_pred rsb_mtx_set_vals() \rsblib_based_on_post

## spmm() [1/3]

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

\rsblib_based_on_pred rsb_spmm() \rsblib_based_on_post \rl_deprecate

## spmm() [2/3]

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

\rsblib_based_on_prei rsb_spmm() \rsblib_based_on_post

## spmm() [3/3]

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

\rsblib_spmm_snip

\rsblib_based_on_prei rsb_spmm() \rsblib_based_on_post

## spmv() [1/4]

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

\rsblib_based_on_prei rsb_spmv() \rsblib_based_on_post

\rsblib_spmv_snip

## spmv() [2/4]

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

\rsblib_based_on_pred rsb_spmv() \rsblib_based_on_post \rl_deprecate

## spmv() [3/4]

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

\rsblib_based_on_prei rsb_spmv() \rsblib_based_on_post

\rsblib_spmv_snip

## spmv() [4/4]

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

\rsblib_based_on_prei rsb_spmv() \rsblib_based_on_post

\rsblib_spmv_snip

## spsm() [1/5]

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

\rsblib_based_on_prei rsb_spsm() \rsblib_based_on_post

## spsm() [2/5]

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

\rsblib_based_on_prei rsb_spsm() \rsblib_based_on_post

## spsm() [3/5]

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

\rsblib_based_on_pred rsb_spsm() \rsblib_based_on_post \rl_deprecate

## spsm() [4/5]

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

\rsblib_based_on_prei rsb_spsm() \rsblib_based_on_post

## spsm() [5/5]

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

\rsblib_based_on_prei rsb_spsm() \rsblib_based_on_post

## spsv() [1/4]

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

\rsblib_based_on_prei rsb_spsv() \rsblib_based_on_post

## spsv() [2/4]

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

\rsblib_based_on_prei rsb_spsv() \rsblib_based_on_post

## spsv() [3/4]

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

\rsblib_based_on_pred rsb_spsv() \rsblib_based_on_post \rl_deprecate

## spsv() [4/4]

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

\rsblib_based_on_prei rsb_spsv() \rsblib_based_on_post

## tune_spmm() [1/3]

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 )

\rsblib_based_on_prei rsb_tune_spmm() \rsblib_based_on_post

\rsblib_autotune_snip

## tune_spmm() [2/3]

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 )

\rsblib_based_on_pred rsb_tune_spmm() \rsblib_based_on_post

\rsblib_autotune_snip

\rl_deprecate

## tune_spmm() [3/3]

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 )

\rsblib_based_on_prei rsb_tune_spmm() \rsblib_based_on_post

\rsblib_autotune_snip

## tune_spmm_threads()

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

\rsblib_based_on_pred rsb_tune_spmm() \rsblib_based_on_post

\rsblib_autotune_snip \rl_deprecate

## tune_spsm()

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 )

\rsblib_based_on_pred rsb_tune_spsm() \rsblib_based_on_post

\rl_deprecate

## tune_spsm_threads()

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

\rsblib_based_on_pred rsb_tune_spsm() \rsblib_based_on_post

\rl_deprecate

## upd_vals() [1/2]

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

\rsblib_based_on_pred rsb_mtx_upd_vals() \rsblib_based_on_post

\rsblib_upd_vals_snip

## upd_vals() [2/2]

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

\rsblib_based_on_pred rsb_mtx_upd_vals() \rsblib_based_on_post

\rl_deprecate

## ~RsbMatrix()

~RsbMatrix | ( | void |  | ) |

Destructor.
Frees matrix object memory.
\rsblib_based_on_pred rsb_mtx_free() \rsblib_based_on_post

## Variable Documentation

## mtxAp_

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. and 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 and 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 \rsblib avoid pointer-based interfaces completely (using `std::span` only)? */ template<RSBP_Scalar_t NT> class RsbMatrix { private:

/* RSBP_TESTING_ONLY