Data.Massiv.Core

The array family. Representations r describe how data is arranged or computed. All arrays have a common property that each index ix always maps to the same unique element e, even if that element does not yet exist in memory and the array has to be computed in order to get the value of that element. Data is always arranged in a nested row-major fashion. Rank of an array is specified by Dimensions ix.

Type synonym for a single dimension array, or simply a flat vector.

Type synonym for a single dimension mutable array, or simply a flat mutable vector.

Type synonym for a two-dimentsional array, or simply a matrix.

Type synonym for a two-dimentsional mutable array, or simply a mutable matrix.

Any array that can be computed and loaded into memory

Arrays that can be used as source to practically any manipulation function.

Prefered indexing function.

Arrays that have information about their size availible in constant time.

The shape of an array. It is different from Size in that it can be applicable to non-square matrices and might not be available in constant time.

Size hint

Manifest arrays are backed by actual memory and values are looked up versus computed as it is with delayed arrays. Because manifest arrays are located in memory their contents can be mutated once thawed into MArray. The process of changed a mutable MArray back into an immutable Array is called freezing.

Starting with massiv-1.0 Mutable and Manifest are synonymous. Since massiv-1.1 it is deprecated and will be removed in massiv-1.2

Main type for scheduling work. See withScheduler or withScheduler_ for ways to construct and use this data type.

This is a wrapper around Scheduler, but it also keeps a separate state for each individual worker. See withSchedulerWS or withSchedulerWS_ for ways to construct and use this data type.

Computation strategy to use when scheduling work.

Parallel computation using all available cores. Same as ParOn []

Parallel computation using all available cores. Same as ParN 0

Get computation strategy of this array

Set computation strategy for this array

Example

>>> :set -XTypeApplications>>> import Data.Massiv.Array>>> a = singleton @DL @Ix1 @Int 0>>> aArray DL Seq (Sz1 1)  [ 0 ]>>> setComp (ParN 6) a -- use 6 capabilitiesArray DL (ParN 6) (Sz1 1)  [ 0 ]

Append computation strategy using Comp's Monoid instance.

Each worker is capable of keeping it's own state, that can be share for different schedulers, but not at the same time. In other words using the same WorkerStates on Control.Scheduler.withSchedulerS concurrently will result in an error. Can be initialized with initWorkerStates

Initialize a separate state for each worker.

Schedule an action to be picked up and computed by a worker from a pool of jobs. Similar to scheduleWorkId, except the job doesn't get the worker id.

Same as scheduleWork, but only for a Scheduler that doesn't keep the results.

A class for monads in which exceptions may be thrown.

Instances should obey the following law:

throwM e >> x = throwM e

In other words, throwing an exception short-circuits the rest of the monadic computation.

Exceptions that get thrown when there is a problem with an index, size or dimension.

Exception that indicates an issue with an array size.

Exception that can happen upon conversion of a ragged type array into the rectangular kind. Which means conversion from lists is susceptible to this exception.

Throw SizeElementsMismatchException whenever number of elements in both sizes do not match.

Throw an error on Left or produce the result on Right. Exception type is lost, so do not expect to be able to catch it as such. Stick to IO if you need exception control flow.

Throw an impossible error.

Any type that you wish to throw or catch as an exception must be an instance of the Exception class. The simplest case is a new exception type directly below the root:

data MyException = ThisException | ThatException
    deriving Show

instance Exception MyException

The default method definitions in the Exception class do what we need in this case. You can now throw and catch ThisException and ThatException as exceptions:

*Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
Caught ThisException

In more complicated examples, you may wish to define a whole hierarchy of exceptions:

---------------------------------------------------------------------
-- Make the root exception type for all the exceptions in a compiler

data SomeCompilerException = forall e . Exception e => SomeCompilerException e

instance Show SomeCompilerException where
    show (SomeCompilerException e) = show e

instance Exception SomeCompilerException

compilerExceptionToException :: Exception e => e -> SomeException
compilerExceptionToException = toException . SomeCompilerException

compilerExceptionFromException :: Exception e => SomeException -> Maybe e
compilerExceptionFromException x = do
    SomeCompilerException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make a subhierarchy for exceptions in the frontend of the compiler

data SomeFrontendException = forall e . Exception e => SomeFrontendException e

instance Show SomeFrontendException where
    show (SomeFrontendException e) = show e

instance Exception SomeFrontendException where
    toException = compilerExceptionToException
    fromException = compilerExceptionFromException

frontendExceptionToException :: Exception e => e -> SomeException
frontendExceptionToException = toException . SomeFrontendException

frontendExceptionFromException :: Exception e => SomeException -> Maybe e
frontendExceptionFromException x = do
    SomeFrontendException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make an exception type for a particular frontend compiler exception

data MismatchedParentheses = MismatchedParentheses
    deriving Show

instance Exception MismatchedParentheses where
    toException   = frontendExceptionToException
    fromException = frontendExceptionFromException

We can now catch a MismatchedParentheses exception as MismatchedParentheses, SomeFrontendException or SomeCompilerException, but not other types, e.g. IOException:

*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: IOException))
*** Exception: MismatchedParentheses

The SomeException type is the root of the exception type hierarchy. When an exception of type e is thrown, behind the scenes it is encapsulated in a SomeException.

Request a CallStack.

NOTE: The implicit parameter ?callStack :: CallStack is an implementation detail and should not be considered part of the CallStack API, we may decide to change the implementation in the future.

An error that gets thrown when an unitialized element of a boxed array gets accessed. Can only happen when array was constructed with unsafeNew.

Monads which allow their actions to be run in IO.

While MonadIO allows an IO action to be lifted into another monad, this class captures the opposite concept: allowing you to capture the monadic context. Note that, in order to meet the laws given below, the intuition is that a monad must have no monadic state, but may have monadic context. This essentially limits MonadUnliftIO to ReaderT and IdentityT transformers on top of IO.

Laws. For any function run provided by withRunInIO, it must meet the monad transformer laws as reformulated for MonadUnliftIO:

• run . return = return

• run (m >>= f) = run m >>= run . f

Instances of MonadUnliftIO must also satisfy the following laws:

Identity law

withRunInIO (\run -> run m) = m

Inverse law

withRunInIO (\_ -> m) = liftIO m

As an example of an invalid instance, a naive implementation of MonadUnliftIO (StateT s m) might be

withRunInIO inner =
  StateT $ \s ->
    withRunInIO $ \run ->
      inner (run . flip evalStateT s)

This breaks the identity law because the inner run m would throw away any state changes in m.

Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)

Class of monads which can perform primitive state-transformer actions.