dph-prim-par: haddock cleanups
authorBen Lippmeier <benl@ouroborus.net>
Thu, 6 Oct 2011 04:03:50 +0000 (15:03 +1100)
committerBen Lippmeier <benl@ouroborus.net>
Tue, 11 Oct 2011 04:11:42 +0000 (15:11 +1100)
dph-prim-par/Data/Array/Parallel/Unlifted.hs
dph-prim-par/Data/Array/Parallel/Unlifted/Distributed.hs
dph-prim-par/Data/Array/Parallel/Unlifted/Distributed/Arrays.hs
dph-prim-par/Data/Array/Parallel/Unlifted/Distributed/Basics.hs
dph-prim-par/Data/Array/Parallel/Unlifted/Distributed/Combinators.hs
dph-prim-par/Data/Array/Parallel/Unlifted/Distributed/Types/Base.hs
dph-prim-par/Data/Array/Parallel/Unlifted/Parallel.hs
dph-prim-par/Data/Array/Parallel/Unlifted/Parallel/Segmented.hs
dph-prim-par/Data/Array/Parallel/Unlifted/Parallel/UPSSegd.hs
dph-prim-par/Data/Array/Parallel/Unlifted/Parallel/UPSegd.hs
dph-prim-seq/Data/Array/Parallel/Unlifted/Sequential/UVSegd.hs

index 08539e1..9a7116f 100644 (file)
@@ -188,7 +188,7 @@ scan f x arr
 -- Segmented Constructors -----------------------------------------------------
 replicate_s segd arr
         =  tracePrim (TraceReplicate_s (Seq.length arr))
-        $! UPSegd.replicateWith segd arr
+        $! UPSegd.replicateWithP segd arr
 
 
 replicate_rs n arr
@@ -203,19 +203,19 @@ append_s segd xd xs yd ys
 
 -- Segmented Projections ------------------------------------------------------
 indices_s segd
- = let  arr     = UPSegd.indicesWith segd
+ = let  arr     = UPSegd.indicesP segd
    in   tracePrim (TraceIndices_s (Seq.length arr)) arr
 
 
 -- Segmented Folds ------------------------------------------------------------
 fold_s f x segd arr
         =  tracePrim (TraceFold_s (Seq.length arr))
-        $! UPSegd.foldWith f x segd arr
+        $! UPSegd.foldWithP f x segd arr
 
         
 fold1_s f segd arr
         =  tracePrim (TraceFold1_s (Seq.length arr))
-        $! UPSegd.fold1With f segd arr
+        $! UPSegd.fold1WithP f segd arr
 
 
 fold_r f z segSize arr
@@ -230,8 +230,8 @@ sum_r x arr
 
 -- Scattered Segmented Folds --------------------------------------------------
 -- TODO: add tracing
-fold_ss                 = UPSegd.foldWith
-fold1_ss                = UPSegd.fold1With
+fold_ss                 = UPSegd.foldWithP
+fold1_ss                = UPSegd.fold1WithP
 
 
 -- Segment Descriptors --------------------------------------------------------
index a0d0b46..7c32cb8 100644 (file)
@@ -28,9 +28,6 @@ module Data.Array.Parallel.Unlifted.Distributed (
   glueSegdD, carryD,
   Distribution, balanced, unbalanced,
 
-  -- * Distributed scattered segment descriptors
-  splitSSegdOnElemsD,
-
   -- * Permutations
   permuteD, bpermuteD, atomicUpdateD,
 
index 30cf5c2..23bcd31 100644 (file)
@@ -279,18 +279,19 @@ atomicUpdateD g darr upd = runST (
 --
 --   NOTE: This runs sequentially and should only be used for testing purposes.
 --
---   @   pprp $ splitD theGang unbalanced $ fromList [80, 10, 20, 40, 50, 10 :: Int]
---       DVector lengths: [2,2,1,1]
---       chunks:  [[80,10],[20,40],[50],[10]]
+-- @
+-- pprp $ splitD theGang unbalanced $ fromList [80, 10, 20, 40, 50, 10 :: Int]
+-- DVector lengths: [2,2,1,1]
+--         chunks:  [[80,10],[20,40],[50],[10]]
 -- 
---       pprp $ fst 
---            $ carryD theGang (+) 0 
---                     (mkDPrim $ fromList [True, False, True, False]) 
---                     (splitD theGang unbalanced $ fromList [80, 10, 20, 40, 50, 10 :: Int])
+--  pprp $ fst 
+--       $ carryD theGang (+) 0 
+--          (mkDPrim $ fromList [True, False, True, False]) 
+--          (splitD theGang unbalanced $ fromList [80, 10, 20, 40, 50, 10 :: Int])
 --
---        DVector lengths: [1,2,0,1]
---                chunks:  [[80],[30,40],[],[60]]
---   @
+--  DVector lengths: [1,2,0,1]
+--          chunks: [[80],[30,40],[],[60]]
+-- @
 --
 carryD  :: forall a
         .  (Unbox a, DT a)
index c849074..4fc21eb 100644 (file)
@@ -27,13 +27,15 @@ neqD g dx dy = orD g (zipWithD g (/=) dx dy)
 
 
 -- | Generate a distributed value from the first @p@ elements of a list.
---   /NOTE:/ For debugging only, don't use in production code.
+-- 
+--   * For debugging only, don't use in production code.
 toD :: DT a => Gang -> [a] -> Dist a
 toD g xs = newD g (\md -> zipWithM_ (writeMD md) [0 .. gangSize g - 1] xs)
 
 
 -- | Yield all elements of a distributed value.
---   /NOTE:/ For debugging only, don't use in production code.
+--
+--   * For debugging only, don't use in production code.
 fromD :: DT a => Gang -> Dist a -> [a]
 fromD g dt = checkGangD (here "fromDT") g dt $
              map (indexD dt) [0 .. gangSize g - 1]
index 68de3e0..b8f172d 100644 (file)
@@ -65,8 +65,8 @@ imapD' g f !d
 
 -- | Map a function to every instance of a distributed value.
 --
---   NOTE: this applies the function to every thread, but not every value hold
---         by the thread. If you want that then use something like:
+--   This applies the function to every thread, but not every value held
+--   by the thread. If you want that then use something like:
 -- 
 --   @mapD theGang (V.map (+ 1)) :: Dist (Vector Int) -> Dist (Vector Int)@
 --
index f7106ad..31f54b4 100644 (file)
@@ -45,21 +45,25 @@ class DT a where
   -- | Unsafely freeze a mutable distributed value.
   unsafeFreezeMD :: MDist a s             -> ST s (Dist a)
 
+  -- | Ensure a distributed value is fully evaluated.
   deepSeqD       :: a -> b -> b
   deepSeqD = seq
 
 
   -- Debugging ------------------------
   -- | Number of elements in the distributed value.
-  --   For debugging only, as we shouldn't depend on the size of the gang.
+  -- 
+  --   * For debugging only, as code shouldn't be sensitive to the return value.
   sizeD :: Dist a -> Int
 
   -- | Number of elements in the mutable distributed value.
-  --   For debugging only, as we shouldn't care about the actual number.
+  --  
+  --   * For debugging only, as code shouldn't be sensitive to the return value.
   sizeMD :: MDist a s -> Int
 
   -- | Show a distributed value.
-  --   For debugging only.
+  --
+  --   * For debugging only.
   measureD :: a -> String
   measureD _ = "None"
 
index b3453db..6c2e2ff 100644 (file)
@@ -50,13 +50,7 @@ module Data.Array.Parallel.Unlifted.Parallel (
   allUP,     anyUP,
   sumUP,     productUP,
   maximumUP, maximumByUP,
-  maximumIndexByUP,  
-
-  -- * Selector Types
-  UPSel2,
-
-  -- * Segment Descriptor Types
-  UPSegd, UPSSegd,
+  maximumIndexByUP
 ) where
 import Data.Array.Parallel.Unlifted.Parallel.Basics
 import Data.Array.Parallel.Unlifted.Parallel.Combinators
@@ -66,7 +60,3 @@ import Data.Array.Parallel.Unlifted.Parallel.Segmented
 import Data.Array.Parallel.Unlifted.Parallel.Text       ()
 import Data.Array.Parallel.Unlifted.Parallel.Subarrays
 import Data.Array.Parallel.Unlifted.Parallel.Sums
-import Data.Array.Parallel.Unlifted.Parallel.UPSel      (UPSel2)
-import Data.Array.Parallel.Unlifted.Parallel.UPSegd     (UPSegd)
-import Data.Array.Parallel.Unlifted.Parallel.UPSSegd    (UPSSegd)
-
index 68c37bd..5edc569 100644 (file)
@@ -39,7 +39,7 @@ import qualified Data.Vector.Fusion.Stream              as S
 replicateRSUP :: Unbox a => Int -> Vector a -> Vector a
 {-# INLINE_UP replicateRSUP #-}
 replicateRSUP n xs
-        = UPSegd.replicateWith (UPSegd.fromLengths (replicateUP (Seq.length xs) n)) xs
+        = UPSegd.replicateWithP (UPSegd.fromLengths (replicateUP (Seq.length xs) n)) xs
 
 
 -- Append ---------------------------------------------------------------------
index 448d7dc..d6ec7a9 100644 (file)
@@ -1,34 +1,33 @@
 {-# LANGUAGE CPP #-}
 #include "fusion-phases.h"
 
--- | Parallel segment descriptors.
+-- | Parallel scattered segment descriptors.
 module Data.Array.Parallel.Unlifted.Parallel.UPSSegd (
   -- * Types
   UPSSegd, valid,
 
   -- * Constructors
-  mkUPSSegd, empty, singleton,
-  fromUPSegd,
+  mkUPSSegd, fromUSSegd, fromUPSegd,
+  empty, singleton,
   
   -- * Projections
   length,
+  takeUSSegd,
+  takeDistributed,
   takeLengths,
   takeIndices,
   takeElements,
   takeStarts,
   takeSources,
-  takeUSSegd,
-  takeDistributed,
   getSeg,
   
   -- * Append
   appendWith,
   
   -- * Segmented Folds
-  foldWith,
-  fold1With,
-  sumWith,
-  foldSegsWith
+  foldWithP,
+  fold1WithP,
+  foldSegsWithP
 ) where
 import Data.Array.Parallel.Pretty                                       hiding (empty)
 import Data.Array.Parallel.Unlifted.Distributed
@@ -38,6 +37,8 @@ import Data.Array.Parallel.Unlifted.Sequential.USSegd                   (USSegd)
 import Data.Array.Parallel.Unlifted.Sequential.Vector                   (Vector, MVector, Unbox)
 
 import qualified Data.Array.Parallel.Unlifted.Parallel.UPSegd           as UPSegd
+import qualified Data.Array.Parallel.Unlifted.Distributed.USSegd        as DUSSegd
+import qualified Data.Array.Parallel.Unlifted.Sequential.USegd          as USegd
 import qualified Data.Array.Parallel.Unlifted.Sequential.USSegd         as USSegd
 import qualified Data.Array.Parallel.Unlifted.Sequential.Vector         as Seq
 import qualified Data.Array.Parallel.Unlifted.Sequential.Combinators    as Seq
@@ -47,9 +48,11 @@ import Control.Monad.ST
 import Prelude hiding (length)
 
 
--- | A Parallel segment descriptor holds the original descriptor,
---   and a distributed one that describes how to distribute the work
---   on such a segmented array.
+-- | A parallel scattered segment descriptor is an extension of `UPSegd` 
+--   that allows the segments to be scattered through multiple flat arrays.
+--
+--   Each segment is associated with a source id that indicates what 
+--   flat array it is in, along with the starting index in that flat array.
 data UPSSegd 
         = UPSSegd 
         { upssegd_ussegd :: !USSegd
@@ -61,7 +64,7 @@ data UPSSegd
           --   and the offset of that slice in its segment.
           --   See docs of `splitSegdOfElemsD` for an example.
         }
-
+        deriving Show
 
 instance PprPhysical UPSSegd where
  pprp (UPSSegd ussegd dssegd)
@@ -73,7 +76,8 @@ instance PprPhysical UPSSegd where
 
 -- | O(1).
 --   Check the internal consistency of a scattered segment descriptor.
---   TODO: doesn't do any checks yet
+-- 
+--   * TODO: this doesn't do any checks yet
 valid :: UPSSegd -> Bool
 {-# INLINE valid #-}
 valid _ = True
@@ -82,9 +86,9 @@ valid _ = True
 -- Constructors ---------------------------------------------------------------
 -- | O(1). Construct a new segment descriptor.
 mkUPSSegd 
-        :: Vector Int   -- ^ starting index of each segment in its flat array
-        -> Vector Int   -- ^ which array to take each segment from
-        -> USegd        -- ^ contiguous segment descriptor
+        :: Vector Int   -- ^ Starting index of each segment in its flat array.
+        -> Vector Int   -- ^ Source id of the flat array to tach each segment from.
+        -> USegd        -- ^ Contiguous (unscattered) segment descriptor.
         -> UPSSegd
 
 {-# INLINE mkUPSSegd #-}
@@ -92,13 +96,26 @@ mkUPSSegd starts sources usegd
         = fromUSSegd (USSegd.mkUSSegd starts sources usegd)
 
 
--- | O(1).
---  Convert a global `USegd` to a distributed `UPSegd` by splitting
---  it across the gang.
+-- | Promote a global `USSegd` to a parallel `UPSSegd` by distributing
+--   it across the gang.
 fromUSSegd :: USSegd -> UPSSegd
 {-# INLINE fromUSSegd #-}
 fromUSSegd ssegd 
-        = UPSSegd ssegd (splitSSegdOnElemsD theGang ssegd)
+        = UPSSegd ssegd (DUSSegd.splitSSegdOnElemsD theGang ssegd)
+
+
+-- | Promote a plain `UPSegd` to a `UPSSegd`, by assuming that all segments
+--   come from a single flat array with source id 0.
+--
+--   * TODO:
+--     This sequentially constructs the indices and source fields, and we
+--     throw out the existing distributed `USegd`. We could probably keep
+--     some of the existing fields and save reconstructing them.
+--
+fromUPSegd :: UPSegd -> UPSSegd
+{-# INLINE fromUPSegd #-}
+fromUPSegd upsegd
+        = fromUSSegd $ USSegd.fromUSegd $ UPSegd.takeUSegd upsegd
 
 
 -- | O(1). Yield an empty segment descriptor, with no elements or segments.
@@ -112,20 +129,7 @@ empty   = fromUSSegd USSegd.empty
 --   The single segment covers the given number of elements.
 singleton :: Int -> UPSSegd
 {-# INLINE singleton #-}
-singleton n  = fromUSSegd $ USSegd.singleton n
-
-
--- | O(segs). 
---   Promote a plain USSegd to a UPSSegd
---   All segments are assumed to come from a flat array with sourceid 0.
-
---   TODO: Sequential construction of the indices and source field.
---         We throw out the existing distributed usegd here,
---          maybe we can do the promotion while keeping some of the existing fields.
-fromUPSegd :: UPSegd -> UPSSegd
-{-# INLINE fromUPSegd #-}
-fromUPSegd upsegd
-        = fromUSSegd $ USSegd.fromUSegd $ UPSegd.takeUSegd upsegd
+singleton n = fromUSSegd $ USSegd.singleton n
 
 
 -- Projections ----------------------------------------------------------------
@@ -153,25 +157,28 @@ takeLengths :: UPSSegd -> Vector Int
 takeLengths     = USSegd.takeLengths . upssegd_ussegd
 
 
--- | O(1). Yield the segment indices of a segment descriptor.
+-- | O(1). Yield the segment indices.
 takeIndices :: UPSSegd -> Vector Int
 {-# INLINE takeIndices #-}
 takeIndices     = USSegd.takeIndices . upssegd_ussegd
 
 
--- | O(1). Yield the number of data elements.
+-- | O(1). Yield the total number of data elements.
+--
+--  @takeElements upssegd = sum (takeLengths upssegd)@
+--
 takeElements :: UPSSegd -> Int
 {-# INLINE takeElements #-}
 takeElements    = USSegd.takeElements . upssegd_ussegd
 
 
--- | O(1). Yield the starting indices of a `UPSSegd`
+-- | O(1). Yield the starting indices.
 takeStarts :: UPSSegd -> Vector Int
 {-# INLINE takeStarts #-}
 takeStarts      = USSegd.takeStarts . upssegd_ussegd
 
 
--- | O(1). Yield the source ids of a `UPSSegd`
+-- | O(1). Yield the source ids.
 takeSources :: UPSSegd -> Vector Int
 {-# INLINE takeSources #-}
 takeSources     = USSegd.takeSources . upssegd_ussegd 
@@ -187,62 +194,69 @@ getSeg upssegd ix
 
 -- Append ---------------------------------------------------------------------
 -- | O(n)
---   Produce a segment descriptor that describes the result of appending.
+--   Produce a segment descriptor that describes the result of appending two
+--   segmented arrays.
 --   
---   TODO: This calls out to the sequential version.
+--   * TODO: This calls out to the sequential version.
+--
+--   * Appending two nested arrays is an index space transformation. Because
+--     a `UPSSegd` can contain segments from multiple flat data arrays, we can
+--     represent the result of the append without copying elements from the
+--     underlying flat data arrays.
 --
 appendWith
-        :: UPSSegd -> Int        -- ^ ussegd of array, and number of physical data arrays
-        -> UPSSegd -> Int        -- ^ ussegd of array, and number of physical data arrays
+        :: UPSSegd              -- ^ Segment descriptor of first nested array.
+        -> Int                  -- ^ Number of flat data arrays used to represent first nested array.
+        -> UPSSegd              -- ^ Segment descriptor of second nested array. 
+        -> Int                  -- ^ Number of flat data arrays used to represent second nested array.
         -> UPSSegd
 {-# INLINE appendWith #-}
-appendWith
-        upssegd1 pdatas1
-        upssegd2 pdatas2
+appendWith upssegd1 pdatas1
+           upssegd2 pdatas2
  = fromUSSegd 
  $ USSegd.append (upssegd_ussegd upssegd1) pdatas1
                  (upssegd_ussegd upssegd2) pdatas2
 
 
 -- Fold -----------------------------------------------------------------------
--- | Fold segments specified by a UPSegd.
-foldWith :: Unbox a
+-- | Fold segments specified by a `UPSSegd`.
+foldWithP :: Unbox a
          => (a -> a -> a) -> a -> UPSSegd -> V.Vector (Vector a) -> Vector a
-{-# INLINE foldWith #-}
-foldWith f !z
-        = foldSegsWith f (Seq.foldlSSU f z)
+{-# INLINE foldWithP #-}
+foldWithP f !z
+        = foldSegsWithP f (Seq.foldlSSU f z)
 
 
--- | Fold segments specified by a UPSegd, with a non-empty vector.
-fold1With :: Unbox a
+-- | Fold segments specified by a `UPSSegd`, with a non-empty vector.
+fold1WithP :: Unbox a
          => (a -> a -> a) -> UPSSegd -> V.Vector (Vector a) -> Vector a
-{-# INLINE fold1With #-}
-fold1With f
-        = foldSegsWith f (Seq.fold1SSU f)
+{-# INLINE fold1WithP #-}
+fold1WithP f
+        = foldSegsWithP f (Seq.fold1SSU f)
 
 
--- | Sum up segments specified by a UPSegd.
-sumWith :: (Num a, Unbox a)
+-- | Sum up segments specified by a `UPSSegd`.
+sumWithP :: (Num a, Unbox a)
         => UPSSegd -> V.Vector (Vector a) -> Vector a
-{-# INLINE sumWith #-}
-sumWith = foldWith (+) 0
+{-# INLINE sumWithP #-}
+sumWithP = foldWithP (+) 0
 
 
--- | Fold the segments specified by a UPSSegd
+-- | Fold the segments specified by a `UPSSegd`.
 --
 --   Low level function takes a per-element worker and a per-segment worker.
 --   It folds all the segments with the per-segment worker, then uses the
 --   per-element worker to fixup the partial results when a segment 
 --   is split across multiple threads.
 --   
-foldSegsWith
+foldSegsWithP
         :: Unbox a
         => (a -> a -> a)
         -> (USSegd -> V.Vector (Vector a) -> Vector a)
         -> UPSSegd -> V.Vector (Vector a) -> Vector a
 
-{-# INLINE foldSegsWith #-}
-foldSegsWith fElem fSeg segd xss 
+{-# INLINE foldSegsWithP #-}
+foldSegsWithP fElem fSeg segd xss 
  = dcarry `seq` drs `seq` 
    runST (do
         mrs <- joinDM theGang drs
index 9e62105..bbaca1f 100644 (file)
@@ -7,26 +7,28 @@ module Data.Array.Parallel.Unlifted.Parallel.UPSegd (
   UPSegd, valid,
 
   -- * Constructors
-  mkUPSegd, empty, singleton,
-  fromLengths,
+  mkUPSegd, fromUSegd, 
+  empty, singleton, fromLengths,
   
   -- * Projections
   length,
+  takeUSegd,
+  takeDistributed,
   takeLengths,
   takeIndices,
   takeElements,
-  takeUSegd,
-  takeDistributed,
+
+  -- * Indices
+  indicesP,
   
   -- * Replicate
-  replicateWith,
+  replicateWithP,
     
   -- * Segmented Folds
-  foldSegsWith,
-  foldWith,
-  fold1With,
-  sumWith,
-  indicesWith
+  foldWithP,
+  fold1WithP,
+  sumWithP,
+  foldSegsWithP
 ) where
 import Data.Array.Parallel.Unlifted.Distributed
 import Data.Array.Parallel.Unlifted.Sequential.USegd                    (USegd)
@@ -41,9 +43,9 @@ import Control.Monad.ST
 import Prelude  hiding (length)
 
 
--- | A Parallel segment descriptor holds the original descriptor,
---   and a distributed one that describes how to distribute the work
---   on such a segmented array.
+-- | A parallel segment descriptor holds a global (undistributed) segment desciptor, 
+--   as well as a distributed version. The distributed version describes how to split
+--   work on the segmented array over the gang. 
 data UPSegd 
         = UPSegd 
         { upsegd_usegd :: !USegd
@@ -57,20 +59,22 @@ data UPSegd
         }
 
 
+-- Valid ----------------------------------------------------------------------
 -- | O(1).
---   Check the internal consistency of a scattered segment descriptor.
---   TODO: doesn't do any checks yet
+--   Check the internal consistency of a parallel segment descriptor.
+-- 
+--   * TODO: this doesn't do any checks yet
 valid :: UPSegd -> Bool
 {-# INLINE valid #-}
 valid _ = True
 
 
 -- Constructors ---------------------------------------------------------------
--- | O(1). Construct a new segment descriptor.
+-- | O(1). Construct a new parallel segment descriptor.
 mkUPSegd 
-        :: Vector Int   -- ^ length of each segment
-        -> Vector Int   -- ^ starting index of each segment
-        -> Int          -- ^ total number of elements in the flat array
+        :: Vector Int   -- ^ Length of each segment.
+        -> Vector Int   -- ^ Starting index of each segment.
+        -> Int          -- ^ Total number of elements in the flat array.
         -> UPSegd
 
 {-# INLINE mkUPSegd #-}
@@ -78,9 +82,8 @@ mkUPSegd lens idxs n
         = fromUSegd (USegd.mkUSegd lens idxs n)
 
 
--- | O(1).
---  Convert a global `USegd` to a distributed `UPSegd` by splitting
---  it across the gang.
+-- | Convert a global `USegd` to a parallel `UPSegd` by distributing 
+--   it across the gang.
 fromUSegd :: USegd -> UPSegd
 {-# INLINE fromUSegd #-}
 fromUSegd segd   = UPSegd segd (USegd.splitSegdOnElemsD theGang segd)
@@ -100,7 +103,7 @@ singleton :: Int -> UPSegd
 singleton n     = fromUSegd $ USegd.singleton n
 
 
--- | O(n). Convert a length array into a segment descriptor.
+-- | O(n). Convert an array of segment lengths into a parallel segment descriptor.
 -- 
 --   The array contains the length of each segment, and we compute the 
 --   indices from that. Runtime is O(n) in the number of segments.
@@ -117,54 +120,72 @@ length :: UPSegd -> Int
 length          = USegd.length . upsegd_usegd
 
 
+-- | O(1). Yield the global `USegd` of a `UPSegd`.
+takeUSegd :: UPSegd -> USegd
+{-# INLINE takeUSegd #-}
+takeUSegd       = upsegd_usegd
+
+
+-- | O(1). Yield the distributed `USegd` of a `UPSegd`.
+--   
+--  We get a plain `USegd` for each chunk, the segment id of the first
+--  slice in the chunk, and the starting offset of that slice in its segment.
+-- 
+takeDistributed :: UPSegd -> Dist ((USegd,Int),Int)
+{-# INLINE takeDistributed #-}
+takeDistributed = upsegd_dsegd
+
+
 -- | O(1). Yield the lengths of the individual segments.
 takeLengths :: UPSegd -> Vector Int
 {-# INLINE takeLengths #-}
 takeLengths     = USegd.takeLengths . upsegd_usegd
 
 
--- | O(1). Yield the segment indices of a segment descriptor.
+-- | O(1). Yield the segment indices.
 takeIndices :: UPSegd -> Vector Int
 {-# INLINE takeIndices #-}
 takeIndices     = USegd.takeIndices . upsegd_usegd
 
 
--- | O(1). Yield the number of data elements.
+-- | O(1). Yield the total number of array elements.
+-- 
+--  @takeElements upsegd = sum (takeLengths upsegd)@
+--
 takeElements :: UPSegd -> Int
 {-# INLINE takeElements #-}
 takeElements    = USegd.takeElements . upsegd_usegd
 
 
--- | O(1). Yield the global `USegd` of a `UPSegd`
-takeUSegd :: UPSegd -> USegd
-{-# INLINE takeUSegd #-}
-takeUSegd       = upsegd_usegd
-
-
--- | O(1). Yield the distributed `USegd` of a `UPSegd`
-takeDistributed :: UPSegd -> Dist ((USegd,Int),Int)
-{-# INLINE takeDistributed #-}
-takeDistributed = upsegd_dsegd
 
 
 -- Indices --------------------------------------------------------------------
-indicesWith :: UPSegd -> Vector Int
-{-# INLINE_UP indicesWith #-}
-indicesWith
+-- | O(n). Yield a vector containing indicies that give the position of each 
+--         member of the flat array in its corresponding segment.
+--
+--  @indicesP (fromLengths [5, 2, 3]) = [0,1,2,3,4,0,1,0,1,2]@
+--
+indicesP :: UPSegd -> Vector Int
+{-# INLINE_UP indicesP #-}
+indicesP
         = joinD theGang balanced
-        . mapD theGang indices
+        . mapD  theGang indices
         . takeDistributed
   where
     indices ((segd,k),off) = Seq.indicesSU' off segd
 
 
 -- Replicate ------------------------------------------------------------------
--- | Segmented replication.
-replicateWith :: Unbox a => UPSegd -> Vector a -> Vector a
-{-# INLINE_UP replicateWith #-}
-replicateWith segd !xs 
+-- | Copying segmented replication. Each element of the vector is physically 
+--   copied according to the length of each segment in the segment descriptor.
+--
+--   @replicateWith (fromLengths [3, 1, 2]) [5, 6, 7] = [5, 5, 5, 6, 7, 7]@
+--
+replicateWithP :: Unbox a => UPSegd -> Vector a -> Vector a
+{-# INLINE_UP replicateWithP #-}
+replicateWithP segd !xs 
   = joinD theGang balanced
-  . mapD theGang rep
+  . mapD  theGang rep
   $ takeDistributed segd
   where
     rep ((dsegd,di),_)
@@ -172,43 +193,43 @@ replicateWith segd !xs
 
 
 -- Fold -----------------------------------------------------------------------
--- | Fold segments specified by a UPSegd.
-foldWith :: Unbox a
+-- | Fold segments specified by a `UPSegd`.
+foldWithP :: Unbox a
          => (a -> a -> a) -> a -> UPSegd -> Vector a -> Vector a
-{-# INLINE foldWith #-}
-foldWith f !z
-        = foldSegsWith f (Seq.foldlSU f z)
+{-# INLINE foldWithP #-}
+foldWithP f !z
+        = foldSegsWithP f (Seq.foldlSU f z)
 
 
--- | Fold segments specified by a UPSegd, with a non-empty vector.
-fold1With :: Unbox a
+-- | Fold segments specified by a `UPSegd`, with a non-empty vector.
+fold1WithP :: Unbox a
          => (a -> a -> a) -> UPSegd -> Vector a -> Vector a
-{-# INLINE fold1With #-}
-fold1With f
-        = foldSegsWith f (Seq.fold1SU f)
+{-# INLINE fold1WithP #-}
+fold1WithP f
+        = foldSegsWithP f (Seq.fold1SU f)
 
 
--- | Sum up segments specified by a UPSegd.
-sumWith :: (Num e, Unbox e) => UPSegd -> Vector e -> Vector e
-{-# INLINE sumWith #-}
-sumWith = foldWith (+) 0
+-- | Sum up segments specified by a `UPSegd`.
+sumWithP :: (Num e, Unbox e) => UPSegd -> Vector e -> Vector e
+{-# INLINE sumWithP #-}
+sumWithP = foldWithP (+) 0
 
 
--- | Fold the segments specified by a UPSegd.
+-- | Fold the segments specified by a `UPSegd`.
 --
---   Low level function takes a per-element worker and a per-segment worker.
+--   This low level function takes a per-element worker and a per-segment worker.
 --   It folds all the segments with the per-segment worker, then uses the
 --   per-element worker to fixup the partial results when a segment 
 --   is split across multiple threads.
 --   
-foldSegsWith
+foldSegsWithP
         :: Unbox a
         => (a -> a -> a)
         -> (USegd -> Vector a -> Vector a)
         -> UPSegd -> Vector a -> Vector a
 
-{-# INLINE foldSegsWith #-}
-foldSegsWith fElem fSeg segd xs 
+{-# INLINE foldSegsWithP #-}
+foldSegsWithP fElem fSeg segd xs 
  = dcarry `seq` drs `seq` 
    runST (do
         mrs <- joinDM theGang drs
index ee4ae77..96c3a5e 100644 (file)
@@ -41,13 +41,11 @@ import qualified Data.Array.Parallel.Unlifted.Sequential.USegd  as USegd
 
 
 -- UVSegd ---------------------------------------------------------------------
--- TODO shift this to its own module
--- | Defines a virutal nested array based on physical segmentation.
---
---   Or alternatively: represents an index space transformation between
---   indices for the nested array and indices for the physical data.
+-- | Virtual segment descriptors. 
+--   Represents an index space transformation between indices for the nested
+--   array and indices for the physical data.
 --   
---   TODO: It'd probably be better to represent the vsegids as a lens (function)
+--   TODO: It would probably be better to represent the vsegids as a lens (function)
 --         instead of a vector of segids. Much of the time the vsegids are just [0..n] 
 --
 data UVSegd 
@@ -71,7 +69,7 @@ instance PprPhysical UVSegd where
 
 -- Constructors ---------------------------------------------------------------
 -- | O(1). 
---   Construct a new slice segment descriptor.
+--   Construct a new virtual segment descriptor.
 --   All the provided arrays must have the same lengths.
 mkUVSegd
         :: Vector Int   -- ^ array saying which physical segment to use for each
@@ -226,7 +224,8 @@ unsafeMaterialize (UVSegd vsegids ussegd)
 --   Produce a segment descriptor describing the result of appending two arrays.
 --   Note that the implementation of this is similar to `combine2UVSegd`
 --
---   source
+-- @
+--  source1
 --    VIRT1 [[0],[4,2],[5,6,7,8,9]]
 --    PHYS1 UVSegd  vsegids:    [0,1,2]
 --          USSegd  pseglens:   [1,2,5]
@@ -234,6 +233,7 @@ unsafeMaterialize (UVSegd vsegids ussegd)
 --                  psegsrcs:   [0,0,0]
 --          PData   PInt [0,4,2,5,6,7,8,9]
 --
+--  source2
 --    VIRT2 [[1,2,3],[8,6,3],[9,3]]
 --    PHYS2 UVSegd  vsegids:    [0,1,2]
 --          USSegd  pseglens:   [3,3,2]
@@ -241,7 +241,7 @@ unsafeMaterialize (UVSegd vsegids ussegd)
 --                  psegsrcs:   [0,0,0]
 --          PData   PInt [1,2,3,8,6,3,9,3]
 --
----  appended
+--   appended
 --    VIRT  [[0],[4,2],[5,6,7,8,9],[1,2,3],[8,6,3],[9,3]]
 --          UVSegd  vsegids:    [0,1,2,3,4,5]  -- shift second half
 --          USSegd  pseglens:   [1,2,5,3,3,2]  -- appended
@@ -249,7 +249,8 @@ unsafeMaterialize (UVSegd vsegids ussegd)
 --                  psegsrcs:   [0,0,0,1,1,1]  -- shift second half
 --          PData   PInt [0,4,2,5,6,7,8,9]     -- both pdatas in result
 --                  PInt [1,2,3,8,6,3,9,3]     -- ...
---
+-- @
+-- 
 append  :: UVSegd -> Int  -- ^ uvsegd of array, and number of physical data arrays
         -> UVSegd -> Int  -- ^ uvsegd of array, and number of physical data arrays
         -> UVSegd
@@ -277,7 +278,8 @@ append  (UVSegd vsegids1 ussegd1) pdatas1
 --   Combine two virtual segment descriptors.
 --   Note that the implementation of this is similar to `appendUVSegd`
 --
---   source
+-- @
+-- source1
 --    VIRT1 [[0],[4,2],[5,6,7,8,9]]
 --    PHYS1 UVSegd  vsegids:    [0,1,2]
 --          USSegd  pseglens:   [1,2,5]
@@ -285,6 +287,7 @@ append  (UVSegd vsegids1 ussegd1) pdatas1
 --                  psegsrcs:   [0,0,0]
 --          PDATA   PInt [0,4,2,5,6,7,8,9]
 --
+-- source2
 --    VIRT2 [[1,2,3],[8,6,3],[9,3]]
 --    PHYS2 UVSegd  vsegids:    [0,1,2]
 --          USSegd  pseglens:   [3,3,2]
@@ -300,7 +303,8 @@ append  (UVSegd vsegids1 ussegd1) pdatas1
 --                  psegsrcs:   [0,0,0,1,1,1] -- shift second half
 --          PData   PInt [0,4,2,5,6,7,8,9]    -- both pdatas in result
 --                  PInt [1,2,3,8,6,3,9,3]
---   
+-- @  
+-- 
 combine2
         :: USel2
         -> UVSegd -> Int   -- ^ uvsegd of array, and number of physical data arrays