New LB/EK implementations on the python branch

[Jean-Noël Grad]

Dear users,

As you know, the ESPResSo team has been working for the past few years 
on replacing the original ESPResSo implementations of the 
lattice-Boltzmann method (LB) and advection-diffusion-reaction equation 
(EK) with waLBerla, a high-performance library for lattice-based 
methods. Today, we are making the switch on the python branch. This is 
going to affect the way you build and use the software, so please read 
on if you are using the development version of ESPResSo.

Build system changes
====================

This affects all users. The list of ESPResSo features has changed, 
therefore your myconfig.hpp file might no longer work. In addition, new 
CMake flags have been introduced. We recommend that you use a fresh 
build folder to avoid dealing with CMake error messages, and that you 
adapt your myconfig.hpp if you didn't use the default one.

If you are not a LB or EK user, nothing else will affect you, and you 
can stop reading now.

LB and EK users need to pass option -DESPRESSO_BUILD_WITH_WALBERLA=ON to 
build ESPResSo with the new LB and EK implementations. The waLBerla 
dependency will be automatically downloaded by CMake and built alongside 
ESPResSo. We currently pin the waLBerla version to a specific commit at 
the CMake level. This commit will periodically get updated, whenever 
waLBerla gets bugfixes that are relevant to ESPResSo. When this happens, 
you will need to delete the "_deps" folder in the build directory to 
trigger a new download.

When building ESPResSo on a workstation with restricted internet access, 
for example a university cluster or a HPC system, CMake might find 
itself unable to download the waLBerla dependency. You can always 
manually edit the URL of the waLBerla project in the top-level 
CMakeLists.txt file of ESPResSo and replace it with an absolute path to 
a local clone of waLBerla, as explained in the user guide section 
2.4.5.2 [1].

LB users can pass an extra option -DESPRESSO_BUILD_WITH_WALBERLA_AVX=ON 
to build LB kernels using SIMD instructions on microprocessors that 
support AVX2 (run `lscpu | grep avx2` to check if your workstation 
supports it). The SIMD kernels have better performance over the regular 
kernels, because the streaming and collision steps carry out the 
mathematical operations in batches of 4 values at a time (in 
double-precision mode) or 8 values at a time (single-precision mode) 
along the x-axis. EK users can pass an extra option 
-DESPRESSO_BUILD_WITH_WALBERLA_FFT=ON to include a Poisson solver for 
electrostatics, but this requires a local installation of the pfft 
library [2].

Script interface changes
========================

This only affects LB and EK users. The old LB and EK classes have been 
completely replaced by new classes called espressomd.lb.LBFluidWalberla 
and espressomd.electrokinetics.EKSpecies. The list of parameters differs 
significantly from previous ESPResSo releases, so you will need to 
double-check the documentation when adapting your scripts. Both methods 
take an espressomd.electrokinetics.LatticeWalberla object as argument 
that defines the agrid and ghost layer thickness. The LB implementation 
supports Lees-Edwards boundary conditions. VTK output is now written in 
multi-piece XML format. While ParaView can read those files just fine, 
parsing them with vtk.vtkXMLUnstructuredGridReader() is not 
straightforward. Use instead the new espressomd.io.vtk.VTKReader() parser.

There is currently no support for GPU-accelerated LB or EK. We are 
currently developing a LB GPU implementation and will make it available 
in a draft pull request in the next few months. There is currently no 
functionality to calculate forces exerted by the fluid on LB boundaries.

While the new LB and EK methods have been extensively tested by a small 
group of users and developers, it is not ready for a full release yet. 
As a part of the python development branch, it will be continuously 
improved and expanded by the community, with occasional API changes. 
Please bring our attention to issues by sending us feedback in GitHub 
tickets or on the mailing list, if the issue hasn't been described 
before. We also welcome code contributions.

Prototyping new LB and EK methods
=================================

The LB and EK kernels are based on waLBerla and are automatically 
generated from sympy symbols in a Python script. Please refer to the 
user guide sections 13.10 [3] resp. 14.6 [4] for instructions on how to 
modify the LB resp. EK kernels.

Best regards,
Jean-Noël Grad

Links:
[1] 
https://espressomd.github.io/doc/installation.html#cmake-subprojects-without-a-network-connection
[2] https://github.com/mpip/pfft
[3] https://espressomd.github.io/doc/lb.html#prototyping-new-lb-methods
[4] https://espressomd.github.io/doc/ek.html#prototyping-new-ek-methods