README
1ABOUT
2=====
3
4LibGeoDecomp (Library for Geometric Decomposition codes) is an
5auto-parallelizing library for computer simulations. It is written in
6C++ and works best with kernels written in C++, but other languages
7(e.g. Fortran) may be linked in, too. Thanks to its modular design the
8library can harness all state of the art hardware architectures:
9
10- multi-core CPUs
11- GPUs (currently only NVIDIA GPUs, via CUDA)
12- Intel Xeon Phi (thanks to the HPX backend)
13- MPI clusters (with or without accelerators)
14- and yes: the Raspberry Pi, too
15
16Here is how it works: the library takes over the spatial and temporal
17loops of the simulation as well as storage of the simulation data. It
18will call back the user code for performing the actual computations.
19User code in turn calls back the library to access simulation data.
20Thanks to this two-way callback the library can control which part of
21the code runs when.
22
23Users can build custom computer simulations (e.g. engineering or
24natural sciences problems) by encapsulating their model in a C++
25class. This class is then supplied to the library as a template
26parameter. The library essentially relieves the user from the pains of
27parallel programming, but is limited to applications which perform
28space- and time-discrete simulations with only local interactions.
29
30Further information:
31 - homepage: http://www.libgeodecomp.org
32 - mailing list: http://www.libgeodecomp.org/mailing_lists.html
33 - source repository: https://bitbucket.org/gentryx/libgeodecomp
34 - contributors: see file "AUTHORS"
35
36
37DIRECTORY LAYOUT
38================
39
400. libgeodecomp/
41----------------
42
43 The base directory. It holds this file (libgeodecomp/README) along
44 with the LICENSE file and the list of COPYRIGHT holders.
45
461. libgeodecomp/doc/
47--------------------
48 As the name says: documentation. These are mainly files generated by
49 Doxygen. Exception: doc/opencl. This directory contains a cheatsheet
50 contributed by Siegfried Schöfer.
51
522. libgeodecomp/lib/
53--------------------
54
55 Here you'll find 3rd party libraries which LibGeoDecomp needs, but
56 which are generally not available on target systems (e.g.
57 libflatarray for Struct of Array data structures or cxxtest for unit
58 tests). Please note that these libraries may be licensed under
59 different terms than LibGeoDecomp itself.
60
613. libgeodecomp/src/
62--------------------
63
64 The library's source code. This directory holds some basic files
65 such as the main libgeodecomp.h header and the main CMake file. Unit
66 tests are found beneath its subdirectories. The naming conventions
67 is src/foo/test/unit/myclasstest.h for unit tests of a class MyClass
68 in src/foo/myclass.h and src/foo/test/parallel_mpi_X/myclasstest.h
69 for parallel tests with X ranks. Subdirectories are:
70
71 - libgeodecomp/src/communication/
72 -------------------------------
73 All classes which are involved in moving data between processes.
74 Is also home to auxiliary files, e.g. to help with MPI data type
75 generation or Boost.Serialization.
76
77 - libgeodecomp/src/examples/
78 --------------------------
79 Sample applications which explain basic and advanced usage of the
80 library and implementation paradigms.
81
82 - libgeodecomp/src/geometry/
83 --------------------------
84 All classes which are related to domain decomposition and spatial
85 addressing (e.g. stencils and coordinates).
86
87 - libgeodecomp/src/io/
88 --------------------
89 Input and output plugins: Initializers define the initial grid
90 during application startup, Steerers allow modification at runtime
91 (live steering). Writers perform periodic output (e.g. snapshots
92 or interface with VisIt's libsim -- in situ visualization).
93
94 - libgeodecomp/src/loadbalancer/
95 ------------------------------
96 These classes steer the equalization of load within the library.
97 The interface between the parallelization and the load balancers is
98 formed by two weight vectors: one describes the relative ratio of
99 calculation time to communication time (i.e. the load of a node),
100 the other one the number of work items (e.g. number of cells)
101 assigned to a node.
102
103 - libgeodecomp/src/misc/
104 ----------------------
105 Assorted classes which don't fit into other categories, yet don't
106 qualify for a dedicated directory of their own.
107
108 - libgeodecomp/src/parallelization/
109 ---------------------------------
110 Here the various plugins which map computations to different
111 architectures (multi-cores, GPUs, clusters, OpenCL devices...) are
112 stored. This directory also holds the HPX backend: the
113 HpxSimulator. It sports a hierarchical parallelization, very
114 similar to HiParSimulator. Both currently represent our best
115 multi-node parallelizations.
116
117 - libgeodecomp/src/storage/
118 -------------------------
119 Classes related to in memory storage and access to simulation
120 data. This includes grid classes as well as implementations of the
121 neighborhood concept and adapters for other memory layouts.
122
123 - libgeodecomp/src/testbed/
124 -------------------------
125 This directory can be thought of as a staging area for unfinished
126 code, which needs to mature before being migrated to the standard
127 directories. It also holds our performance tests.
128
1294. libgeodecomp/tools/
130----------------------
131 Tools that help us to generate code (typemap generator for MPI
132 datatypes) or compile (build system).
133
134
135BUILDING
136========
137
138For compiling LibGeoDecomp you'll need CMake (http://www.cmake.org) installed.
139We recommend an out-of-source build:
140
141 BUILD_DIR=build/`uname -ms | sed s/\ /-/g`
142 mkdir -p $BUILD_DIR
143 cd $BUILD_DIR
144 cmake ../../
145 make
146
147That's it. CMake will output a number of configure options. You can
148change these by specifying their valued via "-DNAME=value". Note that
149CMake will cache these settings, you don't have to specify them again
150when re-running CMake. The following example turns CUDA support off.
151This may come in handy in case CMake detected CUDA, but you don't have
152a compatible GPU installed:
153
154 cmake -DWITH_CUDA=false ../../
155
156Another common option is to manually specify the compiler. Here I
157select GCC 4.7.0 my Gentoo system, which would otherwise use GCC 4.5.3
158as the standard compiler:
159
160 cmake -DCMAKE_CXX_COMPILER=/usr/x86_64-pc-linux-gnu/gcc-bin/4.7.0/g++ ../../
161
162Additionally you may want to run the library's unit tests via "make
163test" to ensure that it's actually working. For speedier builds you
164may want to run make in parallel, e.g. "make -j 4". Replace the 4 by
165the number of cores in your system. For more details please refer to:
166
167 http://www.libgeodecomp.org/documentation.html#userguide and
168 http://www.libgeodecomp.org/faq.html
169