MGHyPE - Hitchhiker's guide

This documentation is autogenerated from ./tutorials/mghype/hitchhikers-guide.ipynb. Once you clone the Peano repository, please work against this notebook or study Peano's generic description how to generate web docu from Jupyter notebooks.

This tutorial runs through the basic steps of any multigrid application. For this, we assume that you have followed the installation instructions already. We furthermore assume that the following extensions have been added: –enable-blockstructured –enable-particles –enable-loadbalancing –enable-finiteelements –enable-mghype –enable-exaparty –enable-exahype If you have a parallel code, you furthermore need –enable-loadbalancing This is for domain decomposition as we discuss later. Typically, we kick off with a new director for our project. Within this directory, we start with a plain Python script. In this guide, we work with a Jupyter notebook rather than a script. MGHyPE codes need to know where to find the MGHyPE and Peano Python sources. For this, we can either add the Python sources to our environment, or export the path variable prior to invoking our script/kicking off our Jupyter notebook, or we set the path hard-coded in our script. To be honest, this last approach is likely the least elegant one, as it hard-codes the pathes, but it works:

import sys, os
 
sys.path.insert(0, os.path.abspath("../../python/"))
sys.path.insert(0, os.path.abspath("../../src/"))

Our code atm is not super-clean. On the long run, we want to hold all codes, i.e. C++ and Python, within the src directory. For historical reasons, we still have the C++ code mainly in src, and the majority of the Peano code base in python. Only the multigrid Python ingredients are already moved over into src.

Once we have ensured that all pathes are correct, every project built with MGHyPE starts with the same imports:

import peano4.api, mghype

An MGHyPE project and its lowering into a Peano project

Every MGHyPE project defines a sequence of lowering steps. That is, we start with an MGHyPE project object. This represents the domain level, where we do the math. After that we lower this project into a Peano project. This is a technical representation (still in Python) of the arising algorithm, i.e. something that represents the actual code base realising our domain knowledge. Then we ask Peano to lower this project into native C++ code plus a Makefile.

Lowering process

The term lowering stems from the compiler community where they use it to argue about different domain-specific languages and their abstraction levels.

project = mghype.matrixfree.api.Project( project_name = "MyProject", 
                              namespace = [ "tutorials", "mghype" ]
                            )

This creates the domain-specific project. What follows is the lowering. This lowering happens at the end of the setup script typically. We demonstrate it once here to explain the process, even though this will give us a totally empty meaningless project, as we haven't yet added any domain-specific logic:

project.set_Peano4_installation( "../..", peano4.api.output.CompileMode.Asserts )
 
peano4_project = project.generate_Peano4_project()
peano4_project.generate()

We first get some output that stems from the set_Peano4_installation() call. This one parses all the flags you handed into CMake or the configure script, respectively, and picks them up. It also looks which static libraries have been built and so forth. So from hereon, the project "knows" what your installation looks like. It will also run some primitive sanity checks to see if all the required extensions are activtated.

Once completed, we lower the domain-specific object into a Peano 4 object. We can still add further content on this abstraction level (e.g. external libraries can be added here), but eventually we call generate(). This makes the code dump a lot of glue file which is at this point largely empty, as we haven't added any functionality yet. Later on, the code will automatically befill them with something meaningful. We end up with a complete C++ code base with all of our functionality plus a plain old Makefile to build our actual code:

!ls

shows us that we now have a Makefile, which we can either use on the command line, or we trigger the make from through a Python subprocess call. The generated code that is now scattered over all the generated subdirectories follows the generic Architecture of any code built on top of Peano:

System architecture

A domain-specific code sits on top of some extensions plus the Peano core, and all of the components use a common technical architecture. Third-party libraries are either hidden by the tarch, or they are plugged into the domain-specific code. We don't use any so far.

Add the functionality

Every single multigrid project adds solvers before it lowers the project into a Peano 4 project, and also sets some simulation parameters:

cube_size = 1.0
dimensions = 3
project.set_global_simulation_parameters(
  dimensions            = dimensions,
  offset                = [ 0.0       for _ in range(dimensions) ],
  domain_size           = [ cube_size for _ in range(dimensions) ],
  plot_after_each_mesh_sweep  = True,
)

You obviously have to do this prior to the lowering into C++. And then there's the actual solver missing. That is, at the moment nothing will happen if you compile this project.

Visualisation

Peano writes its own bespoke data file format. There are some scripts delivered to convert them into VTK which you can load into Paraview or VisIt, e.g. A lot of applications also provide their own scripts to analyse the output. In theory, you can embed all of this postprocessing into Jupyter notebooks, too. With Paraview, this can be a little bit fiddly. With other postprocessing, the normal workflow is that you build the code (see remark on Make above), then you run the code on the terminal through the Python notebook (cmp the use of the ls command above) and you pipe the outcome into a text file. You can then invoke the data postprocessing scripts of your choice directly within the notebook on the dumped file and plot the outcome in-situ. We will look into this in a minute.

Exercises

(1) Run through the steps above and then compile the arising code. Peano's project offers a function to this through its API. If you work with Jupyter notebooks, you can also do it directly from within the notebook:

!make

(2) Make an ls on the directory and then run the executable:

(3) The code will dump quite a lot of output. For longer runs, we will want to filter out these dumps. It is therefore time to study the page Logging, tracing, statistics, profiling and assertions of the tarch documentation. MGHyPE is ready to use such a file - just create a log filter file called mghype.log-filter in the directory and modify it accordingly. If you search the repository, you will see a lot of example log files. You don't have to write one from scratch. Just copy it over and modify it. Rerun the code.

(4) Finally, search for outputs. There are no outputs (yet). This makes sense: After all, we haven't added a solver so far. Time to continue with the next tutorial.