Safe Haskell	None
Language	Haskell2010

Numeric.LinAlg.Magma.Mutable

Contents

The read-write monad
Data types
- Mutable
- Immutable
Data transfer
BLAS-like functions
- CUBLAS
- MAGMA
Miscellaneous

Description

This module provides a mutable interface for performing GPU computations using the CUBLAS and MAGMA libraries. It provides a higher level interface to CUBLAS and MAGMA than is provided by the corresponding FFIs, but a lower-level interface than LinAlg.

Synopsis

The read-write monad

data RW s a

A monad that that behaves much like the ST monad. The first type argument is a phantom type that represents the state. A value of type RW s a is a computation which performs mutable operations on the GPU and returns a value of type a.

Like in the ST monad, the first type argument represents the state thread of the computation. Computations which produce values whose type is independent of this state thread are pure, and may be extracted from the monad (see the Internal module). Unlike ST, however, we may still extract values whose types do depend on the state thread (i.e., mutable values). However, when we extract these values into pure Haskell-space, we set the state-thread to the void type Ice, which represents a frozen state thread, where the value may no longer be modified. This is enforced by the type-system.

This allows us to coherently treat mutable and immutable versions of the same datatype! We may have mutable computations which may read from either mutable or immutable value, but only write to mutable values. In our types, we declare that we may read from a value which is in any state thread; in reality there are only two possible state threads in scope - that of this mutable computation, and the frozen state thread, Ice. However, when we write to a value, that value must be in the same state thread as our computation (and cannot be immutable!).

For example, consider the copy operation, which reads from the first vector and writes to the second. The copy operation produces a computation in the state thread s, and so the vector which is written to must also be in the state thread s. The vector which is read from may either be in the state thread s (meaning it is mutable as well) or have state thread Ice (indicating that it is now immutable). Therefore, its type is t, which is implicitly universally quantified, and so may be instantiated by either s or Ice.

Instances

Monad (RW s)
Functor (RW s)
Applicative (RW s)

makeRWD :: (forall s. RW s (dyn s e)) -> dyn Ice e

If a computation in the RW monad is valid for all state threads, and produces a state-dependent type, then we may extract out the value as a pure computation, as long as we coerce the state thread type variable to Ice, indicating that the value is now immutable. We do not need to make a copy of the mutable value; rather, it may no longer be mutated.

makeRWV :: (forall s. RW s (VecP s n e)) -> Vec n e

makeRWM :: (forall s. RW s (MatP s n m e)) -> Mat n m e

runRW :: (forall s. RW s a) -> a

If a computation in the RW monad is valid for all state threads, and produces a type which is independent of the state thread, then we may extract out that value as a pure computation.

creatingV :: (forall s. RW s (VecP s n e)) -> (forall s. VecP s n e -> RW s b) -> Vec n e

A convenient function for creating immutable data with mutable operations. The first argument is an operation to construct a data structure, the second argument operates on the first once it has been constructed, and the resulting data structure is returned as an immutable result.

creatingM :: (forall s. RW s (MatP s n m e)) -> (forall s. MatP s n m e -> RW s b) -> Mat n m e

Data types

class (Cublas e, Magma e, Storable e, Floating e) => CNum e

This class represents the elements on which we can operate.

Instances

CNum CFloat
CNum CDouble
CNum (Complex CFloat)
CNum (Complex CDouble)

Mutable

data VecP s n a

A type for vectors which reside on the GPU. The first type argument is a phantom type that is used similarly to the state type in the ST monad.

Constructors

VecP
Fields ptrV :: DevicePtr a a pointer to the payload on the GPU len :: SNat n the number of elements in the vector stride :: Int the offset in the payload from one element of the vector to the next

data MatP s m n a

A type for matrices which reside on the GPU. Matrices are stored in column-major format, which is the format preferred by CUBLAS. The first type argument is a phantom type that is used similarly to the state type in the ST monad.

Constructors

MatP
Fields ptrM :: DevicePtr a a pointer to the payload on the GPU dim :: (SNat m, SNat n) the dimensions of the matrix (rows, columns) ld :: Int the leading dimension of the matrix

data DVecP s a where

Constructors

DVecP :: VecP s n a -> DVecP s a

data DMatP s a where

Constructors

DMatP :: MatP s m n a -> DMatP s a

Immutable

data Ice

A void type which is used in the "state thread" type variable in mutable structures. As the name suggests, types which have Ice as their state thread are immutable. This immutability is enforced by the type system. The only way in which mutable datatypes in the RW monad are allowed to leave is by having their state thread type variables coerced to Ice.

type Mat = MatP Ice

An immutable version of the MatP primitive matrix data type.

type Vec = VecP Ice

An immutable version of the VecP primitive vector data type.

Data transfer

fromVectP :: Storable a => Vect n a -> RW s (VecP s n a)

Create a new vector from a list.

fromVectsP :: Storable a => Vect n (Vect m a) -> RW s (MatP s m n a)

Create a new matrix from a list of lists. The matrix is loaded in column major format!

toVectP :: CNum e => VecP t n e -> RW s (Vect n e)

Read the elements of a vector into a list.

toListsP :: Storable a => MatP t m n a -> RW s [[a]]

Read the elements of a matrix into a list of lists in column-major format.

toVectsP :: Storable a => MatP t m n a -> RW s (Vect n (Vect m a))

makeVecP :: Storable a => SNat n -> RW s (VecP s n a)

Make a new vector of a given length. Elements remain unitialized.

makeMatP :: Storable a => (SNat m, SNat n) -> RW s (MatP s m n a)

Make a new matrix on the GPU with given dimensions. Elements are uninitialized.

copy :: Cublas a => VecP t n a -> VecP s n a -> RW s ()

Make a copy of a vector.

makeCopyVecP :: (Storable a, Cublas a) => VecP t n a -> RW s (VecP s n a)

Make a copy of a vector.

makeCopyMatP :: Storable a => MatP t m n a -> RW s (MatP s m n a)

Make a copy of a matrix.

memtrans :: CNum a => MatP t m n a -> RW s (MatP s n m a)

Make a transposed copy of a matrix.

fillWithColumns :: (Storable a, Cublas a) => [VecP t m a] -> MatP s m n a -> RW s ()

Copy each vector in a list into a contiguous matrix.

BLAS-like functions

See documentation for CUBLAS and MAGMA for more detailed documentation.

CUBLAS

See CUBLAS documentation.

dot :: CNum a => VecP t n a -> VecP u n a -> RW s a

Vector dot product.

scal :: CNum a => a -> VecP s n a -> RW s ()

Scalar multiplication for vectors.

axpy :: CNum a => a -> VecP t n a -> VecP s n a -> RW s ()

Combined scalar multiplication of and vector addition to a vector.

gemv :: CNum a => a -> (MatP t m n a, Operation) -> VecP u nx a -> a -> VecP s ny a -> RW s ()

Matrix-vector multiplication. XXX: Give this a more specific type

gemm :: CNum a => a -> (MatP t ma na a, Operation) -> (MatP u mb nb a, Operation) -> a -> MatP s m' n' a -> RW s ()

Matrix-matrix multiplication. XXX : Give this a more specific type

trsv :: CNum a => (MatP t n n a, FillMode, Operation, DiagType) -> VecP s n a -> RW s ()

Solution of a triangular linear system against a vector.

trsm :: CNum a => (MatP t n n a, SideMode, FillMode, Operation, DiagType) -> a -> MatP s m p a -> RW s ()

Solution of a triangular linear system against a matrix. XXX: make this type more specific

geam :: CNum a => a -> (MatP t ma na a, Operation) -> a -> (MatP u mb nb a, Operation) -> MatP s m n a -> RW s ()

General addition of matrices. XXX : Give this a more specific type

dgmm :: CNum a => SideMode -> VecP t nx a -> MatP u m n a -> MatP s m n a -> RW s ()

Multiplication of a matrix by a diagonal matrix. XXX: Give this a more specific type

ger :: CNum a => a -> VecP t m a -> VecP u n a -> MatP s m n a -> RW s ()

Symmetric rank-1 addition.

syrk :: CNum a => (MatP t ma na a, Operation) -> a -> a -> (MatP s mb nb a, FillMode) -> RW s ()

Symmetric low-rank addition. XXX: Give this a more specific type

MAGMA

See MAGMA documentation.

gesv :: CNum a => MatP s n n a -> MatP s n m a -> RW s ()

General matrix-matrix linear system solver. Warning! gesv acts destructively on both matrices.

potrf :: CNum a => (MatP s n n a, FillMode) -> RW s ()

Cholesky decomposition of a positive-definite matrix.

Miscellaneous

asColumns :: Storable a => MatP s m n a -> Vect n (VecP s m a)

Produce a list of views of each of the columns of a matrix.

asVecP :: MatP s m n a -> VecP s (m * n) a

Treat a matrix as one gigantic vector (throws an error if the leading dimension is larger than the number of rows).

dimCheck :: (Eq b, Show b) => String -> [[b]] -> a -> a

For each list that is provided, checks that all of the elemnts in the list are the same. If not, causes an error which is prefixed by the provided string.

handle :: Handle

A global handle created when CUBLAS initializes that is passed to all CUBLAS calls.

magmaHandle :: Maybe ()

A fake handle for MAGMA, because we similarly must initialize MAGMA prior to calling any MAGMA functions.

setZeroMatP :: CNum a => MatP s m n a -> RW s ()

Set all of the elements in a matrix to 0.

takeDiagP :: MatP s n n e -> VecP s n e

View the diagonal of a matrix as a vector. Note that this does not make a copy (as is evident from the type)!