Docs cleanup after MPI merge (#600)

Author: Sfonxu

MPI/README.md

@@ -0,0 +1,53 @@
+# PyMPDATA-MPI
+PyMPDATA-MPI constitutes a [PyMPDATA](https://github.com/open-atmos/PyMPDATA) +
+[numba-mpi](https://github.com/numba-mpi/numba-mpi) coupler enabling numerical solutions
+of transport equations with the MPDATA numerical scheme in a
+hybrid parallelisation model with both multi-threading and MPI distributed memory communication.
+PyMPDATA-MPI adapts to API of PyMPDATA offering domain decomposition logic.
+
+## Dependencies and installation
+
+Along with ``PyMPDATA`` dependencies, this package also depends on ``numba-mpi`` and ``h5py``.
+
+To install PyMPDATA-MPI, first we recommend installing MPI-compatible ``h5py`` and then downloading the package via pip:
+```
+HDF5_MPI="ON" pip install --no-binary=h5py h5py
+pip install PyMPDATA-MPI
+```
+
+## Examples gallery
+
+We strongly encourage to take a look at out examples gallery availible on [Github](https://open-atmos.github.io/PyMPDATA/PyMPDATA_MPI.html).
+
+## Contributing, reporting issues, seeking support 
+
+Submitting new code to the project, please preferably use [GitHub pull requests](https://github.com/open-atmos/PyMPDATA/pulls) it helps to keep record of code authorship, 
+track and archive the code review workflow and allows to benefit
+from the continuous integration setup which automates execution of tests 
+with the newly added code. 
+
+## Design goals
+
+- MPI support for [PyMPDATA](https://pypi.org/project/PyMPDATA/) implemented externally (i.e., not incurring any overhead or additional dependencies for PyMPDATA users)
+- MPI calls within [Numba njitted code](https://numba.pydata.org/numba-doc/dev/reference/jit-compilation.html) (hence not using [`mpi4py`](https://mpi4py.readthedocs.io/), but rather [`numba-mpi`](https://pypi.org/p/numba-mpi/))
+- hybrid domain-decomposition parallelism: threading (internal in PyMPDATA, in the inner dimension) + MPI (either inner or outer dimension)
+- example simulation scenarios featuring HDF5/MPI-IO output storage (using [h5py](https://www.h5py.org/))
+- [py-modelrunner](https://github.com/zwicker-group/py-modelrunner) simulation orchestration
+- portability across Linux & macOS (no Windows support as of now due to [challenges in getting HDF5/MPI-IO to work there](https://docs.h5py.org/en/stable/build.html#source-installation-on-windows))
+- Continuous Integration (CI) with different OSes and different MPI implementations (leveraging to mpi4py's [setup-mpi Github Action](https://github.com/mpi4py/setup-mpi/))
+- full test coverage including CI builds asserting on same results with multi-node vs. single-node computations (with help of [pytest-mpi](https://pypi.org/p/pytest-mpi/))
+- ships as a [pip-installable package](https://pypi.org/project/PyMPDATA-MPI) - aimed to be a dependency of domain-specific packages
+
+## Credits & acknowledgments:
+
+PyMPDATA-MPI started as a separate project for the [MSc thesis of Kacper Derlatka](https://www.ap.uj.edu.pl/diplomas/166883) ([@Delcior](https://github.com/Delcior)).
+Integration of PyMPDATA-MPI into PyMPDATA repo was carried out as a part of BEng project of [Michał Wroński](https://github.com/Sfonxu/).
+
+Development of PyMPDATA-MPI has been supported by the [Poland's National Science Centre](https://www.ncn.gov.pl/?language=en)
+(grant no. 2020/39/D/ST10/01220).
+
+We acknowledge Poland’s high-performance computing infrastructure [PLGrid](https://plgrid.pl/) (HPC Centers: [ACK Cyfronet AGH](https://www.cyfronet.pl/en/))
+for providing computer facilities and support within computational grant no. PLG/2023/016369
+
+copyright: [Jagiellonian University](https://en.uj.edu.pl/en) & [AGH University of Krakow](https://agh.edu.pl/en)
+licence: [GPL v3](https://www.gnu.org/licenses/gpl-3.0.html)

MPI/docs/pympdata_mpi_landing.md

@@ -15,9 +15,9 @@ Every node (process) is responsible for computing its part of the decomposed dom
 In spherical geometry, the $G$ factor represents the Jacobian of coordinate transformation.
 In this example (based on a test case from [Williamson & Rasch 1989](https://doi.org/10.1175/1520-0493(1989)117%3C0102:TDSLTW%3E2.0.CO;2)),
   domain decomposition is done cutting the sphere along meridians.
-The inner dimension uses the [`MPIPolar`](https://open-atmos.github.io/PyMPDATA-MPI/mpi_polar.html)
+The inner dimension uses the [`MPIPolar`](https://open-atmos.github.io/PyMPDATA/PyMPDATA_MPI/mpi_polar.html)
   boundary condition class, while the outer dimension uses
-  [`MPIPeriodic`](https://open-atmos.github.io/PyMPDATA-MPI/mpi_periodic.html).
+  [`MPIPeriodic`](https://open-atmos.github.io/PyMPDATA/PyMPDATA_MPI/mpi_periodic.html).
 Note that the spherical animations below depict simulations without MPDATA corrective iterations,
   i.e. only plain first-order upwind scheme is used (FIX ME).
 

MPI/pyproject.toml

@@ -13,7 +13,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "pympdata-mpi"
 description = "PyMPDATA + numba-mpi coupler sandbox"
-readme = "docs/pympdata_mpi_landing.md"
+readme = "README.md"
 requires-python = ">=3.10"
 keywords = ["MPI", "MPDATA", "Numba", "PyMPDATA"]
 license = {text = "GPL-3.0"}

README.md

@@ -39,7 +39,8 @@ see, e.g. [Smolarkiewicz and Margolin 1998](https://doi.org/10.1006/jcph.1998.59
 
 PyMPDATA [documentation](https://open-atmos.github.io/PyMPDATA/index.html) is generated via [``pdoc``](https://pdoc.dev/).
 
-A separate project called [``PyMPDATA-MPI``](https://github.com/open-atmos/PyMPDATA-MPI) 
+
+A [``PyMPDATA``] and [``numba-mpi``] coupler sandbox called [``PyMPDATA-MPI``](https://pypi.org/project/pympdata-mpi/)
   depicts how [``numba-mpi``](https://pypi.org/project/numba-mpi) can be used
   to enable distributed memory parallelism in PyMPDATA.applications, and provide a validation of the implementation
   and its performance.

docs/templates/index.html.jinja2

@@ -33,7 +33,7 @@
         <h2>What is PyMPDATA?</h2>
         <p>
             <div style="float:right; width:25%">
-                <img width="100%" 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 width="100%" src="https://github.com/open-atmos/PyMPDATA/releases/download/tip/n_iters.3_rank_0_size_1_c_field_.0.5.0.25._mpi_dim_0_n_threads_3-CartesianScenario-anim.gif">
                 <br />
                 <br />
                 <img width="100%" src="https://github.com/open-atmos/PyMPDATA/releases/download/tip/boussinesq_2d_anim.gif">