blas_sparse.h File Reference

This is the ALP implementation of a subset of the NIST Sparse BLAS standard. More...

Go to the source code of this file.

Typedefs
typedef void *	blas_sparse_matrix
	A sparse matrix.

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.
int	BLAS_duscr_end (blas_sparse_matrix A)
	Signals that the matrix A can now be finalised – all contents have been added.
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.
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.
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.
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.
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.
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.
int	BLAS_usds (blas_sparse_matrix A)
	Frees a given matrix.
int	EXTBLAS_dusm_clear (blas_sparse_matrix A)
	Removes all entries from a finalised sparse matrix.
int	EXTBLAS_dusm_close (const blas_sparse_matrix A)
	Closes a sparse matrix read-out.
int	EXTBLAS_dusm_get (const blas_sparse_matrix A, double *value, int *row, int *col)
	Retrieves a sparse matrix entry.
int	EXTBLAS_dusm_nz (const blas_sparse_matrix A, int *nz)
	Retrieves the number of nonzeroes in a given, finalised, sparse matrix.
int	EXTBLAS_dusm_open (const blas_sparse_matrix A)
	Opens a given sparse matrix for read-out.
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.
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.
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.

Detailed Description

This is the ALP implementation of a subset of the NIST Sparse BLAS standard.

While the API is standardised, this header makes some implementation-specific extensions.

Typedef Documentation

blas_sparse_matrix

typedef void* blas_sparse_matrix

A sparse matrix.

See the SparseBLAS paper for the full specification.

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