ABOUT

LibGeoDecomp (Library for Geometric Decomposition codes) is an auto-parallelizing library for computer simulations. It is written in C++ and works best with kernels written in C++, but other languages (e.g. Fortran) may be linked in, too. Thanks to its modular design the library can harness all state of the art hardware architectures:

• multi-core CPUs
• GPUs (currently only NVIDIA GPUs, via CUDA)
• Intel Xeon Phi (thanks to the HPX backend)
• MPI clusters (with or without accelerators)
• and yes: the Raspberry Pi, too.

Here is how it works: the library takes over the spatial and temporal loops of the simulation as well as storage of the simulation data. It will call back the user code for performing the actual computations. User code in turn calls back the library to access simulation data. Thanks to this two-way callback the library can control which part of the code runs when.

Users can build custom computer simulations (e.g. engineering or natural sciences problems) by encapsulating their model in a C++ class. This class is then supplied to the library as a template parameter. The library essentially relieves the user from the pains of parallel programming, but is limited to applications which perform space- and time-discrete simulations with only local interactions.

Further information:

• homepage: http://www.libgeodecomp.org
• mailing list: http://www.libgeodecomp.org/mailing_lists.html
• source repository: https://bitbucket.org/gentryx/libgeodecomp
• contributors: see file "AUTHORS"

DIRECTORY LAYOUT

0. libgeodecomp/

The base directory. It holds this file (libgeodecomp/README) along with the LICENSE file and the list of COPYRIGHT holders.

1. libgeodecomp/doc/

As the name says: documentation. These are mainly files generated by Doxygen. Exception: doc/opencl. This directory contains a cheatsheet contributed by Siegfried Schöfer.

2. libgeodecomp/lib/

Here you'll find 3rd party libraries which LibGeoDecomp needs, but which are generally not available on target systems (e.g. libflatarray for Struct of Array data structures or cxxtest for unit tests). Please note that these libraries may be licensed under different terms than LibGeoDecomp itself.

3. libgeodecomp/src/

The library's source code. This directory holds some basic files such as the main libgeodecomp.h header and the main CMake file. Unit tests are found beneath its subdirectories. The naming conventions is src/foo/test/unit/myclasstest.h for unit tests of a class MyClass in src/foo/myclass.h and src/foo/test/parallel_mpi_X/myclasstest.h for parallel tests with X ranks. Subdirectories are:

• libgeodecomp/src/communication/

  All classes which are involved in moving data between processes. Is also home to auxiliary files, e.g. to help with MPI data type generation or Boost.Serialization.

• libgeodecomp/src/examples/

  Sample applications which explain basic and advanced usage of the library and implementation paradigms.

• libgeodecomp/src/geometry/

  All classes which are related to domain decomposition and spatial addressing (e.g. stencils and coordinates).

• libgeodecomp/src/io/

  Input and output plugins: Initializers define the initial grid during application startup, Steerers allow modification at runtime (live steering). Writers perform periodic output (e.g. snapshots or interface with VisIt's libsim -- in situ visualization).

• libgeodecomp/src/loadbalancer/

  These classes steer the equalization of load within the library. The interface between the parallelization and the load balancers is formed by two weight vectors: one describes the relative ratio of calculation time to communication time (i.e. the load of a node), the other one the number of work items (e.g. number of cells) assigned to a node.

• libgeodecomp/src/misc/

  Assorted classes which don't fit into other categories, yet don't qualify for a dedicated directory of their own.

• libgeodecomp/src/parallelization/

  Here the various plugins which map computations to different architectures (multi-cores, GPUs, clusters, OpenCL devices...) are stored. This directory also holds the HPX backend: the HpxSimulator. It sports a hierarchical parallelization, very similar to HiParSimulator. Both currently represent our best multi-node parallelizations.

• libgeodecomp/src/storage/

  Classes related to in memory storage and access to simulation data. This includes grid classes as well as implementations of the neighborhood concept and adapters for other memory layouts.

• libgeodecomp/src/testbed/

  This directory can be thought of as a staging area for unfinished code, which needs to mature before being migrated to the standard directories. It also holds our performance tests.

4. libgeodecomp/tools/

Tools that help us to generate code (typemap generator for MPI datatypes) or compile (build system).

BUILDING

For compiling LibGeoDecomp you'll need CMake (http://www.cmake.org) installed. We recommend an out-of-source build:

BUILD_DIR=build/uname -ms | sed s/\ /-/g mkdir -p $BUILD_DIR cd $BUILD_DIR cmake ../../ make

That's it. CMake will output a number of configure options. You can change these by specifying their valued via "-DNAME=value". Note that CMake will cache these settings, you don't have to specify them again when re-running CMake. The following example turns CUDA support off. This may come in handy in case CMake detected CUDA, but you don't have a compatible GPU installed:

cmake -DWITH_CUDA=false ../../

Another common option is to manually specify the compiler. Here I select GCC 4.7.0 my Gentoo system, which would otherwise use GCC 4.5.3 as the standard compiler:

cmake -DCMAKE_CXX_COMPILER=/usr/x86_64-pc-linux-gnu/gcc-bin/4.7.0/g++ ../../

After your build is complete, you might want to ensure that LibGeoDecomp is functioning as advertised by running its unit tests:

make check

For speedier builds you may want to run make in parallel, e.g. "make -j 4". Replace the 4 by the number of cores in your system. For more details please refer to:

http://www.libgeodecomp.org/documentation.html#userguide and http://www.libgeodecomp.org/faq.html

INSTALLATION

After building the library you can install it via

make install

An installation prefix can be configured via CMake by specifying the option CMAKE_INSTALL_PREFIX. Alternatively you could check whether your distribution (in the case of Linux) already comes with a prepackaged version of LibGeoDecomp.