ALP User Documentation
0.8.preview
Algebraic Programming User Documentation
|
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... | |
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 void* blas_sparse_matrix |
A sparse matrix.
See the SparseBLAS paper for the full specification.
typedef void* extblas_sparse_vector |
A sparse vector.
This is an implementation-specific extension.
enum blas_order_type |
The supported dense storages.
See the SparseBLAS paper for the full specification.
enum 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
.
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.
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.
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.
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.
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.
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.
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
See the SparseBLAS paper for the full specification.
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
See the SparseBLAS paper for the full specification.
int BLAS_usds | ( | blas_sparse_matrix | A | ) |
Frees a given matrix.
See the SparseBLAS paper for the full specification.
int EXTBLAS_dusm_clear | ( | blas_sparse_matrix | A | ) |
Removes all entries from a finalised sparse matrix.
[in,out] | A | The matrix to clear. |
This is an implementation-specific extension.
int EXTBLAS_dusm_close | ( | const blas_sparse_matrix | A | ) |
Closes a sparse matrix read-out.
[in] | A | The matrix which is in a read-out state. |
This is an implementation-specific extension.
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.
[in] | A | The 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.
[out] | value | The value of the retrieved nonzero. |
[out] | row | The row coordinate of the retrieved nonzero. |
[out] | col | The column coordinate of the retrieved nonzero. |
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.
int EXTBLAS_dusm_nz | ( | const blas_sparse_matrix | A, |
int * | nz | ||
) |
Retrieves the number of nonzeroes in a given, finalised, sparse matrix.
[in] | A | The matrix to return the number of nonzeroes of. |
[out] | nz | Where to store the number of nonzeroes. |
This is an implementation-specific extension.
int EXTBLAS_dusm_open | ( | const blas_sparse_matrix | A | ) |
Opens a given sparse matrix for read-out.
[in] | A | The matrix to read out. |
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.
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
[in] | transa | The requested transposition of A. |
[in] | alpha | The scalar with which to element-wise multiply the result of \( AB \). |
[in] | A | The left-hand input matrix \( A \). |
[in] | transb | The requested transposition of B. |
[in] | B | The right-hand input matrix \( B \). |
[in,out] | C | The output matrix \( C \) into which the result of the matrix–matrix multiplication is added. |
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
[in] | transa | The requested transposition of \( A \). |
[in] | alpha | The scalar with which to element-wise multiply the result of the matrix–vector multiplication (prior to addition to \( y \)). |
[in] | A | The matrix \( A \) with which to multiply x. |
[in] | x | The vector \( x \) with which to multiply A. |
[in,out] | y | The output vector \( y \) into which the result of the matrix–vector multiplication is added. |
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.
[in] | n | The returned vector size. |
int EXTBLAS_dusv_clear | ( | extblas_sparse_vector | x | ) |
Removes all entries from a finalised sparse vector.
[in] | x | The vector to clear. |
This is an implementation-specific extension.
int EXTBLAS_dusv_close | ( | const extblas_sparse_vector | x | ) |
Closes a sparse vector read-out.
[in] | x | The vector which is in a read-out state. |
This is an implementation-specific extension.
int EXTBLAS_dusv_end | ( | extblas_sparse_vector | x | ) |
Signals the end of sparse vector construction, making the given vector ready for use.
[in,out] | x | The sparse vector that is under construction. |
This is an implementation-specific extension.
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.
[in] | x | The 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.
[out] | val | The value of the retrieved nonzero. |
[out] | ind | The index of the retrieved nonzero value. |
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.
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.
[in,out] | x | The sparse vector to which to add a nonzero. |
[in] | val | The nonzero to add to x. |
[in] | index | The 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.
This is an implementation-specific extension.
int EXTBLAS_dusv_nz | ( | const extblas_sparse_vector | x, |
int * | nz | ||
) |
Retrieves the number of nonzeroes in a given finalised sparse vector.
[in] | x | The vector of which to return the number of nonzeroes. |
[out] | nz | Where to store the number of nonzeroes in a given sparse vector. |
This is an implementation-specific extension.
int EXTBLAS_dusv_open | ( | const extblas_sparse_vector | x | ) |
Opens a sparse vector for read-out.
[in] | x | The vector to read out. |
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.
int EXTBLAS_dusvds | ( | extblas_sparse_vector | x | ) |
Destroys the given sparse vector.
[in] | x | The finalised sparse vector to destroy. |
This is an implementation-specific extension.
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.