blas_sparse_vec.h File Reference

This is an ALP-specific extension to the NIST Sparse BLAS standard, which the ALP libsparseblas transition path also introduces to the de-facto spblas standard. More...

Go to the source code of this file.

Typedefs
typedef void *	extblas_sparse_vector
	A sparse vector. More...

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

Detailed Description

This is an ALP-specific extension to the NIST Sparse BLAS standard, which the ALP libsparseblas transition path also introduces to the de-facto spblas standard.

Typedef Documentation

extblas_sparse_vector

typedef void* extblas_sparse_vector

A sparse vector.

This is an implementation-specific extension.

Function Documentation

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.