xref: /honee/README.md (revision 29175549b319f8d8abc6e68e5bbc4975840c2f4a) 
1# HONEE
2
3[![GitLab-CI](https://gitlab.com/phypid/honee/badges/main/pipeline.svg?key_text=GitLab-CI)](https://gitlab.com/phypid/honee/badges/main/pipeline.svg?key_text=GitLab-CI)
4[![BSD-2-Clause](https://img.shields.io/badge/License-BSD%202--Clause-orange.svg)](https://opensource.org/licenses/BSD-2-Clause)
5[![Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-orange.svg)](https://opensource.org/license/Apache-2-0)
6[![Documentation](https://img.shields.io/badge/Documentation-latest-blue.svg)](https://honee.phypid.org)
7[![Code Coverage](https://gitlab.com/phypid/honee/badges/main/coverage.svg)](https://gitlab.com/phypid/honee/-/commits/main)
8
9<!-- abstract -->
10HONEE (High-Order Navier-stokes Equation Evaluator, pronounced "honey") is a fluids mechanics library based on [libCEED](https://libceed.org) and [PETSc](https://petsc.org) with support for efficient high-order elements and CUDA, ROCm, and Intel GPUs.
11
12HONEE uses continuous-Galerkin stabilized finite element methods, namely SUPG, with a focus on scale-resolving simulations.
13Effort is made to maintain flexibility in state variable choice, boundary conditions, time integration scheme (both implicit and explicit), and other solver choices.
14High-order finite elements are implemented in an analytic matrix-free fashion to maximize performance on GPU hardware, while matrix assembly may also be used if desired.
15
16# Getting Started
17<!-- getting-started -->
18
19## Download and Install
20
21A local build and installation provides greater control over build options and optimization.
22HONEE is open-source and can be downloaded from [the HONEE repository on GitLab](https://gitlab.com/phypid/honee).
23
24```console
25$ git clone https://gitlab.com/phypid/honee
26```
27
28### Prerequisites
29
30HONEE is based upon libCEED and PETSc.
31
32#### libCEED
33
34HONEE requires libCEED's `main` development branch, which can be [cloned from Github](https://github.com/CEED/libCEED).
35
36```console
37$ git clone https://github.com/CEED/libCEED
38$ make -j8 -C libCEED
39```
40
41The above will be enough for most simple CPU installations; see the [libCEED documentation](https://libceed.org/en/latest/gettingstarted/#) for details on using GPUs, tuning, and more complicated environments.
42
43#### PETSc
44
45HONEE requires PETSc's `main` development branch, which can be [cloned from GitLab](https://gitlab.com/petsc/petsc).
46
47```console
48$ git clone https://gitlab.com/petsc/petsc
49```
50
51Follow the [PETSc documentation](https://petsc.org/main/install/) to configure and build PETSc.
52It is recommended that you install with [CGNS library](https://cgns.github.io/) support using `--download-hdf5 --download-cgns`.
53
54### Building
55
56The environment variables `CEED_DIR`, `PETSC_DIR`, and `PETSC_ARCH` must be set to build HONEE.
57
58Assuming you have cloned the HONEE repository as above, build using:
59
60```console
61$ export CEED_DIR=[path to libCEED] PETSC_DIR=[path to PETSc] PETSC_ARCH=[PETSc arch]
62$ make -j8
63```
64
65To run a sample problem, run:
66
67```console
68$ build/navierstokes -options_file examples/gaussianwave.yaml
69```
70
71To test the installation, use
72
73```console
74$ make test -j8
75```
76
77### Demo Build
78
79Here we walk through a complete, step-by-step demonstration of building and installing HONEE and its dependencies.
80This will be aimed at the minimal-viable install; better performance may be gained from different configurations, compiler flags, etc.
81As such, it will only target a CPU installation of HONEE.
82
83Generally, we assume that the system you're installing on has a pre-existing installation of MPI loaded into the environment.
84If this is not true, you can add a `--download-mpich` flag to PETSc's configuration command to have PETSc build and install MPICH.
85
86```console
87$ export CC=mpicc CXX=mpicxx # PETSc and libCEED will use these environment variables to select compiler
88$ mkdir honee_build_dir
89$ cd honee_build_dir
90$ ## Build PETSc
91$ git clone https://gitlab.com/petsc/petsc
92$ cd petsc
93$ export PETSC_DIR=$PWD PETSC_ARCH=arch-linux-c-opt
94$ ./configure \
95  --with-fc=0 \
96  --download-f2cblaslapack \
97  --download-hdf5 \
98  --download-cgns \
99  --with-debugging=0 \
100  COPTFLAGS='-O3 -g -march=native' \
101  CXXOPTFLAGS='-O3 -g -march=native'
102$ make -j
103$ ## Build libCEED
104$ cd ..
105$ git clone https://github.com/CEED/libCEED
106$ cd libCEED
107$ make -j
108$ ## Build HONEE
109$ cd ..
110$ git clone https://gitlab.com/phypid/honee
111$ cd honee
112$ make -j
113```
114
115<!-- citing -->
116
117## License
118
119HONEE is licensed under either of
120
121 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
122 * BSD-2-Clause license ([LICENSE-BSD](LICENSE-BSD) or https://opensource.org/licenses/BSD-2-Clause)
123
124at your option.
125