Reorganize psydac examples

[FrederikSchnack]

Hi Team, this PR fixes #170 .

I think the PR is in a good state for a review, the machinery seems to work quite well and the generated documentation looks nice. We can add more notebooks and examples over time.

New Examples

As discussed in the meeting, we proposed the following examples presented as jupyter notebooks:

• Define an equation symbolically, discretize it, compute some error norms, plot solution and error – Poisson 2D on a square with “Collela” mapping (Yaman)
• FEEC API multipatch – Maxwell 2D time harmonic (Frederik)
• FEM example: L2 projection (Martin)
• [ ] FEM example: geometric projection (Martin)
• Example with geometry file (Yaman)
• 3D example with VTK and Paraview (Elena)
• Get eigenvalues (FEEC) with SciPy (serial) (Frederik)
• Get eigenvalues with PETSc + SLEPc (parallel) (Elena)
• FEEC 3D vector potential (Julian): adapt new examples/vector_potential_3d.py to a notebook

Note: the geometric projections will be illustrated in a later PR, together with a discussion on the geometric nature of the (de Rham) conforming projections.

We can discuss these examples contents and allocation below.

Other todos:

• create tests using the new examples (should not take too long)
• expose notebooks to the documentation
• move multipatch examples in psydac/feec/multipatch/examples to examples/feec and remove the psydac/feec/multipatch folder altogether
• add feec example tests to CI testing
• move old examples to examples/old_examples
• move performance examples in performance to examples/performance
• fix some minor things in documentation
• move mpi test script.
• remove old examples?
• add tests to the other folders in examples/?

Getting the notebooks into the documentation

• We need to install psydac in the documentation CI. (Should the documentation be deployed by one of the test CIs?)
• All notebooks should have a cleared output, we could use nb-clean as a requirement similarly to in IGA-Python (and maybe also run it with the CI).
• The CI copy-pastes the notebooks + images into the doc folder
• nbsphinx (with ipykernel) can execute the notebooks and put them in the examples.rst toc.
• Should we put the assests of notebooks (e.g. pregenerated plots) in the examples folders or somewhere in the documentation?

Testing the notebooks

The notebooks get run by the documentation CI, so any errors lead to a failing build of the documentation.
We can additionally employ ipytest to check for explicit asserts (e.g. convergence errors) for example. I implemented this in the Poisson_non_periodic.ipynb notebook.
This is what a failing test looks like:

If the tests are passing, they are also written in the documentation, which looks like this:

Adding examples

You can try to keep a similar structure to the current notebooks in examples/notebooks. Before commiting new notebooks, please run

nb-clean clean --remove-empty-cells --remove-all-notebook-metadata examples/notebooks/new_notebook.ipynb

To see the generated documentation download the artifact from the docs CI summary and open it in your browser locally.

[campospinto]

I just added a temporary example to illustrate how to perform an L2 projection on a FEM space, with basic manipulations and visualizations in 2D.

At this stage this example is a work-in-progress, hopefully useful to decide which FEM functionalities should be exposed to the users (and possibly identify issues with the current api)

[campospinto]

I think the notebook on FEM + L2 projection is good now (for review), I also mentioned the (H1) conforming projection. I can try to add another one with geometric projections or with "conga-type" Poisson solve, but I'm not sure this is really needed for the 1st release

[yguclu]

Looks good to me!