numba-mpi 0.40__py3-none-any.whl → 0.43__py3-none-any.whl

numba_mpi/__init__.py

@@ -1,4 +1,6 @@
-""" Numba @njittable MPI wrappers tested on Linux, macOS and Windows """
+"""
+.. include::../README.md
+"""
 
 from importlib.metadata import PackageNotFoundError, version
 

numba_mpi/api/requests.py

@@ -34,6 +34,9 @@ def wait(request):
     """Wrapper for MPI_Wait. Returns integer status code (0 == MPI_SUCCESS).
     Status is currently not handled. Requires 'request' parameter to be a
     c-style pointer to MPI_Request (such as returned by 'isend'/'irecv').
+
+    Uninitialized contents of 'request' (e.g., from numpy.empty()) may
+    cause invalid pointer dereference and segmentation faults.
     """
 
     status_buffer = create_status_buffer()
@@ -64,6 +67,9 @@ def waitall(requests):
     """Wrapper for MPI_Waitall. Returns integer status code (0 == MPI_SUCCESS).
     Status is currently not handled. Requires 'requests' parameter to be an
     array or tuple of MPI_Request objects.
+
+    Uninitialized contents of 'requests' (e.g., from numpy.empty()) may
+    cause invalid pointer dereference and segmentation faults.
     """
     if isinstance(requests, np.ndarray):
         return _waitall_array_impl(requests)
@@ -123,6 +129,9 @@ def waitany(requests):
     status; second - the index of request that was completed. Status is
     currently not handled. Requires 'requests' parameter to be an array
     or tuple of MPI_Request objects.
+
+    Uninitialized contents of 'requests' (e.g., from numpy.empty()) may
+    cause invalid pointer dereference and segmentation faults.
     """
 
     if isinstance(requests, np.ndarray):
@@ -167,6 +176,9 @@ def test(request):
     flag that indicates whether given request is completed. Status is currently
     not handled. Requires 'request' parameter to be a c-style pointer to
     MPI_Request (such as returned by 'isend'/'irecv').
+
+    Uninitialized contents of 'request' (e.g., from numpy.empty()) may
+    cause invalid pointer dereference and segmentation faults.
     """
 
     status_buffer = create_status_buffer()
@@ -203,6 +215,9 @@ def testall(requests):
     flag that indicates whether given request is completed. Status is currently
     not handled. Requires 'requests' parameter to be an array or tuple of
     MPI_Request objects.
+
+    Uninitialized contents of 'requests' (e.g., from numpy.empty()) may
+    cause invalid pointer dereference and segmentation faults.
     """
     if isinstance(requests, np.ndarray):
         return _testall_array_impl(requests)
@@ -269,6 +284,9 @@ def testany(requests):
     that indicates whether any of requests is completed, and index of request
     that is guaranteed to be completed. Requires 'requests' parameter to be an
     array or tuple of MPI_Request objects.
+
+    Uninitialized contents of 'requests' (e.g., from numpy.empty()) may
+    cause invalid pointer dereference and segmentation faults.
     """
 
     if isinstance(requests, np.ndarray):

numba_mpi-0.43.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.1
+Name: numba-mpi
+Version: 0.43
+Summary: Numba @njittable MPI wrappers tested on Linux, macOS and Windows
+Home-page: https://github.com/numba-mpi/numba-mpi
+Author: https://github.com/numba-mpi/numba-mpi/graphs/contributors
+License: GPL v3
+Project-URL: Tracker, https://github.com/numba-mpi/numba-mpi/issues
+Project-URL: Documentation, https://numba-mpi.github.io/numba-mpi
+Project-URL: Source, https://github.com/numba-mpi/numba-mpi
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numba
+Requires-Dist: numpy
+Requires-Dist: mpi4py
+Requires-Dist: psutil
+Provides-Extra: tests
+Requires-Dist: pytest <8.0.0 ; extra == 'tests'
+
+# <img src="https://raw.githubusercontent.com/numba-mpi/numba-mpi/main/.github/numba_mpi_logo.svg" style="height:50pt" alt="numba-mpi logo"> numba-mpi
+
+[![Python 3](https://img.shields.io/static/v1?label=Python&logo=Python&color=3776AB&message=3)](https://www.python.org/)
+[![LLVM](https://img.shields.io/static/v1?label=LLVM&logo=LLVM&color=gold&message=Numba)](https://numba.pydata.org)
+[![Linux OK](https://img.shields.io/static/v1?label=Linux&logo=Linux&color=yellow&message=%E2%9C%93)](https://en.wikipedia.org/wiki/Linux)
+[![macOS OK](https://img.shields.io/static/v1?label=macOS&logo=Apple&color=silver&message=%E2%9C%93)](https://en.wikipedia.org/wiki/macOS)
+[![Windows OK](https://img.shields.io/static/v1?label=Windows&logo=Windows&color=white&message=%E2%9C%93)](https://en.wikipedia.org/wiki/Windows)
+[![Github Actions Status](https://github.com/numba-mpi/numba-mpi/workflows/tests+pypi/badge.svg?branch=main)](https://github.com/numba-mpi/numba-mpi/actions/workflows/tests+pypi.yml)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/numba-mpi/numba-mpi/graphs/commit-activity)
+[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0.html)
+[![PyPI version](https://badge.fury.io/py/numba-mpi.svg)](https://pypi.org/project/numba-mpi)
+[![Anaconda-Server Badge](https://anaconda.org/conda-forge/numba-mpi/badges/version.svg)](https://anaconda.org/conda-forge/numba-mpi)
+[![AUR package](https://repology.org/badge/version-for-repo/aur/python:numba-mpi.svg)](https://aur.archlinux.org/packages/python-numba-mpi)
+[![DOI](https://zenodo.org/badge/316911228.svg)](https://zenodo.org/badge/latestdoi/316911228)
+
+### Overview
+numba-mpi provides Python wrappers to the C MPI API callable from within [Numba JIT-compiled code](https://numba.readthedocs.io/en/stable/user/jit.html) (@njit mode).
+
+Support is provided for a subset of MPI routines covering: `size`/`rank`, `send`/`recv`, `allreduce`, `bcast`, `scatter`/`gather` & `allgather`, `barrier`, `wtime`
+and basic asynchronous communication with `isend`/`irecv` (only for contiguous arrays); for request handling including `wait`/`waitall`/`waitany` and `test`/`testall`/`testany`.
+
+The API uses NumPy and supports both numeric and character datatypes (e.g., `broadcast`). 
+Auto-generated docstring-based API docs are published on the web: https://numba-mpi.github.io/numba-mpi
+
+Packages can be obtained from 
+  [PyPI](https://pypi.org/project/numba-mpi), 
+  [Conda Forge](https://anaconda.org/conda-forge/numba-mpi), 
+  [Arch Linux](https://aur.archlinux.org/packages/python-numba-mpi)
+  or by invoking `pip install git+https://github.com/numba-mpi/numba-mpi.git`.
+
+numba-mpi is a pure-Python package.
+The codebase includes a test suite used through the GitHub Actions workflows ([thanks to mpi4py's setup-mpi](https://github.com/mpi4py/setup-mpi)!)
+for automated testing on: Linux ([MPICH](https://www.mpich.org/), [OpenMPI](https://www.open-mpi.org/doc/) 
+& [Intel MPI](https://www.intel.com/content/www/us/en/developer/tools/oneapi/mpi-library.html)), 
+macOS ([MPICH](https://www.mpich.org/) & [OpenMPI](https://www.open-mpi.org/doc/)) and 
+Windows ([MS MPI](https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi)).
+
+Features that are not implemented yet include (help welcome!):
+- support for non-default communicators
+- support for `MPI_IN_PLACE` in `[all]gather`/`scatter` and `allreduce`
+- support for `MPI_Type_create_struct` (Numpy structured arrays) 
+- ...
+
+### Hello world send/recv example:
+```python
+import numba, numba_mpi, numpy
+
+@numba.njit()
+def hello():
+    src = numpy.array([1., 2., 3., 4., 5.])
+    dst_tst = numpy.empty_like(src)
+
+    if numba_mpi.rank() == 0:
+        numba_mpi.send(src, dest=1, tag=11)
+    elif numba_mpi.rank() == 1:
+        numba_mpi.recv(dst_tst, source=0, tag=11)
+
+hello()
+```
+
+### Example comparing numba-mpi vs. mpi4py performance:
+
+The example below compares `Numba`+`mpi4py` vs. `Numba`+`numba-mpi` performance.
+The sample code estimates $\pi$ by numerical integration of $\int_0^1 (4/(1+x^2))dx=\pi$ 
+dividing the workload into `n_intervals` handled by separate MPI processes 
+and then obtaining a sum using `allreduce` (see, e.g., analogous [Matlab docs example](https://www.mathworks.com/help/parallel-computing/numerical-estimation-of-pi-using-message-passing.html)).
+The computation is carried out in a JIT-compiled function `get_pi_part()` and is repeated
+`N_TIMES`. The repetitions and the MPI-handled reduction are done outside or 
+inside of the JIT-compiled block for `mpi4py` and `numba-mpi`, respectively.
+Timing is repeated `N_REPEAT` times and the minimum time is reported.
+The generated plot shown below depicts the speedup obtained by replacing `mpi4py`
+with `numba_mpi`, plotted as a function of `N_TIMES / n_intervals` - the number of MPI calls per 
+interval. The speedup, which stems from avoiding roundtrips between JIT-compiled
+and Python code is significant (150%-300%) in all cases. The more often communication
+is needed (smaller `n_intervals`), the larger the measured speedup. Note that nothing 
+in the actual number crunching (within the `get_pi_part()` function) or in the employed communication logic
+(handled by the same MPI library) differs between the `mpi4py` or `numba-mpi` solutions.
+These are the overhead of `mpi4py` higher-level abstractions and the overhead of 
+repeatedly entering and leaving the JIT-compiled block if using `mpi4py`, which can be
+eliminated by using `numba-mpi`, and which the measured differences in execution time
+stem from.
+```python
+import timeit, mpi4py, numba, numpy as np, numba_mpi
+
+N_TIMES = 10000
+RTOL = 1e-3
+
+@numba.jit
+def get_pi_part(n_intervals=1000000, rank=0, size=1):
+    h = 1 / n_intervals
+    partial_sum = 0.0
+    for i in range(rank + 1, n_intervals, size):
+        x = h * (i - 0.5)
+        partial_sum += 4 / (1 + x**2)
+    return h * partial_sum
+
+@numba.jit
+def pi_numba_mpi(n_intervals):
+    pi = np.array([0.])
+    part = np.empty_like(pi)
+    for _ in range(N_TIMES):
+        part[0] = get_pi_part(n_intervals, numba_mpi.rank(), numba_mpi.size())
+        numba_mpi.allreduce(part, pi, numba_mpi.Operator.SUM)
+        assert abs(pi[0] - np.pi) / np.pi < RTOL
+
+def pi_mpi4py(n_intervals):
+    pi = np.array([0.])
+    part = np.empty_like(pi)
+    for _ in range(N_TIMES):
+        part[0] = get_pi_part(n_intervals, mpi4py.MPI.COMM_WORLD.rank, mpi4py.MPI.COMM_WORLD.size)
+        mpi4py.MPI.COMM_WORLD.Allreduce(part, (pi, mpi4py.MPI.DOUBLE), op=mpi4py.MPI.SUM)
+        assert abs(pi[0] - np.pi) / np.pi < RTOL
+
+plot_x = [x for x in range(1, 11)]
+plot_y = {'numba_mpi': [], 'mpi4py': []}
+for x in plot_x:
+    for impl in plot_y:
+        plot_y[impl].append(min(timeit.repeat(
+            f"pi_{impl}(n_intervals={N_TIMES // x})",
+            globals=locals(),
+            number=1,
+            repeat=10
+        )))
+
+if numba_mpi.rank() == 0:
+    from matplotlib import pyplot
+    pyplot.figure(figsize=(8.3, 3.5), tight_layout=True)
+    pyplot.plot(plot_x, np.array(plot_y['mpi4py'])/np.array(plot_y['numba_mpi']), marker='o')
+    pyplot.xlabel('number of MPI calls per interval')
+    pyplot.ylabel('mpi4py/numba-mpi wall-time ratio')
+    pyplot.title(f'mpiexec -np {numba_mpi.size()}')
+    pyplot.grid()
+    pyplot.savefig('readme_plot.svg')
+```
+
+![plot](https://github.com/numba-mpi/numba-mpi/releases/download/tip/readme_plot.png)
+
+
+### MPI resources on the web:
+
+- MPI standard and general information:
+    - https://www.mpi-forum.org/docs
+    - https://en.wikipedia.org/wiki/Message_Passing_Interface
+- MPI implementations:
+    - OpenMPI: https://www.open-mpi.org
+    - MPICH: https://www.mpich.org
+    - MS MPI: https://learn.microsoft.com/en-us/message-passing-interface
+    - Intel MPI: https://intel.com/content/www/us/en/developer/tools/oneapi/mpi-library-documentation.html
+- MPI bindings:
+    - Python: https://mpi4py.readthedocs.io
+    - Julia: https://juliaparallel.org/MPI.jl
+    - Rust: https://docs.rs/mpi
+    - C++: https://boost.org/doc/html/mpi.html
+    - R: https://cran.r-project.org/web/packages/Rmpi
+
+### Acknowledgements:
+
+Development of numba-mpi has been supported by the [Polish National Science Centre](https://ncn.gov.pl/en) (grant no. 2020/39/D/ST10/01220).
+

{numba_mpi-0.40.dist-info → numba_mpi-0.43.dist-info}/RECORD

@@ -1,4 +1,4 @@
-numba_mpi/__init__.py,sha256=mpW16BzokTCNGHClW6K4qGvMIRqPrw0K2OHNSCSml5Y,781
+numba_mpi/__init__.py,sha256=VkDzjRJcaS6j739oHdCqhdUcZLBlMFxfcn58zDjevoQ,741
 numba_mpi/common.py,sha256=2JJoUrd3Qa6GIFk6Zlt2NudS7ZurPxpVwBLRGSkCg5E,2266
 numba_mpi/utils.py,sha256=gfGFuzmGgs4FnBqzPI91ftAq4UHgXb_HFkvxrVWkcIo,1866
 numba_mpi/api/__init__.py,sha256=Zj5df4lWeGpxAXV8jKGFnmtLBQ50HwNU8dPf-os06X8,51
@@ -11,13 +11,13 @@ numba_mpi/api/isend.py,sha256=2mpP4FhMk0GrikjDluKwRnpVywdLj9RD4HVVEMSj9A8,1080
 numba_mpi/api/operator.py,sha256=3VTPZAdOP05bxdqt3lA0hRDICM-iaBMa4m-krEdO91s,342
 numba_mpi/api/rank.py,sha256=pqayxw-5QDJ7VJ3gKrvuu1G0sBlYEZt1juhnaDi_JD8,549
 numba_mpi/api/recv.py,sha256=YsYK-q7PNfi3zt0ftVddM363VsnJ4XFfmgMq8aeCr-o,1260
-numba_mpi/api/requests.py,sha256=oDe85ZQ4xFbHWlNdrDhqVLvCkcQHs_9upUf3ms8x58k,8300
+numba_mpi/api/requests.py,sha256=5EhgFyeQCGP8YclSPwxP95c2AhBo19CLlShK0TxCR2U,9114
 numba_mpi/api/scatter_gather.py,sha256=goZn4BxMKakWQHjfXIOdjzK3DJ-lTeaiQQwgnyQeZ_s,2410
 numba_mpi/api/send.py,sha256=jn1hPw0YHBHOaeJop_ZbjaBChaqgfw3nM1xGhW9sabI,909
 numba_mpi/api/size.py,sha256=fYLeUrygvz_XcxIDsLiZlMtS-aiWfp58Zi7aIOAgaj8,549
 numba_mpi/api/wtime.py,sha256=qrTqlefW7K7hqnAQKkGYm8kgdiRGuSAGiHmPcTrhLzE,279
-numba_mpi-0.40.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-numba_mpi-0.40.dist-info/METADATA,sha256=Ps3MqS8YJUUvQOXTGjPJdaKZCr-Ta8ah-9VncEAi5DY,4038
-numba_mpi-0.40.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-numba_mpi-0.40.dist-info/top_level.txt,sha256=yb_ktLmrfuhOZS0rjS81FFNC-gK_4c19WbLG2ViP73g,10
-numba_mpi-0.40.dist-info/RECORD,,
+numba_mpi-0.43.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+numba_mpi-0.43.dist-info/METADATA,sha256=oMga9o3BuVvyY-f-9tCWPqkYjj06J7cIbhLZHGZgW4g,8995
+numba_mpi-0.43.dist-info/WHEEL,sha256=cpQTJ5IWu9CdaPViMhC9YzF8gZuS5-vlfoFihTBC86A,91
+numba_mpi-0.43.dist-info/top_level.txt,sha256=yb_ktLmrfuhOZS0rjS81FFNC-gK_4c19WbLG2ViP73g,10
+numba_mpi-0.43.dist-info/RECORD,,

{numba_mpi-0.40.dist-info → numba_mpi-0.43.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: setuptools (70.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

numba_mpi-0.40.dist-info/METADATA

@@ -1,66 +0,0 @@
-Metadata-Version: 2.1
-Name: numba-mpi
-Version: 0.40
-Summary: Numba @njittable MPI wrappers tested on Linux, macOS and Windows
-Home-page: https://github.com/numba-mpi/numba-mpi
-Author: https://github.com/numba-mpi/numba-mpi/graphs/contributors
-License: GPL v3
-Project-URL: Tracker, https://github.com/numba-mpi/numba-mpi/issues
-Project-URL: Documentation, https://numba-mpi.github.io/numba-mpi
-Project-URL: Source, https://github.com/numba-mpi/numba-mpi
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numba
-Requires-Dist: numpy
-Requires-Dist: mpi4py
-Requires-Dist: psutil
-Provides-Extra: tests
-Requires-Dist: pytest <8.0.0 ; extra == 'tests'
-
-# <img src="https://raw.githubusercontent.com/numba-mpi/numba-mpi/main/.github/numba_mpi_logo.svg" style="height:50pt" alt="numba-mpi logo"> numba-mpi
-
-[![Python 3](https://img.shields.io/static/v1?label=Python&logo=Python&color=3776AB&message=3)](https://www.python.org/)
-[![LLVM](https://img.shields.io/static/v1?label=LLVM&logo=LLVM&color=gold&message=Numba)](https://numba.pydata.org)
-[![Linux OK](https://img.shields.io/static/v1?label=Linux&logo=Linux&color=yellow&message=%E2%9C%93)](https://en.wikipedia.org/wiki/Linux)
-[![macOS OK](https://img.shields.io/static/v1?label=macOS&logo=Apple&color=silver&message=%E2%9C%93)](https://en.wikipedia.org/wiki/macOS)
-[![Windows OK](https://img.shields.io/static/v1?label=Windows&logo=Windows&color=white&message=%E2%9C%93)](https://en.wikipedia.org/wiki/Windows)
-[![Github Actions Status](https://github.com/numba-mpi/numba-mpi/workflows/tests+pypi/badge.svg?branch=main)](https://github.com/numba-mpi/numba-mpi/actions/workflows/tests+pypi.yml)
-[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/numba-mpi/numba-mpi/graphs/commit-activity)
-[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0.html)
-[![PyPI version](https://badge.fury.io/py/numba-mpi.svg)](https://pypi.org/project/numba-mpi)
-[![Anaconda-Server Badge](https://anaconda.org/conda-forge/numba-mpi/badges/version.svg)](https://anaconda.org/conda-forge/numba-mpi)
-[![AUR package](https://repology.org/badge/version-for-repo/aur/python:numba-mpi.svg)](https://aur.archlinux.org/packages/python-numba-mpi)
-[![DOI](https://zenodo.org/badge/316911228.svg)](https://zenodo.org/badge/latestdoi/316911228)
-
-#### Numba @njittable MPI wrappers
-- covering: `size`/`rank`, `send`/`recv`, `allreduce`, `bcast`, `scatter`/`gather` & `allgather`, `barrier` and `wtime`
-- basic asynchronous communication with `isend`/`irecv` (only for contiguous arrays); for request handling including `wait`/`waitall`/`waitany` and `test`/`testall`/`testany`
-- not yet implemented: support for non-default communicators, ...
-- API based on NumPy and supporting numeric and character datatypes 
-- auto-generated docstring-based API docs on the web: https://numba-mpi.github.io/numba-mpi
-- pure-Python implementation with packages available at [PyPI](https://pypi.org/project/numba-mpi), [Conda Forge](https://anaconda.org/conda-forge/numba-mpi) and for [Arch Linux](https://aur.archlinux.org/packages/python-numba-mpi)
-- CI-tested on: Linux ([MPICH](https://www.mpich.org/), [OpenMPI](https://www.open-mpi.org/doc/) & [Intel MPI](https://www.intel.com/content/www/us/en/developer/tools/oneapi/mpi-library.html)), macOS ([MPICH](https://www.mpich.org/) & [OpenMPI](https://www.open-mpi.org/doc/)) and Windows ([MS MPI](https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi))
-
-Hello world example:
-```python
-import numba, numba_mpi, numpy
-
-@numba.njit()
-def hello():
-  print(numba_mpi.rank())
-  print(numba_mpi.size())
-
-  src = numpy.array([1., 2., 3., 4., 5.])
-  dst_tst = numpy.empty_like(src)
-
-  if numba_mpi.rank() == 0:
-    numba_mpi.send(src, dest=1, tag=11)
-  elif numba_mpi.rank() == 1:
-    numba_mpi.recv(dst_tst, source=0, tag=11)
-
-hello()
-```
-
-For information on MPI, see:
-- https://www.mpi-forum.org/docs/
-- https://mpi4py.readthedocs.io/en/stable/