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.