xref: /honee/README.md (revision 82a28dbf6f835b0288ae9e42adc91d80fb7eff1f) 
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 -C -j8 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<!-- citing -->
78
79## License
80
81HONEE is licensed under either of
82
83 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
84 * BSD-2-Clause license ([LICENSE-BSD](LICENSE-BSD) or https://opensource.org/licenses/BSD-2-Clause)
85
86at your option.
87