Foreign.CUDA.BLAS.Sparse

The cuSPARSE library is an implementation of Sparse BLAS (Basic Linear Algebra Subprograms) for NVIDIA GPUs. Sparse matrices are those where the majority of elements are zero. Sparse BLAS routines are specifically implemented to take advantage of this sparsity.

To use operations from the cuSPARSE library, the user must allocate the required matrices and vectors in the GPU memory space, fill them with data, call the desired sequence of cuSPARSE functions, then copy the results from the GPU memory space back to the host.

The cuda package can be used for writing to and retrieving data from the GPU.

Example

The following is based on the following example:

http://docs.nvidia.com/cuda/cusparse/index.html#appendix-b-cusparse-library-c---example

It assumes basic familiarity with the cuda package, as described in the Foreign.CUDA.Driver module.

>>> import Foreign.CUDA.Driver      as CUDA
>>> import Foreign.CUDA.BLAS.Sparse as Sparse
>>> CUDA.initialise []
>>> dev <- CUDA.device 0
>>> ctx <- CUDA.create dev []

We begin by creating the following matrix in COO format and transferring to the GPU:

\[ \left(\begin{matrix} 1.0 & & 2.0 & 3.0 \\ & 4.0 & & \\ 5.0 & & 6.0 & 7.0 \\ & 8.0 & & 9.0 \end{matrix}\right) \]

>>> let n = 4
>>> let nnz = 9
>>> d_cooRowIdx <- newListArray [ 0,0,0, 1, 2,2,2, 3,3 ]  :: IO (DevicePtr Int32)
>>> d_cooColIdx <- newListArray [ 0,2,3, 1, 0,2,3, 1,3 ]  :: IO (DevicePtr Int32)
>>> d_vals      <- newListArray [ 1..9 ]                  :: IO (DevicePtr Double)

Create a sparse and dense vector:

>>> let nnz_vector = 3
>>> d_xVal <- newListArray [ 100, 200, 400 ] :: IO (DevicePtr Double)
>>> d_xIdx <- newListArray [ 0,   1,   3 ]   :: IO (DevicePtr Int32)
>>> d_y    <- newListArray [ 10, 20 .. 80 ]  :: IO (DevicePtr Double)

Initialise the cuSPARSE library and set up the matrix descriptor:

>>> hdl <- Sparse.create
>>> mat <- Sparse.createMatDescr
>>> Sparse.setMatrixType mat General
>>> Sparse.setIndexBase mat Zero

Exercise the conversion routines to convert from COO to CSR format:

>>> d_csrRowPtr <- CUDA.mallocArray (n+1) :: IO (DevicePtr Int32)
>>> xcoo2csr hdl d_cooRowIdx nnz n d_csrRowPtr Zero
>>> peekListArray (n+1) d_csrRowPtr
[0,3,4,7,9]

Scatter elements from the sparse vector into the dense vector:

>>> dsctr hdl nnz_vector d_xVal d_xIdx (d_y `plusDevPtr` (n * sizeOf (undefined::Double))) Zero
>>> peekListArray 8 d_y
[10.0,20.0,30.0,40.0,100.0,200.0,70.0,400.0]

Multiply the matrix in CSR format with the dense vector:

>>> with 2.0 $ \alpha ->
>>> with 3.0 $ \beta  ->
>>> dcsrmv hdl N n n nnz alpha mat d_vals d_csrRowPtr d_cooColIdx d_y beta (d_y `plusDevPtr` (n * sizeOf (undefined::Double)))
>>> peekListArray 8 d_y
[10.0,20.0,30.0,40.0,680.0,760.0,1230.0,2240.0]

Multiply the matrix in CSR format with a dense matrix:

>>> d_z <- CUDA.mallocArray (2*(n+1)) :: IO (DevicePtr Double)
>>> memset (castDevPtr d_z :: DevicePtr Word8) (2*(n+1)*sizeOf (undefined::Double)) 0
>>> with 5.0 $ \alpha ->
>>> with 0.0 $ \beta  ->
>>> dcsrmm hdl N n 2 n nnz alpha mat d_vals d_csrRowPtr d_cooColIdx d_y n beta d_z (n+1)
>> peekListArray (2*(n+1)) d_z
[950.0,400.0,2550.0,2600.0,0.0,49300.0,15200.0,132300.0,131200.0,0.0]

Finally, we should free the device memory we allocated, and release the Sparse BLAS context handle:

>>> Sparse.destroy hdl

Additional information

For more information, see the NVIDIA cuSPARSE documentation:

http://docs.nvidia.com/cuda/cusparse/index.html

Control

data PointerMode

For functions which take scalar value arguments, determines whether those values are passed by reference on the host or device.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsepointermode_t

Constructors

Host

Device

Instances

Enum PointerMode

Defined in Foreign.CUDA.BLAS.Sparse.Context

Methods

succ :: PointerMode -> PointerMode

pred :: PointerMode -> PointerMode

toEnum :: Int -> PointerMode

fromEnum :: PointerMode -> Int

enumFrom :: PointerMode -> [PointerMode]

enumFromThen :: PointerMode -> PointerMode -> [PointerMode]

enumFromTo :: PointerMode -> PointerMode -> [PointerMode]

enumFromThenTo :: PointerMode -> PointerMode -> PointerMode -> [PointerMode]

Eq PointerMode

Defined in Foreign.CUDA.BLAS.Sparse.Context

Methods

(==) :: PointerMode -> PointerMode -> Bool

(/=) :: PointerMode -> PointerMode -> Bool

Show PointerMode

Defined in Foreign.CUDA.BLAS.Sparse.Context

Methods

showsPrec :: Int -> PointerMode -> ShowS

show :: PointerMode -> String

showList :: [PointerMode] -> ShowS

newtype Handle

An opaque handle to the cuSPARSE library context, which is passed to all library function calls.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsehandlet

Constructors

Handle (Ptr ())

create :: IO Handle

This function initializes the cuSPARSE library and creates a handle on the cuSPARSE context. It must be called before any other cuSPARSE API function is invoked. It allocates hardware resources necessary for accessing the GPU.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsecreate

destroy :: Handle -> IO ()

This function releases CPU-side resources used by the cuSPARSE library. The release of GPU-side resources may be deferred until the application shuts down.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsedestroy

setPointerMode :: Handle -> PointerMode -> IO ()

Set the pointer mode used by cuSPARSE library functions.

The default mode is for values to be passed by reference from the host.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsesetpointermode

getPointerMode :: Handle -> IO PointerMode

Get the pointer mode used by cuSPARSE library functions to pass scalar arguments.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsegetpointermode

newtype Info_prune

Constructors

Info_prune

Fields

• useInfo_prune :: Ptr ()

newtype Info_csru2csr

Constructors

Info_csru2csr

Fields

• useInfo_csru2csr :: Ptr ()

newtype Info_color

Constructors

Info_color

Fields

• useInfo_color :: Ptr ()

newtype Info_csrsm2

https://docs.nvidia.com/cuda/cusparse/index.html#csrsm2infot

Constructors

Info_csrsm2

Fields

• useInfo_csrsm2 :: Ptr ()

newtype Info_csrgemm2

http://docs.nvidia.com/cuda/cusparse/index.html#csrgemm2infot

Constructors

Info_csrgemm2 (Ptr ())

newtype Info_bsrilu02

http://docs.nvidia.com/cuda/cusparse/index.html#bsrilu02infot

Constructors

Info_bsrilu02

Fields

• useInfo_bsrilu02 :: Ptr ()

newtype Info_bsric02

http://docs.nvidia.com/cuda/cusparse/index.html#bsric02infot

Constructors

Info_bsric02

Fields

• useInfo_bsric02 :: Ptr ()

newtype Info_bsrsm2

http://docs.nvidia.com/cuda/cusparse/index.html#bsrsvminfot

Constructors

Info_bsrsm2 (Ptr ())

newtype Info_bsrsv2

http://docs.nvidia.com/cuda/cusparse/index.html#bsrsv2infot

Constructors

Info_bsrsv2 (Ptr ())

newtype Info_csrilu02

http://docs.nvidia.com/cuda/cusparse/index.html#csrilu02infot

Constructors

Info_csrilu02

Fields

• useInfo_csrilu02 :: Ptr ()

newtype Info_csric02

http://docs.nvidia.com/cuda/cusparse/index.html#csric02infot

Constructors

Info_csric02

Fields

• useInfo_csric02 :: Ptr ()

newtype Info_csrsv2

http://docs.nvidia.com/cuda/cusparse/index.html#csrsv2infot

Constructors

Info_csrsv2 (Ptr ())

newtype Info

An opaque structure holding the information collected in the analysis phase of the solution of the sparse triangular linear system.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsesolveanalysisinfot

Constructors

Info (Ptr ())

createInfo :: IO Info

Create and initialise the solve and analysis structure to default values.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsecreatesolveanalysisinfo

destroyInfo :: Info -> IO ()

Release memory associated with a matrix solver structure.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsedestroysolveanalysisinfo

createInfo_csrsv2 :: IO Info_csrsv2

destroyInfo_csrsv2 :: Info_csrsv2 -> IO ()

createInfo_csric02 :: IO Info_csric02

destroyInfo_csric02 :: Info_csric02 -> IO ()

createInfo_csrilu02 :: IO Info_csrilu02

destroyInfo_csrilu02 :: Info_csrilu02 -> IO ()

createInfo_bsrsv2 :: IO Info_bsrsv2

destroyInfo_bsrsv2 :: Info_bsrsv2 -> IO ()

createInfo_bsrsm2 :: IO Info_bsrsm2

destroyInfo_bsrsm2 :: Info_bsrsm2 -> IO ()

createInfo_bsric02 :: IO Info_bsric02

destroyInfo_bsric02 :: Info_bsric02 -> IO ()

createInfo_bsrilu02 :: IO Info_bsrilu02

destroyInfo_bsrilu02 :: Info_bsrilu02 -> IO ()

createInfo_csrgemm2 :: IO Info_csrgemm2

destroyInfo_csrgemm2 :: Info_csrgemm2 -> IO ()

createInfo_csrsm2 :: IO Info_csrsm2

destroyInfo_csrsm2 :: Info_csrsm2 -> IO ()

createInfo_color :: IO Info_color

destroyInfo_color :: Info_color -> IO ()

createInfo_csru2csr :: IO Info_csru2csr

destroyInfo_csru2csr :: Info_csru2csr -> IO ()

createInfo_prune :: IO Info_prune

destroyInfo_prune :: Info_prune -> IO ()

data CUSparseException

Constructors

ExitCode Status

UserError String

Instances

Show CUSparseException

Defined in Foreign.CUDA.BLAS.Sparse.Error

Methods

showsPrec :: Int -> CUSparseException -> ShowS

show :: CUSparseException -> String

showList :: [CUSparseException] -> ShowS

Exception CUSparseException

Defined in Foreign.CUDA.BLAS.Sparse.Error

Methods

toException :: CUSparseException -> SomeException

fromException :: SomeException -> Maybe CUSparseException

displayException :: CUSparseException -> String

data Status

Error codes used by cuSPARSE library functions

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsestatust

Constructors

Success

NotInitialized

AllocFailed

InvalidValue

ArchMismatch

MappingError

ExecutionFailed

InternalError

MatrixTypeNotSupported

ZeroPivot

Instances

Enum Status

Defined in Foreign.CUDA.BLAS.Sparse.Error

Methods

succ :: Status -> Status

pred :: Status -> Status

toEnum :: Int -> Status

fromEnum :: Status -> Int

enumFrom :: Status -> [Status]

enumFromThen :: Status -> Status -> [Status]

enumFromTo :: Status -> Status -> [Status]

enumFromThenTo :: Status -> Status -> Status -> [Status]

Eq Status

Defined in Foreign.CUDA.BLAS.Sparse.Error

Methods

(==) :: Status -> Status -> Bool

(/=) :: Status -> Status -> Bool

Show Status

Defined in Foreign.CUDA.BLAS.Sparse.Error

Methods

showsPrec :: Int -> Status -> ShowS

show :: Status -> String

showList :: [Status] -> ShowS

describe :: Status -> String

cusparseError :: String -> IO a

Raise a CUSparseException in the IO Monad

checkStatus :: CInt -> IO ()

Throw an error if given error code is not CUSPARSE_STATUS_SUCCESS

data MatrixType

Indicates the type of matrix.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsematrixtypet

Constructors

General

Symmetric

Hermitian

Triangular

Instances

Enum MatrixType

Create a new matrix descriptor, with matrix type General and index base Zero, while leaving other fields uninitialised.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsecreatematdescr

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

succ :: MatrixType -> MatrixType

pred :: MatrixType -> MatrixType

toEnum :: Int -> MatrixType

fromEnum :: MatrixType -> Int

enumFrom :: MatrixType -> [MatrixType]

enumFromThen :: MatrixType -> MatrixType -> [MatrixType]

enumFromTo :: MatrixType -> MatrixType -> [MatrixType]

enumFromThenTo :: MatrixType -> MatrixType -> MatrixType -> [MatrixType]

Eq MatrixType

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

(==) :: MatrixType -> MatrixType -> Bool

(/=) :: MatrixType -> MatrixType -> Bool

Show MatrixType

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

showsPrec :: Int -> MatrixType -> ShowS

show :: MatrixType -> String

showList :: [MatrixType] -> ShowS

data IndexBase

Indicates whether indexing of matrix elements starts at zero or one.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparseindexbaset

Constructors

Zero

One

Instances

Enum IndexBase

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

succ :: IndexBase -> IndexBase

pred :: IndexBase -> IndexBase

toEnum :: Int -> IndexBase

fromEnum :: IndexBase -> Int

enumFrom :: IndexBase -> [IndexBase]

enumFromThen :: IndexBase -> IndexBase -> [IndexBase]

enumFromTo :: IndexBase -> IndexBase -> [IndexBase]

enumFromThenTo :: IndexBase -> IndexBase -> IndexBase -> [IndexBase]

Eq IndexBase

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

(==) :: IndexBase -> IndexBase -> Bool

(/=) :: IndexBase -> IndexBase -> Bool

Show IndexBase

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

showsPrec :: Int -> IndexBase -> ShowS

show :: IndexBase -> String

showList :: [IndexBase] -> ShowS

data Fill

Indicates whether the upper or lower part of the sparse matrix is stored.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsefillmodet

Constructors

Lower

Upper

Instances

Enum Fill

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

succ :: Fill -> Fill

pred :: Fill -> Fill

toEnum :: Int -> Fill

fromEnum :: Fill -> Int

enumFrom :: Fill -> [Fill]

enumFromThen :: Fill -> Fill -> [Fill]

enumFromTo :: Fill -> Fill -> [Fill]

enumFromThenTo :: Fill -> Fill -> Fill -> [Fill]

Eq Fill

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

(==) :: Fill -> Fill -> Bool

(/=) :: Fill -> Fill -> Bool

Show Fill

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

showsPrec :: Int -> Fill -> ShowS

show :: Fill -> String

showList :: [Fill] -> ShowS

data Diagonal

Indicates whether the diagonal elements of the matrix are unity. The diagonal elements are always assumed to be present, but if Unit is passed to an API routine, then the routine assumes that all diagonal entries are unity and will not read or modify those entries.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsediagtypet

Constructors

NonUnit

Unit

Instances

Enum Diagonal

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

succ :: Diagonal -> Diagonal

pred :: Diagonal -> Diagonal

toEnum :: Int -> Diagonal

fromEnum :: Diagonal -> Int

enumFrom :: Diagonal -> [Diagonal]

enumFromThen :: Diagonal -> Diagonal -> [Diagonal]

enumFromTo :: Diagonal -> Diagonal -> [Diagonal]

enumFromThenTo :: Diagonal -> Diagonal -> Diagonal -> [Diagonal]

Eq Diagonal

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

(==) :: Diagonal -> Diagonal -> Bool

(/=) :: Diagonal -> Diagonal -> Bool

Show Diagonal

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor

Methods

showsPrec :: Int -> Diagonal -> ShowS

show :: Diagonal -> String

showList :: [Diagonal] -> ShowS

newtype MatrixDescriptor

An opaque type used to describe the shape and properties of a matrix.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsematdescrt

Constructors

MatrixDescriptor (Ptr ())

createMatDescr :: IO MatrixDescriptor

destroyMatDescr :: MatrixDescriptor -> IO ()

Release memory associated with a matrix descriptor.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsedestroymatdescr

getDiagonal :: MatrixDescriptor -> IO Diagonal

Get the Diagonal type field of the matrix descriptor.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsegetmatdiagtype

getFillMode :: MatrixDescriptor -> IO Fill

Get the Fill mode of the matrix descriptor.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsegetmatfillmode

getIndexBase :: MatrixDescriptor -> IO IndexBase

Get the IndexBase mode of the matrix descriptor.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsegetmatindexbase

getMatrixType :: MatrixDescriptor -> IO MatrixType

Get the MatrixType mode of the matrix descriptor.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsegetmattype

setDiagonal :: MatrixDescriptor -> Diagonal -> IO ()

Set the Diagonal type field of the matrix descriptor.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsesetmatdiagtype

setFillMode :: MatrixDescriptor -> Fill -> IO ()

Set the Fill mode of the matrix descriptor.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsesetmatfillmode

setIndexBase :: MatrixDescriptor -> IndexBase -> IO ()

Set the IndexBase mode of the matrix descriptor.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsesetmatindexbase

setMatrixType :: MatrixDescriptor -> MatrixType -> IO ()

Set the MatrixType mode of the matrix descriptor.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsesetmattype

data HybridPartition

Indicates how to perform the partitioning of the matrix into regular (ELL) and irregular (COO) parts of the HYB format.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsehybpartitiont

Constructors

Auto

User

Max

Instances

Enum HybridPartition

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Hybrid

Methods

succ :: HybridPartition -> HybridPartition

pred :: HybridPartition -> HybridPartition

toEnum :: Int -> HybridPartition

fromEnum :: HybridPartition -> Int

enumFrom :: HybridPartition -> [HybridPartition]

enumFromThen :: HybridPartition -> HybridPartition -> [HybridPartition]

enumFromTo :: HybridPartition -> HybridPartition -> [HybridPartition]

enumFromThenTo :: HybridPartition -> HybridPartition -> HybridPartition -> [HybridPartition]

Eq HybridPartition

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Hybrid

Methods

(==) :: HybridPartition -> HybridPartition -> Bool

(/=) :: HybridPartition -> HybridPartition -> Bool

Show HybridPartition

Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Hybrid

Methods

showsPrec :: Int -> HybridPartition -> ShowS

show :: HybridPartition -> String

showList :: [HybridPartition] -> ShowS

newtype Hybrid

An opaque structure holding the matrix in hybrid (HYB) format.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsehybmatt

Constructors

Hybrid (Ptr ())

createHYB :: IO Hybrid

Create a new (opaque) hybrid matrix.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsecreatehybmat

destroyHYB :: Hybrid -> IO ()

Destroy and release any memory associated with a hybrid matrix.

http://docs.nvidia.com/cuda/cusparse/index.html#cusparsedestroyhybmat

module Foreign.CUDA.BLAS.Sparse.Stream

Operations

module Foreign.CUDA.BLAS.Sparse.Level1

module Foreign.CUDA.BLAS.Sparse.Level2

module Foreign.CUDA.BLAS.Sparse.Level3

module Foreign.CUDA.BLAS.Sparse.Precondition

module Foreign.CUDA.BLAS.Sparse.Reorder

module Foreign.CUDA.BLAS.Sparse.Convert