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


-- | An embedded language for accelerated array processing
--   
--   This library defines an embedded language for regular,
--   multi-dimensional array computations with multiple backends to
--   facilitate high-performance implementations. Currently, there are two
--   backends: (1) an interpreter that serves as a reference implementation
--   of the intended semantics of the language and (2) a CUDA backend
--   generating code for CUDA-capable NVIDIA GPUs.
--   
--   To use the CUDA backend, you need to have CUDA version 3.x installed.
--   The CUDA backend still misses some features of the full language; in
--   particular, the array operations <a>replicate</a>, <a>slice</a>, and
--   <a>foldSeg</a> are not yet supported.
--   
--   Known bugs in this version:
--   http:<i></i>trac.haskell.org<i>accelerate</i>query?status=new&amp;status=assigned&amp;status=reopened&amp;status=closed&amp;version=0.7.1.0&amp;order=priority
--   
--   <ul>
--   <li>New in 0.7.1.0: the CUDA backend and a number of scalar
--   functions</li>
--   </ul>
@package accelerate
@version 0.7.1.0


-- | This interpreter is meant to be a reference implementation of the
--   semantics of the embedded array language. The emphasis is on defining
--   the semantics clearly, not on performance.
module Data.Array.Accelerate.Interpreter

-- | Characterises the types that may be returned when running an array
--   program.
class (Delayable as) => Arrays as

-- | Run a complete embedded array program using the reference interpreter.
run :: (Arrays a) => Acc a -> a
instance (Arrays as1, Arrays as2) => Arrays (as1, as2)
instance Arrays (Array dim e)
instance Arrays ()


-- | This module defines an embedded language of array computations for
--   high-performance computing. Computations on multi-dimensional, regular
--   arrays are expressed in the form of parameterised collective
--   operations (such as maps, reductions, and permutations). These
--   computations are online compiled and executed on a range of
--   architectures.
--   
--   <i>Abstract interface</i>
--   
--   The types representing array computations are only exported abstractly
--    i.e., client code can generate array computations and submit them
--   for for execution, but it cannot inspect these computations. This is
--   to allow for more flexibility for future extensions of this library.
--   
--   <i>Code execution</i>
--   
--   Access to the various backends is via a <tt>run</tt> function in
--   backend-specific toplevel modules. Currently, we have the following:
--   
--   <ul>
--   <li><a>Data.Array.Accelerate.Interpreter</a>: simple interpreter in
--   Haskell as a reference implementation defining the semantics of the
--   Accelerate language</li>
--   </ul>
module Data.Array.Accelerate

-- | 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 Prelude.minBound and Prelude.maxBound from the
--   Prelude.Bounded class.
data Int :: *

-- | 8-bit signed integer type
data Int8 :: *

-- | 16-bit signed integer type
data Int16 :: *

-- | 32-bit signed integer type
data Int32 :: *

-- | 64-bit signed integer type
data Int64 :: *

-- | A <a>Word</a> is an unsigned integral type, with the same size as
--   <a>Int</a>.
data Word :: *

-- | 8-bit unsigned integer type
data Word8 :: *

-- | 16-bit unsigned integer type
data Word16 :: *

-- | 32-bit unsigned integer type
data Word32 :: *

-- | 64-bit unsigned integer type
data Word64 :: *

-- | Haskell type representing the C <tt>short</tt> type.
data CShort :: *

-- | Haskell type representing the C <tt>unsigned short</tt> type.
data CUShort :: *

-- | Haskell type representing the C <tt>int</tt> type.
data CInt :: *

-- | Haskell type representing the C <tt>unsigned int</tt> type.
data CUInt :: *

-- | Haskell type representing the C <tt>long</tt> type.
data CLong :: *

-- | Haskell type representing the C <tt>unsigned long</tt> type.
data CULong :: *

-- | Haskell type representing the C <tt>long long</tt> type.
data CLLong :: *

-- | Haskell type representing the C <tt>unsigned long long</tt> type.
data CULLong :: *

-- | 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 :: *

-- | 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 :: *

-- | Haskell type representing the C <tt>float</tt> type.
data CFloat :: *

-- | Haskell type representing the C <tt>double</tt> type.
data CDouble :: *
data Bool :: *
data Char :: *

-- | Haskell type representing the C <tt>char</tt> type.
data CChar :: *

-- | Haskell type representing the C <tt>signed char</tt> type.
data CSChar :: *

-- | Haskell type representing the C <tt>unsigned char</tt> type.
data CUChar :: *

-- | Multi-dimensional arrays for array processing
--   
--   <ul>
--   <li>If device and host memory are separate, arrays will be transferred
--   to the device when necessary (if possible asynchronously and in
--   parallel with other tasks) and cached on the device if sufficient
--   memory is available.</li>
--   </ul>
data Array dim e

-- | Scalars
type Scalar e = Array DIM0 e

-- | Vectors
type Vector e = Array DIM1 e

-- | Segment descriptor
type Segments = Vector Int

-- | Class that characterises the types of values that can be array
--   elements.
class (Show a, Typeable a, Typeable (ElemRepr a), Typeable (ElemRepr' a), ArrayElem (ElemRepr a), ArrayElem (ElemRepr' a)) => Elem a

-- | Shapes and indices of multi-dimensional arrays
class (Shape ix, Ix (ElemRepr ix)) => Ix ix
dim :: (Ix ix) => ix -> Int
size :: (Ix ix) => ix -> Int

-- | Identifier for entire dimensions in slice descriptors
data All
All :: All

-- | Slices -aka generalised indices- as n-tuples and mappings of slice
--   indicies to slices, co-slices, and slice dimensions
class (Shape sl, SliceIx (ElemRepr sl), Ix (Slice sl), Ix (CoSlice sl), Ix (SliceDim sl), SliceIxConv sl) => SliceIx sl where { type family Slice sl :: *; type family CoSlice sl :: *; type family SliceDim sl :: *; }
sliceIndex :: (SliceIx sl) => sl -> SliceIndex (ElemRepr sl) (Slice (ElemRepr sl)) (CoSlice (ElemRepr sl)) (SliceDim (ElemRepr sl))
type DIM0 = ()
type DIM1 = Int
type DIM2 = (Int, Int)
type DIM3 = (Int, Int, Int)
type DIM4 = (Int, Int, Int, Int)
type DIM5 = (Int, Int, Int, Int, Int)

-- | Array shape in plain Haskell code
arrayShape :: (Ix dim) => Array dim e -> dim

-- | Array indexing in plain Haskell code
indexArray :: Array dim e -> dim -> e

-- | Convert an <a>IArray</a> to an accelerated array.
fromIArray :: (IArray a e, Ix dim, Ix dim, Elem e) => a dim e -> Array dim e

-- | Convert an accelerated array to an <a>IArray</a>
toIArray :: (IArray a e, Ix dim, Ix dim, Elem e) => Array dim e -> a dim e

-- | Convert a list (with elements in row-major order) to an accelerated
--   array.
fromList :: (Ix dim, Elem e) => dim -> [e] -> Array dim e

-- | Convert an accelerated array to a list in row-major order.
toList :: Array dim e -> [e]

-- | Array-valued collective computations
data Acc a

-- | Scalar expressions used to parametrise collective array operations
data Exp t

-- | Constant scalar expression
constant :: (Elem t) => t -> Exp t

-- | Array inlet: makes an array available for processing using the
--   Accelerate language; triggers asynchronous host-&gt;device transfer if
--   necessary.
use :: (Ix dim, Elem e) => Array dim e -> Acc (Array dim e)

-- | Scalar inlet: injects a scalar (or a tuple of scalars) into a
--   singleton array for use in the Accelerate language.
unit :: (Elem e) => Exp e -> Acc (Scalar e)

-- | Change the shape of an array without altering its contents, where
--   
--   <pre>
--   precondition: size dim == size dim'
--   </pre>
reshape :: (Ix dim, Ix dim', Elem e) => Exp dim -> Acc (Array dim' e) -> Acc (Array dim e)

-- | Index an array with a *generalised* array index (supplied as the
--   second argument). The result is a new array (possibly a singleton)
--   containing all dimensions in their entirety.
slice :: (SliceIx slix, Elem e) => Acc (Array (SliceDim slix) e) -> Exp slix -> Acc (Array (Slice slix) e)

-- | Replicate an array across one or more dimensions as specified by the
--   *generalised* array index provided as the first argument.
--   
--   For example, assuming <tt>arr</tt> is a vector (one-dimensional
--   array),
--   
--   <pre>
--   replicate (2, All, 3) arr
--   </pre>
--   
--   yields a three dimensional array, where <tt>arr</tt> is replicated
--   twice across the first and three times across the third dimension.
replicate :: (SliceIx slix, Elem e) => Exp slix -> Acc (Array (Slice slix) e) -> Acc (Array (SliceDim slix) e)

-- | Combine the elements of two arrays pairwise. The shape of the result
--   is the intersection of the two argument shapes.
zip :: (Ix dim, Elem a, Elem b) => Acc (Array dim a) -> Acc (Array dim b) -> Acc (Array dim (a, b))

-- | The converse of <a>zip</a>, but the shape of the two results is
--   identical to the shape of the argument.
unzip :: (Ix dim, Elem a, Elem b) => Acc (Array dim (a, b)) -> (Acc (Array dim a), Acc (Array dim b))

-- | Apply the given function elementwise to the given array.
map :: (Ix dim, Elem a, Elem b) => (Exp a -> Exp b) -> Acc (Array dim a) -> Acc (Array dim b)

-- | Apply the given binary function elementwise to the two arrays.
zipWith :: (Ix dim, Elem a, Elem b, Elem c) => (Exp a -> Exp b -> Exp c) -> Acc (Array dim a) -> Acc (Array dim b) -> Acc (Array dim c)

-- | Prescan of a vector. The type 'a' together with the binary function
--   (first argument) and value (second argument) must form a monoid; i.e.,
--   the function must be <i>associative</i> and the value must be its
--   <i>neutral element</i>.
--   
--   The resulting vector of prescan values has the same size as the
--   argument vector. The resulting scalar is the reduction value.
scanl :: (Elem a) => (Exp a -> Exp a -> Exp a) -> Exp a -> Acc (Vector a) -> (Acc (Vector a), Acc (Scalar a))

-- | The right-to-left dual of <a>scanl</a>.
scanr :: (Elem a) => (Exp a -> Exp a -> Exp a) -> Exp a -> Acc (Vector a) -> (Acc (Vector a), Acc (Scalar a))

-- | Reduction of an array. The type <tt>a</tt> together with the binary
--   function (first argument) and value (second argument) must form a
--   monoid; i.e., the function must be <i>associative</i> and the value
--   must be its <i>neutral element</i>.
fold :: (Ix dim, Elem a) => (Exp a -> Exp a -> Exp a) -> Exp a -> Acc (Array dim a) -> Acc (Scalar a)

-- | Segmented reduction.
foldSeg :: (Elem a) => (Exp a -> Exp a -> Exp a) -> Exp a -> Acc (Vector a) -> Acc Segments -> Acc (Vector a)

-- | Forward permutation specified by an index mapping. The result array is
--   initialised with the given defaults and any further values that are
--   permuted into the result array are added to the current value using
--   the given combination function.
--   
--   The combination function must be <i>associative</i>. Elements that are
--   mapped to the magic value <a>ignore</a> by the permutation function
--   are being dropped.
permute :: (Ix dim, Ix dim', Elem a) => (Exp a -> Exp a -> Exp a) -> Acc (Array dim' a) -> (Exp dim -> Exp dim') -> Acc (Array dim a) -> Acc (Array dim' a)

-- | Backward permutation
backpermute :: (Ix dim, Ix dim', Elem a) => Exp dim' -> (Exp dim' -> Exp dim) -> Acc (Array dim a) -> Acc (Array dim' a)
class Tuple tup where { type family TupleT tup; }
tuple :: (Tuple tup) => tup -> TupleT tup
untuple :: (Tuple tup) => TupleT tup -> tup

-- | Extract the first component of a pair
fst :: (Elem a, Elem b) => Exp (a, b) -> Exp a

-- | Extract the second component of a pair
snd :: (Elem a, Elem b) => Exp (a, b) -> Exp b

-- | Converts an uncurried function to a curried function
curry :: (Elem a, Elem b) => (Exp (a, b) -> Exp c) -> Exp a -> Exp b -> Exp c

-- | Converts a curried function to a function on pairs
uncurry :: (Elem a, Elem b) => (Exp a -> Exp b -> Exp c) -> Exp (a, b) -> Exp c

-- | Conditional expression.
(?) :: (Elem t) => Exp Bool -> (Exp t, Exp t) -> Exp t

-- | Expression form that extracts a scalar from an array.
(!) :: (Ix dim, Elem e) => Acc (Array dim e) -> Exp dim -> Exp e
shape :: (Ix dim, Elem dim) => Acc (Array dim e) -> Exp dim

-- | Equality lifted into Accelerate expressions.
(==*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp Bool

-- | Inequality lifted into Accelerate expressions.
(/=*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp Bool

-- | Smaller-than lifted into Accelerate expressions.
(<*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp Bool

-- | Smaller-or-equal lifted into Accelerate expressions.
(<=*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp Bool

-- | Greater-than lifted into Accelerate expressions.
(>*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp Bool

-- | Greater-or-equal lifted into Accelerate expressions.
(>=*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp Bool

-- | Determine the maximum of two scalars.
max :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp t

-- | Determine the minimum of two scalars.
min :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp t
bit :: (Elem t, IsIntegral t) => Exp Int -> Exp t
setBit :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp t
clearBit :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp t
complementBit :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp t
testBit :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp Bool
shift :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp t
shiftL :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp t
shiftR :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp t
rotate :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp t
rotateL :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp t
rotateR :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp t

-- | Conjunction
(&&*) :: Exp Bool -> Exp Bool -> Exp Bool

-- | Disjunction
(||*) :: Exp Bool -> Exp Bool -> Exp Bool

-- | Negation
not :: Exp Bool -> Exp Bool

-- | Convert a Boolean value to an <a>Int</a>, where <a>False</a> turns
--   into '0' and <a>True</a> into '1'.
boolToInt :: Exp Bool -> Exp Int

-- | Convert an Int to a Float
intToFloat :: Exp Int -> Exp Float

-- | Round Float to Int
roundFloatToInt :: Exp Float -> Exp Int

-- | Truncate Float to Int
truncateFloatToInt :: Exp Float -> Exp Int

-- | Magic value identifying elements that are ignored in a forward
--   permutation
ignore :: (Ix dim) => Exp dim