 |
HyTeG
Matrix-Free Finite Elements
|
|
HyTeG
Matrix-Free Finite Elements
|
HyTeG (Hybrid Tetrahedral Grids) is a C++ framework for extreme-scale matrix-free finite element simulations strong focus on geometric multigrid.
For detailed information and references have a look at the documentation.
To build HyTeG, clone the GitLab repository via:
$ git clone --recurse-submodules https://i10git.cs.fau.de/hyteg/hyteg.git
The option --recurse-submodules is required and will automatically initialize and clone waLBerla, Eigen and hyteg-operators as git submodules (details below).
Create a build directory and invoke cmake:
$ mkdir hyteg-build $ cd hyteg-build $ cmake ../hyteg
CMake will then produce Makefiles for the included tests and applications. To build and run an application (e.g. a tutorial on isoviscous convection) invoke:
hyteg-build $ cd tutorials/07_IsoviscousConvectionAnnulus hyteg-build/tutorials/07_IsoviscousConvectionAnnulus $ make hyteg-build/tutorials/07_IsoviscousConvectionAnnulus $ ./IsoviscousConvectionAnnulus
... or for a parallel run:
hyteg-build/tutorials/07_IsoviscousConvectionAnnulus $ mpirun -np 4 ./IsoviscousConvectionAnnulus
Required:
Automatically cloned via git submodules (NO need to install/download/clone these manually):
Optional:
-DHYTEG_BUILD_WITH_ADIOS2=yes, version >= 2.9.2)-DHYTEG_BUILD_WITH_PETSC=yes)-DHYTEG_BUILD_WITH_TRILINOS=yes)-DHYTEG_BUILD_WITH_MPFR=yes)The builds are configured with standard CMake commands and arguments (starting with CMAKE_<...>) and there are several additional configuration options from HyTeG (starting with HYTEG_<...>) and inherited from waLBerla (starting with WALBERLA_<...>).
To pass options via the commandline, prepend -D to the options, like, e.g., cmake -DHYTEG_BUILD_WITH_PETSC=yes.
The most relevant options are listed below, with defaults in parentheses:
CMAKE_BUILD_TYPE (Release)
Standard CMake build types. Make sure to build in release mode when running applications and in debug for debugging (many asserts help debugging that are disabled in relase mode).
HYTEG_BUILD_WITH_PETSC (no)
Attempts to find a PETSc installation and enables fast sparse solvers (mostly relevant for multigrid coarse grid solvers) and for debugging.
HYTEG_BUILD_WITH_TRILINOS (no)
Same as for PETSc but with less support.
HYTEG_BUILD_WITH_ADIOS2 (no)
Finds and enables the ADIOS2 library if installed for efficient parallel I/O.
HYTEG_TERRANEO_MODULE (no)
Builds the shipped TerraNeo module for large-scale Geodynamics simulations. Details below.
HYTEG_DOWNLOAD_BOOST (no)
Downloads the C++ boost (header-only) library which is required for the TerraNeo module for instance and required if not found automatically.
WALBERLA_OPTIMIZE_FOR_LOCALHOST (yes)
Optimizes the build for the present architecture (for instance to enable vector intrinsics if the instruction set is available).
TerraNeo is a module of HyTeG that is providing functionality for running mantle convection models from Geodynamics. As this is a specialised application, the module is not built by default. In order to compile the corresponding sources, tests and apps (re)run CMake with the following option
-DHYTEG_TERRANEO_MODULE=yes
Please note that the module depends on Boost library, which is a header-only library.
CMake will search for installed Boost libraries. Should these not be found, you can tell it to download them also by setting
-DHYTEG_DOWNLOAD_BOOST=yes
The HyTeG Operator Generator (HOG) is a python library for the automated generation of matrix-free C++ compute kernels from a symbolic description of the weak form of a finite element operator.
To avoid having users of HyTeG generate (or implement) their required kernels from scratch, many generated and optimized operators are available under src/hyteg_operators and src/hyteg_operators_composites. src/hyteg_operators is a git submodule that is cloned automatically from the hyteg-operators repository.
For specific needs, additional operators can be generated from the scripts therein or directly using the HOG. Our preprint (arXiv:2404.08371) provides background information on its design and performance analysis.
Our documentation page provides additional documentation beyond this README, such as tutorials, API reference, etc.
Consult the tutorial programs under tutorials/ and the generated documentation to get started with the software.
See also the publications below for more in-depth discussion of applications, scalability, and results computed with HyTeG.
For an overview of the TerraNeo project, refer to the corresponding site.
If you are interested in more background information or are looking for a way to cite us, a list of articles is found below. If in doubt, cite the first article.
Overview:
Finite element data structures:
Multigrid for Stokes
Eulerian-Lagrangian methods
Performance engineering ...
... and kernel generation
TerraNeo
Surrogates
To contribute, you need an account for this GitLab instance. Please contact Dominik Thönnes dominik.thoennes@fau.de for details.
To keep our code consistently formatted, we use ClangFormat. There is a .clang-format file located in the root directory where all the formatting rules are documented. The rules can be automatically applied by using:
clang-format -i $FileName
A merge request (MR) can be in three different states:
Due to the large amount of generated files it can be advisable to activate ccache. To do so use the CMake setting
-DCMAKE_CXX_COMPILER_LAUNCHER=ccache
See also this StackOverflow answer.
Nils Kohl nils.kohl@lmu.de or Dominik Thönnes dominik.thoennes@fau.de.
This project is licensed under the GNU General Public License v3.0 or later.
Artwork by Manuel Weimann.
1.10.0