Peano is an open source framework for solvers on dynamically adaptive Cartesian meshes. Its core is written in C++, but many tools around it are written in Python. Peano is based upon the fact that spacetrees, a generalisation of the classical octree concept, yield a cascade of adaptive Cartesian grids. Consequently, any spacetree traversal is equivalent to an element-wise traversal of the hierarchy of the adaptive Cartesian grids. The software Peano realises such a grid traversal and storage algorithm, and it provides hook-in points for applications performing per-element, per-vertex, and so forth operations on the grid. It takes care of mesh management, data storage, domain decomposition and the mesh traversal, and it provides interfaces for dynamic load balancing, sophisticated geometry representations, and other features. Peano is free software and currently available in its fourth generation.

ExaHyPE 2	MGHyPE	ExaParty
ExaGRyPE	ExaSeis

On top of Peano, we have created multiple extensions which use this meshing infrastructure for particular application domains: hyperbolic PDE solvers (ExaHyPE 2), multigrid solvers (MGHyPE) and SPH (ExaParty, formerly known as Swift 2). The architecture page provides an overview including some illustrations. The extensions are tools that allow you to write simulations for your particular domain. They are typically not "ready to use" products, even though some of them can almost be used as such.

On top of these extensions, we in return implement various applications. ExaGRyPE (numerical general relativity) and ExaSeis (seismology) are popular examples. You find more applications in the respective subdirectories.

Peano (with any extension) is not a code. It is a tool to build your code. However, some of the applications built on top of Peano with all its toolboxes and extensions provide "ready to use" options. All components are integrated into one repository, one code base, and documented on these pages.

Getting Peano

Peano is hosted on the GitHub. We do not provide regular snapshots. Instead, clone the repository and use the latest version of the default branch p4:

git clone -b p4 https://github.com/tobiasweinzierl/peano.git

Tagged versions are listed under Tags and Releases. After that, follow the installation guide. For HPC systems and reproducible environments, we also maintain Spack packages, Dockerfiles and Apptainer definition files.

Content

Extensions
The C++ core

This is the documentation of Peano, generated automatically through Doxygen. The latest version is published at tobiasweinzierl.github.io/peano. To build it locally, run

doxygen documentation/Doxyfile

from the repository root. The output is written to doxygen-html/html. Peano comprises the core Peano 4 modules, the Python API, and a set of Peano extensions as well as benchmarks. The most important extensions at the moment are ExaHyPE 2, MGHyPE (our multigrid and PETSc toolkit) and ExaParty.

Citing Peano

Most users work with Peano through one of its Python APIs. These generate the glue code and a makefile, plus a Readme file which lists the Peano components that your code uses and the papers to cite for each of them. Please consult this file when you publish results.

If you want to cite Peano in general, please use

@article{Weinzierl:2019:Peano,
  author  = {Weinzierl, Tobias},
  title   = {The Peano Software---Parallel, Automaton-based, Dynamically Adaptive Grid Traversals},
  journal = {ACM Transactions on Mathematical Software},
  volume  = {45},
  number  = {2},
  articleno = {14},
  year    = {2019},
  doi     = {10.1145/3319797}
}

The file CITATION.cff in the repository root holds the citation metadata of the software itself, including the list of contributors.

Contributing, code of conduct and licence

Contributions are welcome and very much appreciated. If you want to merge your work into the main code base, contact us and we will give you write access to the repository. The contribution guide CONTRIBUTING.md in the repository root and the developer guidelines provide more details. We follow a code of conduct (CODE_OF_CONDUCT.md). Please follow its rules when participating in our community.

Peano is released under a modified BSD licence. The full terms are in the file LICENSE in the repository root.

Peano has been awarded the SQAaaS silver badge for software.

Recent updates

History

Peano is currently available in its fourth generation. The development of the original set of Peano codes started around 2002. 2005-2009, these codes were merged into one Peano kernel (2nd generation). In 2009, a complete reimplementation of the kernel started with special emphasis on reusability, application-independent design and the support for rapid prototyping. This third generation of the code ended around 2019 when we released the ExaHyPE code - a hyperbolic equation system solver engine which uses Peano's AMR meshes. The documentation discusses Peano 4, which reuses ideas and lessons learned from Peano 3 as well as lots of code building blocks, but can be seen as a major rewrite starting from scratch.

Peano has been the code base for multiple projects over the past years. One of them is ExaHyPE. The first generation of ExaHyPE has been a stand-alone project using Peano as one required library or framework out of many. Peano had been an external (git) dependency. The second generation, ExaHyPE 2, is merged into Peano as an extension. This document therefore covers ExaHyPE 2, too.