ALP User Documentation  0.8.preview
Algebraic Programming User Documentation
Typedefs | Enumerations | Functions
SparseBLAS

A SparseBLAS implementation enabled by ALP/GraphBLAS. More...

Typedefs

typedef void * blas_sparse_matrix
 A sparse matrix. More...
 
typedef void * extblas_sparse_vector
 A sparse vector. More...
 

Enumerations

enum  blas_order_type
 The supported dense storages. More...
 
enum  blas_trans_type
 The possible transposition types. More...
 

Functions

blas_sparse_matrix BLAS_duscr_begin (const int m, const int n)
 Creates a handle to a new / empty sparse matrix. More...
 
int BLAS_duscr_end (blas_sparse_matrix A)
 Signals that the matrix A can now be finalised – all contents have been added. More...
 
int BLAS_duscr_insert_col (blas_sparse_matrix A, const int j, const int nnz, const double *vals, const int *rows)
 Inserts a column into A. More...
 
int BLAS_duscr_insert_entries (blas_sparse_matrix A, const int nnz, const double *vals, const int *rows, const int *cols)
 Inserts a block of entries into A. More...
 
int BLAS_duscr_insert_entry (blas_sparse_matrix A, const double val, const int row, const int col)
 Inserts a single nonzero entry into A. More...
 
int BLAS_duscr_insert_row (blas_sparse_matrix A, const int i, const int nnz, const double *vals, const int *cols)
 Inserts a row into A. More...
 
int BLAS_dusmm (const enum blas_order_type order, const enum blas_trans_type transa, const int nrhs, const double alpha, const blas_sparse_matrix A, const double *B, const int ldb, const double *C, const int ldc)
 Sparse matrix–dense matrix multiplication. More...
 
int BLAS_dusmv (const enum blas_trans_type transa, const double alpha, const blas_sparse_matrix A, const double *const x, int incx, double *const y, const int incy)
 Sparse matrix–dense vector multiplication. More...
 
int BLAS_usds (blas_sparse_matrix A)
 Frees a given matrix. More...
 
int EXTBLAS_dusm_clear (blas_sparse_matrix A)
 Removes all entries from a finalised sparse matrix. More...
 
int EXTBLAS_dusm_close (const blas_sparse_matrix A)
 Closes a sparse matrix read-out. More...
 
int EXTBLAS_dusm_get (const blas_sparse_matrix A, double *value, int *row, int *col)
 Retrieves a sparse matrix entry. More...
 
int EXTBLAS_dusm_nz (const blas_sparse_matrix A, int *nz)
 Retrieves the number of nonzeroes in a given, finalised, sparse matrix. More...
 
int EXTBLAS_dusm_open (const blas_sparse_matrix A)
 Opens a given sparse matrix for read-out. More...
 
int EXTBLAS_dusmsm (const enum blas_trans_type transa, const double alpha, const blas_sparse_matrix A, const enum blas_trans_type transb, const blas_sparse_matrix B, blas_sparse_matrix C)
 Performs sparse matrix–sparse matrix multiplication. More...
 
int EXTBLAS_dusmsv (const enum blas_trans_type transa, const double alpha, const blas_sparse_matrix A, const extblas_sparse_vector x, extblas_sparse_vector y)
 Performs sparse matrix–sparse vector multiplication. More...
 
extblas_sparse_vector EXTBLAS_dusv_begin (const int n)
 Creates a handle to a new sparse vector that holds no entries. More...
 
int EXTBLAS_dusv_clear (extblas_sparse_vector x)
 Removes all entries from a finalised sparse vector. More...
 
int EXTBLAS_dusv_close (const extblas_sparse_vector x)
 Closes a sparse vector read-out. More...
 
int EXTBLAS_dusv_end (extblas_sparse_vector x)
 Signals the end of sparse vector construction, making the given vector ready for use. More...
 
int EXTBLAS_dusv_get (const extblas_sparse_vector x, double *const val, int *const ind)
 Retrieves a sparse vector entry. More...
 
int EXTBLAS_dusv_insert_entry (extblas_sparse_vector x, const double val, const int index)
 Inserts a new nonzero entry into a sparse vector that is under construction. More...
 
int EXTBLAS_dusv_nz (const extblas_sparse_vector x, int *nz)
 Retrieves the number of nonzeroes in a given finalised sparse vector. More...
 
int EXTBLAS_dusv_open (const extblas_sparse_vector x)
 Opens a sparse vector for read-out. More...
 
int EXTBLAS_dusvds (extblas_sparse_vector x)
 Destroys the given sparse vector. More...
 
int EXTBLAS_free ()
 This function is an implementation-specific extension of SparseBLAS that clears any buffer memory that preceding SparseBLAS operations may have created and used. More...
 

Detailed Description

A SparseBLAS implementation enabled by ALP/GraphBLAS.

ALP provides a (presently partial) implementation of the Sparse BLAS standard as defined by the BLAS forum and in the following paper:

We also provide a couple of extensions over this standard, in particular to add support for sparse vectors. Such extensions are prefixed by EXTBLAS_ and extblas_, such as, for example,

The functionalities defined by the standard of course retain the prefix defined by the standard: BLAS_ and blas_, such as, e.g.,

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

Typedef Documentation

◆ blas_sparse_matrix

typedef void* blas_sparse_matrix

A sparse matrix.

See the SparseBLAS paper for the full specification.

◆ extblas_sparse_vector

typedef void* extblas_sparse_vector

A sparse vector.

This is an implementation-specific extension.

Enumeration Type Documentation

◆ blas_order_type

The supported dense storages.

See the SparseBLAS paper for the full specification.

◆ blas_trans_type

The possible transposition types.

See the SparseBLAS paper for the full specification.

This implementation at present does not support blas_conj_trans.

Function Documentation

◆ BLAS_duscr_begin()

blas_sparse_matrix BLAS_duscr_begin ( const int  m,
const int  n 
)

Creates a handle to a new / empty sparse matrix.

A call to this function must always be paired with one to

See the SparseBLAS paper for the full specification.

◆ BLAS_duscr_end()

int BLAS_duscr_end ( blas_sparse_matrix  A)

Signals that the matrix A can now be finalised – all contents have been added.

See the SparseBLAS paper for the full specification.

◆ BLAS_duscr_insert_col()

int BLAS_duscr_insert_col ( blas_sparse_matrix  A,
const int  j,
const int  nnz,
const double *  vals,
const int *  rows 
)

Inserts a column into A.

See the SparseBLAS paper for the full specification.

◆ BLAS_duscr_insert_entries()

int BLAS_duscr_insert_entries ( blas_sparse_matrix  A,
const int  nnz,
const double *  vals,
const int *  rows,
const int *  cols 
)

Inserts a block of entries into A.

See the SparseBLAS paper for the full specification.

◆ BLAS_duscr_insert_entry()

int BLAS_duscr_insert_entry ( blas_sparse_matrix  A,
const double  val,
const int  row,
const int  col 
)

Inserts a single nonzero entry into A.

See the SparseBLAS paper for the full specification.

◆ BLAS_duscr_insert_row()

int BLAS_duscr_insert_row ( blas_sparse_matrix  A,
const int  i,
const int  nnz,
const double *  vals,
const int *  cols 
)

Inserts a row into A.

See the SparseBLAS paper for the full specification.

◆ BLAS_dusmm()

int BLAS_dusmm ( const enum blas_order_type  order,
const enum blas_trans_type  transa,
const int  nrhs,
const double  alpha,
const blas_sparse_matrix  A,
const double *  B,
const int  ldb,
const double *  C,
const int  ldc 
)

Sparse matrix–dense matrix multiplication.

This function computes one of

  • \( C \to \alpha AB + C \)
  • \( C \to \alpha A^TB + C \)

See the SparseBLAS paper for the full specification.

◆ BLAS_dusmv()

int BLAS_dusmv ( const enum blas_trans_type  transa,
const double  alpha,
const blas_sparse_matrix  A,
const double *const  x,
int  incx,
double *const  y,
const int  incy 
)

Sparse matrix–dense vector multiplication.

This function computes one of

  • \( y \to \alpha A x + y \)
  • \( y \to \alpha A^T x + y \)

See the SparseBLAS paper for the full specification.

◆ BLAS_usds()

int BLAS_usds ( blas_sparse_matrix  A)

Frees a given matrix.

See the SparseBLAS paper for the full specification.

◆ EXTBLAS_dusm_clear()

int EXTBLAS_dusm_clear ( blas_sparse_matrix  A)

Removes all entries from a finalised sparse matrix.

Parameters
[in,out]AThe matrix to clear.
Returns
0 If A was successfully cleared.
Any other integer in case of error, which brings A into an undefined state.

This is an implementation-specific extension.

◆ EXTBLAS_dusm_close()

int EXTBLAS_dusm_close ( const blas_sparse_matrix  A)

Closes a sparse matrix read-out.

Parameters
[in]AThe matrix which is in a read-out state.
Returns
0 If A is successfully returned to a finalised state.
Any other integer in case of error, which brings A to an undefined state.

This is an implementation-specific extension.

◆ EXTBLAS_dusm_get()

int EXTBLAS_dusm_get ( const blas_sparse_matrix  A,
double *  value,
int *  row,
int *  col 
)

Retrieves a sparse matrix entry.

Each call to this function will retrieve a new entry. The order in which entries are returned is unspecified.

Parameters
[in]AThe matrix to retrieve an entry of.

The given matrix must be opened for read-out, and must not have been closed in the mean time.

Parameters
[out]valueThe value of the retrieved nonzero.
[out]rowThe row coordinate of the retrieved nonzero.
[out]colThe column coordinate of the retrieved nonzero.
Returns
0 If a nonzero was successfully returned and a next value is not available; i.e., the read-out has completed. When this is returned, A will no longer be a legal argument for a call to this function.
1 If a nonzero was successfully returned and a next nonzero is available.
Any other integer in case of error.

In case of error, the output memory areas pointed to by value, row, and col will remain untouched. Furthermore, A will no longer be a legal argument for a call to this function.

This is an implementation-specific extension.

◆ EXTBLAS_dusm_nz()

int EXTBLAS_dusm_nz ( const blas_sparse_matrix  A,
int *  nz 
)

Retrieves the number of nonzeroes in a given, finalised, sparse matrix.

Parameters
[in]AThe matrix to return the number of nonzeroes of.
[out]nzWhere to store the number of nonzeroes.
Returns
0 If the function call is successful.
Any other value on error, in which case nz will remain untouched.

This is an implementation-specific extension.

◆ EXTBLAS_dusm_open()

int EXTBLAS_dusm_open ( const blas_sparse_matrix  A)

Opens a given sparse matrix for read-out.

Parameters
[in]AThe matrix to read out.
Returns
0 If the call was successful.
Any other value if it was not, in which case the state of A shall remain unchanged.

After a successful call to this function, A moves into a read-out state. This means A shall only be a valid argument for calls to EXTBLAS_dusm_get and EXTBLAS_dusm_close.

This is an implementation-specific extension.

◆ EXTBLAS_dusmsm()

int EXTBLAS_dusmsm ( const enum blas_trans_type  transa,
const double  alpha,
const blas_sparse_matrix  A,
const enum blas_trans_type  transb,
const blas_sparse_matrix  B,
blas_sparse_matrix  C 
)

Performs sparse matrix–sparse matrix multiplication.

This function is an implementation-specific extension of SparseBLAS that performs one of

  • \( C \to \alpha A B + C \),
  • \( C \to \alpha A^T B + C \),
  • \( C \to \alpha A B^T + C \), or
  • \( C \to \alpha A^T B^T + C \).
Parameters
[in]transaThe requested transposition of A.
[in]alphaThe scalar with which to element-wise multiply the result of \( AB \).
[in]AThe left-hand input matrix \( A \).
[in]transbThe requested transposition of B.
[in]BThe right-hand input matrix \( B \).
[in,out]CThe output matrix \( C \) into which the result of the matrix–matrix multiplication is added.
Returns
0 If the multiplication has completed successfully.
Any other integer on error, in which case the contents of all arguments to this function shall remain unmodified.

◆ EXTBLAS_dusmsv()

int EXTBLAS_dusmsv ( const enum blas_trans_type  transa,
const double  alpha,
const blas_sparse_matrix  A,
const extblas_sparse_vector  x,
extblas_sparse_vector  y 
)

Performs sparse matrix–sparse vector multiplication.

This function is an implementation-specific extension of SparseBLAS that performs one of

  • \( y \to \alpha A x + y \), or
  • \( y \to \alpha A^T x + y \).
Parameters
[in]transaThe requested transposition of \( A \).
[in]alphaThe scalar with which to element-wise multiply the result of the matrix–vector multiplication (prior to addition to \( y \)).
[in]AThe matrix \( A \) with which to multiply x.
[in]xThe vector \( x \) with which to multiply A.
[in,out]yThe output vector \( y \) into which the result of the matrix–vector multiplication is added.
Returns
0 If the requested operation completed successfully.
Any other integer in case of error. If returned, all arguments to the call to this function shall remain unmodified.

◆ EXTBLAS_dusv_begin()

extblas_sparse_vector EXTBLAS_dusv_begin ( const int  n)

Creates a handle to a new sparse vector that holds no entries.

This is an implementation-specific extension.

Parameters
[in]nThe returned vector size.
Returns
An extblas_sparse_vector that is under construction.

◆ EXTBLAS_dusv_clear()

int EXTBLAS_dusv_clear ( extblas_sparse_vector  x)

Removes all entries from a finalised sparse vector.

Parameters
[in]xThe vector to clear.
Returns
0 If x was successfully cleared.
Any other integer in case of error, which brings x into an undefined state.

This is an implementation-specific extension.

◆ EXTBLAS_dusv_close()

int EXTBLAS_dusv_close ( const extblas_sparse_vector  x)

Closes a sparse vector read-out.

Parameters
[in]xThe vector which is in a read-out state.
Returns
0 If x is successfully returned to a finalised state.
Any other integer in case of error, which brings A to an undefined state.

This is an implementation-specific extension.

◆ EXTBLAS_dusv_end()

int EXTBLAS_dusv_end ( extblas_sparse_vector  x)

Signals the end of sparse vector construction, making the given vector ready for use.

Parameters
[in,out]xThe sparse vector that is under construction.
Returns
0 If x has successfully been moved to a finalised state.
Any other integer if the call was unsuccessful, in which case the state of x becomes undefined.

This is an implementation-specific extension.

◆ EXTBLAS_dusv_get()

int EXTBLAS_dusv_get ( const extblas_sparse_vector  x,
double *const  val,
int *const  ind 
)

Retrieves a sparse vector entry.

Each call to this function will retrieve a new entry. The order in which entries are returned is unspecified.

Parameters
[in]xThe vector to retrieve an entry of.

The given vector must be opened for read-out, and must not have been closed in the mean time.

Parameters
[out]valThe value of the retrieved nonzero.
[out]indThe index of the retrieved nonzero value.
Returns
0 If a nonzero was successfully returned but a next value is not available; i.e., the read-out has completed. When this is returned, x will no longer be a legal argument for a call to this function.
1 If a value was successfully returned and a next nonzero is available.
Any other integer in case of error.

In case of error, the output memory areas pointed to by val and ind shall remain untouched. Furthermore, x will no longer be a valid argument for a call to this function.

This is an implementation-specific extension.

◆ EXTBLAS_dusv_insert_entry()

int EXTBLAS_dusv_insert_entry ( extblas_sparse_vector  x,
const double  val,
const int  index 
)

Inserts a new nonzero entry into a sparse vector that is under construction.

Parameters
[in,out]xThe sparse vector to which to add a nonzero.
[in]valThe nonzero to add to x.
[in]indexThe nonzero coordinate.

The value index must be smaller than the size of the vector x as given during the call to EXTBLAS_dusv_begin that returned x.

Returns
0 If x has successfully ingested the given nonzero.
Any other integer on error, in which case the state of x shall become undefined.

This is an implementation-specific extension.

◆ EXTBLAS_dusv_nz()

int EXTBLAS_dusv_nz ( const extblas_sparse_vector  x,
int *  nz 
)

Retrieves the number of nonzeroes in a given finalised sparse vector.

Parameters
[in]xThe vector of which to return the number of nonzeroes.
[out]nzWhere to store the number of nonzeroes in a given sparse vector.
Returns
0 If the call was successful and nz was set.
Any other integer if the call was unsuccessful, in which case nz shall remain untouched.

This is an implementation-specific extension.

◆ EXTBLAS_dusv_open()

int EXTBLAS_dusv_open ( const extblas_sparse_vector  x)

Opens a sparse vector for read-out.

Parameters
[in]xThe vector to read out.
Returns
0 If the call was successful.
Any other integer indicating an error, in which case the state of x shall remain unchanged.

After a successful call to this function, x moves into a read-out state. This means x shall only be a valid argument for calls to EXTBLAS_dusv_get and EXTBLAS_dusv_close.

This is an implementation-specific extension.

◆ EXTBLAS_dusvds()

int EXTBLAS_dusvds ( extblas_sparse_vector  x)

Destroys the given sparse vector.

Parameters
[in]xThe finalised sparse vector to destroy.
Returns
0 If the call was successful, after which x should no longer be used unless it is overwritten by a call to EXTBLAS_dusv_begin.
Any other integer if the call was unsuccessful, in which case the state of x becomes undefined.

This is an implementation-specific extension.

◆ EXTBLAS_free()

int EXTBLAS_free ( )

This function is an implementation-specific extension of SparseBLAS that clears any buffer memory that preceding SparseBLAS operations may have created and used.

Returns
0 On success.
Any other integer on failure, in which case the ALP/SparseBLAS implementation enters an undefined state.