dph-lifted-vseg: cleanup and fix haddocs
authorBen Lippmeier <benl@ouroborus.net>
Thu, 10 Nov 2011 03:42:38 +0000 (14:42 +1100)
committerBen Lippmeier <benl@ouroborus.net>
Fri, 11 Nov 2011 01:44:22 +0000 (12:44 +1100)
23 files changed:
dph-lifted-vseg/Data/Array/Parallel.hs
dph-lifted-vseg/Data/Array/Parallel/Lifted/Closure.hs
dph-lifted-vseg/Data/Array/Parallel/Lifted/Combinators.hs
dph-lifted-vseg/Data/Array/Parallel/PArr.hs
dph-lifted-vseg/Data/Array/Parallel/PArray.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PData.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PData/Base.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PData/Double.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PData/Int.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PData/Nested.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PData/Sum2.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PData/Tuple.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PData/Unit.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PData/Void.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PData/Word8.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PData/Wrap.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PRepr.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PRepr/Base.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PRepr/Instances.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PRepr/Nested.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/PRepr/Tuple.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/Reference.hs
dph-lifted-vseg/Data/Array/Parallel/PArray/Scalar.hs

index 484b01e..fdad621 100644 (file)
@@ -1,13 +1,19 @@
 {-# LANGUAGE ParallelArrays #-}
 {-# OPTIONS_GHC -fvectorise #-}
 
--- | User level interface of parallel arrays.
+-- | User level interface to vectorised parallel arrays.
+--
+--  /WARNING:/ In the current implementation, the functionality provided in
+--  this module is tied to the vectoriser pass of GHC, invoked by `-fvectorise`.
+--  These functions will not work at all in unvectorised code. To operate on
+--  parallel arrays in unvectorised code, use the functions in
+--  "Data.Array.Parallel.PArray" and convert between array representations by
+--  using `fromPArrayP` and `toPArrayP` from /vectorised/ code.
 --
 --  The semantic difference between standard Haskell arrays (aka "lazy
 --  arrays") and parallel arrays (aka "strict arrays") 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
 --  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: `iterate', `repeat', and `cycle'.
--- 
---  /WARNING:/ 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!
 --
 --  UGLY HACK ALERT: Same ugly hack as in 'base:GHC.PArr'!  We could do without in this module by
 --                   using the type synonym 'PArr' instead of '[::]', but that would lead to
@@ -69,7 +70,7 @@ import Data.Array.Parallel.PArr
 import Data.Array.Parallel.Prelude
 import Data.Array.Parallel.Prelude.Int
 import Data.Array.Parallel.Lifted
-import Data.Array.Parallel.PArray               (PArray(..))
+import Data.Array.Parallel.PArray.PData.Base    (PArray(..))
 import Prelude hiding (Int)
 
 
@@ -95,18 +96,21 @@ import Prelude hiding (Int)
 --
 
 -- Conversions ----------------------------------------------------------------
+-- | O(1). Convert between `PArray` and [::] array representations.
 fromPArrayP :: PArray a -> [:a:]
 fromPArrayP !_  = emptyP
 {-# NOINLINE  fromPArrayP #-}
 {-# VECTORISE fromPArrayP = fromPArrayPP #-}
 
 
+-- | O(1). Convert between `PArray` and [::] array representations.
 toPArrayP :: [:a:] -> PArray a
 toPArrayP !_    = PArray 0# (error "toPArrayP: unvectorised")
 {-# NOINLINE  toPArrayP #-}
 {-# VECTORISE toPArrayP = toPArrayPP #-}
 
 
+-- | O(1). Convert between `PArray` and [::] array representations.
 fromNestedPArrayP :: PArray (PArray a) -> [:[:a:]:]
 fromNestedPArrayP !_ = emptyP
 {-# NOINLINE  fromNestedPArrayP #-}
@@ -193,6 +197,7 @@ zipWithP !_ !_ !_       = emptyP
 
 
 -- Filtering -----------------------------------------------------------------
+-- | Filter an array, keeping only those elements that match the given predicate.
 filterP :: (a -> Bool) -> [:a:] -> [:a:]
 filterP !_ !_   = emptyP
 {-# NOINLINE  filterP #-}
index af6e64d..9a8b335 100644 (file)
@@ -1,7 +1,7 @@
 #include "fusion-phases.h"
 
--- | Closures
----  Used when closure converting the source program during vectorisation.
+-- | Closures.
+--   Used when closure converting the source program during vectorisation.
 module Data.Array.Parallel.Lifted.Closure 
         ( -- * Closures.
           (:->)(..)
index ecfa3a3..5f9a731 100644 (file)
@@ -4,9 +4,10 @@
 -- | Closure converted lifted array combinators.
 --   The vectoriser produces code that uses these combinators directly.
 -- 
---   All of the combinators in this module are polymorphic, work on PArrays, and
---   take PA dictionaries. Combinators that are specific to a certain element type,
---   like Int, are defined in the corresponding prelude module, eg D.A.P.Prelude.Int.
+--   All of the combinators in this module are polymorphic, work on `PArray`, and
+--   take `PA` dictionaries. Combinators that are specific to a certain element type,
+--   like `Int`, are defined in the corresponding prelude module, 
+--   eg "Data.Array.Parallel.Prelude.Int".
 --
 module Data.Array.Parallel.Lifted.Combinators 
         ( -- * Conversions
@@ -86,19 +87,19 @@ fromNestedPArrayPP = closure1 (\xs -> xs) (\_ xss -> xss)
 
 
 -- Constructors ---------------------------------------------------------------
--- | O(1). An empty array.
+-- | O(1). Construct an empty array.
 emptyPP :: PA a => PArray a
 emptyPP         = PA.empty
 {-# INLINE_PA emptyPP #-}
 
 
--- | O(1). Produce an array containing a single element.
+-- | O(1). Construct an array containing a single element.
 singletonPP :: PA a => a :-> PArray a
 singletonPP     = closure1' PA.singleton PA.singletonl
 {-# INLINE_PA singletonPP #-}
 
 
--- | O(n). Define an array of the given size, that maps all elements to the same value.
+-- | O(n). Construct an array of the given size, that maps all elements to the same value.
 replicatePP     :: PA a => Int :-> a :-> PArray a
 replicatePP     = closure2' PA.replicate PA.replicatel
 {-# INLINE_PA replicatePP #-}
@@ -110,7 +111,7 @@ appendPP        = closure2' PA.append PA.appendl
 {-# INLINE_PA appendPP #-}
 
 
--- | O(len result). Concatenate some arrays.
+-- | O(len result). Concatenate a nested array.
 concatPP :: PA a => PArray (PArray a) :-> PArray a
 concatPP        = closure1' PA.concat PA.concatl
 {-# INLINE_PA concatPP #-}
index d95e8a6..d6b0541 100644 (file)
@@ -1,7 +1,6 @@
 {-# OPTIONS_GHC -funbox-strict-fields #-}
 {-# OPTIONS_HADDOCK hide #-}
 
--- #hide
 -- | Unvectorised functions that work directly on parallel arrays of [::] type.
 --   These are used internally in the DPH library, but the user never sees them.
 --   Only vectorised functions are visible in the DPH client programs.
index 458371f..a41ca07 100644 (file)
@@ -1,17 +1,18 @@
 {-# OPTIONS -fno-spec-constr #-}
 #include "fusion-phases.h"
 
--- | Operators that work directly on PArrays.
-
---   * These operators are used by the D.A.P.Lifted.Combinator module to
---     define the closures that the vectoriser uses.
+-- | Unvectorised parallel arrays.
+--
+--   * These operators may be used directly by unvectorised client programs.
 --
---   * They also may also be used directly by user programs.
+--   * They are also used by the "Data.Array.Parallel.Lifted.Combinators"
+--     module to define the closure converted versions that vectorised code
+--     uses.
 --
---   * In general, the operators are all unsafe and don't do bounds checks.
+--   * In general, the operators here are all unsafe and don't do bounds checks.
 --     The lifted versions also don't check that each of the argument arrays
 --     have the same length.
---
+
 --   TODO:
 --   Export unsafe versions from Data.Array.Parallel.PArray.Unsafe, and ensure
 --   this module exports safe wrappers. We want to use the unsafe versions in
@@ -21,7 +22,7 @@
 --   the user may not obey this restriction.
 -- 
 module Data.Array.Parallel.PArray 
-        ( PArray(..), PA
+        ( PArray, PA
         , valid
         , nf
 
@@ -50,8 +51,8 @@ module Data.Array.Parallel.PArray
         , enumFromTo,   enumFromTol     -- from D.A.P.PArray.Scalar
 
         -- * Tuples
-        , zip,          zipl            -- from D.A.P.PArray.Tuple
-        , unzip,        unzipl          -- from D.A.P.PArray.Tuple
+        , zip,          zipl
+        , unzip,        unzipl
 
         -- * Conversions
         , fromVector,   toVector
@@ -80,7 +81,7 @@ import Prelude hiding
 
 
 -- Pretty ---------------------------------------------------------------------
-instance PA a => PprPhysical (PArray a) where
+instance PA a => T.PprPhysical (PArray a) where
  pprp (PArray n# pdata)
         =     ( T.text "PArray " T.<+> T.int (I# n#))
         T.$+$ ( T.nest 4 
@@ -88,7 +89,7 @@ instance PA a => PprPhysical (PArray a) where
 
 
 -- Array -----------------------------------------------------------------------
--- | Generic interface to PArrays.
+--  Generic interface to PArrays.
 --
 --  NOTE: 
 --  The toVector conversion is defined by looking up every index instead of
@@ -351,7 +352,7 @@ slicel (PArray n# sliceStarts) (PArray _ sliceLens) (PArray _ darr)
 --   plain Segd. This is unsafe because it can cause index space overflow.
 unsafeTakeSegd :: PArray (PArray a) -> U.Segd
 unsafeTakeSegd (PArray _ pdata)
-        = unsafeTakeSegdPD pdata
+        = takeSegdPD pdata
 {-# INLINE_PA unsafeTakeSegd #-}
 
 
@@ -419,6 +420,38 @@ combine2 sel arr1@(PArray _ darr1) arr2@(PArray _ darr2)
 {-# INLINE_PA combine2 #-}
 
 
+-- Tuples ---------------------------------------------------------------------
+
+-- | O(1). Zip a pair of arrays into an array of pairs.
+--   The two arrays must have the same length, else `error`. 
+zip :: PArray a -> PArray b -> PArray (a, b)
+zip (PArray n# pdata1) (PArray _ pdata2)
+        = PArray n# $ zipPD pdata1 pdata2
+{-# INLINE_PA zip #-}
+
+
+-- | Lifted zip.
+zipl    :: (PA a, PA b)
+        => PArray (PArray a) -> PArray (PArray b) -> PArray (PArray (a, b))
+zipl (PArray n# xs) (PArray _ ys)
+        = PArray n# $ ziplPA xs ys
+
+
+-- | O(1). Unzip an array of pairs into a pair of arrays.
+unzip :: PArray (a, b) -> (PArray a, PArray b)
+unzip (PArray n# (PTuple2 xs ys))
+        = (PArray n# xs, PArray n# ys)
+{-# INLINE_PA unzip #-}
+
+
+-- | Lifted unzip
+unzipl :: PArray (PArray (a, b)) -> PArray (PArray a, PArray b)
+unzipl (PArray n# pdata)
+        = PArray n# $ unziplPD pdata
+
+
+
+
 -- Conversions ----------------------------------------------------------------
 -- | Convert a `Vector` to a `PArray`
 fromVector :: PA a => Vector a -> PArray a
index cdd2248..c323ccf 100644 (file)
@@ -1,14 +1,26 @@
 
--- | Parallel array types and operators that work on them.
+-- | Parallel array data.
+--
+--   This is an interface onto the internal array types and operators defined
+--   by the library, and should not normally be used by client programs.
 module Data.Array.Parallel.PArray.PData 
-        ( module Data.Array.Parallel.PArray.PData.Base
-        , module Data.Array.Parallel.PArray.PData.Wrap
-        , module Data.Array.Parallel.PArray.PData.Nested
-        , module Data.Array.Parallel.PArray.PData.Tuple
+        (
+        -- * Parallel array types
+          PArray (..), PData(..), PDatas(..)
+        , length, takeData
+        
+        -- * PR (Parallel Representation)
+        , PR (..)        
+
+        -- * Extra conversions
         , fromListPR
         , toListPR
-        , mapdPR
-        , zipWithdPR)
+
+        -- * Nested arrays
+        , module Data.Array.Parallel.PArray.PData.Nested
+
+        -- * Tuple arrays
+        , module Data.Array.Parallel.PArray.PData.Tuple)
 where
 import Data.Array.Parallel.PArray.PData.Base
 import Data.Array.Parallel.PArray.PData.Wrap
@@ -22,6 +34,7 @@ import Data.Array.Parallel.PArray.PData.Double          ()
 import Data.Array.Parallel.PArray.PData.Sum2            ()
 import Data.Array.Parallel.PArray.PRepr.Instances       ()
 import qualified Data.Vector                            as V
+import Prelude hiding (length)
 
 
 -- | Convert a list to a PData.
@@ -33,22 +46,3 @@ fromListPR      = fromVectorPR . V.fromList
 toListPR :: PR a => PData a -> [a]
 toListPR        = V.toList . toVectorPR
 
-
--- | Apply a worked function to all PData in a collection.
-mapdPR  :: (PR a, PR b)
-        => (PData a -> PData b)
-        -> PDatas a -> PDatas b
-mapdPR f pdatas
-        = fromVectordPR $ V.map f (toVectordPR pdatas)
-
-
--- | Combine all PData in a collection with an operator.
-zipWithdPR
-        :: (PR a, PR b, PR c)
-        => (PData a -> PData b  -> PData c)
-        -> PDatas a -> PDatas b -> PDatas c
-zipWithdPR f pdatas1 pdatas2
-        = fromVectordPR $ V.zipWith f 
-                (toVectordPR pdatas1)
-                (toVectordPR pdatas2)
-
index a0e54f8..b6765e1 100644 (file)
@@ -1,3 +1,4 @@
+{-# OPTIONS_HADDOCK hide #-}
 {-# LANGUAGE UndecidableInstances, ParallelListComp #-}
 -- Undeciable instances only need for derived Show instance
 
@@ -9,7 +10,6 @@ module Data.Array.Parallel.PArray.PData.Base
         ( -- * Parallel Array types.
           PArray(..)
         , length, takeData
-        , PprPhysical (..), PprVirtual (..)
 
         , PR (..)
         , PData(..), PDatas(..))
@@ -24,14 +24,8 @@ import qualified Data.Vector                    as V
 import Prelude hiding (length)
 
 -- PArray ---------------------------------------------------------------------
--- | A parallel array. 
---   A PArray has a finite length. In contrast, an array of type PData Void
---   is "defined everywhere" and has no notion of length.
---
---   A PArray is the 'user view' of the data, where the elements have the same
---   type as in the source program. In contrast, a PData array is the 'library'
---   view, where the element have been converted to our generic representation.
---
+-- | A parallel array consisting of a length field and some array data.
+
 --   IMPORTANT: 
 --   The vectoriser requires the PArray data constructor to have this specific
 --   form, because it builds them explicitly. Specifically, the array length
@@ -43,22 +37,37 @@ import Prelude hiding (length)
 data PArray a
         = PArray Int# (PData  a)
 
--- | Take the length of an array
+-- | Take the length field of a `PArray`.
 {-# INLINE_PA length #-}
 length :: PArray a -> Int
 length (PArray n# _)   = (I# n#)
 
 
--- | Take the data from an array.
+-- | Take the `PData` of a `PArray`.
 {-# INLINE_PA takeData #-}
 takeData :: PArray a -> PData a
 takeData (PArray _ d)   = d
 
 
 -- Parallel array data --------------------------------------------------------
-{-# ANN type PData NoSpecConstr #-}
+-- | A chunk of parallel array data with a linear index space.
+-- 
+--   In contrast to a `PArray`, a `PData` may not have a fixed length, and its
+--   elements may have been converted to a generic representation. Whereas a
+--   `PArray` is the \"user view\" of an array, a `PData` is a type only
+--   used internally to the library.
+
+--   An example of an array with no length is PData Void. We can index this
+--   at an arbitrary position, and always get a 'void' element back.
+--
 data family PData a
+{-# ANN type PData NoSpecConstr #-}
 
+-- | Several chunks of parallel array data.
+--
+--   Although a `PArray` of atomic type such as `Int` only contains a
+--   single `PData` chunk, nested arrays may contain several, which we 
+--   wrap up into a `PDatas`.
 {-# ANN type PDatas NoSpecConstr #-}
 data family PDatas a
 
@@ -72,38 +81,45 @@ data instance PDatas Int
 
 
 -- PR -------------------------------------------------------------------------
--- | The PR class holds primitive array operators that work on our generic
---   representation of data.
+-- | The PR (Parallel Representation) class holds primitive array operators that
+--   work on our generic representation of data.
+--
+--   There are instances for all atomic types such  as `Int` and `Double`, tuples,
+--   nested arrays `PData (PArray a)` and for the  generic types we used to represent
+--   user level algebraic data, `Sum2` and `Wrap` and `Void`. All array data 
+--   is converted to this fixed set of types.
 class PR a where
 
   -- House Keeping ------------------------------
   --  These methods are helpful for debugging, but we don't want their
   --  associated type classes as superclasses of PR.
 
-  -- | Check that an array has a well formed representation.
-  --   This should only return False where there is a bug in the library.
+  -- | (debugging) Check that an array has a well formed representation.
+  --   This should only return `False` where there is a bug in the library.
   validPR       :: PData a -> Bool
 
-  -- | Ensure there are no thunks in the representation of a manifest array.
+  -- | (debugging) Ensure an array is fully evaluted.
   nfPR          :: PData a -> ()
 
-  -- | Weak equality of contained elements.
-  --   Returns True for functions of the same type.  
-  --   In the case of nested arrays, this ignores the physical representation,
-  --   that is, it doesn't care about the exact form of segment descriptors.
+  -- | (debugging) Weak equality of contained elements.
+  --
+  --   Returns `True` for functions of the same type. In the case of nested arrays,
+  --   returns `True` if the array defines the same set of elements, but does not
+  --   care about the exact form of the segement descriptors.
   similarPR     :: a -> a -> Bool
 
-  -- | Check that an index is within this array.
-  --   The (PData Void) arrays don't have a real length, but we still want to
-  --   to check that indices are in-range during testing.
-  --   If the array has a hard length, and the flag is True, then we allow
-  --   the index to be equal to this length.
+  -- | (debugging) Check that an index is within an array.
+  -- 
+  --   Arrays containing `Void` elements don't have a fixed length, and return 
+  --   `Void` for all indices. If the array does have a fixed length, and the 
+  --   flag is true, then we allow the index to be equal to this length, as
+  --   well as less than it.
   coversPR      :: Bool -> PData a -> Int   -> Bool
 
-  -- | Pretty print the physical representation of an element.
+  -- | (debugging) Pretty print the physical representation of an element.
   pprpPR        :: a       -> Doc
 
-  -- | Pretty print the physical representation of this array.
+  -- | (debugging) Pretty print the physical representation of some array data.
   pprpDataPR    :: PData a -> Doc
 
 
@@ -111,74 +127,85 @@ class PR a where
   -- | Produce an empty array with size zero.
   emptyPR       :: PData a
 
-  -- | Define an array of the given size, that maps all elements to the same value.
-  --   We require the replication count to be > 0 so that it's easier to maintain
-  --   the validPR invariants for nested arrays.
-  --   O(n). 
-  replicatePR   :: Int          -- ^ length of result array. Must be > 0.
-                -> a            -- ^ element to replicate.
-                -> PData a
+  -- | O(n). Define an array of the given size, that maps all elements to the
+  --  same value.
+  -- 
+  --   We require the replication count to be > 0 so that it's easier to
+  --   maintain the `validPR` invariants for nested arrays.
+  replicatePR   :: Int -> a -> PData a
 
   -- | O(sum lengths). Segmented replicate.
-  --   TODO: This takes a whole Segd instead of just the lengths, because we could
-  --         do it more efficiently if we knew there were no zero lengths.
-  replicatesPR  :: U.Segd               -- ^ segment descriptor defining the lengths of the segments.
-                -> PData a              -- ^ data elements to replicate
-                -> PData a
-
-  -- | Append two sized arrays.
+  --   
+  --   Given a Segment Descriptor (Segd), replicate each each element in the
+  --   array according to the length of the corrsponding segment.
+  --   The array data must define at least as many elements as there are segments
+  --   in the descriptor.
+
+  --   TODO: This takes a whole Segd instead of just the lengths. If the Segd knew
+  --         that there were no zero length segments then we could implement this
+  --         more efficiently in the nested case case. If there are no zeros, then
+  --         all psegs in the result are reachable from the vsegs, and we wouldn't
+  --         need to pack them after the replicate.
+  --         
+  replicatesPR  :: U.Segd -> PData a -> PData a
+
+  -- | Append two arrays.
   appendPR      :: PData a -> PData a -> PData a
 
-  -- | Segmented append
-  appendsPR     :: U.Segd               -- ^ segd of result
-                -> U.Segd -> PData a    -- ^ segd/data of first  arrays
-                -> U.Segd -> PData a    -- ^ segd/data of second arrays
+  -- | Segmented append.
+  --
+  --   The first descriptor defines the segmentation of the result, 
+  --   and the others define the segmentation of each source array.
+  appendsPR     :: U.Segd
+                -> U.Segd -> PData a
+                -> U.Segd -> PData a
                 -> PData a
 
 
   -- Projections --------------------------------
   -- | O(1). Get the length of an array, if it has one.
-  --   A (PData Void) array has no length, so this returns `error` in that case.
-  --   To check array bounds, use coversPR instead, as that's a total function.
+  --  
+  --   Applying this function to an array of `Void` will yield `error`, as
+  --   these arrays have no fixed length. To check array bounds, use the
+  --   `coversPR` method instead, as that is a total function.
   lengthPR      :: PData a -> Int
   
-  -- | O(1). Lookup a single element from the source array.
+  -- | O(1). Retrieve a single element from a single array.
   indexPR       :: PData a -> Int -> a
 
-  -- | Lookup several elements from several source arrays
-  indexlPR      :: PData (PArray a)
-                -> PData Int
-                -> PData a
-
-  -- | O(n). Extract a range of elements from an array.
-  extractPR     :: PData a 
-                -> Int                  -- ^ starting index
-                -> Int                  -- ^ length of slice
-                -> PData a
+  -- | O(1). Lifted indexing. 
+  --  Retrieve a single element from each of several ararys.
+  indexlPR      :: PData (PArray a) -> PData Int -> PData a
 
-  -- | O(sum seglens). Segmented extract.
-  extractsPR    :: PDatas a
-                -> U.SSegd              -- ^ segment descriptor describing scattering of data.
-                -> PData a
+  -- | O(len indices) Backwards permutation.
+  --   Retrieve several elements from a single array.
+  bpermutePR    :: PData a -> U.Array Int -> PData a
 
-  -- | Backwards permutation
-  bpermutePR    :: PData a              -- ^ source array
-                -> U.Array Int          -- ^ source indices
-                -> PData a
+  -- | O(slice len). Extract a slice of elements from an array, given the starting
+  --  index and length of the slice.
+  extractPR     :: PData a -> Int -> Int -> PData a
 
+  -- | O(sum seglens). Segmented extract. Extract several slices from several
+  --  source arrays.
+  --  
+  --  The Scattered Segment Descriptor (`SSegd`) describes where to get each 
+  --  slice, and all slices are concatenated together into the result.
+  extractsPR    :: PDatas a -> U.SSegd -> PData a
+  
 
   -- Pack and Combine ---------------------------
-  -- | Filter an array based on some tags.
-  packByTagPR   :: PData a              -- ^ source array
-                -> U.Array Tag          -- ^ array of tags
-                -> Tag                  -- ^ tag of elements to select
-                -> PData a
+  -- | Select elements of an array that have their corresponding tag set to
+  --   the given value. 
+  --
+  --   The data array must define at least as many elements as the length
+  --   of the tags array. 
+  packByTagPR   :: PData a -> U.Array Tag -> Tag -> PData a
 
   -- | Combine two arrays based on a selector.
-  combine2PR    :: U.Sel2               -- ^ selector
-                -> PData a              -- ^ first source array
-                -> PData a              -- ^ second source array
-                -> PData a
+  -- 
+  --   See the documentation for selectors in the dph-prim-seq library
+  --   for how this works.
+  combine2PR    :: U.Sel2 -> PData a -> PData a -> PData a
 
 
   -- Conversions --------------------------------
@@ -190,28 +217,28 @@ class PR a where
 
 
   -- PDatas -------------------------------------
-  -- | O(1). Yield an empty collection of PData.
+  -- | O(1). Yield an empty collection of `PData`.
   emptydPR      :: PDatas a
 
-  -- | O(1). Yield a singleton collection of PData.
+  -- | O(1). Yield a singleton collection of `PData`.
   singletondPR  :: PData a  -> PDatas a
 
-  -- | O(1). Yield how many PData are in the collection.
+  -- | O(1). Yield how many `PData` are in the collection.
   lengthdPR     :: PDatas a -> Int
 
-  -- | O(1). Lookup a PData from a collection.
+  -- | O(1). Lookup a `PData` from a collection.
   indexdPR      :: PDatas a -> Int -> PData a
 
-  -- | O(n). Append two collections of PData.
+  -- | O(n). Append two collections of `PData`.
   appenddPR     :: PDatas a -> PDatas a -> PDatas a
 
-  -- | O(n). Combine several collections of PData into a single one.
+  -- | O(n). Combine several collections of `PData` into a single one.
   concatdPR     :: V.Vector (PDatas a) -> PDatas a
 
-  -- | O(n). Convert a vector of PData to a PDatas collection.
+  -- | O(n). Convert a vector of `PData` to a `PDatas`.
   fromVectordPR :: V.Vector (PData a) -> PDatas a
 
-  -- | O(n). Convert a PDatas collection to a vector of PData.
+  -- | O(n). Convert a `PDatas` to a vector of `PData`.
   toVectordPR   :: PDatas a           -> V.Vector (PData a)
 
 
index 03753ad..e1aa2ee 100644 (file)
@@ -1,13 +1,17 @@
+{-# OPTIONS_HADDOCK hide #-}
 #include "fusion-phases.h"
 
 -- | PR instance for Doubles.
-module Data.Array.Parallel.PArray.PData.Double where
+module Data.Array.Parallel.PArray.PData.Double 
+        ( PData (..)
+        , PDatas(..))
+where
+import Data.Array.Parallel.Pretty
 import Data.Array.Parallel.PArray.PData.Base
 import Data.Array.Parallel.PArray.PData.Nested
 import qualified Data.Array.Parallel.Unlifted   as U
 import qualified Data.Vector                    as V
 import qualified Data.Vector.Unboxed            as VU
-import Text.PrettyPrint
 
 -------------------------------------------------------------------------------
 data instance PData Double
index 3213da5..b43bcd2 100644 (file)
@@ -1,7 +1,8 @@
+{-# OPTIONS_HADDOCK hide #-}
 #include "fusion-phases.h"
 
 -- | PR instance for Ints
-module Data.Array.Parallel.PArray.PData.Int where
+module Data.Array.Parallel.PArray.PData.Int () where
 import Data.Array.Parallel.PArray.PData.Base
 import Data.Array.Parallel.PArray.PData.Nested
 import qualified Data.Array.Parallel.Unlifted   as U
@@ -9,6 +10,7 @@ import qualified Data.Vector                    as V
 import qualified Data.Vector.Unboxed            as VU
 import Text.PrettyPrint
 import Prelude                                  as P
+import Data.Array.Parallel.Pretty
 
 -- PR -------------------------------------------------------------------------
 instance PR Int where
index 60581d8..0c27807 100644 (file)
@@ -1,3 +1,4 @@
+{-# OPTIONS_HADDOCK hide #-}
 {-# LANGUAGE UndecidableInstances, ParallelListComp #-}
 {-# OPTIONS -fno-spec-constr #-}
 #include "fusion-phases.h"
@@ -7,35 +8,19 @@ module Data.Array.Parallel.PArray.PData.Nested
         ( PData(..)
         , PDatas(..)
         , mkPNested
-        , pnested_vsegids
-        , pnested_pseglens
-        , pnested_psegstarts
-        , pnested_psegsrcids
-
-        -- * Testing functions. TODO: move these somewhere else
-        , validIx
-        , validLen
-        , validBool
-                
-        -- * Functions derived from PR primops
         , concatPR,     concatlPR
+        , flattenPR,    takeSegdPD
         , unconcatPR
         , appendlPR
-        , unsafeFlattenPR
-
-        -- * Functions that work on nested PData arrays but don't care
-        --   about the element type, and need no dictionary.
-        , unsafeTakeSegdPD
         , slicelPD)
 where
 import Data.Array.Parallel.Base
-
+import Data.Array.Parallel.Pretty
 import Data.Array.Parallel.PArray.PData.Base    as PA
 import qualified Data.IntSet                    as IS
 import qualified Data.Array.Parallel.Unlifted   as U
 import qualified Data.Vector                    as V
 import qualified Data.Vector.Unboxed            as VU
-import Text.PrettyPrint
 import GHC.Exts
 
 -- TODO: Using plain V.Vector for the psegdata field means that operations on
@@ -53,7 +38,9 @@ data instance PData (PArray a)
           -- ^ Virtual segmentation descriptor. 
           --   Defines a virtual nested array based on physical data.
 
-        , pnested_psegdata     :: !(PDatas a) }
+        , pnested_psegdata     :: !(PDatas a) 
+          -- ^ Chunks of array data, where each chunk has a linear index space. 
+        }
 
 data instance PDatas (PArray a)
         = PNesteds (V.Vector (PData (PArray a)))
@@ -62,7 +49,23 @@ data instance PDatas (PData a)
         = PPDatas (V.Vector (PData a))
 
 
--- TODO: we shouldn't be using these directly.
+-- | Conatruct a nested array.
+mkPNested :: U.Array Int        -- ^ Virtual segment ids.
+          -> U.Array Int        -- ^ Lengths of physical segments.
+          -> U.Array Int        -- ^ Starting indices of physical segments.
+          -> U.Array Int        -- ^ Source id (what chunk to get each segment from).
+          -> PDatas a           -- ^ Chunks of array data.
+          -> PData (PArray a)
+mkPNested vsegids pseglens psegstarts psegsrcids psegdata
+        = PNested
+                (U.mkVSegd vsegids 
+                        $ U.mkSSegd psegstarts psegsrcids
+                        $ U.lengthsToSegd pseglens)
+                psegdata
+
+
+-- Old projection functions. 
+-- TODO: refactor to eliminate the need for these.
 pnested_vsegids    :: PData (PArray a) -> U.Array Int
 pnested_vsegids    =  U.takeVSegidsOfVSegd . pnested_uvsegd
 
@@ -75,24 +78,11 @@ pnested_psegstarts  = U.startsSSegd  . U.takeSSegdOfVSegd . pnested_uvsegd
 pnested_psegsrcids :: PData (PArray a) -> U.Array Int
 pnested_psegsrcids  = U.sourcesSSegd . U.takeSSegdOfVSegd . pnested_uvsegd
 
-mkPNested :: U.Array Int
-          -> U.Array Int
-          -> U.Array Int
-          -> U.Array Int
-          -> PDatas a
-          -> PData (PArray a)
-mkPNested vsegids pseglens psegstarts psegsrcids psegdata
-        = PNested
-                (U.mkVSegd vsegids 
-                        $ U.mkSSegd psegstarts psegsrcids
-                        $ U.lengthsToSegd pseglens)
-                psegdata
 
 
+-- PR Instances ---------------------------------------------------------------
 instance U.Elt (Int, Int, Int)
 
-
--- PR Instances ---------------------------------------------------------------
 instance PR a => PR (PArray a) where
   -- TODO: make this check all sub arrays as well
   -- TODO: ensure that all psegdata arrays are referenced from some psegsrc.
@@ -418,8 +408,8 @@ instance PR a => PR (PArray a) where
   --
   {-# INLINE_PDATA appendsPR #-}
   appendsPR rsegd segd1 xarr segd2 yarr
-   = let (xsegd, xs)    = unsafeFlattenPR xarr
-         (ysegd, ys)    = unsafeFlattenPR yarr
+   = let (xsegd, xs)    = flattenPR xarr
+         (ysegd, ys)    = flattenPR yarr
    
          xsegd' = U.lengthsToSegd 
                 $ U.sum_s segd1 (U.lengthsSegd xsegd)
@@ -516,31 +506,32 @@ instance PR a => PR (PArray a) where
 
 
 -------------------------------------------------------------------------------
--- | Flatten a nested array into its segment descriptor and data.
---
---   WARNING: Doing this to replicated arrays can cause index overflow.
---            See the warning in `unsafeMaterializeUVSegd`.
---
-unsafeFlattenPR :: PR a => PData (PArray a) -> (U.Segd, PData a)
-{-# INLINE unsafeFlattenPR #-}
-unsafeFlattenPR arr@(PNested uvsegd _)
- =      ( U.demoteToSegdOfVSegd uvsegd
-        , concatPR arr)
-
-
--------------------------------------------------------------------------------
 -- | O(len result). Concatenate a nested array.
 --
---   This physically performs a 'gather' operation, whereby array data is copied
---   through the index-space transformation defined by the segment descriptor.
---   We need to do this because discarding the segment descriptor means that we
---   can no-longer represent the data layout of the logical array other than by
---   physically creating it.
---
---   The segment descriptor keeps track of the layout of the data, and if it 
---   knows that the segments are already in a single, contiguous array with
---   no sharing then we can just return that array directly in O(1) time.
+--   This physically performs a gather operation, whereby array data is copied
+--   through the index-space transformation defined by the segment descriptor
+--   in the nested array. We must perform this copy because reducing the level
+--   of nesting corresponds to discarding the segment descriptor, which means we
+--   can no longer represent the layout of the array other than by physically
+--   creating it.
 --
+--   As an optimisation, if the segment descriptor knows that the segments are
+--   already in a single contiguous `PData` no sharing, then concat can just
+--   return the underlying array directly, in constant time.
+-- 
+--   WARNING: 
+--   Concatenating a replicated array can cause index overflow, because the 
+--   source array can define more elements than we can count with a single
+--   machine word.
+--   For example, if we replicate an array with 1Meg elements 1Meg times then
+--   the result defines a total of 1Meg*1Meg = 1Tera elements. This in itself
+--   is fine, because the nested array is defined by an index space transform
+--   that maps all the inner arrays back to the original data. However, if we 
+--   then concatenate the replicated array then we must physically copy the 
+--   data as we loose the segment descriptor that defines the mapping. Sad 
+--   things will happen when the library tries to construct an physical array
+--   1Tera elements long, especially on 32 bit machines.
+
 --   IMPORTANT:
 --   In the case where there is sharing between segments, or they are scattered
 --   through multiple arrays, only outer-most two levels of nesting are physically
@@ -572,12 +563,14 @@ concatPR (PNested vsegd pdatas)
 {-# INLINE_PDATA concatPR  #-}
 
 
--- | Lifted concat.
+-- | Lifted concatenation.
+-- 
+--   Concatenate all the arrays in a triply nested array.
+--
 concatlPR :: PR a => PData (PArray (PArray a)) -> PData (PArray a)
 concatlPR arr
- = let  (segd1, darr1)  = unsafeFlattenPR arr
-        (segd2, darr2)  = unsafeFlattenPR darr1
-
+ = let  (segd1, darr1)  = flattenPR arr
+        (segd2, darr2)  = flattenPR darr1
 
         -- Generate indices for the result array
         --  There is a tedious edge case when the last segment in the nested
@@ -620,7 +613,7 @@ concatlPR arr
 
 -- | Build a nested array given a single flat data vector, 
 --   and a template nested array that defines the segmentation.
--- 
+
 --   Although the template nested array may be using vsegids to describe
 --   internal sharing, the provided data array has manifest elements
 --   for every segment. Because of this we need flatten out the virtual
@@ -647,13 +640,26 @@ unconcatPR (PNested vsegd _) pdata
 --  need to inline it to specialise it for the element type.
 
 
+-- | Flatten a nested array, yielding a plain segment descriptor and 
+--   concatenated data.
+--
+--   WARNING:
+--   This can cause index space overflow, see the note in `concatPR`.
+--
+flattenPR :: PR a => PData (PArray a) -> (U.Segd, PData a)
+{-# INLINE flattenPR #-}
+flattenPR arr@(PNested uvsegd _)
+ =      ( U.demoteToSegdOfVSegd uvsegd
+        , concatPR arr)
+
+
 -- | Lifted append.
 --   Both arrays must contain the same number of elements.
 appendlPR :: PR a => PData (PArray a) -> PData (PArray a) -> PData (PArray a)
 {-# INLINE_PDATA appendlPR #-}
 appendlPR  arr1 arr2
- = let  (segd1, darr1)  = unsafeFlattenPR arr1
-        (segd2, darr2)  = unsafeFlattenPR arr2
+ = let  (segd1, darr1)  = flattenPR arr1
+        (segd2, darr2)  = flattenPR arr2
         segd'           = U.plusSegd segd1 segd2
    in   PNested (U.promoteSegdToVSegd segd' )
                 (singletondPR
@@ -668,23 +674,27 @@ appendlPR  arr1 arr2
 --
 
 -- | Take the segment descriptor from a nested array and demote it to a
---   plain Segd. This is unsafe because it can cause index space overflow.
-unsafeTakeSegdPD :: PData (PArray a) -> U.Segd
-unsafeTakeSegdPD (PNested vsegd _) 
+--   plain Segd.
+-- 
+--   WARNING:
+--   This can cause index space overflow, see the note in `concatPR`.
+--
+takeSegdPD :: PData (PArray a) -> U.Segd
+takeSegdPD (PNested vsegd _) 
         = U.demoteToSegdOfVSegd vsegd
-{-# INLINE_PDATA unsafeTakeSegdPD #-}
-
-
+{-# INLINE_PDATA takeSegdPD #-}
 
 
 -- | Extract some slices from some arrays.
---   The arrays of starting indices and lengths must themselves
---   have the same length.
+--
+--   All three parameters must have the same length, and we take
+--   one slice from each of the source arrays. 
+
 --   TODO: cleanup pnested projections
 slicelPD
-        :: PData Int            -- ^ starting indices of slices
-        -> PData Int            -- ^ lengths of slices
-        -> PData (PArray a)     -- ^ arrays to slice
+        :: PData Int            -- ^ Starting indices of slices.
+        -> PData Int            -- ^ Lengths of slices.
+        -> PData (PArray a)     -- ^ Arrays to slice.
         -> PData (PArray a)
 
 slicelPD (PInt sliceStarts) (PInt sliceLens) arr
@@ -708,23 +718,15 @@ slicelPD (PInt sliceStarts) (PInt sliceLens) arr
 --  need to inline it to specialise it for the element type.
 
 
-
 -- Testing --------------------------------------------------------------------
--- TODO: shift this stuff into dph-base
-validIx  :: String -> Int -> Int -> Bool
-validIx str len ix 
-        = check str len ix (ix >= 0 && ix < len)
-
-validLen :: String -> Int -> Int -> Bool
-validLen str len ix 
-        = checkLen str len ix (ix >= 0 && ix <= len)
-
 -- TODO: slurp debug flag from base 
 validBool :: String -> Bool -> Bool
 validBool str b
         = if b  then True 
                 else error $ "validBool check failed -- " ++ str
 
+
+-- Pretty ---------------------------------------------------------------------
 deriving instance Show (PDatas a) => Show (PDatas (PArray a))
 deriving instance Show (PDatas a) => Show (PData  (PArray a))
 
index 5078dc7..1836cd2 100644 (file)
@@ -1,7 +1,11 @@
+{-# OPTIONS_HADDOCK hide #-}
 #include "fusion-phases.h"
 
 -- | PR instance for Sum2.
-module Data.Array.Parallel.PArray.PData.Sum2 where
+module Data.Array.Parallel.PArray.PData.Sum2 
+        ( PData(..)
+        , PDatas(..))
+where
 import Data.Array.Parallel.PArray.PData.Int     ()
 import Data.Array.Parallel.PArray.PData.Base
 import Data.Array.Parallel.PArray.Types
@@ -10,7 +14,7 @@ import Data.Array.Parallel.Unlifted             as U
 import qualified Data.Vector                    as V
 import Text.PrettyPrint
 import Prelude                                  as P
-
+import Data.Array.Parallel.Pretty
 
 -------------------------------------------------------------------------------
 data instance PData (Sum2 a b)
index 6bf75e5..30bc82d 100644 (file)
@@ -1,16 +1,17 @@
+{-# OPTIONS_HADDOCK hide #-}
 #include "fusion-phases.h"
 
 -- | PR instance for tuples.
 module Data.Array.Parallel.PArray.PData.Tuple 
         ( PData(..),    PDatas(..)
-        , zip,          zipPD
-        ,               ziplPR
-        , unzip,        unzipPD
-        , unzipl,       unziplPD)
+        , zipPD
+        , ziplPR
+        , unzipPD
+        , unziplPD)
 where
+import Data.Array.Parallel.Pretty
 import Data.Array.Parallel.PArray.PData.Base
 import Data.Array.Parallel.PArray.PData.Nested
-import Text.PrettyPrint
 import GHC.Exts
 import Prelude hiding (zip, unzip)
 import qualified Data.Vector                    as V
@@ -206,8 +207,8 @@ ziplPR arr1 arr2
         -- that the vsegds of both arrays have the same form.
         -- One of the arrays may have been created with replicate, and 
         -- thus has internal sharing, while the other does not.
-        (segd1, pdata1) = unsafeFlattenPR arr1
-        (_,     pdata2) = unsafeFlattenPR arr2
+        (segd1, pdata1) = flattenPR arr1
+        (_,     pdata2) = flattenPR arr2
 
    in   PNested (U.promoteSegdToVSegd segd1)
                 (PTuple2s (singletondPR pdata1) (singletondPR pdata2))
@@ -229,30 +230,6 @@ unziplPD (PNested uvsegd (PTuple2s xsdata ysdata))
 {-# INLINE_PA unziplPD #-}
 
 
--- PArray functions -----------------------------------------------------------
--- These work on PArrays of tuples, but don't need a PA or PR dictionary.
-
--- | O(1). Zip a pair of arrays into an array of pairs.
---   The two arrays must have the same length, else `error`. 
-zip :: PArray a -> PArray b -> PArray (a, b)
-zip (PArray n# pdata1) (PArray _ pdata2)
-        = PArray n# $ zipPD pdata1 pdata2
-{-# INLINE_PA zip #-}
-
-
--- | O(1). Unzip an array of pairs into a pair of arrays.
-unzip :: PArray (a, b) -> (PArray a, PArray b)
-unzip (PArray n# (PTuple2 xs ys))
-        = (PArray n# xs, PArray n# ys)
-{-# INLINE_PA unzip #-}
-
-
--- | Lifted unzip
-unzipl :: PArray (PArray (a, b)) -> PArray (PArray a, PArray b)
-unzipl (PArray n# pdata)
-        = PArray n# $ unziplPD pdata
-
-
 -- Show -----------------------------------------------------------------------
 deriving instance (Show (PData  a), Show (PData  b)) => Show (PData  (a, b))
 deriving instance (Show (PDatas a), Show (PDatas b)) => Show (PDatas (a, b))
index 1e1c241..2aa391d 100644 (file)
@@ -1,11 +1,12 @@
+{-# OPTIONS_HADDOCK hide #-}
 #include "fusion-phases.h"
 
 -- | PR instance for unit.
 module Data.Array.Parallel.PArray.PData.Unit where
 import Data.Array.Parallel.PArray.PData.Base
+import Data.Array.Parallel.Pretty
 import qualified Data.Array.Parallel.Unlifted   as U
 import qualified Data.Vector                    as V
-import Text.PrettyPrint
 
 -------------------------------------------------------------------------------
 -- | TODO: For arrays of units, we're currently maintaining their length so
index e5ae7de..d9d27f3 100644 (file)
@@ -1,3 +1,4 @@
+{-# OPTIONS_HADDOCK hide #-}
 #include "fusion-phases.h"
 
 -- | PR instance for the void type.
index 24a76d0..b8fbe8d 100644 (file)
@@ -1,3 +1,4 @@
+{-# OPTIONS_HADDOCK hide #-}
 #include "fusion-phases.h"
 
 -- | PR instance for Word8.
@@ -10,6 +11,7 @@ import qualified Data.Vector.Unboxed            as VU
 import Text.PrettyPrint
 import Prelude                                  as P
 import Data.Word
+import Data.Array.Parallel.Pretty
 
 -------------------------------------------------------------------------------
 data instance PData Word8
index 754573e..42d93a4 100644 (file)
@@ -1,3 +1,4 @@
+{-# OPTIONS_HADDOCK hide #-}
 #include "fusion-phases.h"
 
 -- | PR instance for the Wrap type.
index 80f7bbd..97fba96 100644 (file)
@@ -1,12 +1,21 @@
 {-# LANGUAGE UndecidableInstances #-}
 #include "fusion-phases.h"
 
+-- | Defines the `PRepr` family and `PA` class that converts between the user
+--   level element types and our generic representation.
+--   Apart from `unpackPA`, the `PA` wrapper functions defined here all have
+--   equivalent `PR` versions in "Data.Array.Parallel.PArray.PData",
+--   so see there for documentation.
 module Data.Array.Parallel.PArray.PRepr
         ( module Data.Array.Parallel.PArray.PRepr.Base
         , module Data.Array.Parallel.PArray.PRepr.Instances
+
+        -- * Nested Arrays
         , module Data.Array.Parallel.PArray.PRepr.Nested
-        , module Data.Array.Parallel.PArray.PRepr.Tuple
-        , unpackPA)
+        , unpackPA
+
+        -- * Tuple Arrays
+        , module Data.Array.Parallel.PArray.PRepr.Tuple)
 where
 import Data.Array.Parallel.PArray.PRepr.Base
 import Data.Array.Parallel.PArray.PRepr.Instances
@@ -19,7 +28,6 @@ import qualified Data.Vector                    as V
 
 
 -- Pretty -------------------------------------------------------------------
--- | Show a virtual array.
 instance (Show a, PA a)
         => Show (PArray a) where
  show (PArray _ pdata)
@@ -30,7 +38,6 @@ instance (Show a, PA a)
                 <> text "|"
 
 
--- | Pretty print a virtual array.
 instance  (PprVirtual a, PA a)
         => PprVirtual (PArray a) where
  pprv (PArray _ pdata)
@@ -53,28 +60,3 @@ instance PA a => PprPhysical (Vector a) where
 unpackPA :: PA a => PArray a -> PData (PRepr a)
 unpackPA (PArray _ pdata)
         = toArrPRepr pdata
-
-{-
-mapdPA  :: (PA a, PA b)
-        => (PData  a -> PData  b) 
-        ->  PDatas a -> PDatas b
-mapdPA f xs
- = fromArrPReprs
- $ mapdPR
-        (\x -> toArrPRepr $ f $ fromArrPRepr x)
-        (toArrPReprs xs)
-{-# INLINE_PA mapdPA #-}
-
-
-
-zipWithdPA
-        :: (PA a, PA b, PA c)
-        => (PData  a -> PData  b -> PData  c)
-        ->  PDatas a -> PDatas b -> PDatas c
-zipWithdPA f xs ys
- = fromArrPReprs
- $ zipWithdPR
-        (\x y -> toArrPRepr $ f (fromArrPRepr x) (fromArrPRepr y))
-        (toArrPReprs xs) (toArrPReprs ys)
-{-# INLINE_PA zipWithdPA #-}
--}
index a0b8e37..09deafb 100644 (file)
@@ -1,3 +1,4 @@
+{-# OPTIONS_HADDOCK hide #-}
 #include "fusion-phases.h"
 
 -- | Definition of the PRepr/PA family and class.
@@ -52,13 +53,11 @@ import qualified Data.Array.Parallel.Unlifted   as U
 import qualified Data.Vector                    as V
 
 -- PRepr / PA -----------------------------------------------------------------
--- | Representable types.
+-- | Family of Representable types. These are the types that we know how to
+--   represent generically. `PRepr` takes an arbitrary type and produces the
+--   generic type we use to  represent it.
 --
---   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 D.A.P.PArray.PRepr.Instances.
+--   Instances for simple types are defined by the library. 
 --   For algebraic types, it's up to the vectoriser/client module to create
 --   a suitable instance.
 --
@@ -67,6 +66,7 @@ type family PRepr a
 
 -- | A PA dictionary contains the functions that we use to convert a
 --   representable type to and from its generic representation.
+--
 --   The conversions methods should all be O(1). 
 class PR (PRepr a) => PA a where
   toPRepr       :: a                -> PRepr a
@@ -79,6 +79,7 @@ class PR (PRepr a) => PA a where
   fromArrPReprs :: PDatas (PRepr a) -> PDatas a
 
 
+-- | Convert a nested array to its generic representation.
 toNestedArrPRepr
         :: PA a 
         => PData (PArray a)
index 22902b4..8cd5ea4 100644 (file)
@@ -1,5 +1,6 @@
-#include "fusion-phases.h"
+{-# OPTIONS_HADDOCK hide #-}
 {-# LANGUAGE UndecidableInstances #-}
+#include "fusion-phases.h"
 
 -- | Simple instances for the PRRepr/PA family and class.
 --   This module is kept separate from PRepr.Base to break an import cycle
index 11dcbac..ece2494 100644 (file)
@@ -1,11 +1,11 @@
+{-# OPTIONS_HADDOCK hide #-}
 #include "fusion-phases.h"
 
 -- | PRepr/PA instance for nested arrays, 
 --   and PA wrappers for other functions defined in D.A.P.PArray.PData.Nested.
 module Data.Array.Parallel.PArray.PRepr.Nested
-        ( concatPA
+        ( concatPA,  concatlPA
         , unconcatPA
-        , concatlPA
         , appendlPA)
 where
 import Data.Array.Parallel.PArray.PRepr.Base
index ac132f2..0461b0b 100644 (file)
@@ -1,10 +1,11 @@
+{-# OPTIONS_HADDOCK hide #-}
 #include "fusion-phases.h"
 
 -- | PRepr instance for tuples
 --   and PD wrappers for other functions defined in D.A.P.PArray.PData.Tuple.
 module Data.Array.Parallel.PArray.PRepr.Tuple
         ( PRepr
-        , zipl)
+        , ziplPA)
 where
 import Data.Array.Parallel.PArray.Types
 import Data.Array.Parallel.PArray.PRepr.Base
@@ -45,13 +46,6 @@ instance (PA a, PA b) => PA (a,b) where
         = PTuple2s as bs
 
 
--- | Lifted zip.
-zipl    :: (PA a, PA b)
-        => PArray (PArray a) -> PArray (PArray b) -> PArray (PArray (a, b))
-zipl (PArray n# xs) (PArray _ ys)
-        = PArray n# $ ziplPA xs ys
-
-
 -- | Lifted zip on PData arrays.
 ziplPA  :: (PA a, PA b) 
         => PData (PArray a) -> PData (PArray b) -> PData (PArray (a, b))
index 6f29fcb..0ff2284 100644 (file)
@@ -1,10 +1,10 @@
 
 -- | During testing, we compare the output of each invocation of the lifted
---   combinators in D.A.P.PArray with the reference implementations. 
+--   combinators in "Data.Array.Parallel.PArray" with the reference implementations. 
 --
 --   This module helps convert the to and from the array representation
 --   used by the reference implementation.
---
+
 --   TODO: we could use this to trace the lengths of the vectors being used, 
 --         as well as the types that each opeartor is being called at.
 --
@@ -12,7 +12,6 @@ module Data.Array.Parallel.PArray.Reference
         ( withRef1, withRef2
         , toRef1,   toRef2,   toRef3)
 where
-import Data.Array.Parallel.PArray.PData
 import Data.Array.Parallel.PArray.PRepr
 import Debug.Trace
 import qualified Data.Array.Parallel.Array      as A
@@ -56,7 +55,7 @@ withRef1 name arrRef arrImpl
         resultFail
          = error $ T.render $ T.vcat
                 [ T.text "withRef1: failure " T.<> T.text name
-                , T.nest 4 $ pprp  $ A.toVectors1 arrRef
+                , T.nest 4 $ T.pprp  $ A.toVectors1 arrRef
                 , T.nest 4 $ pprpPA arrImpl ]
 
    in   trace' (if debugLiftedCompare
index 972115c..d46664b 100644 (file)
@@ -228,7 +228,7 @@ fold1sIndex
 
 {-# INLINE_PA fold1sIndex #-}
 fold1sIndex f (PArray n# pdata)
- = let  segd    = unsafeTakeSegdPD pdata
+ = let  segd    = takeSegdPD pdata
         xs      = concatPA pdata
    in   PArray n#
          $ toScalarPData