 |
Peano
|
|
Peano
|
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.
Peano's core is plain C++17/C++20 code. We however use a whole set of tools around it.
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.
We currently provide support for Autotools and CMake with Peano. After you have cloned the repository, you will have to to set up your installation using either of these two build systems. 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 or our PETSc multigrid environment.
autoconf, automake and libtool.Set up the configure environment:
libtoolize; aclocal; autoconf; autoheader; cp src/config.h.in . automake –add-missing
These steps should only be required once, unless you push major revisions to the development branch.
Next, type in
./configure –help
The --help option should give you some information about the available variants of Peano, its extensions and toolboxes.
I recommend that you start a first test without any additional flavours of Peano, i.e. to work with a plain ./configure call. Once the tests pass, I recommend that you add further options (IO) and/or parallelisation. Please note that the baseline configure is not sufficient for most applications, as it builds merely Peano's core libraries.
Besides Peano's toolboxes and extensions, compilers, linkers and both compiler and linker flags can be changed by resetting the corresponding environment variables (such as CXX or LDFLAGS or CCFLAGS) prior to the configure call. Alternatively, you can pass the variables to be used to configure through arguments (./configure CXX=icpc ..., e.g.). Please consult the --help output for details.
Most Linux tools prefer you to specify a dedicated installation directory via --prefix. For Peano, things are slightly different: Peano is a mere set of libraries, i.e. not "useful" per se. It is applications built on top of Peano that become tools that you might later want to install/deploy on your system. Therefore, I ship Peano with static libraries only, and most users work with the code in the download/installation directory. So no need to specify a proper installation directory via --prefix.
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.
Once you have compiled, I recommend that you run all tests using
make check
The call launches Peano's unit test, i.e. all the unit tests for the core plus the extensions that you have enabled.
I have written the test target such that it works out-of-the-box for non-MPI calls. If you have configured with --with-mpi, then the unit tests will fail. But this does not mean that the unit tests are broken. It is simply due to the fact that the Makefile's test target does not know that you have to use the mpirun prefix. To make a long story short: If you use MPI and you want to run the unit tests, you have to do so manually.
To run 2D and 3D tests individually, use
src/unittests/UnitTests2d src/unittests/UnitTests3d
You can run these builds with different core counts and also MPI support if you have compiled with MPI. The executables contain both node correctness tests and MPI ping-pong tests, i.e. you can both assess a valid build plus a working MPI environment.
Peano's Python front-end (API) is developed with Python 3. Python 2 is not supported.
The easiest way to install the Peano Python packages 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:
-e flag does). Otherwise, you'll have to re-install the packages every time something is changed.As an alternative to installing the packages, you can modify your Python path. 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.
Peano currently relies on the following Python packages/projects:
jinja2 for all the templated glue code. Most Linux distributions ship this one as
python3-jinja2
numpy for numeric operations. Most Linux distributions ship this one as
python3-numpy
sympy for the symbolic modelling of partial differential equations. Most Linux distributions ship it through
python3-sympy
matplotlib for plotting:
python3-matplotlib
Optional: Some scripts in the particles/swift2 make use of the Python HDF5 package:
python3-h5py
on GitHub.If you don't use Fortran in your own code, ignore this section.
Peano's core does not use any Fortran at all. However, some users use Fortran for their domain-specific programming. If you want to have a seemless integration of your particular Fortran choice through 's Python API, invoke ./configure ensuring that the Fortran variables—in particular the environment variable FC identifying the compiler—are properly set.
For many codes and the GNU Fortran compiler, you need the flag -fdefault-real-8. You can export FCFLAGS and make it contain this argument before you invoke configure. As the Peano's core does not use Fortran—it is only applications built on top of —you can redefine the flags later on.
Please find below a sample shell script for Autotools that will install Peano with ExaHyPE enabled. Here we use GCC and G++ as the C and C++ compiler, as well as OpenMP for the multithreading support. We also include some flags to suppress warnings.
Please find below a sample shell script for CMake that will install Peano with ExaHyPE enabled. Here we use GCC and G++ as the C and C++ compiler, as well as OpenMP for the multithreading support. All required flags are automatically added by CMake.
1.10.0