Utilities

Numerical tolerances

template<typename T> T RandBLAS::sqrt_epsilon(): Alias for sqrt(numeric_limits<T>::epsilon()). For example, \({\texttt{sqrt_epsilon<float>()} \approx 0.0003452}\) , and \({\texttt{sqrt_epsilon<double>()} \approx 1.4901\text{e-}8}\) .

Random sampling from index sets

template<typename T> void RandBLAS::weights_to_cdf(int64_t n, T *w, T error_if_below = -sqrt_epsilon<T>())

Checks if all elements of length-\(n\) array “\(w\)” are at no smaller than \(\texttt{error_if_below}.\) If this check passes, then we (implicitly) initialize \(v := w\) and overwrite \(w\) by

\[w_i = \frac{\textstyle\sum_{\ell=1}^{i}\max\{0, v_{\ell}\}}{\textstyle\sum_{j=1}^n \max\{0, v_j\}}.\]

On exit, \({w}\) is a CDF suitable for use with sample_indices_iid.

template<typename T, SignedInteger sint_t, typename state_t = RNGState<DefaultRNG>> state_t RandBLAS::sample_indices_iid(int64_t n, const T *cdf, int64_t k, sint_t *samples, const state_t &state)

\(\texttt{cdf}\) encodes a cumulative distribution function over \(\{0, \ldots, n - 1\}.\) For \(0 \leq i < n-1,\) it satisfies

\[0 \leq \texttt{cdf}[i] \leq \texttt{cdf}[i+1] \leq \texttt{cdf}[n-1] = 1.\]

On exit, \(\texttt{samples}\) is overwritten by \(k\) independent samples from \(\texttt{cdf}.\) The returned RNGState should be used for the next call to a random sampling function whose output should be statistically independent from \(\texttt{samples}.\)

template<SignedInteger sint_t = int64_t, typename state_t = RNGState<DefaultRNG>> state_t RandBLAS::sample_indices_iid_uniform(int64_t n, int64_t k, sint_t *samples, const state_t &state): This function overwrites \(\texttt{samples}\) with \(k\) (independent) samples from the uniform distribution over \(\{0, \ldots, n - 1\}.\) The returned RNGState should be used for the next call to a random sampling function whose output should be statistically independent from \(\texttt{samples}.\)

template<SignedInteger sint_t, typename state_t = RNGState<DefaultRNG>> inline state_t RandBLAS::repeated_fisher_yates(int64_t k, int64_t n, int64_t r, sint_t *samples, const state_t &state)

This function is used for sampling a sequence of \({k}\) elements uniformly without replacement from the index set \({\{0,\ldots,n-1\}.}\) It uses a special implementation of Fisher-Yates shuffling to produce \({r}\) such samples in \({O(n + rk)}\) time. These samples are stored by writing to \({\texttt{samples}}\) in \({r}\) blocks of length \({k.}\)

The returned RNGState should be used for the next call to a random sampling function whose output should be statistically independent from \({\texttt{samples}.}\)

Debugging and I/O

class Error : public std::exception

Minimalist exception class for RandBLAS errors.

These are typically triggered by statements of the form randblas_require(cond) where cond was false. The curious can examine RandBLAS/exceptions.hh for the definition of randblas_require.

The vast majority of errors thrown by RandBLAS are due to invalid parameters for matrix dimensions or strides. These error messages only say what went wrong; they offer no suggestions on how to fix what went wrong or why it might have happened. Please get in touch with us on GitHub if you’ve having trouble understanding or resolving an error.

Public Functions

inline Error(std::string const &msg): Constructs error with message.

inline virtual const char *what() const noexcept override

Returns a C-string representation of this error’s message. It’s common to wrap this function’s return value with std::string. For example …

try {
    /* do something that might raise a RandBLAS error */
    randblas_require(1 < 0);
} catch (RandBLAS::Error &e) {
    std::string message{e.what()};
    /* inspect the message */
    std::cout << message << std::endl;
}

enum RandBLAS::ArrayStyle

Specifies whether string representations of matrices should use MATLAB-style or Python-style formatting. You should be able to copy the output of an array printed in a given style and paste it directly into the corresponding programming language’s interpreter.

Values:

enumerator MATLAB

enumerator Python

template<typename T, typename cout_able = std::string> void RandBLAS::print_buff_to_stream(std::ostream &stream, blas::Layout layout, int64_t n_rows, int64_t n_cols, T *A, int64_t lda, cout_able &label, int decimals = 8, ArrayStyle style = ArrayStyle::MATLAB): Writes a string representation of \({\operatorname{mat}(A)}\) to the provided stream. The first line of the output will be \({\texttt{label},}\) followed by a style-specific representation of the matrix (MATLAB style or NumPy/Python style).

template<class T> std::string RandBLAS::typeinfo_as_string(): When called as typeinfo_as_string<your_variable>(), this function returns a string giving all available type information for your_variable. This can be useful for inspecting types in the heretical practice of print statement debugging.