README.md 4.37 KB
Newer Older
1
2
# waLBerla

Dominik Thoennes's avatar
Dominik Thoennes committed
3
4
5
6
7
8
9
10
waLBerla (widely applicable Lattice Boltzmann from Erlangen) is a massively
parallel framework for multi physics applications. Besides its original
objective, Lattice Boltzmann solvers for hydrodynamics, it now contains
modules for other applications like Multigrid and rigid body dynamics
as well. Great emphasis is placed on the interoperability between the modules
in particular the fluid-particle coupling.
It scales from laptops to current and future supercomputers while maintaining
near-perfect efficiency.
11

12
See https://www.walberla.net/ for more information and a showcase of applications.
13
14
15
16

## Documentation and Tutorials

Documentation for the C++ framework is available in
Dominik Thoennes's avatar
Dominik Thoennes committed
17
18
[Doxygen](http://walberla.net/doxygen/index.html), while the Python interface
is documented in [Sphinx](http://walberla.net/sphinx/index.html).
19
20
21

## Getting started

22
23
The minimum requirements are a C++17-compliant compiler (e.g. GCC or Clang)
and the [CMake](http://www.cmake.org)
24
build system. Furthermore, you need an MPI library (like
Dominik Thoennes's avatar
Dominik Thoennes committed
25
26
27
[Open MPI](http://www.open-mpi.org)) if you want to make use of parallel
processing capabilities. All of these dependencies are typically available in
your operating system's package manager.
28
29
30
31
32
33

### CMake

The typical steps, assuming your are in the waLBerla source directory, are:

- `mkdir build; cd build` create a build directory and change into it
Jonas Plewinski's avatar
Jonas Plewinski committed
34
- `cmake ..` call CMake with the waLBerla source directory as an argument
35
36
37
38
39
40
41
42
43
44
45
- `make` build waLBerla

To specify a CMake option you need to use `-D(Option)=(Value)`. For example to set the C++ compiler one can use:
`cmake -DCMAKE_CXX_COMILER=clang++`

To list and modify the CMake options the `ccmake` tool can be used. Just call `ccmake .` in your **build** directory to see and change the
CMake options and variables.

Some important CMake variables:

- `WALBERLA_BUILD_WITH_CODEGEN` Enable pystencils code generation"
Dominik Thoennes's avatar
Dominik Thoennes committed
46
- `Python_ROOT_DIR` Specify the directory of the `python` executable. e.g. `~/miniconda/bin/`
Jonas Plewinski's avatar
Jonas Plewinski committed
47
- `MPI_HOME` Specify the base directory of the MPI installation.
48
49
50
- `WALBERLA_BUILD_WITH_PYTHON` Support for embedding Python
- `WALBERLA_BUILD_WITH_CUDA` Enable CUDA support

Jonas Plewinski's avatar
Jonas Plewinski committed
51
For a full list of CMake Option see the [CMakeLists.txt](CMakeLists.txt) file or use `ccmake` as described above.
52
53
54

### Codegen and Python

Jonas Plewinski's avatar
Jonas Plewinski committed
55
To use the `lbmpy`/`pystencils` code generation please install the packages with e.g. `pip3 install lbmpy` and specify the correct python
56
57
58
59
environment when calling CMake.

In previous versions of CMake one could use `PYTHON_EXECUTABLE` or `PYTHON_ROOT_DIR` (all upper case) to specify the python executable or
the directory. This does **NOT** work anymore. Please use `Python_ROOT_DIR`.
60
61
62
63
64
65

## Get involved

### Contributing

Please submit all code contributions on our
Dominik Thoennes's avatar
Dominik Thoennes committed
66
67
[GitLab](https://i10git.cs.fau.de/walberla/walberla). To get an account, please
sign and submit the [contributor license agreement](CONTRIBUTING.txt).
68
69
70
71
72
73
74
75
76
77
78
79

### Support

While we currently do not have a mailing list, any questions can be asked via
the [Issue Tracker](https://i10git.cs.fau.de/walberla/walberla/issues).

## Authors

Many thanks go to waLBerla's [contributors](AUTHORS.txt)

### Please cite us

Michael Kuron's avatar
Michael Kuron committed
80
If you use waLBerla in a publication, please cite the following articles:
81

82
Overview:
Dominik Thoennes's avatar
Dominik Thoennes committed
83
84
- M. Bauer et al, *waLBerla: A block-structured high-performance framework for
  multiphysics simulations*. Computers & Mathematics with Applications, 2020.
85
  https://doi.org/10.1016/j.camwa.2020.01.007.
Christoph Rettinger's avatar
Christoph Rettinger committed
86

87
Grid Refinement:
Dominik Thoennes's avatar
Dominik Thoennes committed
88
89
- F. Schornbaum and U. Rüde, *Massively parallel algorithms for the lattice boltzmann
  method on nonuniform grids*. SIAM Journal on Scientific Computing, 2016.
90
  https://doi.org/10.1137/15M1035240
Christoph Rettinger's avatar
Christoph Rettinger committed
91
92

LBM - Particle Coupling:
Dominik Thoennes's avatar
Dominik Thoennes committed
93
94
- C. Rettinger and U. Rüde, *A comparative study of fluid-particle coupling methods for
  fully resolved lattice Boltzmann simulations*. Computers & Fluids, 2017.
95
  https://doi.org/10.1016/j.compfluid.2017.05.033
Christoph Rettinger's avatar
Christoph Rettinger committed
96

97
MESA-PD:
Dominik Thoennes's avatar
Dominik Thoennes committed
98
99
- S. Eibl and U. Rüde, *A Modular and Extensible Software Architecture for Particle Dynamics*.
  Proceedings Of The 8Th International Conference On Discrete Element Methods.
100
  https://mercurylab.co.uk/dem8/full-papers/#page-content
Christoph Rettinger's avatar
Christoph Rettinger committed
101

102
Carbon Nanotubes:
103
- G. Drozdov et al, *Densification of single-walled carbon nanotube films:
Dominik Thoennes's avatar
Dominik Thoennes committed
104
105
  Mesoscopic distinct element method simulations and experimental validation*.
  Journal of Applied Physics, 2020. https://doi.org/10.1063/5.0025505
106
107
108

## License

Jonas Plewinski's avatar
Jonas Plewinski committed
109
waLBerla is licensed under [GPLv3](COPYING.txt).