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.
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.
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.
# 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 .