Documentation

This page should get you started with writing your own computer simulations with LibGeoDecomp: build the library, write a simple Hello World application, then tune it for performance. Documentation on the library's internals can be found at the bottom.

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.

If you've already installed the library, then you may wish to compile a program using it. You can use pkg-config to auto-magically set the correct compiler flags, e.g. via 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: Thu Oct 23 04:51:44 2014 +0200