new example: buoyant-bubble with a Boussinesq system (velocity extrapolation in time + pressure solver) (AGH eng. project by Michał Kowalczyk @Caastlefox) (#495)

Co-authored-by: Caastlefox <[email protected]>
Co-authored-by: Castlefox <[email protected]>

Author: 3 people

.github/workflows/tests.yml

@@ -126,7 +126,7 @@ jobs:
       - run: |
           python -m pip install $PIP_INSTALL_ARGS -e .  # to check if usable without test/example dependencies
           python -We -c "import PyMPDATA"
-          python -m pip install $PIP_INSTALL_ARGS -e .[tests] ./examples
+          python -m pip install $PIP_INSTALL_ARGS -e .[tests] -e ./examples
 
       # https://github.com/numba/numba/issues/6350#issuecomment-728174860
       - if: startsWith(matrix.platform, 'ubuntu-')
@@ -161,7 +161,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - run: python -m pip install $PIP_INSTALL_ARGS -e .[tests] ./examples
+      - run: python -m pip install $PIP_INSTALL_ARGS -e .[tests] -e ./examples
       - run: python -m pip install $PIP_INSTALL_ARGS -r tests/devops_tests/requirements.txt
       - if: matrix.platform == 'ubuntu-latest'
         run: |
@@ -189,6 +189,7 @@ jobs:
         run: |
           mkdir -p /home/runner/work/_temp/_github_home/figures
           rm /tmp/pytest-of-runner/pytest-current/test_run_notebooks_examples_Pycurrent
+          mv /tmp/pytest-of-runner/pytest-current/test_run_notebooks_examples_*/boussinesq_2d_anim.gif /home/runner/work/_temp/_github_home/figures
           mv /tmp/pytest-of-runner/pytest-current/test_run_notebooks_examples_*/fig_4.svg /home/runner/work/_temp/_github_home/figures
           mv /tmp/pytest-of-runner/pytest-current/test_run_notebooks_examples_*/advection_diffusion.gif /home/runner/work/_temp/_github_home/figures
 

.gitignore

@@ -157,4 +157,4 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-.idea/
+.idea/

.zenodo.json

@@ -25,13 +25,8 @@
       "name": "Drenda, Szymon"
     },
     {
-      "affiliation": "Jagiellonian University, Kraków, Poland",
-      "name": "Manna, Maciej"
-    },
-    {
-      "affiliation": "Jagiellonian University, Kraków, Poland",
-      "name": "Olesik, Michael",
-      "orcid": "0000-0002-6319-9358"
+      "affiliation": "AGH University of Krakow, Poland",
+      "name": "Michał Kowalczyk"
     },
     {
       "affiliation": "AGH University of Krakow, Poland",
@@ -42,6 +37,11 @@
       "affiliation": "Jagiellonian University, Kraków, Poland",
       "name": "Manna, Maciej"
     },
+    {
+      "affiliation": "Jagiellonian University, Kraków, Poland",
+      "name": "Olesik, Michael",
+      "orcid": "0000-0002-6319-9358"
+    },
     {
       "affiliation": "Jagiellonian University, Kraków, Poland",
       "name": "Rozwoda, Paweł"

docs/bibliography.json

@@ -39,7 +39,8 @@
   "https://doi.org/10.1006/jcph.1998.5901": {
     "usages": [
       "README.md",
-      "docs/markdown/pympdata_landing.md"
+      "docs/markdown/pympdata_landing.md",
+      "examples/PyMPDATA_examples/Jaruga_et_al_2015/fig19.ipynb"
     ],
     "label": "Smolarkiewicz & Margolin 1998 (J. Comp. Phys. 140)",
     "title": "MPDATA: A Finite-Difference Solver for Geophysical Flows"
@@ -112,7 +113,9 @@
     "usages": [
       "docs/markdown/pympdata_landing.md",
       "examples/PyMPDATA_examples/Molenkamp_test_as_in_Jaruga_et_al_2015_Fig_12/demo.ipynb",
-      "examples/PyMPDATA_examples/Molenkamp_test_as_in_Jaruga_et_al_2015_Fig_12/__init__.py"
+      "examples/PyMPDATA_examples/Molenkamp_test_as_in_Jaruga_et_al_2015_Fig_12/__init__.py",
+      "tests/smoke_tests/jaruga_et_al_2015/test_boussinesq.py",
+      "examples/PyMPDATA_examples/Jaruga_et_al_2015/fig19.ipynb"
     ],
     "label": "Jaruga et al. 2015 (Geosci. Model Dev. 8)",
     "title": "libmpdata++ 1.0: a library of parallel MPDATA solvers for systems of generalised transport equations "
@@ -153,5 +156,20 @@
     ],
     "label": "Molenkamp 1968 (J. Appl. Meteorol. Climatol. 7)",
     "title": "Accuracy of Finite-Difference Methods Applied to the Advection Equation"
+  },
+  "https://osti.gov/biblio/785403": {
+    "usages": [
+      "examples/PyMPDATA_examples/Jaruga_et_al_2015/fig19.ipynb"
+    ],
+    "label": "Smolarkiewicz & Margolin 2000 (LANL report)",
+    "title": "Variational methods for elliptic problems in fluid models"
+  },
+  "https://doi.org/10.1175/1520-0469(1992)049%3C2082:ACOSLA%3E2.0.CO;2": {
+    "usages": [
+      "examples/PyMPDATA_examples/Jaruga_et_al_2015/fig19.ipynb",
+      "tests/smoke_tests/jaruga_et_al_2015/test_boussinesq.py"
+    ],
+    "label": "Smolarkiewicz and Pudykiewicz 1992 (J. Atmos. Sci. 49)",
+    "title": "A Class of Semi-Lagrangian Approximations for Fluids"
   }
 }

docs/templates/index.html.jinja2

@@ -33,6 +33,7 @@
         <h2>What is PyMPDATA?</h2>
         <p>
             <img align="right" src="https://github.com/open-atmos/PyMPDATA-MPI/releases/download/latest-generated-plots/n_iters.3_rank_0_size_1_c_field_.0.5.0.25._mpi_dim_0_n_threads_3-CartesianScenario-anim.gif">
+            <img align="right" src="https://github.com/open-atmos/PyMPDATA/releases/download/tip/boussinesq_2d_anim.gif">
             PyMPDATA is a <b><a href="https://numba.pydata.org">Numba-accelerated</a></b> <mark>multi-threaded</mark> Pythonic implementation of the 
             <b>MPDATA algorithm</b> of <a href="https://doi.org/10.1016/0021-9991(84)90121-9">Smolarkiewicz et al.</a> used in 
             <mark>geophysical fluid dynamics</mark> and beyond for

examples/PyMPDATA_examples/Jaruga_et_al_2015/__init__.py

@@ -24,6 +24,7 @@ The examples are grouped by the dimensionality of the computational grid.
 ## in 2D
 | tags                                                                                                                                                                                                                                                                                                    | link                                                                                                                                                                                                                                                                                                   |
 |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| <mark>Boussinesq equations</mark> for buoyancy-driven flows<br/>$$\begin{eqnarray} \partial_t v+\mathrm{\nabla}\cdot\left(\vec{v}\otimes \vec{v}\right)=-\nabla\pi-\vec{g}\frac{\theta^\prime}{\theta_0}~ \\\ \partial_t \theta+ \nabla\cdot\left(\vec{v}\theta\right)=0~ \\\ \nabla\cdot\ \vec{v}=0$$  | `PyMPDATA_examples.Jaruga_et_al_2015`<br/><img src="https://github.com/open-atmos/PyMPDATA/releases/download/tip/boussinesq_2d_anim.gif" width="50%" alt="boussinesq-2d">                                                                                                                              |
 | <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`<br/><img src="https://github.com/open-atmos/PyMPDATA/wiki/files/KiD-1D_PyMPDATA_n_iters=3.gif" width="50%" alt="spectral-spatial">                                                                                                                           |
 | <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`*                                                                                                                                                                                                                                                                |

examples/PyMPDATA_examples/Jaruga_et_al_2015/fig19.ipynb

@@ -79,11 +79,13 @@ def get_long_description():
             ),
             "jupyter-core" + ("<5.0.0" if CI else ""),
             "ipywidgets" + ("!=8.0.3" if CI else ""),
+            "ipykernel" + ("<6.22.0" if CI else ""),
             "ghapi",
             "pytest",
             "pytest-benchmark",
             "joblib" + ("==1.4.0" if CI else ""),
             "imageio",
+            "nbformat",
         ]
     },
     author="https://github.com/open-atmos/PyMPDATA/graphs/contributors",

examples/docs/pympdata_examples_landing.md

@@ -0,0 +1,58 @@
+""" tests for buoyant-bubble test case from Fig. 3 in [Smolarkiewicz & Pudykiewicz
+1992](https://doi.org/10.1175/1520-0469(1992)049%3C2082:ACOSLA%3E2.0.CO;2),
+as in libmpdata++ paper ([Jaruga et al. 2015](https://doi.org/10.5194/gmd-8-1005-2015), Fig. 19)"""
+
+# pylint: disable=missing-class-docstring,missing-function-docstring
+
+from pathlib import Path
+
+import numpy as np
+import pytest
+from open_atmos_jupyter_utils import notebook_vars
+from PyMPDATA_examples import Jaruga_et_al_2015
+
+PLOT = False
+
+
+@pytest.fixture(scope="session", name="variables")
+def variables_fixture():
+    return notebook_vars(
+        file=Path(Jaruga_et_al_2015.__file__).parent / "fig19.ipynb",
+        plot=PLOT,
+    )
+
+
+class TestFig19:
+    @staticmethod
+    def test_maximal_theta(variables):
+        max_at_t0 = variables["SETUP"].Tht_ref + variables["SETUP"].Tht_dlt
+        acceptable_overshoot = 1e-4
+        assert (
+            max_at_t0 < np.amax(variables["output"]) < max_at_t0 + acceptable_overshoot
+        )
+
+    @staticmethod
+    def test_minimal_theta(variables):
+        min_at_t0 = variables["SETUP"].Tht_ref
+        acceptable_undershoot = 5e-3
+        assert (
+            min_at_t0 - acceptable_undershoot < np.amin(variables["output"]) < min_at_t0
+        )
+
+    @staticmethod
+    @pytest.mark.parametrize(
+        "area",
+        (
+            (slice(0, 20), slice(None)),
+            (slice(80, None), slice(None)),
+            (slice(None), slice(0, 30)),
+            (slice(None), slice(70, None)),
+        ),
+    )
+    def test_theta_at_domain_edges_equal_to_reference_value(area, variables):
+        psi_at_last_step = variables["output"][-1, :, :]
+        np.testing.assert_allclose(
+            actual=psi_at_last_step[area],
+            desired=variables["SETUP"].Tht_ref,
+            rtol=1.5e-5,
+        )