-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Data structures for Nested Data-Parallel Haskell.
--   
--   Data structures for Nested Data-Parallel Haskell.
@package dph-par


-- | Parallel Arrays.
--   
--   Parallel arrays use a fixed generic representation. All data stored in
--   them is converted to the generic representation, and we have a small
--   number of operators that work on arrays of these generic types.
--   
--   Representation types include Ints, Floats, Tuples and Sums, so arrays
--   of these types can be stored directly. However, user defined algebraic
--   data needs to be converted as we don't have operators that work
--   directly on arrays of these types.
--   
--   The top-level PArray type is built up from several type families and
--   clases:
--   
--   PArray - This is the top level type. It holds an array length, and
--   array data in the generic representation (PData).
--   
--   PRepr - Family of types that can be converted to the generic
--   representation. We supply instances for basic types like Ints Floats
--   etc, but the vectoriser needs to make the instances for user-defined
--   data types itself. PA class - Contains methods to convert to and from
--   the generic representation (PData).
--   
--   PData - Family of types that can be stored directly in parallel
--   arrays. We supply all the PData instances we need here in the library.
--   PR class - Contains methods that work directly on parallel arrays.
--   Most of these are just wrappers for the corresponding U.Array
--   operators.
--   
--   Scalar class - Contains methods to convert between the generic
--   representation (PData) and plain U.Arrays.
--   
--   Note that the PRepr family and PA class are related. so are the PData
--   family and PR class.
--   
--   For motivational material see: <a>An Approach to Fast Arrays in
--   Haskell</a>, Chakravarty and Keller, 2003
--   
--   For discussion of how the mapping to generic types works see:
--   <a>Instant Generics: Fast and Easy</a>, Chakravarty, Ditu and Keller,
--   2009
module Data.Array.Parallel.PArray

-- | Lifted/bulk parallel arrays This contains the array length, along with
--   the element data.
data PArray a

-- | A PA dictionary contains the functions that we use to convert a
--   representable type to and from its generic representation. The
--   conversion methods should all be O(1).
class PR (PRepr a) => PA a
class Random a
randoms :: (Random a, RandomGen g) => Int -> g -> PArray a
randomRs :: (Random a, RandomGen g) => Int -> (a, a) -> g -> PArray a

-- | O(1). Yield the length of an array.
length :: PA a => PArray a -> Int

-- | O(1). An empty array, with no elements.
empty :: PA a => PArray a

-- | O(n). Produce an array containing copies of a given element.
replicate :: PA a => Int -> a -> PArray a

-- | O(1). Produce an array containing a single element.
singleton :: PA a => a -> PArray a

-- | O(1). Retrieve a numbered element from an array.
(!:) :: PA a => PArray a -> Int -> a

-- | O(1). Takes two arrays and returns an array of corresponding pairs. If
--   one array is short, excess elements of the longer array are discarded.
zip :: (PA a, PA b) => PArray a -> PArray b -> PArray (a, b)

-- | O(1). Transform an array into an array of the first components, and an
--   array of the second components.
unzip :: (PA a, PA b) => PArray (a, b) -> (PArray a, PArray b)

-- | Select the elements of an array that have their tag set as True.
--   
--   <pre>
--   packPA [12, 24, 42, 93] [True, False, False, True]
--    = [24, 42]
--   </pre>
pack :: PA a => PArray a -> PArray Bool -> PArray a

-- | Concatenate an array of arrays into a single array.
concat :: PA a => PArray (PArray a) -> PArray a

-- | Append two arrays
(+:+) :: PA a => PArray a -> PArray a -> PArray a

-- | O(n). Tag each element of an array with its index.
--   
--   <pre>
--   indexed [42, 93, 13] = [(0, 42), (1, 93), (2, 13)]
--   </pre>
indexed :: PA a => PArray a -> PArray (Int, a)

-- | Extract a subrange of elements from an array. The first argument is
--   the starting index, while the second is the length of the slice.
slice :: PA a => Int -> Int -> PArray a -> PArray a

-- | Copy the source array in the destination, using new values for the
--   given indices.
update :: PA a => PArray a -> PArray (Int, a) -> PArray a

-- | O(n). Backwards permutation of array elements.
--   
--   <pre>
--   bpermute [50, 60, 20, 30] [0, 3, 2]  = [50, 30, 20]
--   </pre>
bpermute :: PA a => PArray a -> PArray Int -> PArray a

-- | O(n). Generate a range of <tt>Int</tt>s.
enumFromTo :: Int -> Int -> PArray Int

-- | Create a <a>PArray</a> from a list.
fromList :: PA a => [a] -> PArray a

-- | Create a list from a <a>PArray</a>.
toList :: PA a => PArray a -> [a]

-- | Create a PArray out of a scalar U.Array, reading the length directly
--   from the U.Array.
fromUArrPA' :: Scalar a => Array a -> PArray a

-- | Ensure an array is fully evaluated.
nf :: PA a => PArray a -> ()
instance Random Double
instance Random Int
instance (PA a, Show a) => Show (PArray a)

module Data.Array.Parallel.Lifted

-- | Lifted/bulk parallel arrays This contains the array length, along with
--   the element data.
data PArray a
PArray :: Int# -> (PData a) -> PArray a

-- | Parallel Data. This is the family of types that store parallel array
--   data.
--   
--   PData takes the type of an element and produces the type we use to
--   store an array of those elements. The instances for PData use an
--   efficient representation that depends on the type of elements being
--   stored. For example, an array of pairs is stored as two separate
--   arrays, one for each element type. This lets us avoid storing the
--   intermediate Pair/Tuple constructors and the pointers to the elements.
--   
--   Most of the instances are defined in
--   <a>Data.Array.Parallel.PArray.Instances</a>, though the instances for
--   function closures are defined in their own module,
--   <a>Data.Array.Parallel.Lifted.Closure</a>.
--   
--   Note that PData is just a flat chunk of memory containing elements,
--   and doesn't include a field giving the length of the array. We use
--   PArray when we want to pass around the array data along with its
--   length.

-- | A PA dictionary contains the functions that we use to convert a
--   representable type to and from its generic representation. The
--   conversion methods should all be O(1).
class PR (PRepr a) => PA a
toPRepr :: PA a => a -> PRepr a
fromPRepr :: PA a => PRepr a -> a
toArrPRepr :: PA a => PData a -> PData (PRepr a)
fromArrPRepr :: PA a => PData (PRepr a) -> PData a

-- | Take the length field of a PArray.
lengthPA# :: PArray a -> Int#

-- | Take the data field of a PArray.
dataPA# :: PArray a -> PData a
replicatePA# :: PA a => Int# -> a -> PArray a
replicatelPA# :: PA a => Segd -> PArray a -> PArray a
repeatPA# :: PA a => Int# -> PArray a -> PArray a
emptyPA :: PA a => PArray a
indexPA# :: PA a => PArray a -> Int# -> a
extractPA# :: PA a => PArray a -> Int# -> Int# -> PArray a
bpermutePA# :: PA a => PArray a -> Int# -> Array Int -> PArray a
appPA# :: PA a => PArray a -> PArray a -> PArray a
applPA# :: PA a => Segd -> Segd -> PArray a -> Segd -> PArray a -> PArray a
packByTagPA# :: PA a => PArray a -> Int# -> Array Tag -> Int# -> PArray a
combine2PA# :: PA a => Int# -> Sel2 -> PArray a -> PArray a -> PArray a
updatePA# :: PA a => PArray a -> Array Int -> PArray a -> PArray a
fromListPA# :: PA a => Int# -> [a] -> PArray a
fromListPA :: PA a => [a] -> PArray a
nfPA :: PA a => PArray a -> ()
replicatePD :: PA a => T_replicatePR a
replicatelPD :: PA a => T_replicatelPR a
repeatPD :: PA a => T_repeatPR a
emptyPD :: PA a => T_emptyPR a
indexPD :: PA a => T_indexPR a
extractPD :: PA a => T_extractPR a
bpermutePD :: PA a => T_bpermutePR a
appPD :: PA a => T_appPR a
applPD :: PA a => T_applPR a
packByTagPD :: PA a => T_packByTagPR a
combine2PD :: PA a => T_combine2PR a
updatePD :: PA a => T_updatePR a
fromListPD :: PA a => T_fromListPR a
nfPD :: PA a => T_nfPR a

-- | Representable types.
--   
--   The family of types that we know how to represent generically. PRepr
--   takes an arbitrary type and produces the generic type we use to
--   represent it.
--   
--   Instances for simple types are defined in
--   Data.Array.Parallel.Lifted.Instances. For algebraic types, it's up to
--   the vectoriser/client module to create a suitable instance.

-- | A PR dictionary contains the primitive functions that operate directly
--   on parallel array data.
--   
--   It's called PR because the functions work on our internal, efficient
--   Representation of the user-level array.
class PR a
emptyPR :: PR a => T_emptyPR a
replicatePR :: PR a => T_replicatePR a
replicatelPR :: PR a => T_replicatelPR a
repeatPR :: PR a => T_repeatPR a
indexPR :: PR a => T_indexPR a
extractPR :: PR a => T_extractPR a
bpermutePR :: PR a => T_bpermutePR a
appPR :: PR a => T_appPR a
applPR :: PR a => T_applPR a
packByTagPR :: PR a => T_packByTagPR a
combine2PR :: PR a => T_combine2PR a
updatePR :: PR a => T_updatePR a
fromListPR :: PR a => T_fromListPR a
nfPR :: PR a => T_nfPR a

-- | Class of scalar types. Scalar types are the ones that we can store in
--   our underlying U.Arrays (which are currently implemented as
--   Data.Vectors).
--   
--   To perform an operation on a PData array of scalar elements, we coerce
--   it to the underling U.Array and use the corresponding U.Array
--   operators.
class Elt a => Scalar a
fromScalarPData :: Scalar a => PData a -> Array a
toScalarPData :: Scalar a => Array a -> PData a
replicatePRScalar :: Scalar a => T_replicatePR a
replicatelPRScalar :: Scalar a => T_replicatelPR a
repeatPRScalar :: Scalar a => T_repeatPR a
emptyPRScalar :: Scalar a => T_emptyPR a
indexPRScalar :: Scalar a => T_indexPR a
extractPRScalar :: Scalar a => T_extractPR a
bpermutePRScalar :: Scalar a => T_bpermutePR a
appPRScalar :: Scalar a => T_appPR a
applPRScalar :: Scalar a => T_applPR a
packByTagPRScalar :: Scalar a => T_packByTagPR a
combine2PRScalar :: Scalar a => T_combine2PR a
updatePRScalar :: Scalar a => T_updatePR a
fromListPRScalar :: Scalar a => T_fromListPR a
nfPRScalar :: Scalar a => T_nfPR a

-- | The type of closures. This bundles up: 1) the vectorised version of
--   the function that takes an explicit environment 2) the lifted version,
--   that works on arrays. the first parameter of this function is the
--   'lifting context' that gives the length of the array. 3) the
--   environment of the closure.
--   
--   The vectoriser closure-converts the source program so that all
--   functions types are expressed in this form.
data (:->) a b

-- | Apply a closure to its argument.
($:) :: (a :-> b) -> a -> b

-- | Lifted closure application
($:^) :: PArray (a :-> b) -> PArray a -> PArray b
fromPArrayPA :: PA a => PArray a :-> PArray a
toPArrayPA :: PA a => PArray a :-> PArray a
fromNestedPArrayPA :: PA a => (PArray (PArray a) :-> PArray (PArray a))

module Data.Array.Parallel.Prelude.Int

-- | A fixed-precision integer type with at least the range <tt>[-2^29 ..
--   2^29-1]</tt>. The exact range for a given implementation can be
--   determined by using <tt>Prelude.minBound</tt> and
--   <tt>Prelude.maxBound</tt> from the <tt>Prelude.Bounded</tt> class.
data Int :: *
(==, >=, >, <=, <, /=) :: Int -> Int -> Bool
min, max :: Int -> Int -> Int
minimumP, maximumP :: [:Int:] -> Int
minIndexP :: [:Int:] -> Int
maxIndexP :: [:Int:] -> Int
(+, *, -) :: Int -> Int -> Int
negate, abs :: Int -> Int
sumP, productP :: [:Int:] -> Int
div, mod :: Int -> Int -> Int
sqrt :: Int -> Int
enumFromToP :: Int -> Int -> [:Int:]

module Data.Array.Parallel.Prelude.Word8

-- | 8-bit unsigned integer type
data Word8 :: *
(==, >=, >, <=, <, /=) :: Word8 -> Word8 -> Bool
min, max :: Word8 -> Word8 -> Word8
minimumP, maximumP :: [:Word8:] -> Word8
minIndexP :: [:Word8:] -> Int
maxIndexP :: [:Word8:] -> Int
(+, *, -) :: Word8 -> Word8 -> Word8
negate, abs :: Word8 -> Word8
sumP, productP :: [:Word8:] -> Word8
div, mod :: Word8 -> Word8 -> Word8
sqrt :: Word8 -> Word8
toInt :: Word8 -> Int
fromInt :: Int -> Word8

module Data.Array.Parallel.Prelude.Float

-- | Single-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   single-precision type.
data Float :: *
(==, >=, >, <=, <, /=) :: Float -> Float -> Bool
min, max :: Float -> Float -> Float
minimumP, maximumP :: [:Float:] -> Float
minIndexP :: [:Float:] -> Int
maxIndexP :: [:Float:] -> Int
(+, *, -) :: Float -> Float -> Float
negate, abs :: Float -> Float
sumP, productP :: [:Float:] -> Float
(/) :: Float -> Float -> Float
recip :: Float -> Float
pi :: Float
exp, acosh, atanh, asinh, cosh, tanh, sinh, acos, atan, asin, cos, tan, sin, log, sqrt :: Float -> Float
(**, logBase) :: Float -> Float -> Float
fromInt :: Int -> Float
truncate, floor, ceiling, round :: Float -> Int

module Data.Array.Parallel.Prelude.Double

-- | Double-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   double-precision type.
data Double :: *
(==, >=, >, <=, <, /=) :: Double -> Double -> Bool
min, max :: Double -> Double -> Double
minimumP, maximumP :: [:Double:] -> Double
minIndexP :: [:Double:] -> Int
maxIndexP :: [:Double:] -> Int
(+, *, -) :: Double -> Double -> Double
negate, abs :: Double -> Double
sumP, productP :: [:Double:] -> Double
(/) :: Double -> Double -> Double
recip :: Double -> Double
pi :: Double
exp, acosh, atanh, asinh, cosh, tanh, sinh, acos, atan, asin, cos, tan, sin, log, sqrt :: Double -> Double
(**, logBase) :: Double -> Double -> Double
fromInt :: Int -> Double
truncate, floor, ceiling, round :: Double -> Int


-- | This module (as well as the type-specific modules
--   <tt>Data.Array.Parallel.Prelude.*</tt>) are a temporary kludge needed
--   as DPH programs cannot directly use the (non-vectorised) functions
--   from the standard Prelude. It also exports some conversion helpers.
--   
--   <i>This module should not be explicitly imported in user code
--   anymore.</i> User code should only import <tt>Data.Array.Parallel</tt>
--   and, until the vectoriser supports type classes, the type-specific
--   modules <tt>Data.Array.Parallel.Prelude.*</tt>.
module Data.Array.Parallel.Prelude
data Bool :: *
False :: Bool
True :: Bool

-- | <a>otherwise</a> is defined as the value <a>True</a>. It helps to make
--   guards more readable. eg.
--   
--   <pre>
--   f x | x &lt; 0     = ...
--       | otherwise = ...
--   </pre>
otherwise :: Bool
(&&) :: Bool -> Bool -> Bool
(||) :: Bool -> Bool -> Bool
not :: Bool -> Bool
andP :: [:Bool:] -> Bool
orP :: [:Bool:] -> Bool
and_l :: PArray Bool -> PArray Bool -> PArray Bool
or_l :: PArray Bool -> PArray Bool -> PArray Bool
not_l :: PArray Bool -> PArray Bool
tup2 :: (PA a, PA b) => a :-> (b :-> (a, b))
tup3 :: (PA a, PA b, PA c) => a :-> (b :-> (c :-> (a, b, c)))

-- | Lifted/bulk parallel arrays This contains the array length, along with
--   the element data.
data PArray a

-- | Class of scalar types. Scalar types are the ones that we can store in
--   our underlying U.Arrays (which are currently implemented as
--   Data.Vectors).
--   
--   To perform an operation on a PData array of scalar elements, we coerce
--   it to the underling U.Array and use the corresponding U.Array
--   operators.
class Elt a => Scalar a
fromScalarPData :: Scalar a => PData a -> Array a
toScalarPData :: Scalar a => Array a -> PData a

-- | Convert a PArray back to a plain U.Array.
toUArrPA :: Scalar a => PArray a -> Array a

-- | Create a PArray out of a scalar U.Array, reading the length directly
--   from the U.Array.
fromUArrPA' :: Scalar a => Array a -> PArray a

-- | Convert a U.Array of pairs to a PArray, reading the length directly
--   from the U.Array.
fromUArrPA_2' :: (Scalar a, Scalar b) => Array (a, b) -> PArray (a, b)

-- | Convert a U.Array of triples to a PArray.
fromUArrPA_3 :: (Scalar a, Scalar b, Scalar c) => Int -> Array ((a, b), c) -> PArray (a, b, c)

-- | Convert a U.Array of triples to a PArray, reading the length directly
--   from the U.Array.
fromUArrPA_3' :: (Scalar a, Scalar b, Scalar c) => Array ((a, b), c) -> PArray (a, b, c)

-- | O(1). Create a nested array, using the same length as the source
--   array.
nestUSegdPA' :: Segd -> PArray a -> PArray (PArray a)


-- | User level interface of parallel arrays.
--   
--   The semantic difference between standard Haskell arrays (aka <a>lazy
--   arrays</a>) and parallel arrays (aka <a>strict arrays</a>) is that the
--   evaluation of two different elements of a lazy array is independent,
--   whereas in a strict array either non or all elements are evaluated. In
--   other words, when a parallel array is evaluated to WHNF, all its
--   elements will be evaluated to WHNF. The name parallel array indicates
--   that all array elements may, in general, be evaluated to WHNF in
--   parallel without any need to resort to speculative evaluation. This
--   parallel evaluation semantics is also beneficial in the sequential
--   case, as it facilitates loop-based array processing as known from
--   classic array-based languages, such as Fortran.
--   
--   The interface of this module is essentially a variant of the list
--   component of the Prelude, but also includes some functions (such as
--   permutations) that are not provided for lists. The following list of
--   operations are not supported on parallel arrays, as they would require
--   the infinite parallel arrays: <a>iterate</a>, <a>repeat</a>, and
--   <a>cycle</a>.
--   
--   <i>WARNING:</i> In the current implementation, the functionality
--   provided in this module is tied to the vectoriser pass of GHC invoked
--   by passing the `-fvectorise` option. Without vectorisation these
--   functions will not work at all!
module Data.Array.Parallel
emptyP :: [:a:]
singletonP :: a -> [:a:]
replicateP :: Int -> a -> [:a:]
lengthP :: [:a:] -> Int
(!:) :: [:a:] -> Int -> a
(+:+) :: [:a:] -> [:a:] -> [:a:]
concatP :: [:[:a:]:] -> [:a:]
mapP :: (a -> b) -> [:a:] -> [:b:]
filterP :: (a -> Bool) -> [:a:] -> [:a:]
combineP :: [:a:] -> [:a:] -> [:Int:] -> [:a:]
zipP :: [:a:] -> [:b:] -> [:(a, b):]
unzipP :: [:(a, b):] -> ([:a:], [:b:])
zipWithP :: (a -> b -> c) -> [:a:] -> [:b:] -> [:c:]
bpermuteP :: [:a:] -> [:Int:] -> [:a:]
updateP :: [:a:] -> [:(Int, a):] -> [:a:]
indexedP :: [:a:] -> [:(Int, a):]
sliceP :: Int -> Int -> [:e:] -> [:e:]
crossMapP :: [:a:] -> (a -> [:b:]) -> [:(a, b):]
fromPArrayP :: PArray a -> [:a:]
toPArrayP :: [:a:] -> PArray a
fromNestedPArrayP :: PArray (PArray a) -> [:[:a:]:]