Support functions provided to read sparse matrices from file

Functions to help read the contents of matrix market files from disk. More...

Classes
struct	clsparseMetaSizeResult
	A structure returned by value from the clsparseCsrMetaSize function. This serves as a result/status pair for the size of the meta data associated with a sparse matrix. More...

Functions
CLSPARSE_EXPORT clsparseStatus	clsparseHeaderfromFile (clsparseIdx_t *nnz, clsparseIdx_t *row, clsparseIdx_t *col, const char *filePath)
	Read the sparse matrix header from file. More...
CLSPARSE_EXPORT clsparseStatus	clsparseSCooMatrixfromFile (clsparseCooMatrix *cooMatx, const char *filePath, clsparseControl control, cl_bool read_explicit_zeroes)
	Read sparse matrix data from file in single precision COO format. More...
CLSPARSE_EXPORT clsparseStatus	clsparseDCooMatrixfromFile (clsparseCooMatrix *cooMatx, const char *filePath, clsparseControl control, cl_bool read_explicit_zeroes)
	Read sparse matrix data from file in double precision COO format. More...
CLSPARSE_EXPORT clsparseStatus	clsparseSCsrMatrixfromFile (clsparseCsrMatrix *csrMatx, const char *filePath, clsparseControl control, cl_bool read_explicit_zeroes)
	Read sparse matrix data from file in single precision CSR format. More...
CLSPARSE_EXPORT clsparseStatus	clsparseDCsrMatrixfromFile (clsparseCsrMatrix *csrMatx, const char *filePath, clsparseControl control, cl_bool read_explicit_zeroes)
	Read sparse matrix data from file in double precision CSR format. More...
CLSPARSE_EXPORT clsparseMetaSizeResult	clsparseCsrMetaSize (clsparseCsrMatrix *csrMatx, clsparseControl control)
	Calculate the amount of device memory required to hold meta-data for csr-adaptive SpM-dV algorithm. More...
CLSPARSE_EXPORT clsparseStatus	clsparseCsrMetaCreate (clsparseCsrMatrix *csrMatx, clsparseControl control)
	Allocate memory and calculate the meta-data for csr-adaptive SpM-dV algorithm. More...
CLSPARSE_EXPORT clsparseStatus	clsparseCsrMetaDelete (clsparseCsrMatrix *csrMatx)
	Delete meta data associated with a CSR encoded matrix. More...

Detailed Description

Functions to help read the contents of matrix market files from disk.

Function Documentation

CLSPARSE_EXPORT clsparseStatus clsparseCsrMetaCreate	(	clsparseCsrMatrix *	csrMatx,
		clsparseControl	control
	)

Allocate memory and calculate the meta-data for csr-adaptive SpM-dV algorithm.

CSR-adaptive is a high performance sparse matrix times dense vector algorithm. It requires a pre-processing step to calculate meta-data on the sparse matrix. This meta-data is stored alongside and carried along with the other matrix data. This function allocates memory for the meta-data and initializes it with proper values. It is important to remember to deallocate the meta memory with clsparseCsrMetaDelete

Parameters

[in,out]	csrMatx	The CSR sparse structure that represents the matrix in device memory
[in]	control	A valid clsparseControl created with clsparseCreateControl

Note

This function assumes that the memory for rowBlocks has already been allocated by client program

Examples:

sample-cg.cpp, and sample-spmv.cpp.

CLSPARSE_EXPORT clsparseStatus clsparseCsrMetaDelete

(

clsparseCsrMatrix *

csrMatx

)

Delete meta data associated with a CSR encoded matrix.

Meta data for a sparse matrix may occupy device memory, and this informs the library to release it

Parameters

[in,out]

csrMatx

The CSR sparse structure that represents the matrix in device memory

Examples:

sample-cg.cpp, and sample-spmv.cpp.

CLSPARSE_EXPORT clsparseMetaSizeResult clsparseCsrMetaSize	(	clsparseCsrMatrix *	csrMatx,
		clsparseControl	control
	)

Calculate the amount of device memory required to hold meta-data for csr-adaptive SpM-dV algorithm.

CSR-adaptive is a high performance sparse matrix times dense vector algorithm. It requires a pre-processing step to calculate meta-data on the sparse matrix. This meta-data is stored alongside and carried along with the other matrix data.

Parameters

[in,out]	csrMatx	The CSR sparse structure that represents the matrix in device memory
[in]	control	A valid clsparseControl created with clsparseCreateControl

CLSPARSE_EXPORT clsparseStatus clsparseDCooMatrixfromFile	(	clsparseCooMatrix *	cooMatx,
		const char *	filePath,
		clsparseControl	control,
		cl_bool	read_explicit_zeroes
	)

Read sparse matrix data from file in double precision COO format.

This function reads the contents of the sparse matrix file into clsparseCooMatrix data structure. The data structure represents the contents of the sparse matrix data in OpenCL device memory. This function sorts the values read (on host) by row, then column before copying them into device memory. If the data on disk is stored in single precision, this function will up-convert the values to double.

Parameters

[out]	cooMatx	The COO sparse structure that represents the matrix in device memory
[in]	filePath	A path in the file-system to the sparse matrix file
[in]	control	A valid clsparseControl created with clsparseCreateControl
[in]	read_explicit_zeroes	If the file contains values explicitly declared zero, this controls whether they are stored in the COO

Note

The number of non-zeroes actually read from the file may be less than the number of non-zeroes reported from the file header. Symmetrix matrices may store up to twice as many non-zero values compared to the number of values in the file. Explicitly declared zeroes may be stored or not depending on the input read_explicit_zeroes.

The OpenCL device memory must be allocated before the call to this function.

Postcondition

The sparse data is sorted first by row, then by column.

Returns

clsparseSuccess

CLSPARSE_EXPORT clsparseStatus clsparseDCsrMatrixfromFile	(	clsparseCsrMatrix *	csrMatx,
		const char *	filePath,
		clsparseControl	control,
		cl_bool	read_explicit_zeroes
	)

Read sparse matrix data from file in double precision CSR format.

This function reads the contents of the sparse matrix file into clsparseCsrMatrix data structure. The data structure represents the contents of the sparse matrix data in OpenCL device memory. This function sorts the values read (on host) by row, then column before copying them into device memory. If the data on disk is stored in single precision, this function will up-convert the values to double.

Parameters

[out]	csrMatx	The CSR sparse structure that represents the matrix in device memory
[in]	filePath	A path in the file-system to the sparse matrix file
[in]	control	A valid clsparseControl created with clsparseCreateControl
[in]	read_explicit_zeroes	If the file contains values explicitly declared zero, this controls whether they are stored in the CSR

Note

The number of non-zeroes actually read from the file may be less than the number of non-zeroes reported from the file header. Symmetrix matrices may store up to twice as many non-zero values compared to the number of values in the file. Explicitly declared zeroes may be stored or not depending on the input read_explicit_zeroes.

The OpenCL device memory must be allocated before the call to this function.

Postcondition

The sparse data is sorted first by row, then by column

Returns

clsparseSuccess

CLSPARSE_EXPORT clsparseStatus clsparseHeaderfromFile	(	clsparseIdx_t *	nnz,
		clsparseIdx_t *	row,
		clsparseIdx_t *	col,
		const char *	filePath
	)

Read the sparse matrix header from file.

Parameters

[out]	nnz	The number of non-zeroes present in the sparse matrix structure
[out]	row	The number of rows in the sparse matrix
[out]	col	The number of columns in the sparse matrix
[in]	filePath	A path in the file-system to the sparse matrix file

Note

At this time, only matrix market (.MTX) files are supported

Warning

The value returned in nnz is the maximum possible number of non-zeroes from the sparse matrix on disk (can be used to allocate memory). The actual number of non-zeroes may be less, depending if explicit zeroes were stored in file.

Returns

clsparseSuccess

Examples:

sample-cg.cpp, and sample-spmv.cpp.

CLSPARSE_EXPORT clsparseStatus clsparseSCooMatrixfromFile	(	clsparseCooMatrix *	cooMatx,
		const char *	filePath,
		clsparseControl	control,
		cl_bool	read_explicit_zeroes
	)

Read sparse matrix data from file in single precision COO format.

This function reads the contents of the sparse matrix file into clsparseCooMatrix data structure. The data structure represents the contents of the sparse matrix data in OpenCL device memory. This function sorts the values read (on host) by row, then column before copying them into device memory

Parameters

[out]	cooMatx	The COO sparse structure that represents the matrix in device memory
[in]	filePath	A path in the file-system to the sparse matrix file
[in]	control	A valid clsparseControl created with clsparseCreateControl
[in]	read_explicit_zeroes	If the file contains values explicitly declared zero, this controls whether they are stored in the COO

Note

The number of non-zeroes actually read from the file may be different than the number of non-zeroes reported from the file header. Symmetrix matrices may store up to twice as many non-zero values compared to the number of values in the file. Explicitly declared zeroes may be stored or not depending on the input read_explicit_zeroes.

The OpenCL device memory must be allocated before the call to this function.

Postcondition

The sparse data is sorted first by row, then by column.

Returns

clsparseSuccess

CLSPARSE_EXPORT clsparseStatus clsparseSCsrMatrixfromFile	(	clsparseCsrMatrix *	csrMatx,
		const char *	filePath,
		clsparseControl	control,
		cl_bool	read_explicit_zeroes
	)

Read sparse matrix data from file in single precision CSR format.

This function reads the contents of the sparse matrix file into clsparseCsrMatrix data structure. The data structure represents the contents of the sparse matrix data in OpenCL device memory. This function sorts the values read (on host) by row, then column before copying them into device memory

Parameters

[out]	csrMatx	The CSR sparse structure that represents the matrix in device memory
[in]	filePath	A path in the file-system to the sparse matrix file
[in]	control	A valid clsparseControl created with clsparseCreateControl
[in]	read_explicit_zeroes	If the file contains values explicitly declared zero, this controls whether they are stored in the CSR

Note

The number of non-zeroes actually read from the file may be less than the number of non-zeroes reported from the file header. Symmetrix matrices may store up to twice as many non-zero values compared to the number of values in the file. Explicitly declared zeroes may be stored or not depending on the input read_explicit_zeroes.

The OpenCL device memory must be allocated before the call to this function.

Postcondition

The sparse data is sorted first by row, then by column.

Returns

clsparseSuccess

Examples:

sample-cg.cpp, and sample-spmv.cpp.