Update readme and cabal files with better package descriptions
[packages/dph.git] / README
1
2 Directories in libraries/dph
3
4    dph-base/
5         Common config and debugging functions for Data Parallel Haskell.
6
7    dph-prim-interface/
8         Empty implementation of flat parallel arrays. 
9         This package exists only so that dph-prim-par and dph-prim-seq
10         can provide the same interface.
11
12    dph-prim-seq/
13         Sequential implementation of the flat parallel array API defined
14         in dph-prim-interface.
15         This is normal only used during debugging.
16         You probably want dph-prim-par instead.
17
18    dph-prim-par/
19         Production implementation of the flat parallel array API defined
20         in dph-prim-interface.
21
22    dph-lifted-base/
23         Common definitions used by the other dph-lifted packages.
24
25    The following packages provide:
26      Nested arrays and the primitive operators that work on them (PA functions).
27      The lifted array combinators that the vectoriser introduces (PP functions).
28      The user facing library functions that work on [::] style arrays (P functions).
29
30      dph-lifted-boxed/
31         Incomplete implementation using boxed array elements.
32         This is very slow, but sometimes useful during debugging.
33         
34      dph-lifted-copy/
35         Deprecated implementation that performs deep copying replicate.
36         Using this package can cause the vectorised program to have worse
37         asymptotic complexity than the original.
38         Use dph-lifted-vseg instead.
39
40      dph-lifted-vseg/
41         This implementation directly encodes sharing between array segments,
42         and avoids the copying that dph-lifted-copy would otherwise do.
43         Use this version for production code.
44
45
46 To compile programs use:
47      ghc -rtsopts -threaded 
48          -fllvm -optlo-O3 
49          -Odph -fcpr-off -fno-liberate-case 
50          -package dph-lifted-vseg
51
52 Why:
53      -rtsopts -threaded         -- You'll want to pass +RTS -Nwhatever when running
54                                 --  the compiled program to enable threads.
55
56      -fllvm                     -- LLVM produces much better numerical code than GHC's
57                                 --  default native code generator.
58
59      -optlo-O3                  -- Turn on more LLVM optimisations. 
60                                 --  This can produce better numerical code, 
61                                 --  but sometimes tickles bugs in LLVM.
62
63      -fcpr-off                  -- The Constructed Product Result transform sometimes
64                                 --  interferes with fusion in the Data.Vector Library.
65
66      -fno-liberate-case         -- The LiberateCase transform can duplicate lots of 
67                                 --  intermediate code, result in slow compile times,
68                                 --  large binaries, and minimal performance improvement.
69                                 --  The implementation of the DPH backend library should
70                                 --  manually handle most cases where LiberateCase
71                                 --  would fire.