rsblib/rsb.hpp(3)

📦

version 1.3.0.3 · 4 versions

1.3.0.3 · ubuntu stonking (latest)
1.3.0.0 · ubuntu jammy
1.3.0.2 · debian bookworm
1.3.0.2 · debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute

💜 rsblib/rsb.hpp 💜

okay so bestie, come closer — this is the header where C++ gets to hold hands with librsb, and it is genuinely a lot (so much that it arrives in parts, and part one is what you're holding right now 🫶). the manual name up top is librsb and the page itself is rsblib/rsb.hpp — yes, both, she contains multitudes ✨

🎀 NAME 🎀

librsb — rsblib/rsb.hpp — Classes RsbLib and RsbMatrix provide native C++ access to librsb. 💅

🌸 DESCRIPTION 🌸

okay so the DESCRIPTION section is literally empty. nothing. dead air. nobody home. no cap 💀 so we move on immediately, nothing to see, slay

✨ SYNOPSIS ✨

welcome to the lineup 🌈 everything below is exactly what's in the header — i'm just narrating it for you with the energy it deserves.

🦋 Data Structures 🦋

class RsbLib — Class initializing/finalizing librsb state. she does the hello and the bye and that is her entire job. queen of boundaries 💖

🎀 Macros 🎀

internal helper girlies doing internal helper things, iykyk:

RSBP_DEPRECATED — Internal attribute specifier for deprecated member functions.

#define RSBP_DEPRECATED

RSBP_NODISCARD — Internal attribute.

#define RSBP_NODISCARD

RSBP_WANT_REV — If this is defined to 1 before including <rsb.hpp>, rsb_err_t is the default return type. Otherwise the default is void. (her default value is 0.)

#define RSBP_WANT_REV   0

RSBP_RVT — No return type. genuinely it's just a template line with Err_t defaulting to void, and she shows up all over the place below:

#define RSBP_RVT   template <typename Err_t=void>

RSBP_MSLVRV — Minimal supported librsb version (value of RSB_LIBRSB_VER, defined via rsb.h). the number is 10201, memorize it for the vibe check:

#define RSBP_MSLVRV   10201

💅 Enumerations 💅

enum RsbSym — { IsGen = RSB_FLAG_NOFLAGS, IsHer = RSB_FLAG_HERMITIAN, IsSym = RSB_FLAG_SYMMETRIC, IsTri = RSB_FLAG_TRIANGULAR } — the flavour menu, and every entry maps straight onto an RSB_FLAG_* constant. pick your fighter 🦋
enum RsbOp — { Sum } — one (1) option. she contains multitudes and the multitude is named Sum 😭 iconic

🔥 Functions 🔥

quick vibe check before we dive: everywhere you see RSBP_RVT it's that no-return-type macro riding along, and anything wearing RSBP_DEPRECATED is deprecated — say it with me, deprecated 💀 we still list all of them tho, bc bestie we do not skip.

🫶 constructors + destructor

RsbMatrix (rsb_coo_idx_t nrA, rsb_coo_idx_t ncA, const RsbSym sym=IsGen) — the bare-minimum entrance ✨
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) — she brought RP, JA and VA with her, prepared queen 🎀
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) — the IA/JA/VA trio plus nnzA and flagsA 🦋
RsbMatrix (const rsb_char_t *filename, const RsbSym sym=IsGen) — she reads a filename, no cap
RsbMatrix (const RsbMatrix &A_Rsb, bool do_trans=false, rsb_flags_t flagsA=RSB_FLAG_NOFLAGS) — copy-constructor energy with do_trans and flagsA 🫶
RsbMatrix (RsbMatrix &&other) — move constructor, she moves 💅
~RsbMatrix (void) — the goodbye 💔

🔥 the method girlies

RSBP_RVT RSBP_DEPRECATED Err_t _add (rsb_coo_idx_t i, rsb_coo_idx_t j, NT val) — ⚠️ deprecated, she's got the badge
RSBP_RVT Err_t close (void) — clean shutdown behaviour 🎀
RSBP_RVT RSBP_DEPRECATED Err_t _close (void) — ⚠️ also deprecated (the underscore one, of course)
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 — ⚠️ deprecated pointer-flavoured girlie
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 — the non-deprecated alpha/beta twin ✨
RSBP_RVT Err_t spmv (rsb_trans_t transA, const NT alpha, const NT *Xp, const NT beta, NT *Yp) const — even shorter, still spmv, still valid 💅
RSBP_RVT Err_t spmv (NT *y, const NT *x, bool do_trans=false) const — the cozy minimal one, do_trans defaults to false 🌸
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 — ⚠️ deprecated, she's the long one with ldB and ldC
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 — same energy, alpha/beta era 🦋
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 — the no-ld version, she travels light 💖
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 — ⚠️ deprecated, and yes she takes transT not transA, look closely bestie 👀
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 — current-gen spsm with alpha and beta ✨
RSBP_RVT Err_t spsm (rsb_trans_t transT, const NT alpha, rsb_coo_idx_t nrhs, const NT *Bp, NT *Cp) const — tiny spsm, big presence 🌸
RSBP_RVT Err_t spsm (NT *y, const NT *x, rsb_coo_idx_t nrhs, bool do_trans=false) const — y, x, nrhs, and a polite do_trans=false 🫶
RSBP_RVT Err_t spsm (NT *y, rsb_coo_idx_t nrhs, bool do_trans=false) const — no x this time. she said less 💅
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 — ⚠️ deprecated pointer-style
RSBP_RVT Err_t spsv (rsb_trans_t transT, const NT alpha, const NT *Xp, NT *Yp) const — spsv, value-style, thriving 🌈
RSBP_RVT Err_t spsv (NT *y, const NT *x, bool do_trans=false) const — y/x edition 💖
RSBP_RVT Err_t spsv (NT *y, bool do_trans=false) const — just y. she said rest 😌
size_t get_info_size_t (enum rsb_mif_t mif) const — asks about mif, returns size_t 🎀
rsb_flags_t get_info_rsb_flags_t (enum rsb_mif_t mif) const — returns rsb_flags_t, no surprise there ✨
rsb_blk_idx_t get_info_blk_t (enum rsb_mif_t mif) const — rsb_blk_idx_t girlie 🦋
rsb_nnz_idx_t get_info_nnz_t (enum rsb_mif_t mif) const — rsb_nnz_idx_t, nnz core 💅
rsb_flags_t get_flags_t (enum rsb_mif_t mif) const — the flags one 🚩
rsb_type_t get_type_t (enum rsb_mif_t mif) const — the type one ✨
rsb_coo_idx_t get_info_coo_t (enum rsb_mif_t mif) const — the coo one 🌸
size_t _get_index_storage_bytes (void) const — she measures index storage bytes 🔢
size_t _get_storage_bytes (void) const — and she measures storage bytes too 💖
rsb_nnz_idx_t nnz (void) const — the name is nnz, she's that girl 👑
rsb_blk_idx_t blocks (void) const — blocks. simple. iconic 💅
rsb_coo_idx_t rows (void) const — rows bestie 🌈
rsb_coo_idx_t cols (void) const — and cols 🦋
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 — note the parameter named nnz sitting right next to the member function nnz 💀 (yes, that's really the signature)
NT get_val (const rsb_coo_idx_t i, const rsb_coo_idx_t j, rsb_flags_t flags=RSB_FLAG_NOFLAGS) const — one value, for i and j 🎀
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) — her setting counterpart ✨
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) — plural version, nnz again 💖
RSBP_RVT Err_t get_vec (NT *Dp, enum rsb_extff_t flags) const — Dp plus enum rsb_extff_t flags 🌸
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 — ⚠️ deprecated COO energy
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 — ⚠️ deprecated, CSR flavoured
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 — ⚠️ deprecated, and she brought frA, lrA and rnzp along for the ride 😭
RSBP_RVT Err_t upd_vals (enum rsb_elopf_t elop_flags, const NT &omega) — takes omega by reference 🫶
RSBP_RVT Err_t upd_vals (enum rsb_elopf_t elop_flags, const NT *omegap) — and here's the pointer omegap twin ✨
RSBP_RVT Err_t get_nrm (NT *Np, enum rsb_extff_t flags) const — norm girlie, Np in hand 💅
rsb_type_t rsbtype (void) const — she'll tell you her rsbtype 🎀
rsb_flags_t rsbflags (void) const — and her rsbflags 🚩
rsb_string_t get_info_str (const char *key) const — hands back an rsb_string_t for a key 🌸
RSBP_RVT Err_t get_info (enum rsb_mif_t miflags, void *minfop) const — miflags + minfop, void pointer jumpscare 🙈
rsb_string_t _info (void) const — the underscore info, she's short and she knows it ✨
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 — ⚠️ deprecated, and she is enormous, every single default is right there bestie, don't @ me
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 — ⚠️ deprecated, same giant vibe, spmm edition 🌈
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) — ⚠️ deprecated, no defaults this time, just vibes 💀
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) — ⚠️ deprecated, alpha/beta flavour 🦋
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) — not deprecated, she takes rsb_real_t &sf by reference and she's thriving ✨
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) — ⚠️ deprecated, the spsm sibling 🎀
RSBP_RVT Err_t file_save (const rsb_char_t *filename=RSBP_NULL) const — saves to a filename, defaults to RSBP_NULL 🌸
RsbMatrix & operator= (const RsbMatrix &A_Rsb) — assignment, returns RsbMatrix & 💅
bool _is_complex (void) const — returns a bool, _is_complex, she's asking the real questions ✨
bool operator== (const RsbMatrix &B_Rsb) const — equality, B_Rsb edition 🫶
bool operator!= (const RsbMatrix &B_Rsb) const — and inequality 😌
NT normOne (void) const — normOne 💖
NT normInf (void) const — normInf 🌈
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 — pmWidth=512, pmHeight=512, rflags=RSB_MARF_EPS, all defaults present and accounted for 🎀
RsbMatrix (rsb_trans_t transA, NT alpha, const RsbMatrix &mtxA, rsb_trans_t transB, NT beta, const RsbMatrix &mtxB, RsbOp op) — the two-matrix constructor with her own transA, transB and op 👑
RsbMatrix (const RsbMatrix &mtxA, const RsbMatrix &mtxB, RsbOp op) — the short two-matrix version, just mtxA, mtxB and op 🦋

⭐ Variables ⭐

rsb_mtx_t * mtxAp_ {RSBP_NULL} — Represent a sparse matrix in RSB format by means of librsb. she lives in public, she's initialized to RSBP_NULL, and she's the girl 💖

⏳ bestie we are so not done — and that's exactly how the header wanted it… more coming up next 🫶

✨ DETAILED DESCRIPTION ✨

okay so bestie, 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().
                              sblib does not differ conceptually much rsb.
 Using a rsb  program via

 Errors caught by rsb 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 rsb 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

🌸 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 💖

_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

(no description, just vibes)

close

RSBP_RVT Err_t close (void )

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

sblib_asm_snip

`set_val` 💖

RSBP_RVT Err_t set_val (const NT val, constsblib_based_on_postonst
      sblib_based_on_predbrsb_mtx_set_vals()SB_FLAG_NOFLAGS)

sblib_asm_snip

See also — set_vals(). bestie this one is literally pointing you at its sibling, so go look at 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. that's the whole vibe — you're feeding in entries one at a time while the matrix is still being built, and close() is your "okay I'm done" ✋

sblib_asm_snip

ok so the source page has a mangled sblib_based_on_post marker sitting right here, and then a see-also, so: See also — rsb_mtx_set_vals() 💅

`spmm` 🔥

RSBP_RVT RSBP_DEPRECATED Err_t spmm (rsb_trans_t transA, const NT * alphap,
      rsb_coo_idx_t nrhs, rsb_flags_tsblib_based_on_postB\rl_deprecatex_t ldB,
      sblib_based_on_predTrsb_spmm()_nnz_idx_t ldC) const

⚠️ RSBP_DEPRECATED and a \rl_deprecate slapped on it — this overload is legacy, don't build your whole personality on it.

See also — rsb_spmm().

RSBP_RVT Err_t spmm (rsb_trans_t trsblib_based_on_posta, rsb_coo_idx_t nrhs,
      sblib_based_on_preicrsb_spmm()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 *
      sblib_spmm_snip_t ldC) const

sblib_based_on_post

sblib_based_on_prei rsb_spmm()

`spmv` 🦋

RSBPsblib_based_on_prei rsb_spmv() 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 insblib_based_on_postp\rl_deprecate

⚠️ deprecated overload alert, the \rl_deprecate is right there in the pile.

See also — rsb_spmv().

RSBP_RVT Err_t spmv (rsb_trans_t trsblib_based_on_posta, const NT * Xp,
      sblib_based_on_prei rsb_spmv()

sblib_spmv_snip

RSBP_RVT Err_t spmv (rsb_trans_t trsblib_based_on_posta, const NT * Xp,
      sblib_based_on_prei rsb_spmv()eta, NT * Yp, rsb_coo_idx_t incY) const

sblib_spmv_snip

`spsm` 🌸

RSBP_RVT Err_t spsm (NT * y, const sblib_based_on_post_t nrhs, bool do_trans
      sblib_based_on_prei rsb_spsm()

RSBP_RVT Err_t spsm (NT * y, rsb_cosblib_based_on_postdo_trans = false)
      sblib_based_on_prei rsb_spsm()

RSBP_RVT RSBP_DEPRECATED Err_t spsm (rsb_trans_t transT, const NT * alphap,
      rsb_coo_idx_t nrhs, rsb_flags_tsblib_based_on_postb\rl_deprecateT * Bp,
      sblib_based_on_predNrsb_spsm()b_nnz_idx_t ldC) const

⚠️ RSBP_DEPRECATED, plus a \rl_deprecate — yeah bestie, it's giving legacy 😭

RSBP_RVT Err_t spsm (rsb_trans_t trsblib_based_on_posta, rsb_coo_idx_t nrhs,
      sblib_based_on_prei rsb_spsm()

RSBP_RVT Err_t spsm (rsb_trans_t transT, const NT alpha, rsb_coo_idx_t nrhs,
      rsb_flags_t order, const NT betsblib_based_on_postsb_nnz_idx_t ldB, NT *
      sblib_based_on_preidrsb_spsm()

`spsv` 💜

RSBPsblib_based_on_prei rsb_spsv()do_trans = false) const

RSBPsblib_based_on_prei rsb_spsv() NT * x, bool do_trans = false) const

RSBP_RVT RSBP_DEPRECATED Err_t spsvsblib_based_on_postT\rl_deprecatealphap,
      sblib_based_on_predcrsb_spsv()ncX, NT * Yp, rsb_coo_idx_t incY) const

⚠️ deprecated, \rl_deprecate included, handle with care and maybe a face mask 🧖

RSBP_RVT Err_t spsv (rsb_trans_t trsblib_based_on_posta, const NT * Xp, NT *
      sblib_based_on_prei rsb_spsv()

`tune_spmm` ⭐

RSBP_RVT Err_t tune_spmm (rsb_real_t & sf, rsb_trans_t transA, const NT
      alpha, rsb_coo_idx_t nrhs, rsb_flagssblib_based_on_post* Bp, const NT
      sblib_based_on_prei rsb_tune_spmm()

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 ordesblib_based_on_postsb_nnz_idx_t ldB,
      sblib_based_on_predTrsb_tune_spmm()idx_t ldC)

\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 ordesblib_based_on_postsb_nnz_idx_t ldB,
      sblib_based_on_prei rsb_tune_spmm()_t ldC)

sblib_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 * besblib_based_on_post * Cp =
      sblib_based_on_predirsb_tune_spmm()onst

sblib_autotune_snip \rl_deprecate

⚠️ yep, RSBP_DEPRECATED and \rl_deprecate — it's an autotuner that's been through some things 💀 but look at all those lovely RSBP_NULL, 0, RSB_TRANSPOSITION_N and RSB_FLAG_WANT_COLUMN_MAJOR_ORDER defaults, she ate ✨

`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 ordesblib_based_on_postsb_nnz_idx_t ldB,
      sblib_based_on_predTrsb_tune_spsm()idx_t ldC)

\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 * besblib_based_on_post * Cp =
      sblib_based_on_predirsb_tune_spsm()onst

\rl_deprecate

`rsb_mtx_upd_vals` 🫶

RSBPsblib_based_on_pred rsb_mtx_upd_vals()elop_flags, const NT & omega)

sblib_upd_vals_snip

RSBPsblib_based_on_pred rsb_mtx_upd_vals()elop_flags, const NT * omegap)

\rl_deprecate

`~RsbMatrix` 👑

~RsbMatrix (void )

Destructor. yes bestie she cleans up after herself, main character energy 🫧

sblib_based_on_post

sblib_based_on_pred rsb_mtx_free()

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. like, she's a thin wrapper and she's at peace with that 💅

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. no cap, that's the whole glow-up ✨

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. pick your fighter 🥊

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. the canonical four, iconic 👑

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. 🚧 literally do not get attached, it's a situationship

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 interfaces completely (using std::span only)?

template<RSBP_Scalar_t NT> class RsbMatrix { private:

/* RSBP_TESTING_ONLY

sblib avoid pointer-based

ok not me ending on a dangling open brace, but that's genuinely where the source page stops, bestie 🙈

Author ✍️

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

rsblib/rsb.hpp(3)

💜 rsblib/rsb.hpp 💜

🎀 NAME 🎀

🌸 DESCRIPTION 🌸

✨ SYNOPSIS ✨

🦋 Data Structures 🦋

🎀 Macros 🎀

💅 Enumerations 💅

🔥 Functions 🔥

🫶 constructors + destructor

🔥 the method girlies

⭐ Variables ⭐

✨ DETAILED DESCRIPTION ✨

🌸 AUTHOR 🌸

💅 MACRO DEFINITION DOCUMENTATION 💅

✨ ENUMERATION TYPE DOCUMENTATION ✨

💖 FUNCTION DOCUMENTATION 💖

set_val 💖

set_vals 🎀

spmm 🔥

spmv 🦋

spsm 🌸

spsv 💜

tune_spmm ⭐

tune_spmm_threads 🧚

tune_spsm 🌈

tune_spsm_threads 🍓

rsb_mtx_upd_vals 🫶

~RsbMatrix 👑

Variable Documentation 💾

rsb_mtx_t* mtxAp_ {RSBP_NULL}

Author ✍️

SEE ALSO 🔗

`set_val` 💖

`set_vals` 🎀

`spmm` 🔥

`spmv` 🦋

`spsm` 🌸

`spsv` 💜

`tune_spmm` ⭐

`tune_spmm_threads` 🧚

`tune_spsm` 🌈

`tune_spsm_threads` 🍓

`rsb_mtx_upd_vals` 🫶

`~RsbMatrix` 👑

`rsb_mtx_t* mtxAp_ {RSBP_NULL}`