Copyright | [2017] Trevor L. McDonell |
---|---|
License | BSD3 |
Maintainer | Trevor L. McDonell <tmcdonell@cse.unsw.edu.au> |
Stability | experimental |
Portability | non-portable (GHC extensions) |
Safe Haskell | None |
Language | Haskell2010 |
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:
Synopsis
- data PointerMode
- newtype Handle = Handle (Ptr ())
- create :: IO Handle
- destroy :: Handle -> IO ()
- setPointerMode :: Handle -> PointerMode -> IO ()
- getPointerMode :: Handle -> IO PointerMode
- newtype Info_prune = Info_prune {
- useInfo_prune :: Ptr ()
- newtype Info_csru2csr = Info_csru2csr {
- useInfo_csru2csr :: Ptr ()
- newtype Info_color = Info_color {
- useInfo_color :: Ptr ()
- newtype Info_csrsm2 = Info_csrsm2 {
- useInfo_csrsm2 :: Ptr ()
- newtype Info_csrgemm2 = Info_csrgemm2 (Ptr ())
- newtype Info_bsrilu02 = Info_bsrilu02 {
- useInfo_bsrilu02 :: Ptr ()
- newtype Info_bsric02 = Info_bsric02 {
- useInfo_bsric02 :: Ptr ()
- newtype Info_bsrsm2 = Info_bsrsm2 (Ptr ())
- newtype Info_bsrsv2 = Info_bsrsv2 (Ptr ())
- newtype Info_csrilu02 = Info_csrilu02 {
- useInfo_csrilu02 :: Ptr ()
- newtype Info_csric02 = Info_csric02 {
- useInfo_csric02 :: Ptr ()
- newtype Info_csrsv2 = Info_csrsv2 (Ptr ())
- newtype Info = Info (Ptr ())
- createInfo :: IO Info
- destroyInfo :: Info -> IO ()
- 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
- data Status
- describe :: Status -> String
- cusparseError :: String -> IO a
- checkStatus :: CInt -> IO ()
- data MatrixType
- data IndexBase
- data Fill
- data Diagonal
- newtype MatrixDescriptor = MatrixDescriptor (Ptr ())
- createMatDescr :: IO MatrixDescriptor
- destroyMatDescr :: MatrixDescriptor -> IO ()
- getDiagonal :: MatrixDescriptor -> IO Diagonal
- getFillMode :: MatrixDescriptor -> IO Fill
- getIndexBase :: MatrixDescriptor -> IO IndexBase
- getMatrixType :: MatrixDescriptor -> IO MatrixType
- setDiagonal :: MatrixDescriptor -> Diagonal -> IO ()
- setFillMode :: MatrixDescriptor -> Fill -> IO ()
- setIndexBase :: MatrixDescriptor -> IndexBase -> IO ()
- setMatrixType :: MatrixDescriptor -> MatrixType -> IO ()
- data HybridPartition
- newtype Hybrid = Hybrid (Ptr ())
- createHYB :: IO Hybrid
- destroyHYB :: Hybrid -> IO ()
- module Foreign.CUDA.BLAS.Sparse.Stream
- 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
Control
data PointerMode Source #
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
Instances
Enum PointerMode Source # | |
Defined in Foreign.CUDA.BLAS.Sparse.Context 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 Source # | |
Defined in Foreign.CUDA.BLAS.Sparse.Context (==) :: PointerMode -> PointerMode -> Bool # (/=) :: PointerMode -> PointerMode -> Bool # | |
Show PointerMode Source # | |
Defined in Foreign.CUDA.BLAS.Sparse.Context showsPrec :: Int -> PointerMode -> ShowS # show :: PointerMode -> String # showList :: [PointerMode] -> ShowS # |
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
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 () Source #
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 () Source #
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 Source #
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 Source #
Info_prune | |
|
newtype Info_csru2csr Source #
Info_csru2csr | |
|
newtype Info_color Source #
Info_color | |
|
newtype Info_csrsm2 Source #
Info_csrsm2 | |
|
newtype Info_csrgemm2 Source #
Info_csrgemm2 (Ptr ()) |
newtype Info_bsrilu02 Source #
Info_bsrilu02 | |
|
newtype Info_bsric02 Source #
Info_bsric02 | |
|
newtype Info_bsrsm2 Source #
Info_bsrsm2 (Ptr ()) |
newtype Info_bsrsv2 Source #
Info_bsrsv2 (Ptr ()) |
newtype Info_csrilu02 Source #
Info_csrilu02 | |
|
newtype Info_csric02 Source #
Info_csric02 | |
|
newtype Info_csrsv2 Source #
Info_csrsv2 (Ptr ()) |
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
createInfo :: IO Info Source #
Create and initialise the solve and analysis structure to default values.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsecreatesolveanalysisinfo
destroyInfo :: Info -> IO () Source #
Release memory associated with a matrix solver structure.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsedestroysolveanalysisinfo
destroyInfo_csrsv2 :: Info_csrsv2 -> IO () Source #
destroyInfo_csric02 :: Info_csric02 -> IO () Source #
destroyInfo_csrilu02 :: Info_csrilu02 -> IO () Source #
destroyInfo_bsrsv2 :: Info_bsrsv2 -> IO () Source #
destroyInfo_bsrsm2 :: Info_bsrsm2 -> IO () Source #
destroyInfo_bsric02 :: Info_bsric02 -> IO () Source #
destroyInfo_bsrilu02 :: Info_bsrilu02 -> IO () Source #
destroyInfo_csrgemm2 :: Info_csrgemm2 -> IO () Source #
destroyInfo_csrsm2 :: Info_csrsm2 -> IO () Source #
destroyInfo_color :: Info_color -> IO () Source #
destroyInfo_csru2csr :: Info_csru2csr -> IO () Source #
destroyInfo_prune :: Info_prune -> IO () Source #
data CUSparseException Source #
Instances
Show CUSparseException Source # | |
Defined in Foreign.CUDA.BLAS.Sparse.Error showsPrec :: Int -> CUSparseException -> ShowS # show :: CUSparseException -> String # showList :: [CUSparseException] -> ShowS # | |
Exception CUSparseException Source # | |
Error codes used by cuSPARSE library functions
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsestatust
Success | |
NotInitialized | |
AllocFailed | |
InvalidValue | |
ArchMismatch | |
MappingError | |
ExecutionFailed | |
InternalError | |
MatrixTypeNotSupported | |
ZeroPivot | |
NotSupported |
cusparseError :: String -> IO a Source #
Raise a CUSparseException in the IO Monad
checkStatus :: CInt -> IO () Source #
Throw an error if given error code is not CUSPARSE_STATUS_SUCCESS
data MatrixType Source #
Indicates the type of matrix.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsematrixtypet
Instances
Enum MatrixType Source # | Create a new matrix descriptor, with matrix type http://docs.nvidia.com/cuda/cusparse/index.html#cusparsecreatematdescr |
Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor 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 Source # | |
Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor (==) :: MatrixType -> MatrixType -> Bool # (/=) :: MatrixType -> MatrixType -> Bool # | |
Show MatrixType Source # | |
Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor showsPrec :: Int -> MatrixType -> ShowS # show :: MatrixType -> String # showList :: [MatrixType] -> ShowS # |
Indicates whether indexing of matrix elements starts at zero or one.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparseindexbaset
Instances
Enum IndexBase Source # | |
Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor succ :: IndexBase -> IndexBase # pred :: IndexBase -> IndexBase # fromEnum :: IndexBase -> Int # enumFrom :: IndexBase -> [IndexBase] # enumFromThen :: IndexBase -> IndexBase -> [IndexBase] # enumFromTo :: IndexBase -> IndexBase -> [IndexBase] # enumFromThenTo :: IndexBase -> IndexBase -> IndexBase -> [IndexBase] # | |
Eq IndexBase Source # | |
Show IndexBase Source # | |
Indicates whether the upper or lower part of the sparse matrix is stored.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsefillmodet
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
Instances
Enum Diagonal Source # | |
Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Descriptor | |
Eq Diagonal Source # | |
Show Diagonal Source # | |
newtype MatrixDescriptor Source #
An opaque type used to describe the shape and properties of a matrix.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsematdescrt
MatrixDescriptor (Ptr ()) |
destroyMatDescr :: MatrixDescriptor -> IO () Source #
Release memory associated with a matrix descriptor.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsedestroymatdescr
getDiagonal :: MatrixDescriptor -> IO Diagonal Source #
Get the Diagonal
type field of the matrix descriptor.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsegetmatdiagtype
getFillMode :: MatrixDescriptor -> IO Fill Source #
Get the Fill
mode of the matrix descriptor.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsegetmatfillmode
getIndexBase :: MatrixDescriptor -> IO IndexBase Source #
Get the IndexBase
mode of the matrix descriptor.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsegetmatindexbase
getMatrixType :: MatrixDescriptor -> IO MatrixType Source #
Get the MatrixType
mode of the matrix descriptor.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsegetmattype
setDiagonal :: MatrixDescriptor -> Diagonal -> IO () Source #
Set the Diagonal
type field of the matrix descriptor.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsesetmatdiagtype
setFillMode :: MatrixDescriptor -> Fill -> IO () Source #
Set the Fill
mode of the matrix descriptor.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsesetmatfillmode
setIndexBase :: MatrixDescriptor -> IndexBase -> IO () Source #
Set the IndexBase
mode of the matrix descriptor.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsesetmatindexbase
setMatrixType :: MatrixDescriptor -> MatrixType -> IO () Source #
Set the MatrixType
mode of the matrix descriptor.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsesetmattype
data HybridPartition Source #
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
Instances
Enum HybridPartition Source # | |
Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Hybrid 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 Source # | |
Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Hybrid (==) :: HybridPartition -> HybridPartition -> Bool # (/=) :: HybridPartition -> HybridPartition -> Bool # | |
Show HybridPartition Source # | |
Defined in Foreign.CUDA.BLAS.Sparse.Matrix.Hybrid showsPrec :: Int -> HybridPartition -> ShowS # show :: HybridPartition -> String # showList :: [HybridPartition] -> ShowS # |
An opaque structure holding the matrix in hybrid (HYB) format.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsehybmatt
createHYB :: IO Hybrid Source #
Create a new (opaque) hybrid matrix.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsecreatehybmat
destroyHYB :: Hybrid -> IO () Source #
Destroy and release any memory associated with a hybrid matrix.
http://docs.nvidia.com/cuda/cusparse/index.html#cusparsedestroyhybmat