Merge branch 'open-atmos:main' into main

.github/workflows/readme_rust.yml

@@ -0,0 +1,43 @@
+name: readme_rust
+
+defaults:
+  run:
+    shell: bash
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  schedule:
+    - cron: '0 13 * * 4'
+
+jobs:
+  rust:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rust-src
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.9
+      - run: pip install -e .
+      - run: pip install pytest-codeblocks pytest
+
+      - run: |
+          cat >Cargo.toml <<EOF
+          [package]
+          name = "PyMPDATA"
+          version = "0.1.0"
+          edition = "2021"
+
+          [dependencies]
+          pyo3 = { version = "0.22.2", features=["auto-initialize"]}
+          EOF
+      - run: mkdir src
+      - run: python -c "import pytest_codeblocks; code=pytest_codeblocks.extract_from_file('docs/markdown/pympdata_landing.md'); f=open('src/main.rs', 'w'); f.writelines(block.code for block in code if block.syntax=='Rust'); f.close()"
+      - run: cat -n src/main.rs
+      - run: cargo run
+

.github/workflows/tests+pypi.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/setup-python@v1
+      - uses: actions/setup-python@v5.2.0
         with:
           python-version: "3.10" 
       - run: |
@@ -37,7 +37,7 @@ jobs:
       with:
         submodules: recursive
         fetch-depth: 0 
-    - uses: actions/setup-python@master
+    - uses: actions/setup-python@v5.2.0
       with:
         python-version: 3.9
     - name: Generate coverage report
@@ -60,7 +60,7 @@ jobs:
         submodules: recursive
         fetch-depth: 0 
     - name: Set up Python 3.9
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5.2.0
       with:
         python-version: 3.9
     - name: Install dependencies
@@ -89,16 +89,24 @@ jobs:
         with:
           submodules: recursive
           persist-credentials: false
-      - uses: actions/setup-python@v2
+      - uses: actions/setup-python@v5.2.0
         with:
           python-version: 3.9
       - 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:
@@ -121,37 +129,21 @@ jobs:
     strategy:
       matrix:
         platform: [ubuntu-latest, macos-12, macos-14, windows-latest]
-        python-version: ["3.9", "3.12", "system"]
+        python-version: ["3.9", "3.12"]
         exclude:
-          - platform: ubuntu-latest
-            python-version: system
-          - platform: macos-12
-            python-version: system
-          - platform: windows-latest
-            python-version: system
           - platform: macos-14
             python-version: "3.9"
-          - platform: macos-14
-            python-version: "3.12"
     runs-on: ${{ matrix.platform }}
     steps:
       - uses: actions/checkout@v2
         with:
           submodules: recursive
           fetch-depth: 0 
 
-      - if: matrix.platform != 'macos-14'
-        uses: actions/setup-python@v1
+      - uses: actions/[email protected]
         with:
           python-version: ${{ matrix.python-version }}
 
-      - if: matrix.platform == 'macos-14'
-        run: |
-          sudo ln -s `which python3` /usr/local/bin/python
-          echo "PIP_INSTALL_ARGS=--break-system-packages" >> $GITHUB_ENV
-
-          # Python 3.12 workaround  
-          python -m pip install --break-system-packages setuptools
       - run: |
           python -m pip install $PIP_INSTALL_ARGS -e .  # to check if usable without test/example dependencies
           python -We -c "import PyMPDATA"
@@ -178,17 +170,6 @@ jobs:
       matrix:
         platform: [ubuntu-latest, macos-12, macos-14, windows-latest]
         python-version: ["3.9", "3.12"]
-        exclude:
-          - platform: ubuntu-latest
-            python-version: system
-          - platform: macos-12
-            python-version: system
-          - platform: windows-latest
-            python-version: system
-          - platform: macos-14
-            python-version: "3.9"
-          - platform: macos-14
-            python-version: "3.12"
       fail-fast: false
     runs-on: ${{ matrix.platform }}
     steps:
@@ -197,19 +178,10 @@ jobs:
           submodules: recursive
           fetch-depth: 0 
 
-      - if: matrix.platform != 'macos-14'
-        uses: actions/setup-python@v1
+      - uses: actions/[email protected]
         with:
           python-version: ${{ matrix.python-version }}
 
-      - if: matrix.platform == 'macos-14'
-        run: |
-          sudo ln -s `which python3` /usr/local/bin/python
-          echo "PIP_INSTALL_ARGS=--break-system-packages" >> $GITHUB_ENV
-          
-          # Python 3.12 workaround
-          python -m pip install --break-system-packages setuptools
-
       - run: python -m pip install $PIP_INSTALL_ARGS -e .[tests] ./examples
       - run: python -m pip install $PIP_INSTALL_ARGS -r tests/devops_tests/requirements.txt
       - if: matrix.platform == 'ubuntu-latest'
@@ -279,7 +251,7 @@ jobs:
         with:
           submodules: recursive
           fetch-depth: 0  # https://github.com/pypa/setuptools_scm/issues/480
-      - uses: actions/setup-python@v2
+      - uses: actions/setup-python@v5.2.0
         with:
           python-version: "3.10"
 

docs/markdown/pympdata_landing.md

@@ -42,7 +42,7 @@ The Numba's deviation from Python semantics rendering [closure variables
   information on domain extents, algorithm variant used and problem
   characteristics (e.g., coordinate transformation used, or lack thereof).
 
-# Tutorial (in Python, Julia and Matlab)
+# Tutorial (in Python, Julia, Rust and Matlab)
 ## Options class
 
 The [``Options``](https://open-atmos.github.io/PyMPDATA/PyMPDATA/options.html) class
@@ -93,6 +93,19 @@ options = Options(pyargs('n_iters', 2));
 <details open>
 <summary>Python code (click to expand)</summary>
 
+<details>
+<summary>Rust code (click to expand)</summary>
+```Rust
+use pyo3::prelude::*;
+use pyo3::types::{IntoPyDict, PyDict, PyTuple};
+
+fn main() -> PyResult<()> {
+  Python::with_gil(|py| {
+    let options_args = [("n_iters", 2)].into_py_dict_bound(py);
+    let options = py.import_bound("PyMPDATA")?.getattr("Options")?.call((), Some(&options_args))?;
+```
+</details>
+
 ```Python
 from PyMPDATA import Options
 options = Options(n_iters=2)
@@ -236,6 +249,45 @@ advector = VectorField(pyargs(...
 ));
 ```
 </details>
+
+<details>
+<summary>Rust code (click to expand)</summary>
+```Rust
+    let vector_field = py.import_bound("PyMPDATA")?.getattr("VectorField")?;
+    let scalar_field = py.import_bound("PyMPDATA")?.getattr("ScalarField")?;
+    let periodic = py.import_bound("PyMPDATA.boundary_conditions")?.getattr("Periodic")?;
+
+    let nx_ny = [24, 24];
+    let cx_cy = [-0.5, -0.25];
+    let boundary_con = PyTuple::new_bound(py, [periodic.call0()?, periodic.call0()?]).into_any();
+    let halo = options.getattr("n_halo")?;
+
+    let indices = PyDict::new_bound(py);
+    Python::run_bound(py, &format!(r#"
+import numpy as np
+nx, ny = {}, {}
+xi, yi = np.indices((nx, ny), dtype=float)
+data=np.exp(
+  -(xi+.5-nx/2)**2 / (2*(ny/10)**2)
+  -(yi+.5-nx/2)**2 / (2*(ny/10)**2)
+)
+    "#, nx_ny[0], nx_ny[1]), None, Some(&indices)).unwrap();
+
+    let advectee_arg = vec![("data", indices.get_item("data")?), ("halo", Some(halo.clone())), ("boundary_conditions", Some(boundary_con))].into_py_dict_bound(py);
+    let advectee = scalar_field.call((), Some(&advectee_arg))?;
+    let full = PyDict::new_bound(py);
+    Python::run_bound(py, &format!(r#"
+import numpy as np
+nx, ny = {}, {}
+Cx, Cy = {}, {}
+data = (np.full((nx + 1, ny), Cx), np.full((nx, ny + 1), Cy))
+    "#, nx_ny[0], nx_ny[1], cx_cy[0], cx_cy[1]), None, Some(&full)).unwrap();
+    let boundary_con = PyTuple::new_bound(py, [periodic.call0()?, periodic.call0()?]).into_any();
+    let advector_arg = vec![("data", full.get_item("data")?), ("halo", Some(halo.clone())), ("boundary_conditions", Some(boundary_con))].into_py_dict_bound(py);
+    let advector = vector_field.call((), Some(&advector_arg))?;
+```
+</details>
+
 <details open>
 <summary>Python code (click to expand)</summary>
 
@@ -306,6 +358,18 @@ stepper = Stepper(pyargs(...
 ```
 </details>
 <details open>
+
+<details>
+<summary>Rust code (click to expand)</summary>
+
+```Rust
+let n_dims: i32 = 2;
+let stepper_arg = PyDict::new_bound(py);
+let _ = PyDictMethods::set_item(&stepper_arg, "options", &options);
+let _ = PyDictMethods::set_item(&stepper_arg, "n_dims", &n_dims);
+```
+</details>
+
 <summary>Python code (click to expand)</summary>
 
 ```Python
@@ -332,6 +396,17 @@ stepper = Stepper(pyargs(...
 ));
 ```
 </details>
+
+<details>
+<summary>Rust code (click to expand)</summary>
+
+```Rust
+ let _stepper_arg_alternative = vec![("options", &options), ("grid", &PyTuple::new_bound(py, nx_ny).into_any())].into_py_dict_bound(py);
+ let stepper_ = py.import_bound("PyMPDATA")?.getattr("Stepper")?;
+ let stepper = stepper_.call((), Some(&stepper_arg))?; //or use stepper args alternative
+```
+</details>
+
 <details open>
 <summary>Python code (click to expand)</summary>
 
@@ -406,6 +481,22 @@ solver.advance(pyargs('n_steps', 75));
 state = solver.advectee.get();
 ```
 </details>
+
+<details>
+<summary>Rust code (click to expand)</summary>
+
+```Rust
+    let solver_ = py.import_bound("PyMPDATA")?.getattr("Solver")?;
+    let solver = solver_.call((), Some(&vec![("stepper", stepper), ("advectee", advectee), ("advector", advector)].into_py_dict_bound(py)))?;
+    let _state_0 = solver.getattr("advectee")?.getattr("get")?.call0()?.getattr("copy")?.call0()?;
+    solver.getattr("advance")?.call((), Some(&vec![("n_steps", 75)].into_py_dict_bound(py)))?;
+    let _state = solver.getattr("advectee")?.getattr("get")?.call0()?;
+    Ok(())
+  })
+}
+```
+</details>
+
 <details open>
 <summary>Python code (click to expand)</summary>
 

examples/MANIFEST.in

@@ -1 +1,2 @@
 global-exclude *.ipynb
+include docs/*.md

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