numba-mpi 0.41__py3-none-any.whl → 1.0.0__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
 
@@ -18,6 +20,8 @@ from .api.size import size
 from .api.wtime import wtime
 from .common import RequestType
 
+SUCCESS = 0
+
 try:
     __version__ = version(__name__)
 except PackageNotFoundError:

numba_mpi/api/initialized.py

@@ -17,5 +17,6 @@ def initialized():
     """wrapper for MPI_Initialized()"""
     flag = np.empty((1,), dtype=np.intc)
     status = _MPI_Initialized(flag.ctypes.data)
-    assert status == 0
+    if status != 0:
+        return False
     return bool(flag[0])

numba_mpi/api/rank.py

@@ -15,8 +15,9 @@ _MPI_Comm_rank.argtypes = [_MpiComm, ctypes.c_void_p]
 
 @numba.njit()
 def rank():
-    """wrapper for MPI_Comm_rank()"""
+    """wrapper for MPI_Comm_rank(), in case of failure returns 0"""
     value = np.empty(1, dtype=np.intc)
     status = _MPI_Comm_rank(_mpi_addr(_MPI_Comm_World_ptr), value.ctypes.data)
-    assert status == 0
+    if status != 0:
+        value[0] = 0
     return value[0]

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/api/size.py

@@ -15,8 +15,9 @@ _MPI_Comm_size.argtypes = [_MpiComm, ctypes.c_void_p]
 
 @numba.njit()
 def size():
-    """wrapper for MPI_Comm_size()"""
+    """wrapper for MPI_Comm_size(), in case of failure returns 0"""
     value = np.empty(1, dtype=np.intc)
     status = _MPI_Comm_size(_mpi_addr(_MPI_Comm_World_ptr), value.ctypes.data)
-    assert status == 0
+    if status != 0:
+        value[0] = 0
     return value[0]

{numba_mpi-0.41.dist-info → numba_mpi-1.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: numba-mpi
-Version: 0.41
+Version: 1.0.0
 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
@@ -8,6 +8,7 @@ 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
@@ -16,6 +17,7 @@ Requires-Dist: mpi4py
 Requires-Dist: psutil
 Provides-Extra: tests
 Requires-Dist: pytest <8.0.0 ; extra == 'tests'
+Requires-Dist: py-pde ; 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
 
@@ -79,40 +81,46 @@ 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 integration of $4/(1+x^2)$ between 0 and 1
+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`.
-The computation is carried out in a JIT-compiled function 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.
+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 as a function of `n_intervals` - the more often communication
-is needed (smaller `n_intervals`), the larger the expected speedup.
-
+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
-N_REPEAT = 10
 RTOL = 1e-3
 
-@numba.njit
-def get_pi_part(out, n_intervals, rank, size):
+@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)
-    out[0] = h * partial_sum
+    return h * partial_sum
 
-@numba.njit
+@numba.jit
 def pi_numba_mpi(n_intervals):
     pi = np.array([0.])
     part = np.empty_like(pi)
     for _ in range(N_TIMES):
-        get_pi_part(part, n_intervals, numba_mpi.rank(), numba_mpi.size())
+        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
 
@@ -120,30 +128,30 @@ def pi_mpi4py(n_intervals):
     pi = np.array([0.])
     part = np.empty_like(pi)
     for _ in range(N_TIMES):
-        get_pi_part(part, n_intervals, mpi4py.MPI.COMM_WORLD.rank, mpi4py.MPI.COMM_WORLD.size)
+        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 = [1000 * k for k in range(1, 11)]
+plot_x = [x for x in range(1, 11)]
 plot_y = {'numba_mpi': [], 'mpi4py': []}
-for n_intervals in plot_x:
+for x in plot_x:
     for impl in plot_y:
         plot_y[impl].append(min(timeit.repeat(
-            f"pi_{impl}({n_intervals})",
+            f"pi_{impl}(n_intervals={N_TIMES // x})",
             globals=locals(),
             number=1,
-            repeat=N_REPEAT
+            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('n_intervals (workload in between communication)')
-    pyplot.ylabel('wall time ratio (mpi4py / numba_mpi)')
+    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.png')
+    pyplot.savefig('readme_plot.svg')
 ```
 
 ![plot](https://github.com/numba-mpi/numba-mpi/releases/download/tip/readme_plot.png)
@@ -161,6 +169,7 @@ if numba_mpi.rank() == 0:
     - Intel MPI: https://intel.com/content/www/us/en/developer/tools/oneapi/mpi-library-documentation.html
 - MPI bindings:
     - Python: https://mpi4py.readthedocs.io
+    - Python/JAX: https://mpi4jax.readthedocs.io
     - Julia: https://juliaparallel.org/MPI.jl
     - Rust: https://docs.rs/mpi
     - C++: https://boost.org/doc/html/mpi.html
@@ -168,5 +177,11 @@ if numba_mpi.rank() == 0:
 
 ### 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).
+We thank [all contributors](https://github.com/numba-mpi/numba-mpi/graphs/contributors) and users who reported feedback to the project 
+  through [GitHub issues](https://github.com/numba-mpi/numba-mpi/issues).
+
+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),
+  the [Max Planck Society](https://www.mpg.de/en) and the [European Union](https://erc.europa.eu/) (ERC, EmulSim, 101044662). 
+We further 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.
 

{numba_mpi-0.41.dist-info → numba_mpi-1.0.0.dist-info}/RECORD

@@ -1,23 +1,23 @@
-numba_mpi/__init__.py,sha256=mpW16BzokTCNGHClW6K4qGvMIRqPrw0K2OHNSCSml5Y,781
+numba_mpi/__init__.py,sha256=_DsPxgrR80KiJTLqzZRNMVsK_TUJt7EfNFy_MWvBOWk,754
 numba_mpi/common.py,sha256=2JJoUrd3Qa6GIFk6Zlt2NudS7ZurPxpVwBLRGSkCg5E,2266
 numba_mpi/utils.py,sha256=gfGFuzmGgs4FnBqzPI91ftAq4UHgXb_HFkvxrVWkcIo,1866
 numba_mpi/api/__init__.py,sha256=Zj5df4lWeGpxAXV8jKGFnmtLBQ50HwNU8dPf-os06X8,51
 numba_mpi/api/allreduce.py,sha256=szS7YzrQ5a90LlKDiefyxVEiAXnsHbni5g2M1of0TmE,3261
 numba_mpi/api/barrier.py,sha256=9VSJPBC4V0H-xo47uzlT8Hp4xmQhTNLxg5bAcX3Y03g,461
 numba_mpi/api/bcast.py,sha256=8SsYFj9qRjx4l3Q9367JMZd469izlf4if1qusuYILqU,1843
-numba_mpi/api/initialized.py,sha256=fFmhOGl2GkwS9UvPetXy4YrgE4xhMVsyx7Ac8QP0530,479
+numba_mpi/api/initialized.py,sha256=oKXpZzHeips0VU1U9wEF_578kOrfKb_IEXxD_aQ2c2E,497
 numba_mpi/api/irecv.py,sha256=r4JvE7JJPN_hFpS79-idYL3dtp8tR0y0VoIRuHJ29lM,1120
 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/rank.py,sha256=1xZvHUclsK20aMtK07JzXYxW5F4Er8HZgOmcf495sjo,597
 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/size.py,sha256=-RX-FtcIH4qDxCoGOhZjjgEWXpytt79vsH0YX9dtZuY,597
 numba_mpi/api/wtime.py,sha256=qrTqlefW7K7hqnAQKkGYm8kgdiRGuSAGiHmPcTrhLzE,279
-numba_mpi-0.41.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-numba_mpi-0.41.dist-info/METADATA,sha256=4POxiWzQaU7S3NeU8b_GKcog4H6OBjvvV62h-nPHj5I,8147
-numba_mpi-0.41.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-numba_mpi-0.41.dist-info/top_level.txt,sha256=yb_ktLmrfuhOZS0rjS81FFNC-gK_4c19WbLG2ViP73g,10
-numba_mpi-0.41.dist-info/RECORD,,
+numba_mpi-1.0.0.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+numba_mpi-1.0.0.dist-info/METADATA,sha256=X9KbPWSmXB953BPIUua1e9ZVeXP2XeDM9Ppp0ailOKI,9687
+numba_mpi-1.0.0.dist-info/WHEEL,sha256=y4mX-SOX4fYIkonsAGA5N0Oy-8_gI4FXw5HNI1xqvWg,91
+numba_mpi-1.0.0.dist-info/top_level.txt,sha256=yb_ktLmrfuhOZS0rjS81FFNC-gK_4c19WbLG2ViP73g,10
+numba_mpi-1.0.0.dist-info/RECORD,,

{numba_mpi-0.41.dist-info → numba_mpi-1.0.0.dist-info}/WHEEL

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