Permalink
Browse files

Improve Haddock documentation

Ignore-this: d89fdb32a9e14959f253034bb06de207

darcs-hash:20091003122954-6295e-a854646083d9cb01e4553c98a2f068c2e56f9795.gz
  • Loading branch information...
1 parent 483dd93 commit 16ee3169c1dab257e7e88d8ac705730ac2672073 @mchakravarty mchakravarty committed Oct 3, 2009
View
@@ -1,24 +1,32 @@
--- |An embedded language of accelerated array computations
+-- |
+-- Module : Data.Array.Accelerate
+-- Copyright : [2008..2009] Manuel M T Chakravarty, Gabriele Keller, Sean Lee
+-- License : BSD3
--
--- Copyright (c) [2008..2009] Manuel M T Chakravarty, Gabriele Keller, Sean Lee
+-- Maintainer : Manuel M T Chakravarty <chak@cse.unsw.edu.au>
+-- Stability : experimental
+-- Portability : non-portable (GHC extensions)
--
--- License: BSD3
+-- 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.
--
---- Description ---------------------------------------------------------------
+-- /Abstract interface/
--
--- Abstract interface
--- ~~~~~~~~~~~~~~~~~~
--- The types representing array computations are only exported abstractly.
--- This gives us more flexibility for later changes.
+-- 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.
--
--- Code execution
--- ~~~~~~~~~~~~~~
--- Access to the various backends is via the 'run' function in
--- backend-specific toplevel modules. Currently, we have the following:
+-- /Code execution/
--
--- * 'Data.Array.Accelerate.Interpreter': simple interpreter in Haskell as a
--- reference implementation defining the semantics of the array language
-
+-- Access to the various backends is via a 'run' function in
+-- backend-specific toplevel modules. Currently, we have the following:
+--
+-- * "Data.Array.Accelerate.Interpreter": simple interpreter in Haskell as a
+-- reference implementation defining the semantics of the Accelerate language
module Data.Array.Accelerate (
@@ -37,10 +45,10 @@ module Data.Array.Accelerate (
-- * Array shapes & indices
Ix(dim, size), All(..), SliceIx(..), DIM0, DIM1, DIM2, DIM3, DIM4, DIM5,
- -- * Array operations
+ -- * Operations to use Accelerate arrays from plain Haskell
arrayShape, indexArray, fromIArray, toIArray, fromList, toList,
- -- * Surface language
+ -- * The /Accelerate/ language
module Data.Array.Accelerate.Language,
) where
@@ -56,9 +64,15 @@ import Data.Array.Accelerate.Language
--
-- rename as '(!)' is already used by the EDSL for indexing
+
+-- |Array indexing in plain Haskell code
+--
indexArray :: Array dim e -> dim -> e
indexArray = (Sugar.!)
-- rename as 'shape' is already used by the EDSL to query an array's shape
+
+-- |Array shape in plain Haskell code
+--
arrayShape :: Ix dim => Array dim e -> dim
arrayShape = Sugar.shape
@@ -128,13 +128,15 @@ type instance ElemRepr' (a, b, c, d) = (ElemRepr (a, b, c), ElemRepr' d)
type instance ElemRepr' (a, b, c, d, e) = (ElemRepr (a, b, c, d), ElemRepr' e)
--- |Surface types (tuples of scalars)
+-- Array elements (tuples of scalars)
-- ----------------------------------
-- |Identifier for entire dimensions in slice descriptors
--
data All = All deriving (Typeable, Show)
+-- |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))
@@ -520,8 +522,8 @@ sinkFromElem2 f = \x y -> fromElem $ f (toElem x) (toElem y)
#-}
--- |Surface arrays
--- ---------------
+-- Surface arrays
+-- --------------
-- |Multi-dimensional arrays for array processing
--
@@ -547,7 +549,7 @@ type Vector e = Array DIM1 e
--
type Segments = Vector Int
--- |Shorthand for common shape types
+-- Shorthand for common shape types
--
type DIM0 = ()
type DIM1 = (Int)
@@ -556,10 +558,10 @@ type DIM3 = (Int, Int, Int)
type DIM4 = (Int, Int, Int, Int)
type DIM5 = (Int, Int, Int, Int, Int)
--- |Shape constraints and indexing
--- -
+-- Shape constraints and indexing
+--
--- |Shape elements
+-- Shape elements
--
class Elem shb => ShapeBase shb
instance ShapeBase Int
@@ -593,26 +595,33 @@ type instance FromShapeRepr ((((((), a), b), c), d), e)
= (FromShapeBase a, FromShapeBase b, FromShapeBase c, FromShapeBase d,
FromShapeBase e)
--- |Indices as n-tuples
+-- |Shapes and indices of multi-dimensional arrays
--
class (Shape ix, Repr.Ix (ElemRepr ix)) => Ix ix where
- dim :: ix -> Int -- number of dimensions (>= 0)
- size :: ix -> Int -- for a *shape* yield the total number of
- -- elements in that array
- ignore :: ix -- identifies ignored elements in 'permute'
- index :: ix -> ix -> Int -- corresponding index into a linear, row-major
- -- representation of the array (first argument
- -- is the shape)
+ -- |Number of dimensions of a /shape/ or /index/ (>= 0)
+ dim :: ix -> Int
+
+ -- Total number of elements in an array of the given /shape/
+ size :: ix -> Int
+
+ -- |Magic value identifing elements ignored in 'permute'
+ ignore :: ix
+
+ -- |Map a multi-dimensional index into one in a linear, row-major
+ -- representation of the array (first argument is the /shape/, second
+ -- argument is the index)
+ index :: ix -> ix -> Int
+
+ -- |Iterate through the entire shape, applying the function; third argument
+ -- combines results and fourth is returned in case of an empty iteration
+ -- space; the index space is traversed in row-major order
iter :: ix -> (ix -> a) -> (a -> a -> a) -> a -> a
- -- iterate through the entire shape, applying
- -- the function; third argument combines results
- -- and fourth is returned in case of an empty
- -- iteration space; the index space is traversed
- -- in row-major order
-
- rangeToShape :: (ix, ix) -> ix -- convert a minpoint-maxpoint index
- -- into a shape
+
+ -- |Convert a minpoint-maxpoint index into a /shape/
+ rangeToShape :: (ix, ix) -> ix
+
+ -- |Convert a /shape/ into a minpoint-maxpoint index
shapeToRange :: ix -> (ix, ix)
dim = Repr.dim . fromElem
@@ -636,7 +645,8 @@ instance Ix (Int, Int, Int)
instance Ix (Int, Int, Int, Int)
instance Ix (Int, Int, Int, Int, Int)
--- Slices -aka generalised indices- as n-tuples
+-- |Slices -aka generalised indices- as n-tuples and mappings of slice
+-- indicies to slices, co-slices, and slice dimensions
--
class (Shape sl,
Repr.SliceIx (ElemRepr sl),
@@ -1,17 +1,17 @@
{-# LANGUAGE GADTs, BangPatterns, PatternGuards #-}
{-# LANGUAGE TypeFamilies, ScopedTypeVariables, FlexibleContexts #-}
-
--- |Embedded array processing language: execution by a simple interpreter
---
--- Copyright (c) [2008..2009] Manuel M T Chakravarty, Gabriele Keller, Sean Lee
---
--- License: BSD3
+-- |
+-- Module : Data.Array.Accelerate.Interpreter
+-- Copyright : [2008..2009] Manuel M T Chakravarty, Gabriele Keller, Sean Lee
+-- License : BSD3
--
---- Description ---------------------------------------------------------------
+-- Maintainer : Manuel M T Chakravarty <chak@cse.unsw.edu.au>
+-- Stability : experimental
+-- Portability : non-portable (GHC extensions)
--
--- 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.
+-- 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 (
@@ -33,6 +33,7 @@ import Data.Array.Accelerate.Array.Sugar (
Array(..), Scalar, Vector, Segments)
import Data.Array.Accelerate.Array.Delayed
import Data.Array.Accelerate.AST
+import Data.Array.Accelerate.Tuple
import qualified Data.Array.Accelerate.Smart as Sugar
import qualified Data.Array.Accelerate.Array.Sugar as Sugar
@@ -225,13 +226,29 @@ foldOp f e (DelayedArray sh rf)
= unitOp $
Sugar.toElem (iter sh rf (Sugar.sinkFromElem2 f) (Sugar.fromElem e))
-foldSegOp :: (e -> e -> e)
+foldSegOp :: forall e.
+ (e -> e -> e)
-> e
-> Delayed (Vector e)
-> Delayed Segments
-> Delayed (Vector e)
-foldSegOp f e (DelayedArray sh rf) (DelayedArray shSeg rfSeg)
- = error "Data.Array.Accelerate.Interpreter: foldSegOp not yet implemented"
+foldSegOp f e (DelayedArray _sh rf) seg@(DelayedArray shSeg rfSeg)
+ = delay arr
+ where
+ DelayedPair (DelayedArray _shSeg rfStarts) _ = scanOp (+) 0 seg
+ arr = Sugar.newArray (Sugar.toElem shSeg) foldOne
+ --
+ foldOne :: Sugar.DIM1 -> e
+ foldOne i = let
+ start = (Sugar.liftToElem rfStarts) i
+ len = (Sugar.liftToElem rfSeg) i
+ in
+ fold e start (start + len)
+ --
+ fold :: e -> Sugar.DIM1 -> Sugar.DIM1 -> e
+ fold v j end
+ | j >= end = v
+ | otherwise = fold (f v ((Sugar.liftToElem rf) j)) (j + 1) end
scanOp :: (e -> e -> e)
-> e
@@ -409,9 +426,9 @@ evalPrim PrimBoolToInt = evalBoolToInt
-- ---------------------------------
evalTuple :: Tuple (OpenExp env aenv) t -> Val env -> Val aenv -> t
-evalTuple NilTup env aenv = ()
-evalTuple (tup `SnocTup` e) env aenv = (evalTuple tup env aenv,
- evalOpenExp e env aenv)
+evalTuple NilTup _env _aenv = ()
+evalTuple (tup `SnocTup` e) env aenv = (evalTuple tup env aenv,
+ evalOpenExp e env aenv)
evalPrj :: TupleIdx t e -> t -> e
evalPrj ZeroTupIdx (!_, v) = v
Oops, something went wrong.

0 comments on commit 16ee316

Please sign in to comment.