Adding pdoc-generated example gallery used as both example docs landi…

…ng site and setup.py description (#467) Co-authored-by: Sylwester Arabas <[email protected]>
open-atmos · Oct 24, 2024 · dc969ff · dc969ff
1 parent 857f263
commit dc969ff
Show file tree

Hide file tree

Showing 17 changed files with 115 additions and 63 deletions.
diff --git a/.github/workflows/tests+pypi.yml b/.github/workflows/tests+pypi.yml
@@ -95,10 +95,18 @@ jobs:
       - env:
           JUPYTER_PLATFORM_DIRS: 1
         run: |
-          pip3 install pdoc
+          pip3 install pdoc nbformat
           pip install -e . -e ./examples
-          export PDOC_ALLOW_EXEC=1
-          python -We -m pdoc -o html PyMPDATA examples/PyMPDATA_examples -t docs/templates
+
+          python - <<EOF
+          import glob, nbformat
+          for notebook_path in glob.glob('examples/PyMPDATA_examples/*/*.ipynb'):
+            with open(notebook_path, encoding="utf8") as fin:
+              with open(notebook_path + ".badges.md", 'w') as fout:
+                fout.write(nbformat.read(fin, nbformat.NO_CONVERT).cells[0].source)
+          EOF
+
+          PDOC_ALLOW_EXEC=1 python -We -m pdoc -o html PyMPDATA examples/PyMPDATA_examples -t docs/templates --math
       - if: ${{ github.ref == 'refs/heads/main' && matrix.platform == 'ubuntu-latest' }}
         uses: JamesIves/[email protected]
         with:

diff --git a/docs/markdown/pympdata_examples_landing.md b/docs/markdown/pympdata_examples_landing.md
@@ -4,9 +4,39 @@ They constitute a separate PyMPDATA_examples Python package which is also availa
 The examples have additional dependencies listed in PyMPDATA_examples package setup.py file.
 Running the examples requires the PyMPDATA_examples package to be installed.
 
-Below is an example of how to use the PyMPDATA_examples package to run a simple advection-diffusion in 2D
-`PyMPDATA_examples.advection_diffusion_2d`
-![adv_diff](https://github.com/open-atmos/PyMPDATA/releases/download/tip/advection_diffusion.gif)
+We recommend you look through the example gallery below to see the examples in action.
+
+# Example gallery
+Unless stated otherwise the following examples solve the <mark>basic advection equation</mark>:
+$$ \partial_t (\psi) + \nabla \cdot (u \psi) = 0 $$
+
+The examples are grouped by the dimensionality of the computational grid.
+
+## in 1D
+| tags                                                                                                                                                                                              | link                                                     |
+|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------|
+| <mark>advection-diffusion equation</mark><br/>$$ \partial_t (\psi) + \nabla \cdot (u \psi) + \mu \Delta (\psi) = 0 $$                                                                             | `PyMPDATA_examples.advection_diffusion_1d`*              |
+| <mark>Black-Scholes equation</mark>, option pricing<br>$$  \frac{\partial f}{\partial t} + rS \frac{\partial f}{\partial S} + \frac{\sigma^2}{2} S^2 \frac{\partial^2 f}{\partial S^2} - rf = 0$$ | `PyMPDATA_examples.Arabas_and_Farhat_2020`*              |
+| <mark>advection equation</mark>, homogeneous, several algorithm variants comparison: infinite-gauge, flux-corrected,..                                                                            | `PyMPDATA_examples.Smolarkiewicz_2006_Figs_3_4_10_11_12` |
+| <mark>Size-spectral advection</mark>, particle population condensational growth, coordinate transformation<br>$$ \partial_t (G \psi) + \nabla \cdot (Gu \psi) = 0 $$                              | `PyMPDATA_examples.Olesik_et_al_2022`*                   |
+| <mark>advection equation</mark>, [double-pass donor-cell option](https://osti.gov/servlets/purl/7049237)                                                                                                                       | `PyMPDATA_examples.DPDC`                                 |
+
+## in 2D
+| tags                                                                                                                                                                                                                                                                                                    | link                                                                                                                                                                                                                                                                                                   |
+|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| <mark>advection-diffusion equation</mark><br/>$$ \partial_t (\psi) + \nabla \cdot (u \psi) + \mu \Delta (\psi) = 0 $$                                                                                                                                                                                   | `PyMPDATA_examples.advection_diffusion_2d`*<br/><img src="https://github.com/open-atmos/PyMPDATA/releases/download/tip/advection_diffusion.gif" width="50%" alt="adv-diff">                                                                                                                            |
+| <mark>Spectral-spatial advection</mark>, particle population condensational growth in a vertical column of air, time dependent flow                                                                                                                                                                     | `PyMPDATA_examples.Shipway_and_Hill_2012`                                                                                                                                                                                                                                                              |
+| <mark>shallow-water equations</mark><br/>$$\begin{eqnarray} \partial_t h + \partial_x (uh) + \partial_y (vh) &=& 0~  \\\ \partial_t (uh) + \partial_x ( uuh) + \partial_y (vuh) &=& - h \partial_x h~ \\\ \partial_t (vh) + \partial_x ( uvh) + \partial_y (vvh) &=& - h \partial_y h~ \end{eqnarray}$$ | `PyMPDATA_examples.Jarecka_et_al_2015`*                                                                                                                                                                                                                                                                |
+| <mark>advection equation</mark>, solid body rotation                                                                                                                                                                                                                                                    | `PyMPDATA_examples.Molenkamp_test_as_in_Jaruga_et_al_2015_Fig_12`*                                                                                                                                                                                                                                     |
+| <mark>advection equation</mark>, coordinate transformation, spherical coordinates, see also examples in [PYMPDATA-MPI](https://pypi.org/project/PyMPDATA-MPI/) $$ \partial_t (G \psi) + \nabla \cdot (Gu \psi) = 0 $$                                                                                   | `PyMPDATA_examples.Williamson_and_Rasch_1989_as_in_Jaruga_et_al_2015_Fig_14`<br><img src="https://github.com/open-atmos/PyMPDATA-MPI/releases/download/latest-generated-plots/n_iters.1_rank_0_size_1_c_field_.0.5.0.25._mpi_dim_0_n_threads_1-SphericalScenario-anim.gif", width="50%" alt="mpi-gif"> |
+
+## in 3D
+| tags                                                                                                                                | link                                   |
+|:------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------|
+| <mark>homogeneous advection equation</mark>                                                                                         | `PyMPDATA_examples.Smolarkiewicz_1984` |
+| <mark>homogeneous advection equation</mark>, performance comparison against libmpdata++, scalability analysis in respect to threads | `PyMPDATA_examples.Bartman_et_al_2022` |
+
+\* - with comparison against analytic solution
 
 # Installation
 Since the examples package includes Jupyter notebooks (and their execution requires write access), the suggested install and launch steps are:

diff --git a/examples/PyMPDATA_examples/Arabas_and_Farhat_2020/__init__.py b/examples/PyMPDATA_examples/Arabas_and_Farhat_2020/__init__.py
@@ -4,6 +4,18 @@
   study on pricing of European and American options using MPDATA.
 
 Each notebook in this directory corresponds to a figure or a table in the paper.
+
+fig_1.ipynb:
+.. include:: ./fig_1.ipynb.badges.md
+
+fig_2.ipynb:
+.. include:: ./fig_2.ipynb.badges.md
+
+fig_3.ipynb:
+.. include:: ./fig_3.ipynb.badges.md
+
+tab_1.ipynb:
+.. include:: ./tab_1.ipynb.badges.md
 """
 
 from .simulation import Simulation
diff --git a/examples/PyMPDATA_examples/Bartman_et_al_2022/__init__.py b/examples/PyMPDATA_examples/Bartman_et_al_2022/__init__.py
@@ -1,4 +1,7 @@
 """
 This example is based on the paper:
 [Bartman et al. 2022](https://doi.org/10.21105/joss.03896).
+
+fig_X.ipynb:
+.. include:: ./fig_X.ipynb.badges.md
 """
diff --git a/examples/PyMPDATA_examples/DPDC/__init__.py b/examples/PyMPDATA_examples/DPDC/__init__.py
@@ -1,3 +1,6 @@
 """
 This example demonstrates the use of the Double-Pass Donor-Cell option in `PyMPDATA.options`.
+
+demo.ipynb:
+.. include:: ./demo.ipynb.badges.md
 """
diff --git a/examples/PyMPDATA_examples/Jarecka_et_al_2015/__init__.py b/examples/PyMPDATA_examples/Jarecka_et_al_2015/__init__.py
@@ -2,6 +2,9 @@
 This module showcases the PyMPDATA implementation of an MPDATA-based shallow-water equations
 solver discussed and bencharked against analytical solutions in
 [Jarecka_et_al_2015](https://doi.org/10.1016/j.jcp.2015.02.003).
+
+fig_6.ipynb:
+.. include:: ./fig_6.ipynb.badges.md
 """
 
 from .plot_output import plot_output

diff --git a/examples/PyMPDATA_examples/Molenkamp_test_as_in_Jaruga_et_al_2015_Fig_12/__init__.py b/examples/PyMPDATA_examples/Molenkamp_test_as_in_Jaruga_et_al_2015_Fig_12/__init__.py
@@ -2,4 +2,7 @@
 This is an example based on the solid-body rotation test from
 [Molenkap 1968](http://doi.org/10.1175/1520-0450(1968)007%3C0160:AOFDMA%3E2.0.CO;2)
 (as in Fig. 12 in [Jaruga et al. 2015](https://doi.org/10.5194/gmd-8-1005-2015)).
+
+demo.ipynb:
+.. include:: ./demo.ipynb.badges.md
 """
diff --git a/examples/PyMPDATA_examples/Olesik_et_al_2022/__init__.py b/examples/PyMPDATA_examples/Olesik_et_al_2022/__init__.py
@@ -2,4 +2,19 @@
 This is a PyMPDATA implementation of 1D particle population condensational growth
 problem with coordinate transformations, as presented in
 [Olesik et al. 2022](https://doi.org/10.5194/gmd-15-3879-2022).
+
+demo_analytical_solution.ipynb:
+.. include:: ./demo_analytical_solution.ipynb.badges.md
+
+demo_make_convergences.ipynb:
+.. include:: ./demo_make_convergences.ipynb.badges.md
+
+demo_make_dispersion_ratio.ipynb:
+.. include:: ./demo_make_dispersion_ratio.ipynb.badges.md
+
+demo_make_plots.ipynb:
+.. include:: ./demo_make_plots.ipynb.badges.md
+
+demo_wall_times.ipynb:
+.. include:: ./demo_wall_times.ipynb.badges.md
 """
diff --git a/examples/PyMPDATA_examples/Shipway_and_Hill_2012/__init__.py b/examples/PyMPDATA_examples/Shipway_and_Hill_2012/__init__.py
@@ -2,6 +2,9 @@
 This is an example of 2D droplet size-spectral/spatial problem of
 condensational growth in a column of air,
 as described in [Shipway and Hill 2012](https://doi.org/10.1002/qj.1913).
+
+fig_1.ipynb
+.. include:: ./fig_1.ipynb.badges.md
 """
 
 from .arakawa_c import arakawa_c

diff --git a/examples/PyMPDATA_examples/Smolarkiewicz_1984/__init__.py b/examples/PyMPDATA_examples/Smolarkiewicz_1984/__init__.py
@@ -1,6 +1,9 @@
 """
 This is an example of 3D advection, a spherical signal revolving in a box, based on
 [Smolarkiewicz, 1984](https://doi.org/10.1016/0021-9991(84)90121-9).
+
+figs_13-14.ipynb:
+.. include:: ./figs_13-14.ipynb.badges.md
 """
 
 from .settings import Settings

diff --git a/examples/PyMPDATA_examples/Smolarkiewicz_2006_Figs_3_4_10_11_12/__init__.py b/examples/PyMPDATA_examples/Smolarkiewicz_2006_Figs_3_4_10_11_12/__init__.py
@@ -3,5 +3,8 @@
 [Smolarkiewicz 2006](https://doi.org/10.1002/fld.1071), depicting infinite-gauge and
 flux-corrected transport case.
 
+demo.ipynb:
+.. include:: ./demo.ipynb.badges.md
+
 ![plot](https://github.com/open-atmos/PyMPDATA/releases/download/tip/fig_4.svg)
 """
diff --git a/...es/PyMPDATA_examples/Williamson_and_Rasch_1989_as_in_Jaruga_et_al_2015_Fig_14/__init__.py b/...es/PyMPDATA_examples/Williamson_and_Rasch_1989_as_in_Jaruga_et_al_2015_Fig_14/__init__.py
@@ -3,4 +3,7 @@
 [Williamson and Rasch 1989](https://doi.org/10.1175/1520-0493(1989)117%3C0102:TDSLTW%3E2.0.CO;2).
 It demonstrates the use of `PyMPDATA.solver.g_factor`
 to transform the advection problem onto a sphere.
+
+demo_over_the_pole.ipynb:
+.. include:: ./demo_over_the_pole.ipynb.badges.md
 """
diff --git a/examples/PyMPDATA_examples/advection_diffusion_1d/__init__.py b/examples/PyMPDATA_examples/advection_diffusion_1d/__init__.py
@@ -1,4 +1,6 @@
 """
-PyMPDATA 1D advection-diffusion example with error analysis
-for different initial parameters.
+PyMPDATA 1D advection-diffusion example with error analysis for different initial parameters.
+
+demo.ipynb:
+.. include:: ./demo.ipynb.badges.md
 """
diff --git a/examples/PyMPDATA_examples/advection_diffusion_2d/__init__.py b/examples/PyMPDATA_examples/advection_diffusion_2d/__init__.py
@@ -1,3 +1,6 @@
 """
 PyMPDATA 2D advection-diffusion example with gif creation.
+
+advection-diffusion-2d.ipynb:
+.. include:: ./advection-diffusion-2d.ipynb.badges.md
 """
diff --git a/examples/PyMPDATA_examples/advection_diffusion_2d/advection-diffusion-2d.ipynb b/examples/PyMPDATA_examples/advection_diffusion_2d/advection-diffusion-2d.ipynb
@@ -473,7 +473,7 @@
    "outputs": [],
    "source": [
     "def merge_images_into_gif(image_folder, gif_name, duration=0.01):\n",
-    "    with imageio.get_writer(gif_name, mode='I', duration=duration) as writer:\n",
+    "    with imageio.get_writer(gif_name, mode='I', duration=duration, loop=0) as writer:\n",
     "        for filename in sorted(os.listdir(image_folder)):\n",
     "            image = imageio.v3.imread(os.path.join(image_folder, filename))\n",
     "            writer.append_data(image)"