From 57c8f4d92e1e18dcef0f47e5602dbb1abbe35238 Mon Sep 17 00:00:00 2001 From: Dominik Thoennes <dominik.thoennes@fau.de> Date: Mon, 28 Feb 2022 19:37:30 +0100 Subject: [PATCH] extend Readme with cmake and python info --- README.md | 92 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 62 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index bca339ae9..b67fdf988 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,65 @@ # waLBerla -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. +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. See https://www.walberla.net/ for more information and a showcase of applications. ## Documentation and Tutorials Documentation for the C++ framework is available in -[Doxygen](http://walberla.net/doxygen/index.html), while the Python interface -is documented in [Sphinx](http://walberla.net/sphinx/index.html). +[Doxygen](http://walberla.net/doxygen/index.html), while the Python interface is documented +in [Sphinx](http://walberla.net/sphinx/index.html). ## Getting started The minimum requirements are a C++17-compliant compiler (e.g. GCC or Clang) and the [CMake](http://www.cmake.org) build system. Furthermore, you need an MPI library (like -[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. +[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. + +### 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 +- `cmake ..` call CMake with the waLBerla source directory as a argument +- `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" +- `Python_ROOT_DIR` Define the root directory of a Python installation. +- `MPI_HOME` Specify the base directory of the MPI installation.` +- `WALBERLA_BUILD_WITH_PYTHON` Support for embedding Python +- `WALBERLA_BUILD_WITH_CUDA` Enable CUDA support + +For a full list of CMake Option see the [CMakeLists.txt](CMakeLists.txt) file or use `ccmake as described above.` + +### Codegen and Python + +To use the `lbmpy`/`pystencils` code generation please install the packages with e.g. `pip install lbmpy` and specify the correct python +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`. ## Get involved ### Contributing Please submit all code contributions on our -[GitLab](https://i10git.cs.fau.de/walberla/walberla). To get an account, please -sign and submit the [contributor license agreement](CONTRIBUTING.txt). +[GitLab](https://i10git.cs.fau.de/walberla/walberla). To get an account, please sign and submit +the [contributor license agreement](CONTRIBUTING.txt). ### Support @@ -48,29 +75,34 @@ Many thanks go to waLBerla's [contributors](AUTHORS.txt) If you use waLBerla in a publication, please cite the following articles: Overview: - - M. Bauer et al, *waLBerla: A block-structured high-performance framework for - multiphysics simulations*. Computers & Mathematics with Applications, 2020. - https://doi.org/10.1016/j.camwa.2020.01.007. + +- M. Bauer et al, *waLBerla: A block-structured high-performance framework for multiphysics simulations*. Computers & Mathematics with + Applications, 2020. + https://doi.org/10.1016/j.camwa.2020.01.007. Grid Refinement: - - F. Schornbaum and U. Rüde, *Massively parallel algorithms for the lattice boltzmann - method on nonuniform grids*. SIAM Journal on Scientific Computing, 2016. - https://doi.org/10.1137/15M1035240 + +- F. Schornbaum and U. Rüde, *Massively parallel algorithms for the lattice boltzmann method on nonuniform grids*. SIAM Journal on + Scientific Computing, 2016. + https://doi.org/10.1137/15M1035240 LBM - Particle Coupling: - - C. Rettinger and U. Rüde, *A comparative study of fluid-particle coupling methods for - fully resolved lattice Boltzmann simulations*. Computers & Fluids, 2017. - https://doi.org/10.1016/j.compfluid.2017.05.033 + +- C. Rettinger and U. Rüde, *A comparative study of fluid-particle coupling methods for fully resolved lattice Boltzmann simulations*. + Computers & Fluids, 2017. + https://doi.org/10.1016/j.compfluid.2017.05.033 MESA-PD: - - 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. - https://mercurylab.co.uk/dem8/full-papers/#page-content + +- 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. + https://mercurylab.co.uk/dem8/full-papers/#page-content Carbon Nanotubes: - - G. Drozdov et al, *Densification of single-walled carbon nanotube films: - Mesoscopic distinct element method simulations and experimental validation*. - Journal of Applied Physics, 2020. https://doi.org/10.1063/5.0025505 + +- G. Drozdov et al, *Densification of single-walled carbon nanotube films: + Mesoscopic distinct element method simulations and experimental validation*. Journal of Applied Physics, + 2020. https://doi.org/10.1063/5.0025505 ## License -- GitLab