Introduction

What is Palabos?

The library Palabos offers a framework in C++ for fluid flow simulations with the lattice Boltzmann (LB) method. Originally conceived as a research tool for lattice Boltzmann models, the code has evolved into a general-purpose software for computational fluid dynamics. The programming interface is straightforward and offers an access to the rich world of lattice Boltzmann, even to and audience with restricted theoretical knowledge of this method. However, be aware that computational fluid dynamics is a difficult topic in itself. In spite of the apparent ease of the user interface, a tool like Palabos requires a certain level of know-how from the user in order to produce meaningful results.

A substantial amount of development time for Palabos went into formulating a general programming concept for LB simulation which offers an appropriate balance between generality, ease of use, and numerical efficiency. The difficulty of this task can be understood if one considers that the core ingredients of the LB method are guided by physical considerations rather than criteria from numerical analysis. As a consequence, it is straightforward to implement a LB code for a specific physical model, a rectangular-shaped numerical grid, and simple boundary conditions. However, any of the extensions of the code required for the implementation of practical problems in fluid engineering require careful considerations and a solid amount of programming efforts. It is frequent to find LB codes which implement one specific advanced feature (for example parallelism), but then find themselves in a too rigid shape to allow other extensions (for example coupling of two grids for multi-phase flows). To cope with this problem, the various ingredients of Palabos’ software architecture (physical model, underlying lattice, boundary condition, geometric domain, coupling between grids, parallelism) where largely developed as orthogonal concepts. It is for example possible to formulate a variant of the classical BGK collision model, say a MRT or entropic model, without awareness of the advanced software components of Palabos, and automatically obtain a parallel version of the code, or a multi-phase code based on the new model.

A central concept in Palabos are so-called “dynamics objects” which are associated to each fluid cell and determine the nature of the local collision step. Full locality of inter-particle collisions is a key ingredient of LB models, a fact which is acknowledged in Palabos by promoting the raw numerical efficiency of such model. Specific data structures are also available for non-local ingredients, for implementing for example specific boundary conditions or inter-particle forces in multi-phase models. It is however assumed that these components are more marginal. While their implementation is reasonably efficient, they have been excluded from the low-level number-crunching strategy of Palabos in favor of higher-level programming constructs. In practice, it has been observed that this approach is barely penalizing for the overall program performance, but substantially improves the readability of end-user programs.

The grid structure of the simulations is based on a multi-block approach. Each block behaves like a rudimentary LB implementation, while advanced software ingredients such as parallelism and sparse domain implementations are covered through specific interface couplings between blocks.

The C++ code of Palabos makes a massive use of genericicity in its many facets. Basically, generic programming is intended to offer a single code that can serve many purposes. On one hand, the code implements dynamic genericity through the use of object-oriented interfaces. One use of this is that the behavior of lattice sites can be modified during program execution, to distinguish for example between bulk and boundary cells, or to modify the fluid viscosity or the value of a body force dynamically. On the other hand, C++ templates are used to achieve static genericity. As a result, it is sufficient to write a single generic code for various 3D lattice structures, such as D3Q15, D3Q19, and D3Q27.

The intended audience for Palabos covers scientists and engineers with a background in LB modeling, or at least a solid background in computational fluid dynamics and a basic knowledge of lattice Boltzmann. The software is freely available under the terms of an open-source AGPLv3 license, a copy of which is printed in the appendix of this user guide. It is distributed under the hope that it will promote research in the field of LB modeling, and help researchers concentrate on actual physical problems instead of staying stuck in tedious software development. Furthermore, implementing new LB models in Palabos offers a simple means of promoting new models and exchanging the information between research groups.

Functionality covered by Palabos

Currently implemented

In short, the current release of Palabos covers the following ingredients:

Physics:

Incompressible Navier-Stokes equations, weakly compressible, non-thermal Navier-Stokes equations, flows with body-force term, thermal flows with Boussinesq approximation, single-component multi-phase fluids (Shan/Chen model), multi-component multi-phase fluids (Shan/Chen model), static Smagorinsky model for fluid turbulence.

Basic fluid models:

BGK, incompressible BGK, a given MRT model, regularized BGK, a given entropic model.

Straight-wall boundary conditions:

Zou/He, Inamuro, Skordos, regularized BC, simple equilibrium, bounce-back, periodic. All boundary conditions work for straight walls with interior/exterior corners, and can be used to implement a Dirichlet or Neumann condition for the velocity or the pressure. The bounce-back condition is also used for curved boundaries, represented by a stair-case shape.

Off-lattice boundary conditions:

GUO model, and generalized off-lattice boundary condition. Automatic, and massively parallel, voxelization of STL file and instantiation of off-lattice walls.

Particles:

Massively parallel (billions of particles are no problem on a parallel machine) simulation of passive scalars, or interacting particles.

Grid:

The implemented grids are D2Q9, D3Q13, D3Q15, D3Q19, and D3Q27. In all cases, the domain is either a regular matrix or a sparse domain, approximated by a multi-grid pattern.

Parallelism:

All mentioned models and ingredients are parallelized with MPI for shared-memory and distributed-memory platforms, including I/O operations.

Pre-processing:

The domain of a simulation can be constructed manually, or automatically from a corresponding STL-file.

Post-processing:

The code has the ability to save the data in ASCII or binary files or to directly produce GIF images. Furthermore, the data can be saved in VTK format and further post-processed with an appropriate tool. For better efficiency, Palabos can natively post-process data, producing streamlines and iso-surfaces.

Check-pointing:

At every moment, the state of the simulation can be saved, and loaded at a later point.

Under development:

The following features have been repeatedly requested by the community and are currently developed:

• Free-surface flow (will be soon released).
• Grid refinement.
• Thermal flows using lattices with extended neighborhoods.

Authors

Project supervision and core development are taken care of by Jonas Latt (FlowKit Ltd.+Universite de Geneve, Switzerland). Orestis Malaspinas (FlowKit Ltd.+Universite de Geneve, Switzerland) writes alternative LB collision terms (MRT, entropic), some of the boundary conditions, and coupled physical models (thermal, multi-phase). Free-Surface and multi-phase models are actively developed by Andrea Parmigiani (Universite de Geneve, Switzerland) and by Dimitrios Kontaxakis (FlowKit Ltd, Switzerland). Grid refinement is taken care of by Daniel Lagrava (Universite de Geneve, Switzerland). Many other people have contributed by writing code, thinking about programming concepts, or understanding some of the LB models for which the literature is sparse. We particularly mention, in alphabetical order, the contributions of Fokko Beekhof (Universite de Geneve, Switzerland), Bastien Chopard (Universite de Geneve, Switzerland), Mathias Krause (Rechenzentrum Karlsruhe, Germany), Switzerland), Bernd Stahl(Universite de Geneve, Switzerland).

Getting help

Installation instructions and a short overview of the code are provided in the section Getting started with Palabos. Additionally to the user guide, the following resources are available as a support for Palabos users:

The tutorial:

It is highly recommended, to get started, to work through Tutorial 1. The tutorial provides both an overview of high-level structures, and information on the way Palabos works internally.

The forum:

The forum is the right place to post questions which are not answered in the user guide or the FAQ, to exchange with other Palabos users, or to communicate with the Palabos authors.

The FAQ:

We try to frequently distill the essence from the forum questions, and to summarize the answers in the FAQ [As of the first Palabos release, there is nothing yet in the FAQ].

The automatic code documentation:

This guide is automatically generated from the source code, using the program Doxygen . It has little didactic value but offers detailed insight into the class hierarchies and the syntax of the function calls.