[EXTENDED] PR 26 Parallelized multiple right-hand side support, fully typed tools

.gitignore

@@ -83,7 +83,7 @@ celerybeat-schedule
 .env
 
 # virtualenv
-.venv
+.venv*
 venv/
 ENV/
 

CHANGELOG.md

@@ -2,104 +2,146 @@
 
 All notable changes to **pentapy** will be documented in this file.
 
+## [2.0.0] - 2024-06
+
+See [#27](https://github.com/GeoStat-Framework/pentapy/pull/27)
+
+### Breaking Changes
+
+- fully parallelized the Cython implementation of PTRANS-I and PTRANS-II for single and multiple right-hand sides support that can now be enabled via the new `num_threads` parameter in `pentapy.solve` (default: 1)
+- updated the **Cython low level interfaces** to PTRANS-I and PTRANS-II to **only accept C-contiguous arrays** (not backwards compatible)
+
+### Enhancements
+
+- improved error handling and added debug information to error messages
+
+### Changes
+
+- refactored and documented the Cython implementation of PTRANS-I and PTRANS-II for single and multiple right-hand sides support
+- fully typed the `pentapy.tools` module and the function ``pentapy.solve`
+- made internal solver alias handling of `pentapy.solve` smarter, more robust, and removed all duplicate code
+- gave all solvers a consistent interface
+- made code in ``pentapy.core` `more maintainable
+- fixed typos in documentation
+
+### Bugfixes
+
+- fixed error handling in case of zero-division to trigger dead error handling branch (see [Issue 23](https://github.com/GeoStat-Framework/pentapy/issues/23))
+- fixed edge case error for row/column count of 3 (see [Issue 24](https://github.com/GeoStat-Framework/pentapy/issues/24))
+
+### Tests
+
+- transitioned from `unittest`-based testing to fully `pytest`-based testing with parametrized and parallelized exhaustive testing (see [Issue 25](https://github.com/GeoStat-Framework/pentapy/issues/25))
+- made actual tests more meaningful by comparing them to LAPACK as reference standard (see [Issue 25](https://github.com/GeoStat-Framework/pentapy/issues/25))
+- included external solver bindings accessible via `pentapy.solve` as part of the test suite
+- increased true coverage (not line-hit coverage) close to 100%
 
 ## [1.3.0] - 2024-04
 
 See [#21](https://github.com/GeoStat-Framework/pentapy/pull/21)
 
 ### Enhancements
+
 - added support for python 3.12
 - added support for numpy 2
 - build extensions with numpy 2 and cython 3
 
 ### Changes
+
 - dropped python 3.7 support
 - dropped 32bit builds
 - linted cython files
 - increase maximal line length to 88 (black default)
 
-
 ## [1.2.0] - 2023-04
 
 See [#19](https://github.com/GeoStat-Framework/pentapy/pull/19)
 
 ### Enhancements
+
 - added support for python 3.10 and 3.11
 - add wheels for arm64 systems
 - created `solver.pxd` file to be able to cimport the solver module
 - added a `CITATION.bib` file
 
 ### Changes
+
 - move to `src/` based package structure
 - dropped python 3.6 support
 - move meta-data to pyproject.toml
 - simplified documentation
 
 ### Bugfixes
+
 - determine correct version when installing from archive
 
 ## [1.1.2] - 2021-07
 
 ### Changes
+
 - new package structure with `pyproject.toml` ([#15](https://github.com/GeoStat-Framework/pentapy/pull/15))
 - Sphinx-Gallery for Examples
 - Repository restructuring: use a single `main` branch
 - use `np.asarray` in `solve` to speed up computation ([#17](https://github.com/GeoStat-Framework/pentapy/pull/17))
 
-
 ## [1.1.1] - 2021-02
 
 ### Enhancements
+
 - Python 3.9 support
 
 ### Changes
-- GitHub Actions for CI
 
+- GitHub Actions for CI
 
 ## [1.1.0] - 2020-03-22
 
 ### Enhancements
+
 - Python 3.8 support
 
 ### Changes
+
 - python only builds are no longer available
 - Python 2.7 and 3.4 support dropped
 
-
 ## [1.0.3] - 2019-11-10
 
 ### Enhancements
+
 - the algorithms `PTRANS-I` and `PTRANS-II` now raise a warning when they can not solve the given system
 - there are now switches to install scipy and umf solvers as extra requirements
 
 ### Bugfixes
-- multiple minor bugfixes
 
+- multiple minor bugfixes
 
 ## [1.0.0] - 2019-09-18
 
 ### Enhancements
-- the second algorithm `PTRANS-II` from *Askar et al. 2015* is now implemented and can be used by `solver=2`
+
+- the second algorithm `PTRANS-II` from _Askar et al. 2015_ is now implemented and can be used by `solver=2`
 - the package is now tested and a coverage is calculated
 - there are now pre-built binaries for Python 3.7
 - the documentation is now available under https://geostat-framework.readthedocs.io/projects/pentapy
 
 ### Changes
-- pentapy is now licensed under the MIT license
 
+- pentapy is now licensed under the MIT license
 
 ## [0.1.1] - 2019-03-08
 
 ### Bugfixes
-- MANIFEST.in was missing in the 0.1.0 version
 
+- MANIFEST.in was missing in the 0.1.0 version
 
 ## [0.1.0] - 2019-03-07
 
 This is the first release of pentapy, a python toolbox for solving pentadiagonal linear equation systems.
 The solver is implemented in cython, which makes it really fast.
 
-
+[2.0.0]: https://github.com/GeoStat-Framework/pentapy/compare/v1.4.0...v2.0.0
+[1.4.0]: https://github.com/GeoStat-Framework/pentapy/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/GeoStat-Framework/pentapy/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/GeoStat-Framework/pentapy/compare/v1.1.2...v1.2.0
 [1.1.2]: https://github.com/GeoStat-Framework/pentapy/compare/v1.1.1...v1.1.2

README.md

@@ -107,7 +107,7 @@ Have a look at the script: [``examples/03_perform_simple.py``](https://github.co
 
 ## Requirements:
 
-- [NumPy >= 1.14.5](https://www.numpy.org)
+- [NumPy >= 1.20.0](https://www.numpy.org)
 
 ### Optional
 

docs/source/index.rst

@@ -94,7 +94,7 @@ The performance plot was created with ``perfplot`` (`link <https://github.com/ns
 Requirements
 ============
 
-- `Numpy >= 1.14.5 <http://www.numpy.org>`_
+- `Numpy >= 1.20.0 <http://www.numpy.org>`_
 
 Optional
 --------

examples/README.rst

@@ -88,7 +88,7 @@ If M is a full matrix, you call the following:
 
     X = pp.solve(M, Y)
 
-If M is flattend in row-wise order you have to set the keyword argument ``is_flat=True``:
+If M is flattened in row-wise order you have to set the keyword argument ``is_flat=True``:
 
 .. code-block:: python
 
@@ -99,7 +99,7 @@ If M is flattend in row-wise order you have to set the keyword argument ``is_fla
 
     X = pp.solve(M, Y, is_flat=True)
 
-If you got a col-wise flattend matrix you have to set ``index_row_wise=False``:
+If you got a col-wise flattened matrix you have to set ``index_row_wise=False``:
 
 .. code-block:: python
 

paper/paper.md

@@ -51,8 +51,8 @@ $$
 
 Here, $d_i$ are the diagonal entries and $d_i^{(j)}$ represent the $j$-th minor diagonal.
 
-Recently, @askar presented two algorithms to 
-solve the linear systems of equations for $X$, ``PTRANS-I`` and ``PTRANS-II``, 
+Recently, @askar presented two algorithms to
+solve the linear systems of equations for $X$, ``PTRANS-I`` and ``PTRANS-II``,
 applying first transformation to a triangular matrix and then, respectively, backward and forward substitution.
 ``pentapy`` provides Cython [@cython] implementations of these
 algorithms and a set of tools to convert matrices to row-wise or
@@ -73,7 +73,7 @@ The linear algebra solver of NumPy [@numpy] served as a standard reference, whic
 ``pentapy`` is designed to provide a fast solver for the special case of a
 pentadiagonal linear system. To the best of the author's knowledge,
 this package outperforms the current algorithms for solving pentadiagonal systems in Python.
-The solver can handle different input formats of the coefficient matrix, i.e., a flattend matrix or a
+The solver can handle different input formats of the coefficient matrix, i.e., a flattened matrix or a
 quadratic matrix.
 
 

pyproject.toml

@@ -4,6 +4,7 @@ requires = [
     "setuptools_scm>=7",
     "numpy>=2.0.0rc1,<2.3; python_version >= '3.9'",
     "oldest-supported-numpy; python_version < '3.9'",
+    "extension-helpers>=1",
     "Cython>=3.0.10,<3.1.0",
 ]
 build-backend = "setuptools.build_meta"
@@ -35,15 +36,14 @@ classifiers = [
     "Topic :: Scientific/Engineering",
     "Topic :: Utilities",
 ]
-dependencies = ["numpy>=1.20.0"]
+dependencies = [
+    "numpy>=1.20.0",
+]
 
 [project.optional-dependencies]
 scipy = ["scipy"]
 umfpack = ["scikit-umfpack"]
-all = [
-    "scipy",
-    "scikit-umfpack",
-]
+all = ["scipy", "scikit-umfpack"]
 doc = [
     "m2r2>=0.2.8",
     "scipy>=1.1.0",
@@ -54,12 +54,17 @@ doc = [
     "sphinx-gallery>=0.8",
     "sphinx-rtd-theme>=2",
 ]
-test = ["pytest-cov>=3"]
+test = [
+    "pytest>=8",
+    "pytest-cov>=3",
+    "pytest-xdist>=3",
+    "scipy>=1.1.0",
+]
 check = [
-  "black>=24,<25",
-  "isort[colors]",
-  "pylint",
-  "cython-lint",
+    "black>=24,<25",
+    "isort[colors]",
+    "pylint",
+    "cython-lint",
 ]
 
 [project.urls]
@@ -103,6 +108,8 @@ max-line-length = 120
         "*examples*",
         "*tests*",
         "*paper*",
+        "src/pentapy/_version.py",
+        "src/pentapy/__init__.py",
     ]
 
     [tool.coverage.report]
@@ -136,6 +143,9 @@ max-line-length = 120
     max-attributes = 25
     max-public-methods = 75
 
+[tool.pytest.ini_options]
+addopts = "--doctest-modules"
+
 [tool.cibuildwheel]
 # Switch to using build
 build-frontend = "build"

setup.py

@@ -1,23 +1,58 @@
-"""pentapy: A toolbox for pentadiagonal matrizes."""
+"""pentapy: A toolbox for pentadiagonal matrices."""
+
+# === Imports ===
 
 import os
 
 import numpy as np
 from Cython.Build import cythonize
+from extension_helpers import add_openmp_flags_if_available
 from setuptools import Extension, setup
 
+# === Constants ===
+
+# the environment variable key for the build of the serial/parallel version
+PENTAPY_BUILD_PARALLEL = "PENTAPY_BUILD_PARALLEL"
+# the compiler flags for the OpenMP parallelization
+OPENMP = "OPENMP"
+# the number of threads for the Cython build
+CYTHON_BUILD_NUM_THREADS = 1
+
+# === Setup ===
+
 # cython extensions
 CY_MODULES = [
     Extension(
-        name=f"pentapy.solver",
+        name="pentapy.solver",
         sources=[os.path.join("src", "pentapy", "solver.pyx")],
         include_dirs=[np.get_include()],
         define_macros=[("NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION")],
     )
 ]
 
+# the OpenMP link is added if available/requested
+# the environment variables can be PENTAPY_BUILD_PARALLEL = 0 (builds serial version) or
+# PENTAPY_BUILD_PARALLEL != 0 (builds parallel version)
+with_open_mp = False
+if int(os.environ.get(PENTAPY_BUILD_PARALLEL, "0")):
+    openmp_added = [add_openmp_flags_if_available(mod) for mod in CY_MODULES]
+    with_open_mp = any(openmp_added)
+    if with_open_mp:
+        open_mp_str = "linking OpenMP (parallel version)"
+    else:
+        open_mp_str = "not linking OpenMP (serial version)"
+
+    print(f"PENTAPY SETUP - {open_mp_str}")
+
+else:
+    print("PENTAPY SETUP - OpenMP not requested (serial version)")
+
 setup(
-    ext_modules=cythonize(CY_MODULES),
+    ext_modules=cythonize(
+        CY_MODULES,
+        nthreads=CYTHON_BUILD_NUM_THREADS,
+        compile_time_env={OPENMP: with_open_mp},
+    ),
     package_data={"pentapy": ["*.pxd"]},  # include pxd files
     include_package_data=False,  # ignore other files
     zip_safe=False,

src/pentapy/.gitignore

@@ -0,0 +1,2 @@
+# Cython html files
+*.html

src/pentapy/__init__.py

@@ -44,7 +44,7 @@
 
 try:
     from pentapy._version import __version__
-except ImportError:  # pragma: nocover
+except ImportError:  # pragma: no cover
     # package is not installed
     __version__ = "0.0.0.dev0"