If you came here, you will probably have a reasonably clear picture of what LibGeoDecomp does. If not, then have a look at this short write up or at these slides. The following passages will guide you through the process of writing a LibGeoDecomp-based simulation code. For other examples please see the codes that come with LibGeoDecomp.

Whenever you stumble upon a class whose usage doesn't seem clear, take a loop at the API documentation or the unit tests. Tests for class foo/bar.h can be found in foo/test/unit/bartest.h. Many classes also have parallel tests. For those unit gets replaced by parallel_TECH_I, where TECH is the parallelism model (e.g. MPI or HPX) and I represents the number of processes or localities to run the test with.

If you've already installed the library, then you may wish to compile a program using it. You can use pkg-config and CMake to auto-magically set the correct compiler flags. A comprehensive overview of the different ways is available on GitHub. Quick pkg-config example: g++ `pkg-config --cflags --libs libgeodecomp` test.cpp -o test. Just make sure that the install path is found by pkg-config. If not, you may need to set PKG_CONFIG_PATH.

First download and unpack a tarball of LibGeoDecomp. Instead of a configure script we use CMake to customize the build. The listing on the right shows how to build/install/test the library. Run it from your LibGeoDecomp directory. It performs an out-of-source build, meaning that your source tree will not be cluttered by a surge of object files.

make will also compile the examples found in src/examples. The executables will be written to their respective subdirectories in $BUILDDIR/examples. Which examples get built depends on the features you've selected via CMake.

Basic build

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

By default LibGeoDecomp will be installed to /usr/local. That may be undesirable on systems where you don't have root access. It is perfectly fine to tell CMake that it should install the library in your home directory by specifying the CMAKE_INSTALL_PREFIX.

CMake will try to detect reasonable defaults for your host. However, sometimes you may wish to opt-out of some features. These are controlled by the WITH_FOO flags. This may come in handy for instance if you have a CUDA capable GPU installed, but don't want to use its OpenCL drivers. A list of other configurable options is available when running CMake.

Specifying advanced options

# install in my home dir:
cmake -DCMAKE_INSTALL_PREFIX="/home/gentryx/libgeodecomp_install" ../..
# turn off QT and MPI:
cmake -DWITH_QT=false -DWITH_MPI=false ../..
# enforce CUDA, but switch off OpenCL:
cmake -DWITH_CUDA=true -DWITH_OPENCL=false ../..
# select Intel's C++ compiler (icpc):
cmake -DCMAKE_CXX_COMPILER=icpc ../..
# switch off some annoying warnings of icpc:
cmake -DADDITIONAL_COMPILE_FLAGS:STRING="-Wall -Wno-sign-compare -wd981 -wd1418" ../..

This section will detail how to write your first simulation code using LibGeoDecomp and how to tune it for optimum performance. It's not finished yet, so please refer to the examples in the library's source .

last modified: Wed Nov 09 20:38:09 2016 +0100