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:

Duff, Iain S., Michael A. Heroux, and Roldan Pozo. "An overview of the sparse basic linear algebra subprograms: The new standard from the BLAS technical forum." ACM Transactions on Mathematical Software (TOMS) 28(2), 2002, pp. 239-267.

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,

EXTBLAS_dusv_begin and
extblas_sparse_vector. This prefix can be configured differently, please refer to the developer documentation if looking for this option.

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

BLAS_duscr_begin and
blas_sparse_matrix.

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

enum blas_order_type

The supported dense storages.

See the SparseBLAS paper for the full specification.

◆ blas_trans_type

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.

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

BLAS_duscr_end

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] A The 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] A The 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] 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.

Parameters

[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.

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]	A	The matrix to return the number of nonzeroes of.
[out]	nz	Where 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] A The 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]	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.

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]	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.

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] n The 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] x The 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] x The 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] x The 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] 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.

Parameters

[out]	val	The value of the retrieved nonzero.
[out]	ind	The 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]	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.

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]	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.

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] x The 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] x The 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.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ blas_sparse_matrix

◆ extblas_sparse_vector

Enumeration Type Documentation

◆ blas_order_type

◆ blas_trans_type

Function Documentation

◆ BLAS_duscr_begin()

◆ BLAS_duscr_end()

◆ BLAS_duscr_insert_col()

◆ BLAS_duscr_insert_entries()

◆ BLAS_duscr_insert_entry()

◆ BLAS_duscr_insert_row()

◆ BLAS_dusmm()

◆ BLAS_dusmv()

◆ BLAS_usds()

◆ EXTBLAS_dusm_clear()

◆ EXTBLAS_dusm_close()

◆ EXTBLAS_dusm_get()

◆ EXTBLAS_dusm_nz()

◆ EXTBLAS_dusm_open()

◆ EXTBLAS_dusmsm()

◆ EXTBLAS_dusmsv()

◆ EXTBLAS_dusv_begin()

◆ EXTBLAS_dusv_clear()

◆ EXTBLAS_dusv_close()

◆ EXTBLAS_dusv_end()

◆ EXTBLAS_dusv_get()

◆ EXTBLAS_dusv_insert_entry()

◆ EXTBLAS_dusv_nz()

◆ EXTBLAS_dusv_open()

◆ EXTBLAS_dusvds()

◆ EXTBLAS_free()