lssfau / pe

This research project focuses on the development of the pe physics engine. pe is an advanced C++ framework for the simulation of rigid, completely undeformable bodies with arbitrary shape. pe offers both collision solvers for physically accurate simulations as well as fast solvers suitable for computer games. The major focus of pe are large-scale and massively parallel rigid body simulations with up to several billion interacting rigid bodies. The currently largest simulation with 28 billion non-spherical bodies was performed on the SuperMUC Petascale System at the Leibniz Supercomputing Center on 262144 processor cores.

** The pe is now part of waLBerla **
** The standalone version is no longer maintained **

The pe has the following dependencies:

Build-time dependencies:
   CMake >= 2.8.6

Run-time dependencies:
   Boost >= 1.46.1
   Irrlicht >= 1.7.9          (optional unless visualization is needed)
   MPI e.g. OpenMPI >= 1.4.3  (optional unless MPI parallelization is needed)
   OpenCL                     (optional unless GPGPU support is needed)
   gpusolve >= r304           (optional unless GPGPU support is needed)

Documentation dependencies:
   doxygen >= 1.7.5.1
   graphviz >= 2.28.0


In order to build the pe library two build systems can be used. The first one is a custom
configure script accepting a configuration file as an optional parameter. The configuration
options are described in ConfigFile which can be used as a template for your own
configuration. Thus building with a configuration file might work as follows:

cat > config-$HOST.txt <<EOF
   VERSION="debug"
   LIBRARY="static"
   COMPILER="gcc"
   PREPROCESSOR_FLAGS=
   COMPILER_FLAGS=
   LINKER_FLAGS=
   BLAS="no"
   IRRLICHT="yes"
   OPENCL="no"
   MPI="yes"
   MPI_INCLUDE_PATH=/usr/lib64/mpi/gcc/openmpi/include/
   MPI_LIBRARY_PATH=/usr/lib64/mpi/gcc/openmpi/lib64/
   MPI_LIBRARY="mpi_cxx mpi"
   MPI_PREINCLUDE="no"
EOF
./configure config-$HOST.txt
make


After building the library will be located in the lib/ subdirectory. The configure script also
supports out-of-source builds using BUILD_DIRECTORY configuration option in order to avoid
cluttering of the source tree.
If you need custom preprocessor, compiler or linker flags you can use the configuration
options PREPROCESSOR_FLAGS, COMPILER_FLAGS and LINKER_FLAGS. E.g. for profiling runs compile
with COMPILER_FLAGS=-pg and LINKER_FLAGS=-pg and COMPILER=gcc.

An alternative build system working on Unix as well as on Windows is a CMake based build.
CMake supports various generators. On Unix it can generate Makefiles for instance. The
configuration options can be specified on the command line of the CMake call:

mkdir build
cd build
CXX=g++ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE:STRING=RELEASE -DLIBRARY_TYPE:STRING=STATIC -DBLAS:BOOL=OFF -DMPI:BOOL=OFF -DMPI_PREINCLUDE:BOOL=OFF -DOPENCL:BOOL=OFF -DIRRLICHT:BOOL=OFF -DEXAMPLES:BOOL=OFF -DBoost_USE_STATIC_LIBS:BOOL=OFF ..
make VERBOSE=1


Specifying options on the command line is good for automating but is cumbersome otherwise. CMake
also supports configuration files:

cat > cache-$HOST.txt <<EOF
   set( CMAKE_BUILD_TYPE RELEASE CACHE STRING "" )
   set( LIBRARY_TYPE STATIC CACHE STRING "" )
   set( BLAS OFF CACHE BOOL "" )
   set( MPI ON CACHE BOOL "" )
   set( MPI_PREINCLUDE OFF CACHE BOOL "" )
   set( OPENCL OFF CACHE BOOL "" )
   set( IRRLICHT ON CACHE BOOL "" )
   set( EXAMPLES OFF CACHE BOOL "" )
   set( Boost_USE_STATIC_LIBS OFF CACHE BOOL "" )
   set( PREPROCESSOR_FLAGS "" CACHE STRING "" )
   set( COMPILER_FLAGS "" CACHE STRING "" )
   set( LINKER_FLAGS "" CACHE STRING "" )
EOF
mkdir build
cd build
CXX=g++ cmake -G "Unix Makefiles" -C../cache-$HOST.txt ..
make VERBOSE=1


On Windows CMake also supports generating Visual Studio project files:

mkdir build
cd build
cmake -G "Visual Studio 10 Win64" -C../cache-$HOST.txt ..

where cache-$HOST.txt might look like this:

set( CMAKE_BUILD_TYPE RELEASE CACHE STRING "" )
set( LIBRARY_TYPE STATIC CACHE STRING "" )
set( BLAS OFF CACHE BOOL "" )
set( MPI ON CACHE BOOL "" )
set( OPENCL OFF CACHE BOOL "" )
set( IRRLICHT OFF CACHE BOOL "" )
set( EXAMPLES ON CACHE BOOL "" )
set( Boost_USE_STATIC_LIBS ON CACHE BOOL "" )
set( BOOST_INCLUDEDIR "C:/Program Files/boost/boost_1_49_0/include" )
set( BOOST_LIBRARYDIR "C:/Program Files/boost/boost_1_49_0/lib64" )
set( PREPROCESSOR_FLAGS "" CACHE STRING "" )
set( COMPILER_FLAGS "" CACHE STRING "" )
set( LINKER_FLAGS "" CACHE STRING "" )

On Windows CMake also offers a convenient GUI for settings configuration options and generating
project files. On Unix a Curses based interface for CMake exists (ccmake).


Notes
-----
- OpenMPI 1.5.4 offers a binary installer on Windows
- dynamically linking boost libraries currently does not work on Windows
- the MPI configuration options should be determined by inspecting the output of
  "mpicc -showme:compile" and "mpicc -showme:link" and assigning the options to
  the correct configuration variables.