ALP User Documentation  0.8.preview
Algebraic Programming User Documentation
Functions

An SpBLAS implementation enabled by ALP/GraphBLAS. More...

Functions

void alp_cspblas_dcsrgemv (const char *transa, const int *m, const double *a, const int *ia, const int *ja, const double *x, double *y)
 Performs sparse matrix–vector multiplication. More...
 
void alp_cspblas_dcsrmm (const char *transa, const int *m, const int *n, const int *k, const double *alpha, const char *matdescra, const double *val, const int *indx, const int *pntrb, const int *pntre, const double *b, const int *ldb, const double *beta, double *c, const int *ldc)
 Computes a variant of \( C \to \alpha AB+\beta C \). More...
 
void alp_cspblas_dcsrmultcsr (const char *trans, const int *request, const int *sort, const int *m, const int *n, const int *k, double *a, int *ja, int *ia, double *b, int *jb, int *ib, double *c, int *jc, int *ic, const int *nzmax, int *info)
 Computes \( C \to AB \) or \( C \to A^TB \), where all matrices are sparse and employ the Compressed Row Storage (CRS). More...
 
void alp_cspblas_ext_dcsrmultsv (const char *trans, const int *request, const int *m, const int *n, const double *a, const int *ja, const int *ia, const extblas_sparse_vector x, extblas_sparse_vector y)
 Performs sparse matrix–sparse vector multiplication. More...
 
void alp_cspblas_ext_free ()
 An extension that frees any buffers the ALP/GraphBLAS-generated SparseBLAS library may have allocated.
 

Detailed Description

An SpBLAS implementation enabled by ALP/GraphBLAS.

ALP provides a (presently partial) implementation of SpBLAS interface for sparse linear algebra kernels. While not a standard proper, it may bes considered a de-facto one as it is implemented by various vendors as well as open source projects, and enjoys wide-spread use.

This implementation uses a configurable prefix for the primitives it defines; e.g., and by default, alp_cspblas_dcsrgemv for sparse matrix–vector multiplication using double nonzero value types. To reconfigure this name, please see the –spblas-prefix option to the bootstrap script.

Note
Since this is not a properly standardised API, even if choosing another prefix, it remains strongly recommended to make sure the prefix remains unique.

All functions defined have void return types. This implies two important factors:

  1. when breaking the contract defined in the API, undefined behaviour will occur;
  2. this API hence does not permit the graceful handling of any errors that ALP would normally allow graceful recovery from, such as, but not limited to, the detection of dimension mismatches.
Warning
In addition to the above, some idiosyncrasies of the SpBLAS interface may incur significant performance penalties. The use of the SparseBLAS interface, if not the direct use of the ALP/GraphBLAS interface, is strongly recommended when possible.

The implementation of this standard is done by directly mapping this API to the equivalent ALP/GraphBLAS primitives. By default, ALP builds both sequential and shared- memory parallel SpBLAS libraries. It does so simply by compiling the same ALP-based SpBLAS implementation with a sequential and a shared-memory ALP backend, respectively.

Function Documentation

◆ alp_cspblas_dcsrgemv()

void alp_cspblas_dcsrgemv ( const char *  transa,
const int *  m,
const double *  a,
const int *  ia,
const int *  ja,
const double *  x,
double *  y 
)

Performs sparse matrix–vector multiplication.

This function computes one of

  • \( y \to Ax \), or
  • \( y \to A^Tx \).

The matrix \( A \) is \( m \times n \) and holds \( k \) nonzeroes, and is assumed to be stored in Compressed Row Storage (CRS).

Parameters
[in]transaEither 'N' or 'T' for transposed ('T') or not ('N').
[in]mThe row size of \( A \).
[in]aThe nonzero value array of \( A \) of size \( k \).
[in]iaThe row offset array of \( A \) of size \( m+1 \).
[in]jaThe column indices of nonzeroes of \( A \). Must be of size \( k \).
[in]xThe dense input vector \( x \) of length \( n \).
[out]yThe dense output vector \( y \) of length \( m \).

All memory regions must be pre-allocated and initialised.

◆ alp_cspblas_dcsrmm()

void alp_cspblas_dcsrmm ( const char *  transa,
const int *  m,
const int *  n,
const int *  k,
const double *  alpha,
const char *  matdescra,
const double *  val,
const int *  indx,
const int *  pntrb,
const int *  pntre,
const double *  b,
const int *  ldb,
const double *  beta,
double *  c,
const int *  ldc 
)

Computes a variant of \( C \to \alpha AB+\beta C \).

The matrix \( A \) is sparse and employs the Compressed Row Storage (CRS). The matrices \( B, C \) are dense. \( A \) has size \( m \times k \), \( B \) is \( k \times n \) and \( C \) is \( m \times n \).

Parameters
[in]transaEither 'N' or 'T'.
[in]m,n,kPointers to integers that equal \( m, n, k \), resp.
[in]alphaPointer to the scalar \( \alpha \).
[in]matdescraHas several entries. Going from first to last: Either 'G', 'S', 'H', 'T', 'A', or 'D' (similar to MatrixMarket) Either 'L' or 'U', in the case of 'T' (triangular) Either 'N' or 'U' for the diagonal type Either 'F' or 'C' (one or zero based indexing)
[in]valThe values of the nonzeroes in \( A \).
[in]indxThe column index of the nonzeroes in \( A \).
[in]pntrbThe Compressed Row Storage (CRS) row start array.
[in]pntreThe array pntrb shifted by one.
[in]bPointer to the values of \( B \).
[in]ldbLeading dimension of b. If in row-major format, this should be \( n \). If in column-major format, this should be \( k \).
[in]betaPointer to the scalar \( \beta \).
[in]cPointer to the values of \( C \).
[in]ldcLeading dimension of c. If in row-major format, this should be \( n \). If in column-major format, this should be \( m \).

◆ alp_cspblas_dcsrmultcsr()

void alp_cspblas_dcsrmultcsr ( const char *  trans,
const int *  request,
const int *  sort,
const int *  m,
const int *  n,
const int *  k,
double *  a,
int *  ja,
int *  ia,
double *  b,
int *  jb,
int *  ib,
double *  c,
int *  jc,
int *  ic,
const int *  nzmax,
int *  info 
)

Computes \( C \to AB \) or \( C \to A^TB \), where all matrices are sparse and employ the Compressed Row Storage (CRS).

The matrix \( C \) is \( m \times n \), the matrix \( A \) is \( m \times k \), and the matrix \( B \) is \( k \times n \).

Parameters
[in]transEither 'N' or 'T', indicating whether A is to be transposed. The Hermitian operator on A is currently not supported; if required, please submit a ticket.
[in]requestA pointer to an integer that reads either 0, 1, or 2. 0: the output memory area has been pre-allocated and is guaranteed sufficient for storing the output 1: a symbolic phase will be executed that only modifies the row offset array ic. This array must have been pre-allocated and of sufficient size ( \( m+1 \)). 2: assumes 1 has executed prior to this call and that the contents of the row offset arrays have not been modified. It also assumes that the column index and value arrays are (now) of sufficient size to hold the output.
[in]sortA pointer to an integer value of 7. All other values are not supported by this interface. If you require it, please submit a ticket.
[in]m,n,kPointers to the integer sizes of A, B, and C.
[in]aThe value array of nonzeroes in A.
[in]jaThe column index array of nonzeroes in A.
[in]iaThe row offset array of nonzeroes in A.
[in]b,ib,jbSimilar for the nonzeroes in B.
[out]c,ic,jcSimilar for the nonzeroes in C. For these parameters depending on request there are various assumptions on capacity and, for ic, contents.
[in]nzmaxA pointer to an integer that holds the capacity of c and jc.
[out]infoThe integer pointed to will be set to 0 if the call was successful, -1 if the routine only computed the required size of c and jc (stored in ic), and any positive integer when computation has proceeded successfully until (but not including) the returned integer.

◆ alp_cspblas_ext_dcsrmultsv()

void alp_cspblas_ext_dcsrmultsv ( const char *  trans,
const int *  request,
const int *  m,
const int *  n,
const double *  a,
const int *  ja,
const int *  ia,
const extblas_sparse_vector  x,
extblas_sparse_vector  y 
)

Performs sparse matrix–sparse vector multiplication.

This extension performs one of

  1. \( y \to y + \alpha A x \), or
  2. \( y \to y + \alpha A^T x \).

Here, \( A \) is assumed in Compressed Row Storage (CRS), while \( x \) and \( y \) are assumed to be using the extblas_sparse_vector extension.

This API follows loosely that of alp_cspblas_dcsrmultcsr.

Parameters
[in]transEither 'N' or 'T', indicating whether A is to be transposed. The Hermitian operator on A is currently not supported; if required, please submit a ticket.
[in]requestA pointer to an integer that reads either 0 or 1 0: the output vector is guaranteed to have sufficient capacity to hold the output of the computation. 1: a symbolic phase will be executed that only modifies the capacity of the output vector so that it is guaranteed to be able to hold the output of the requested computation.
[in]m,nPointers to integers equal to \( m, n \).
[in]aThe value array of the nonzeroes in \( A \).
[in]jaThe column indices of the nonzeroes in \( A \).
[in]iaThe row offset arrays of the nonzeroes in \( A \).
[in]xThe sparse input vector.
[out]yThe sparse output vector.

This is an ALP implementation-specific extension.