Prepare dph for a vectInfoVar type change
[packages/dph.git] / README
diff --git a/README b/README
index 8036eea..b54d41f 100644 (file)
--- a/README
+++ b/README
@@ -1,49 +1,94 @@
-NDP library
-===========
 
-Home: http://www.cse.unsw.edu.au/~chak/project/dph/
+Directories in libraries/dph
 
-Writing NDP programs
---------------------
+   dph-base/
+        Common config and debugging functions for Data Parallel Haskell.
 
-Import Data.Array.Parallel.Unlifted (sequential combinators) and/or
-Data.Array.Parallel.Unlifted.Parallel (parallel combinators). The subdirectory
-Data/Array/Parallel/test contains several examples.
+   dph-buildbot/
+        Performance regression buildbot.
 
-Before invoking any parallel combinators you must initialise the gang threads,
-usually by calling
+   dph-examples/
+        Examples using Data Parallel Haskell.
 
-  Data.Array.Parallel.Unlifted.Distributed.setGang <T>
+   dph-prim-interface/
+        Empty implementation of flat parallel arrays. 
+        This package exists only so that dph-prim-par and dph-prim-seq
+        can provide the same interface.
 
-where T is the number of threads. Normally, you want to run the program with
-+RTS -N<T> as well as you won't get any parallelism otherwise. This is a
-regrettable hack which will go away eventually.
+   dph-prim-seq/
+        Sequential implementation of the flat parallel array API defined
+        in dph-prim-interface.
+        This is only used during debugging.
+        You probably want dph-prim-par instead.
 
-Compiling NDP programs
-----------------------
+   dph-prim-par/
+        Production implementation of the flat parallel array API defined
+        in dph-prim-interface.
 
-The file ndp.mk shows the options you'll usually want for compiling NDP
-programs. You don't need -fbang-patterns unless you actually use them. You
-might get away with omitting -fmax-simplifier-iterations6; however, sometimes
-GHC will really need that many iterations to fully optimise NDP programs.
+   dph-lifted-base/
+        Common definitions used by the other dph-lifted packages.
 
-NDP on NUMA machines
---------------------
 
-NUMA machines, for instance multiprocessors based on AMD Opterons, might
-benefit from interleaved memory allocation. Under Linux, this can be achieved
-by running
+   The following packages provide:
+     Nested arrays and the primitive operators that work on them (PA functions).
+     The lifted array combinators that the vectoriser introduces (PP functions).
+     The user facing library functions that work on [::] style arrays (P functions).
 
-  numactl --interleave=all <cmd>
+     dph-lifted-boxed/
+        Incomplete implementation using boxed array elements.
+        This is very slow, but sometimes useful for debugging.
+        
+     dph-lifted-copy/
+        Deprecated implementation that performs deep copying replicate.
+        Using this package can cause the vectorised program to have worse
+        asymptotic complexity than the original.
+        Use dph-lifted-vseg instead.
 
-where cmd is the NDP program you want to run. Also, explicitly setting the
-processor affinity (taskset in Linux) might be helpful.
+     dph-lifted-vseg/
+        This implementation directly encodes sharing between array segments,
+        and avoids the copying that dph-lifted-copy would otherwise do.
+        Use this version for production code.
 
-Implemented functionality
--------------------------
 
-At the moment, the library only really supports flat arrays. Segmented arrays
-are provided but you must really know what you are doing to get efficient
-code. A lot of combinators (especially for segmented arrays) are still
-missing.
+   Odds and ends:
+   make/
+        Makefiles used for development and debugging
+
+   dph-test/
+        Quickcheck tests for the array operators.
+
+   dtrace/
+        Old code to add dtrace support to DPH.
+
+   examples/
+        Rotted example code that doesn't build anymore and should 
+        probably just be deleted.
+    
+
+To compile programs use:
+     ghc -rtsopts -threaded 
+         -fllvm -optlo-O3 
+         -Odph -fcpr-off -fno-liberate-case 
+         -package dph-lifted-vseg
+
+Why:
+     -rtsopts -threaded         -- You'll want to pass +RTS -Nwhatever when running
+                                --  the compiled program to enable threads.
+
+     -fllvm                     -- LLVM produces much better numerical code than GHC's
+                                --  default native code generator.
+
+     -optlo-O3                  -- Turn on more LLVM optimisations. 
+                                --  This can produce better numerical code, 
+                                --  but sometimes tickles bugs in LLVM.
+
+     -fcpr-off                  -- The Constructed Product Result transform sometimes
+                                --  interferes with fusion in the Data.Vector Library.
+
+     -fno-liberate-case         -- The LiberateCase transform can duplicate lots of 
+                                --  intermediate code, result in slow compile times,
+                                --  large binaries, and minimal performance improvement.
+                                --  The implementation of the DPH backend library should
+                                --  manually handle most cases where LiberateCase
+                                --  would fire.