This page describes how to obtain a copy of waLBerla and how to setup your environment for development.

Getting waLBerla

Clone the repository

As a first step, check out the waLBerla source code from our git repository:

  git clone https://i10git.cs.fau.de/walberla/walberla

If you are not familiar with the git version control system, this page is a good starting point.

Building waLBerla

Libraries and CMake Options

To compile waLBerla with all modules and features a few third-party libraries are required.

MPI (optional)

The message passing interface (MPI) library is required if you want to run waLBerla with distributed memory parallelization. If MPI is not installed on your system, you still can compile a serial or even an OpenMP thread-parallel version of waLBerla. You can disable MPI using the CMake switch WALBERLA_BUILD_WITH_MPI.

Qt (optional)

waLBerla can be build with a graphical user interface, which is disabled by default. The GUI is mainly useful for debugging and visualizing very small scale simulations. To enable the GUI, set the CMake switch WALBERLA_ENABLE_GUI to ON and install Qt4 on your system.

Compiling the code

  # create a separate build directory
  cd walberla
  mkdir build
  cd build
  
  # set up the build system
  cmake ..

  # modify the configuration if necessary 
  ccmake .       # or alternatively "cmake-gui . "

  # compile the code
  make -j 4

CMake Build Variables

To modify the build configuration go to your build directory and type ccmake . or cmake-gui .

Some commonly-used build variables:

Build variable	Default	Meaning
CMAKE_BUILD_TYPE	Release	Either Debug (non optimized, for debugging with asserts), Release (production runs), DebugOptimized (optimized, but for debugging with asserts), or RelWithDebInfo (Release with debug infos)
WALBERLA_ENABLE_GUI	OFF	Builds the graphical user interface. Make sure you have QT development libraries installed.
WALBERLA_BUILD_TUTORIALS	ON	Builds all the tutorials located in "apps/tutorials" (= they are added to the 'all' target in the Makefile). If disabled, the tutorials can still be built by going to "apps/tutorials" in the build folder and running make.
WALBERLA_BUILD_WITH_MPI	ON	Since one main goal of waLBerla are massively parallel simulations, this is enabled by default. However, MPI can be disabled.
WALBERLA_BUILD_WITH_OPENMP	OFF	Enables/Disables OpenMP support for thread-parallel computation. Can also be combined with MPI for hybrid simulations!
WALBERLA_BUILD_TESTS	OFF	If enabled, all tests are built when running make in the root build folder. But you can always go to a specific directory in your test folder and manually run make.
WALBERLA_BUILD_BENCHMARKS	ON	Enables/Disables the automatic build of all benchmarks located in "apps/benchmarks".
WALBERLA_BUILD_WITH_PYTHON	OFF	Enables Python Support inside waLBerla (embedded Python). Then you can use Python scripts as configuration files and start an embedded python interpreter that can access waLBerla data structures. This builds a shared library (and python module) walberla_cpp.so in "apps/pythonmodule" so that you can use walberla from python.
WALBERLA_BUILD_WITH_CUDA	OFF	Enables/Disables support to run waLBerla on NVIDIA GPUs.
WALBERLA_BUILD_WITH_HIP	OFF	Enables/Disables support to run waLBerla on AMD GPUs.

For a list of all switches, see CMakeLists.txt in the root source folder.

Building waLBerla with Python

There are multiple ways for waLBerla to interact with Python: first a waLBerla C++ application can be built with Python support such that it can be scripted through the config file. In addition to the normal text-based config, such a C++ app can also be called with a Python script that returns configuration options and optionally installs hooks for e.g. geometry setup, post-processing or steering. This mode can be enabled by the CMake variable WALBERLA_BUILD_WITH_PYTHON.

While in this first option the driving code is C++, the second option exports most of waLBerlas functionality as a Python module that can be imported from a regular Python script. Thus the application itself can be written in Python. To build and install the waLBerla Python module enable WALBERLA_BUILD_WITH_PYTHON. Then run 'make pythonModule' to build and 'make pythonModuleInstall' to install the module in your current environment. The python coupling is build up on pybind11 entirely. pybind11 provides a lightweight header only solution for that. Thus there is no need to install additional software since pybind11 is shipped with waLBerla as a submodule. The integration happens automatically when waLBerla is build with python.

The third option is code generation using pystencils and lbmpy and is covered in the tutorial section of waLBerla.

Setup of Integrated Development Environments

Eclipse

If you use eclipse (http://www.eclipse.org/) for development, you can use the provided files in "utilities/eclipse" to setup your environment. For details see Setup Eclipse

Visual Studio

If you use Visual Studio (https://www.visualstudio.com/) for development, add the appropriate generator flag when running CMake for the first time.

  # create a separate build directory
  cd walberla
  mkdir build
  cd build
  
  # set up the build system for Visual Studio
  cmake -G "Visual Studio 14 2015 Win64" ..
  # find other versions at https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators

  # modify the configuration if necessary 
  ccmake .       # or alternatively "cmake-gui . "

Now you can open the file walberla.sln in Visual Studio.

Xcode

If you use Xcode (https://itunes.apple.com/app/xcode/id497799835) for development, add the appropriate generator flag when running CMake for the first time:

  # create a separate build directory
  cd walberla
  mkdir build
  cd build
  
  # set up the build system for Xcode
  cmake -G "Xcode" ..

  # modify the configuration if necessary 
  ccmake .       # or alternatively "cmake-gui . "

Now you can open the file walberla.xcodeproj.