Installation

Table of Contents

• Dependencies and Prerequisites
  • Required
  • Optional
• Configure Peano
  • CMake
• Build
• Test
• Install
• Python Configuration
  • Package Installation
  • Manually Adding the Python Path
  • Python Dependencies
• Containers

Peano is typically acquired through a git clone.

You have to clone this archive first. We grant access free of charge, and the repository is public. However, we ask users to sign up for the software if they intend to push modifications to the code - which we very much appreciate. This way, we can report to funding agencies how frequently the software is used, and I also have at least some ideas about which application areas benefit from the software and where it is actively used and developed. If you do not intend to modify the core code base, you can just clone the code anonymously.

git clone https://gitlab.lrz.de/hpcsoftware/Peano.git

I still maintain the "old" Peano in the repository (version 3). However, we now work with the fourth generation of Peano (p4). Therefore, the default master is called p4.

Dependencies and Prerequisites

Peano's core is plain C++20/C++23 code. We however use a whole set of tools and extensions around it.

Required

• C++20/C++23-compatible C++ compiler.
• CMake 3.27 or newer.
• Python 3.11 or newer.
• MPI. MPI's multithreaded support is recommended.
• OpenMP for multithreading

Optional

• The Visualization Toolkit (VTK) if you want to use the built-in visualisation facilities.
• NVHPC, LLVM Clang, ROCm, AdaptiveCpp or Intel oneAPI for GPU offloading.
• HDF5.
• NetCDF.
• LIBXSMM.

You will also need Doxygen if you want to create HTML pages of the documentation yourself. Unless you work exclusively with the Peano core in C++, you will have to ensure that your Python installation meets all requirements (see remarks below).

We test and maintain Peano for Linux only. If you prefer Windows or MacOS, it should work as long as you provide the mandatory tools from above, but we won't be able to help. Peano is well-integrated with a number of third party tools, but these are all optional.

Configure Peano

Peano is compiled using, CMake, after you have cloned the repository, you will have to to set up your installation using it. This will allow you to build the Peano core libraries and is a step required before you use any application or tool built on top of Peano such as ExaHyPE.

CMake

Using CMake is relatively simple. First, we create a new directory. Typically it is recommended to create a new build directory within the Peano repository's clone:

mkdir build
cd build
cmake ..

Alternatively, you can also create a new build directory anywhere else on your workstation:

mkdir build
cd build
cmake Peano-src

where Peano-src points to the checkout.

Next, you might want to type in cmake help but this might be a little bit overwhelmning. Try

ccmake Peano-dir

instead, where you replace Peano-dir with the directory of Peano's sources. Handing in .. does the job for most of the setups.

This might be the right time to look ahead and study the tutorials of the codes you wanna use. All of them need different toolboxes and extensions. ExaHyPE, for example, requires you to activate BLOCKSTRUCTURED, LOADBALANCING and EXAHYPE at least (PARTICLES is recommended).

Configure by pressing c and then q to finish the configuration. Next, continue with building the code.

Build

Once the configuration has been successful, a simple

make

should build the core. It also builds some examples and all the extensions and toolboxes you have manually enabled. All of these go into static libraries. The code is not small and you thus might prefer

make -jx

with x being the number of parallel builds to use.

Test

Once you have compiled, we recommend that you run all tests using

make test

for CMake.

The call launches Peano's unit test, i.e. all the unit tests for the core plus the extensions that you have enabled.

Good time to stop. Jump straight into one of the tutorials if you want to. If things don't work (Python complains for example), return to this page and read through the text below. But maybe it is the right time just to play around with code.

Install

CMake allows to install all targets in a self-contained bundle. You need to specify the installation path by amending the CMAKE_INSTALL_PREFIX variable:

mkdir build
cd build
cmake Peano-src -DCMAKE_INSTALL_PREFIX=<install_path>
make install

Peano is not a piece of software that you use as a black box. It is an engine that you use to write your own code. You can install Peano and its extensions. That means basically that you move its static libraries to a separate directory. But there is no such thing as a Peano application.

Python Configuration

Peano's Python front-end (API) is developed with Python 3. Python 2 is not supported.

Package Installation

Our code base relies on several Python packages. There's a requirements specification file which you can use to ensure that all requirements are met:

pip install -r requirements.txt

where the requirements.txt file resides within Peano's root directory. Depending on your system, you might have to use pip3 or install the packages in your user space by adding --user.

The easiest way to install the Peano Python packages and to set the Python path directly is to navigate to myPeanoDirectory/ first (you're in the right place if you see the pyproject.toml file), and then run

pip3 install -e .

to install the packages.

Note:

• The Python path is set automatically to the respective Peano modules.
• It is strongly recommended to install the Python packages in editable mode (which is what the -e flag does). Otherwise, you'll have to re-install the packages every time something is changed.
• The packages are not, and likely will never be, available through PyPI or other official Python package distributions. It simply doesn't make sense for them to be published this way.

Manually Adding the Python Path

As an alternative to installing the packages, you can modify your Python path manually. There are multiple ways to do so. The standard way is to set the PYTHONPATH, e.g.:

export PYTHONPATH=$PYTHONPATH:myPeanoDirectory/python

This can even be done in the .bashrc. If you "install" the Peano Python packages this way, you will also need to manually install additional dependencies, as noted below.

Python Dependencies

Peano currently relies on the following Python packages/projects:

Jinja2
mpmath
numpy
matplotlib
scipy
sympy
h5py
vtk
VTUinterface
jupyter
ast-comments

Containers

• page_installation_with_spack
• Installation with Docker
• page_installation_with_apptainer