Reorganize psydac examples (#543)

- Reorganize the `examples` directory
- Add Jupyter notebooks to `examples/notebooks/` folder:
  . Define an equation symbolically, discretize it, compute some error
norms, plot solution and error – Poisson 2D on a square with “Collela”
mapping
  . FEEC API multipatch – Maxwell 2D time harmonic
  . FEM example: L2 projection
  . 3D example with VTK and Paraview
  . Get eigenvalues (FEEC) with SciPy (serial) 
  . Get eigenvalues with PETSc + SLEPc (parallel)
  . FEEC 3D vector potential
- Make the notebooks run by the documentation CI, so any errors lead to a
failing build of the documentation

Fixes #170.

---------

Co-authored-by: Martin Campos Pinto <martin.campos-pinto@ipp.mpg.de>
Co-authored-by: elmosa <Elena.Moral.Sanchez@ipp.mpg.de>
Co-authored-by: Yaman Güçlü <yaman.guclu@gmail.com>
Co-authored-by: jowezarek <julian.owezarek@tum.de>

Author: 5 people

.github/workflows/documentation.yml

@@ -25,28 +25,124 @@ jobs:
     runs-on: ubuntu-latest
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN}}
+      PSYDAC_MESH_DIR: ${{ github.workspace }}/mesh
+      OMP_NUM_THREADS: 2
     steps:
     - name: Checkout
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
+
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version: '3.10'
     - name: Install non-Python dependencies on Ubuntu
+      uses: awalsh128/cache-apt-pkgs-action@latest
+      with:
+        packages: gfortran openmpi-bin libopenmpi-dev libhdf5-openmpi-dev
+        version: 1.0
+        execute_install_scripts: true
+
+    - name: Reconfigure non-Python dependencies on Ubuntu
+      run: |
+        sudo apt-get update
+        sudo apt-get install --reinstall openmpi-bin libhdf5-openmpi-dev liblapack-dev libblas-dev
+        sudo apt install graphviz pandoc
+
+    - name: Print information on MPI and HDF5 libraries
+      run: |
+        ompi_info
+        h5pcc -showconfig -echo || true
+
+    - name: Upgrade pip, setuptools, and wheel
+      run: |
+        python -m pip install --upgrade pip setuptools wheel
+
+    - name: Determine directory of parallel HDF5 library
+      run: |
+        if [[ "${{ matrix.os }}" == "ubuntu-24.04" ]]; then
+          HDF5_DIR=$(dpkg -L libhdf5-openmpi-dev | grep libhdf5.so | xargs dirname)
+        elif [[ "${{ matrix.os }}" == "macos-14" ]]; then
+          HDF5_DIR=$(brew list hdf5-mpi | grep "libhdf5.dylib" | xargs dirname | xargs dirname)
+        fi
+        echo $HDF5_DIR
+        echo "HDF5_DIR=$HDF5_DIR" >> $GITHUB_ENV
+
+    - name: Cache PETSc
+      uses: actions/cache@v4
+      id: cache-petsc
+      env:
+        cache-name: cache-PETSc
+      with:
+        path: "./petsc"
+        key: petsc-${{ matrix.os }}-${{ matrix.python-version }}
+
+    - if: steps.cache-petsc.outputs.cache-hit != 'true'
+      name: Download a specific release of PETSc
+      run: |
+        git clone --depth 1 --branch v3.23.2 https://gitlab.com/petsc/petsc.git
+
+    - if: steps.cache-petsc.outputs.cache-hit != 'true'
+      name: Install PETSc with complex support
+      working-directory: ./petsc
+      run: |
+        export PETSC_DIR=$(pwd)
+        export PETSC_ARCH=petsc-cmplx
+        ./configure --with-scalar-type=complex --with-fortran-bindings=0 --have-numpy=1         
+        make all
+        echo "PETSC_DIR=$PETSC_DIR" > petsc.env
+        echo "PETSC_ARCH=$PETSC_ARCH" >> petsc.env
+
+    # This step is not really necessary and could be combined with PETSc install
+    # step; however it's good to verify if the cached PETSc installation really works!
+    - name: Test PETSc installation
+      working-directory: ./petsc
+      run: |
+        source petsc.env
+        make check
+        echo "PETSC_DIR=$PETSC_DIR" >> $GITHUB_ENV
+        echo "PETSC_ARCH=$PETSC_ARCH" >> $GITHUB_ENV
+
+    - name: Install petsc4py
+      working-directory: ./petsc
+      run: | 
+        python -m pip install wheel Cython numpy
+        python -m pip install src/binding/petsc4py
+
+    - name: Install h5py in parallel mode
+      run: |
+        export CC="mpicc"
+        export HDF5_MPI="ON"
+        python -m pip install h5py --no-cache-dir --no-binary h5py
+        python -m pip list
+
+    - name: Check parallel h5py installation
+      run: |
+          python -c "
+          from mpi4py import MPI
+          import h5py
+          # This particular instantiation of h5py.File will fail if parallel h5py isn't installed
+          f = h5py.File('parallel_test.hdf5', 'w', driver='mpio', comm=MPI.COMM_WORLD)
+          print(f)"
+
+    - name: Install project
       run: |
-        sudo apt update
-        sudo apt install graphviz
-    - name: Install Python dependencies
+        python -m pip install .[test]
+        python -m pip freeze
+
+    - name: Install Python dependencies for Documentation
       run: |
         python -m pip install -r docs/requirements.txt
+
     - name: Make the sphinx doc
       run: |
         rm -rf docs/source/modules/STUBDIR
         make -C docs clean
         make -C docs html
         python docs/update_links.py
+
     - name: Setup Pages
       uses: actions/configure-pages@v5
+
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v3
       with:

.github/workflows/testing.yml

@@ -157,7 +157,7 @@ jobs:
       - name: Initialize test directory
         run: |
           mkdir pytest
-          cp mpi_tester.py pytest
+          cp scripts/mpi_tester.py pytest
 
       - name: Run coverage tests on macOS
         if: matrix.os == 'macos-14'
@@ -203,6 +203,11 @@ jobs:
         run: |
           python mpi_tester.py --mpirun="mpiexec -n 4 ${MPI_OPTS}" --pyargs psydac -m "parallel and petsc"
 
+      - name: Run single-process example tests with Pytest on Ubuntu
+        if: matrix.os == 'ubuntu-24.04'
+        run: |
+          python -m pytest examples/feec
+
       - name: Remove test directory
         if: always()
         run: |

README.md

@@ -1,5 +1,5 @@
 <h1 align="center">
-<img src="https://raw.githubusercontent.com/pyccel/psydac/devel/docs/source/logo/psydac_banner.svg" width="600" alt="Shows the psydac logo.">
+<img src="https://raw.githubusercontent.com/pyccel/psydac/devel/docs/source/logo/psydac_banner.svg" width="600" alt="Shows the psydac logo." class="dark-light">
 </h1><br>
 
 [![devel_tests](https://github.com/pyccel/psydac/actions/workflows/testing.yml/badge.svg)](https://github.com/pyccel/psydac/actions/workflows/testing.yml) [![docs](https://github.com/pyccel/psydac/actions/workflows/documentation.yml/badge.svg)](https://github.com/pyccel/psydac/actions/workflows/documentation.yml)
@@ -38,7 +38,7 @@ PSYDAC requires a certain number of components to be installed on the machine:
 
 The installation instructions depend on the operating system and on the packaging manager used.
 It is particularly important to determine the **HDF5 root folder**, as this will be needed to install the [`h5py`](https://docs.h5py.org/en/latest/build.html#source-installation) package in parallel mode.
-Detailed instructions can be found in the [documentation](https://github.com/pyccel/psydac/blob/devel/docs/installation.md).
+Detailed instructions can be found in the [documentation](https://pyccel.github.io/psydac/installation.html).
 
 Once those components are installed, we recommend using [`venv`](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) to set up a fresh Python virtual environment at a location `<ENV-PATH>`:
 ```bash
@@ -65,12 +65,12 @@ pip install meson-python "pyccel>=2.1.0"
 pip install --no-build-isolation --editable ./psydac
 ```
 
-Again, for more details we refer to our [documentation](https://github.com/pyccel/psydac/blob/devel/docs/installation.md).
+Again, for more details we refer to our [documentation](https://pyccel.github.io/psydac/installation.html).
 
 > [!TIP]
 > PSYDAC provides the functionality to convert its MPI-parallel matrices and vectors to their [PETSc](https://petsc.org) equivalent, and back.
 > This gives the user access to a wide variety of linear solvers and other algorithms.
-> Instructions for installing [PETSc](https://petsc.org) and `petsc4py` can be found in our [documentation](https://github.com/pyccel/psydac/blob/devel/docs/installation.md#optional-petsc-installation).
+> Instructions for installing [PETSc](https://petsc.org) and `petsc4py` can be found in our [documentation](https://pyccel.github.io/psydac/installation.html#id9).
 
 ## Running Tests
 
@@ -108,14 +108,15 @@ This command applies Pyccel to all the kernel files in the source directory. The
 
 ## Examples and Tutorials
 
-A [tutorial](https://pyccel.github.io/IGA-Python/intro.html) on isogeometric analysis, with many example notebooks where various PDEs are solved with PSYDAC, is under construction in the [IGA-Python](https://github.com/pyccel/IGA-Python) repository.
+Our [documentation](https://pyccel.github.io/psydac/examples.html) provides Jupyter notebooks that present many aspects of this library. 
+Additional [tutorials](https://pyccel.github.io/IGA-Python/intro.html) on isogeometric analysis, with many example notebooks where various PDEs are solved with PSYDAC, is under construction in the [IGA-Python](https://github.com/pyccel/IGA-Python) repository.
 Some other examples can be found [here](https://github.com/pyccel/psydac/blob/devel/examples).
 
 ## Library Documentation
 
--   [Output formats](https://github.com/pyccel/psydac/blob/devel/docs/output.md)
--   [Mesh generation](https://github.com/pyccel/psydac/blob/devel/docs/psydac-mesh.md)
--   [Library reference](https://pyccel.github.io/psydac/)
+-   [Output formats](https://pyccel.github.io/psydac/output.html)
+-   [Mesh generation](https://pyccel.github.io/psydac/psydac-mesh.html)
+-   [Modules](https://pyccel.github.io/psydac/modules.html)
 
 ## Contributing
 

docs/Makefile

@@ -17,4 +17,8 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	@mkdir -p source/examples
+	@cp -r ../examples/notebooks/* source/examples/
+	@cp *.md source/
+
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/output.md

@@ -159,9 +159,4 @@ post.export_to_vtk('filename_vtk', grid=grid, npts_per_cell=npts_per_cell, snaps
 ```
 
 ## Further Examples
-Further examples are present in the following files:
-
-*   `examples/poisson_3d_target_torus.py`
-*   `examples/sample_multipatch_parallel.py`
-*   `examples/notebooks/Poisson_non_periodic.ipynb`
-*   `psydac/api/tests/test_postprocessing.py`
+Further examples are present in the [example notebooks](https://pyccel.github.io/psydac/examples.html).

docs/psydac-mesh.md

@@ -6,4 +6,4 @@ After installation, the command `psydac-mesh` will be available.
 
 ```bash
 psydac-mesh -n='16,16' -d='3,3' square mesh.h5
-```
+```

docs/requirements.txt

@@ -3,4 +3,7 @@ pydata_sphinx_theme
 numpydoc
 tomli
 sphinx-math-dollar
+nbsphinx
+ipykernel
+ipytest
 myst-parser

docs/source/conf.py

@@ -52,6 +52,7 @@ def fixed_init(self, app):
 'sphinx.ext.githubpages',
 'sphinx_math_dollar',
 'sphinx.ext.mathjax',
+'nbsphinx',
 'myst_parser',
 ]
 

docs/source/examples.rst

@@ -1,6 +1,47 @@
 Examples
 ========
 
-+------------------------------------------------------------------------------------------------------------------------+
-| Here you will find examples of how to use PSYDAC and explanations thereof as well as links to notebooks in the future. |
-+------------------------------------------------------------------------------------------------------------------------+
+.. +------------------------------------------------------------------------------------------------------------------------+
+.. | Here you will find examples of how to use PSYDAC and explanations thereof as well as links to notebooks in the future. |
+.. +------------------------------------------------------------------------------------------------------------------------+ 
+
+.. The notebooks get copied into the source directory by the continuous integration pipeline. 
+.. The notebooks should have all output cleared before being committed to the repository.
+Notebooks
+---------
+For the documentation, we provide several Jupyter notebooks that illustrate how to use PSYDAC to solve different types of problems.
+They can be found in the `notebooks directory <https://github.com/pyccel/psydac/tree/devel/examples/notebooks>`_, 
+but are also generated as part of the documentation and can be accessed here:
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Notebooks:
+
+   examples/poisson_2d_square
+   examples/Poisson_non_periodic
+   examples/Helmholtz_non_periodic
+   examples/fem_L2_projection
+   examples/regularized_curlcurl_3D_VTK
+   examples/petsc_eigenvalues_regularized_curlcurl
+   examples/feec_curlcurl_eigenvalue
+   examples/feec_time_harmonic_Maxwell
+   examples/feec_vector_potential_torus
+
+FEEC Examples
+-------------
+
+In the `FEEC examples directory <https://github.com/pyccel/psydac/tree/devel/examples/feec>`_, 
+you will find several examples of how to use PSYDAC to solve problems arising within the Finite Element Exterior Calculus (FEEC) framework.
+These examples include:
+
+
+* Poisson problems
+* General curl-curl eigenvalue problems
+* Time-harmonic Maxwell equations with source terms
+* Time-dependent Maxwell equations
+
+
+Performance
+-----------
+There are also some examples in the `performance directory <https://github.com/pyccel/psydac/tree/devel/examples/performance>`_ explaining the assembly algorithms used in PSYDAC.

docs/source/index.rst

@@ -7,12 +7,6 @@
 Welcome to PSYDAC's documentation!
 ==================================
 
-.. _note:
-.. note::
-
-   This documentation is still under construction.
-   For the time being, its purpose is to assist the developers.
-
 .. include:: ../../README.md
    :parser: myst_parser.sphinx_
 
@@ -21,6 +15,9 @@ Welcome to PSYDAC's documentation!
    :maxdepth: 1
    :hidden: 
 
-   modules
+   installation
    examples
+   output
+   modules
+   psydac-mesh
    maintenance