Update examples to support latest Psydac and Python 3.12 (#9)

Summary of changes:

* Update [`deploy-book.yml`](https://github.com/kvrigor/IGA-Python/blob/build-ci-update/.github/workflows/deploy-book.yml):
   - Use the latest version of Psydac (`devel` branch)
   - Simplify Psydac installation
   - Add macOS test;
* Remove duplicate `keywords` field in `references.bib` since `jupyter-book` complains about them;
* Remove author info in `.ipynb` and `.md` files;
* Use [`nb-clean`](https://github.com/srstevenson/nb-clean) to scrub all Jupyter notebooks free of data (e.g. cell execution count, cell result, path to Python environment, etc.) which shouldn't be tracked in `git`. The [Build Jupyter Book step](https://github.com/pyccel/IGA-Python/pull/9/checks#step:6:1) already handles the execution and rendering of these notebooks online;
* Update the [Installation guide](https://github.com/kvrigor/IGA-Python/blob/build-ci-update/chapter1/install.md).

Author: kvrigor

.github/workflows/deploy-book.yml

@@ -1,41 +1,85 @@
-name: Build and Deploy Jupyter Book
+name: Build IGA-Python Jupyter Book
 
 on:
   push:
-    branches:
-      - master
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
 
 jobs:
   deploy-book:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: true
+      matrix:
+        include:
+          - os: ubuntu-24.04
+            python-version: '3.12'
+
+          - os: macos-15
+            python-version: '3.12'
+
+    env:
+      FC: gfortran-14
+
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
 
-    - name: Set up Python
-      uses: actions/setup-python@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
       with:
-        python-version: '3.9'
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        cache-dependency-path: requirements.txt
 
-    - name: Install dependencies
+    - name: Install non-Python dependencies on Ubuntu
+      if: startsWith(matrix.os, '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
+
+    # When loading cached apt packages, the default MPI compiler isn't set.
+    # Workaround is to 'reinstall' openmpi-bin, which doesn't actually perform
+    # installation (since openmpi-bin already exists), but instead reruns
+    # `update-alternatives` which fixes the symlinks to mpicc/mpif90.
+    - name: Reconfigure non-Python dependencies on Ubuntu
+      if: startsWith(matrix.os, 'ubuntu')
       run: |
-        python -m pip install --upgrade pip
         sudo apt-get update
-        sudo apt-get install gfortran
-        sudo apt-get install openmpi-bin libopenmpi-dev
-        sudo apt-get install libhdf5-openmpi-dev
-        git clone https://github.com/pyccel/psydac.git
-        cd psydac
-        python -m pip install -r requirements.txt
-        python -m pip install -r requirements_extra.txt --no-build-isolation
-        pip install .
-        pip install jupyter-book ghp-import sphinx_proof
-        python -m ipykernel install --user --name .iga-python --display-name "IGA-Python"
-        python -m ipykernel install --user --name v_psydac --display-name "Python (v_psydac)"
+        sudo apt-get install --reinstall openmpi-bin libhdf5-openmpi-dev
+
+    - name: Install non-Python dependencies on macOS
+      if: startsWith(matrix.os, 'macos')
+      run: |
+        brew install open-mpi hdf5-mpi libomp
+
+    - name: Check gfortran version
+      run: |
+        if [[ "${{ matrix.os }}" == *"macos"* ]]; then 
+          # pyccel searches for a Fortran compiler exactly named 'gfortran'
+          # which the macos runner doesn't have. A simple workaround is to 
+          # create a symlink named 'gfortran'.
+          FC_path=$(which $FC)
+          FC_dir=$(dirname ${FC_path})
+          ln -sv ${FC_path} ${FC_dir}/gfortran
+        fi
+        gfortran --version
+
+    - name: Install Jupyter Book and Psydac
+      run: |
+        pip install --upgrade pip
+        pip install -r requirements.txt
 
     - name: Build Jupyter Book
-      run: jupyter-book build .
+      run: make docs
 
     - name: Deploy to GitHub Pages
+      if: ${{ (github.ref == 'refs/heads/master') && startsWith(matrix.os, 'ubuntu') }}
       run: ghp-import -n -p -f _build/html
       env:
         GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

AUTHORS

@@ -0,0 +1,4 @@
+Ahmed Ratnani
+Mohamed Jalal Maaouni
+Paul Rigor
+

Makefile

@@ -0,0 +1,25 @@
+BUILD_DIR = ./_build
+SRC_DIR = .
+
+.PHONY: docs docs-strict clean clean-notebooks
+
+docs:
+	@echo "Building IGA-Python docs..."
+	@jupyter-book build .
+	@echo "Done."
+
+docs-strict:
+	@echo "Building IGA-Python docs with strict rules on..."
+	@jupyter-book build --warningiserror --nitpick --keep-going .
+	@echo "Done."
+
+clean:
+	@echo "Removing previous IGA-Python build artifacts..."
+	@jupyter-book clean .
+	@echo "Done."
+
+clean-notebooks:
+	@echo "Running 'nb-clean --remove-empty-cells --remove-all-notebook-metadata' on all '*.ipynb' files..."
+	@find . -type f -iname '*.ipynb' -exec nb-clean clean --remove-empty-cells --remove-all-notebook-metadata {} \+
+	@echo "Done."
+

README.md

@@ -1 +1,72 @@
 # Welcome to IGA-Python
+
+This project provides a tutorial for isogeometric analysis (IGA) using Python and the Psydac library (pyccel/psydac). The numerical examples can be consulted online at pyccel.github.io/IGA-Python, or run with JupyterNotebook on a personal computer.
+
+## Editing and building IGA-Python locally
+
+1. Clone this repository and then install the required dependencies.
+
+```bash
+git clone https://github.com/pyccel/IGA-Python.git
+cd IGA-Python
+IGA_PYTHON_DIR=$(pwd)
+
+# Install dependencies on a virtual environment
+python3 -m venv iga-python-env
+source iga-python-env/bin/activate
+pip3 install -r requirements_ntbk.txt
+```
+
+2. Install Psydac. Skip this step if Psydac is already installed.
+
+```bash
+# Modify these variables if you're using your own psydac fork/branch
+PSYDAC_REMOTE="https://github.com/pyccel/psydac.git"
+BRANCH="devel"
+
+# Install psydac
+pip install git+${PSYDAC_REMOTE}@${BRANCH}
+```
+
+3. Run or modify the desired Python notebooks (`*.ipynb`) and Markdown files (`*.md`). Check the [MyST syntax cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) for reference.
+
+> [!NOTE]  
+> Before committing changes to git, the notebooks have to be cleaned first. See ["Committing your changes to git"](#committing-your-changes-to-git) for more information.
+
+4. Build the docs by running `make` under the IGA-Python folder. This involves running all `*.ipynb` files in the background to make sure they are functional.
+
+```bash
+cd ${IGA_PYTHON_DIR}
+make
+```
+
+5. View your changes on the browser.
+
+```bash
+open ${IGA_PYTHON_DIR}/_build/html/index.html
+```
+
+## Committing your changes to git
+
+Running the Python notebooks embeds extra information like the name of virtual environment, Python version used, cell outputs, etc. The notebooks should be free of system- and runtime-specific information before committing them to source control. We suggest the following commit workflow:
+
+1. Run [`nb-clean`](https://github.com/srstevenson/nb-clean) on the modified notebook/s. There are different ways to run this command:
+
+```bash
+# Clean a single notebook
+nb-clean clean --remove-empty-cells --remove-all-notebook-metadata chapter1/poisson.ipynb
+
+# Clean all '.ipynb' files under IGA-Python
+make clean-notebooks
+
+# Automatically run nb-clean on `git add`-ed *.ipynb files
+nb-clean add-filter --remove-empty-cells --remove-all-notebook-metadata
+
+# Undo previous command
+nb-clean remove-filter
+```
+
+2. Create a branch for your local changes, e.g. `git checkout -b my-local-fixes`.
+3. Stage the modified files with `git add`. Then run `git diff` to check if the changed `*.ipynb` notebooks doesn't include unnecessary diffs (e.g. notebook metadata).
+4. `git commit` your changes.
+5. *OPTIONAL*. Share your changes to this repo via a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).

_toc.yml

@@ -32,7 +32,7 @@ parts:
           - file: chapter1/topology
           - file: chapter1/space
           - file: chapter1/rules
-      - file: chapter1/poisson 
+      - file: chapter1/poisson
       - file: chapter1/boundary-conditions
       - file: chapter1/geometry
         sections:

chapter0/bezier-curves.md

@@ -1,5 +1,5 @@
 # Bézier curves
-*Author: Ahmed Ratnani*
+
 
 We recall the definition of a Bézier curve:
 

chapter0/bezier.md

@@ -1,5 +1,5 @@
 # Bernstein polynomials
-*Author: Ahmed Ratnani*
+
 
 Without loss of generality, we restrict to the case of the unit interval, namely $a=0$ and $b=1$.
 In figure (Fig. \ref{fig:bernstein-polynomials}), we plot the first sixth Bernstein polynomials.

chapter0/bsplines-curves.md

@@ -1,5 +1,5 @@
 # B-Splines curves
-*Author: Ahmed Ratnani*
+
 
 Let $(\mathbf{P}_i)_{ 0 \leqslant i \leqslant n}\in \mathbb{R}^d$  be a sequence of control points. Following the same approach as for Bézier curves, we define B-Splines curves as
 

chapter0/bsplines-operations.md

@@ -1,5 +1,5 @@
 # Fundamental geometric operations for B-Splines
-*Author: Ahmed Ratnani*
+
 
 Having more control on a curve, adding new control points, can be done in two different ways:
 

chapter0/bsplines-surfaces.md

@@ -1,5 +1,5 @@
 # B-Splines surfaces
-*Author: Ahmed Ratnani*
+
 
 The B-spline surface in $\mathbb{R}^d$ associated to knots $(T_u, T_v)$ where $T_u=(u_i)_{0\leqslant i \leqslant n_u + p_u + 1}$ and $T_v=(v_i)_{0\leqslant i \leqslant n_v + p_v + 1}$, and control points $(\mathbf{P}_{ij})_{ 0 \leqslant i \leqslant n_u,  0 \leqslant j \leqslant n_v}$ is defined by :