pymatsolver 0.2.0__tar.gz → 0.3.0__tar.gz

pymatsolver-0.3.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.1
+Name: pymatsolver
+Version: 0.3.0
+Summary: pymatsolver: Matrix Solvers for Python
+Author-email: SimPEG developers <rowanc1@gmail.com>
+License: The MIT License (MIT)
+        
+        Copyright (c) 2013-2016 Rowan Cockett
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of
+        this software and associated documentation files (the "Software"), to deal in
+        the Software without restriction, including without limitation the rights to
+        use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+        the Software, and to permit persons to whom the Software is furnished to do so,
+        subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+        FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+        COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+        IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+        CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+        
+Project-URL: Homepage, https://simpeg.xyz
+Project-URL: Documentation, https://simpeg.xyz/pymatsolver/
+Project-URL: Repository, https://github.com/simpeg/pymatsolver
+Keywords: matrix solver
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Natural Language :: English
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scipy>=1.8
+Provides-Extra: pardiso
+Requires-Dist: pydiso; extra == "pardiso"
+Provides-Extra: mumps
+Requires-Dist: python-mumps; extra == "mumps"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Requires-Dist: pydata-sphinx-theme; extra == "docs"
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Provides-Extra: build
+Requires-Dist: setuptools_scm>=8; extra == "build"
+Requires-Dist: setuptools>=64; extra == "build"
+
+pymatsolver
+***********
+
+.. image:: https://img.shields.io/pypi/v/pymatsolver.svg
+    :target: https://pypi.python.org/pypi/pymatsolver
+    :alt: Latest PyPI version
+
+.. image:: https://img.shields.io/badge/license-MIT-blue.svg
+    :target: https://github.com/simpeg/pymatsolver/blob/master/LICENSE
+    :alt: MIT license.
+
+.. image:: https://codecov.io/gh/simpeg/pymatsolver/branch/main/graph/badge.svg?token=8uQoxzxf3r
+    :target: https://codecov.io/gh/simpeg/pymatsolver
+    :alt: Coverage status
+
+
+A (sparse) matrix solver for python.
+
+Solving Ax = b should be as easy as:
+
+.. code-block:: python
+
+    Ainv = Solver(A)
+    x = Ainv * b
+
+In pymatsolver we provide a number of wrappers to existing numerical packages. Nothing fancy here.
+
+Solvers Available
+=================
+
+All solvers work with :code:`scipy.sparse` matricies, and a single or multiple right hand sides using :code:`numpy`:
+
+* L/U Triangular Solves
+* Wrapping of SciPy matrix solvers (direct and indirect)
+* Pardiso solvers
+* Mumps solvers
+
+
+Installing Solvers
+==================
+Often, there are faster solvers available for your system than the default scipy factorizations available.
+pymatsolver provides a consistent interface to both MKL's ``Pardiso`` routines and the ``MUMPS`` solver package. To
+make use of these we use intermediate wrappers for the libraries that must be installed separately.
+
+Pardiso
+-------
+The Pardiso interface is recommended for Intel processor based systems. The interface is enabled by
+the ``pydiso`` python package, which can be installed through conda-forge as:
+
+.. code::
+
+    conda install -c conda-forge pydiso
+
+Mumps
+-----
+Mumps is available for all platforms. The mumps interface is enabled by installing the ``python-mumps``
+wrapper package. This can easily be installed through conda-forge with:
+
+.. code::
+
+    conda install -c conda-forge python-mumps
+
+
+
+Code:
+https://github.com/simpeg/pymatsolver
+
+
+Tests:
+https://github.com/simpeg/pymatsolver/actions
+
+
+Bugs & Issues:
+https://github.com/simpeg/pymatsolver/issues
+
+License: MIT

pymatsolver-0.3.0/README.rst

@@ -0,0 +1,76 @@
+pymatsolver
+***********
+
+.. image:: https://img.shields.io/pypi/v/pymatsolver.svg
+    :target: https://pypi.python.org/pypi/pymatsolver
+    :alt: Latest PyPI version
+
+.. image:: https://img.shields.io/badge/license-MIT-blue.svg
+    :target: https://github.com/simpeg/pymatsolver/blob/master/LICENSE
+    :alt: MIT license.
+
+.. image:: https://codecov.io/gh/simpeg/pymatsolver/branch/main/graph/badge.svg?token=8uQoxzxf3r
+    :target: https://codecov.io/gh/simpeg/pymatsolver
+    :alt: Coverage status
+
+
+A (sparse) matrix solver for python.
+
+Solving Ax = b should be as easy as:
+
+.. code-block:: python
+
+    Ainv = Solver(A)
+    x = Ainv * b
+
+In pymatsolver we provide a number of wrappers to existing numerical packages. Nothing fancy here.
+
+Solvers Available
+=================
+
+All solvers work with :code:`scipy.sparse` matricies, and a single or multiple right hand sides using :code:`numpy`:
+
+* L/U Triangular Solves
+* Wrapping of SciPy matrix solvers (direct and indirect)
+* Pardiso solvers
+* Mumps solvers
+
+
+Installing Solvers
+==================
+Often, there are faster solvers available for your system than the default scipy factorizations available.
+pymatsolver provides a consistent interface to both MKL's ``Pardiso`` routines and the ``MUMPS`` solver package. To
+make use of these we use intermediate wrappers for the libraries that must be installed separately.
+
+Pardiso
+-------
+The Pardiso interface is recommended for Intel processor based systems. The interface is enabled by
+the ``pydiso`` python package, which can be installed through conda-forge as:
+
+.. code::
+
+    conda install -c conda-forge pydiso
+
+Mumps
+-----
+Mumps is available for all platforms. The mumps interface is enabled by installing the ``python-mumps``
+wrapper package. This can easily be installed through conda-forge with:
+
+.. code::
+
+    conda install -c conda-forge python-mumps
+
+
+
+Code:
+https://github.com/simpeg/pymatsolver
+
+
+Tests:
+https://github.com/simpeg/pymatsolver/actions
+
+
+Bugs & Issues:
+https://github.com/simpeg/pymatsolver/issues
+
+License: MIT

pymatsolver-0.3.0/pymatsolver/__init__.py

@@ -0,0 +1,117 @@
+"""
+===
+API
+===
+.. currentmodule:: pymatsolver
+
+.. autosummary::
+  :toctree: generated/
+
+  solvers.Base
+
+Basic Solvers
+=============
+
+Diagonal
+--------
+.. autosummary::
+  :toctree: generated/
+
+  Diagonal
+
+Triangular
+----------
+.. autosummary::
+  :toctree: generated/
+
+  Triangle
+  Forward
+  Backward
+
+Iterative Solvers
+=================
+
+.. autosummary::
+  :toctree: generated/
+
+  SolverCG
+  BiCGJacobi
+
+Direct Solvers
+==============
+
+.. autosummary::
+  :toctree: generated/
+
+  Solver
+  SolverLU
+  Pardiso
+  Mumps
+"""
+
+# Simple solvers
+from .solvers import Diagonal, Triangle, Forward, Backward
+from .wrappers import wrap_direct, WrapDirect
+from .wrappers import wrap_iterative, WrapIterative
+
+# Scipy Iterative solvers
+from .iterative import SolverCG
+from .iterative import SolverBiCG
+from .iterative import BiCGJacobi
+
+# Scipy direct solvers
+from .direct import Solver, pardiso
+from .direct import SolverLU
+
+from .solvers import SolverAccuracyError
+from .direct import Pardiso, Mumps
+from .direct.pardiso import _available as _pardiso_available
+from .direct.mumps import _available as _mumps_available
+
+SolverHelp = {}
+AvailableSolvers = {
+    "Diagonal": True,
+    "Solver": True,
+    "SolverLU": True,
+    "SolverCG": True,
+    "Triangle": True,
+    "Pardiso": _pardiso_available,
+    "Mumps": _mumps_available,
+}
+
+BicgJacobi = BiCGJacobi  # backwards compatibility
+PardisoSolver = Pardiso  # backwards compatibility
+
+if not AvailableSolvers["Pardiso"]:
+    SolverHelp['Pardiso'] = """Pardiso is not working
+
+Ensure that you have pydiso installed, which may also require Python
+to be installed through conda.
+"""
+
+if not AvailableSolvers["Mumps"]:
+    SolverHelp['Mumps'] = """Mumps is not working.
+
+Ensure that you have python-mumps installed, which may also require Python
+to be installed through conda.
+"""
+
+__author__ = 'SimPEG Team'
+__license__ = 'MIT'
+__copyright__ = '2013 - 2024, SimPEG Team, https://simpeg.xyz'
+
+from importlib.metadata import version, PackageNotFoundError
+
+# Version
+try:
+    # - Released versions just tags:       0.8.0
+    # - GitHub commits add .dev#+hash:     0.8.1.dev4+g2785721
+    # - Uncommitted changes add timestamp: 0.8.1.dev4+g2785721.d20191022
+    __version__ = version("pymatsolver")
+except PackageNotFoundError:
+    # If it was not installed, then we don't know the version. We could throw a
+    # warning here, but this case *should* be rare. discretize should be
+    # installed properly!
+    from datetime import datetime
+
+    __version__ = "unknown-" + datetime.today().strftime("%Y%m%d")

pymatsolver-0.3.0/pymatsolver/direct/__init__.py

@@ -0,0 +1,10 @@
+from scipy.sparse.linalg import spsolve, splu
+
+from ..wrappers import WrapDirect
+from .pardiso import Pardiso
+from .mumps import Mumps
+
+Solver = WrapDirect(spsolve, factorize=False, name="Solver")
+SolverLU = WrapDirect(splu, factorize=True, name="SolverLU")
+
+__all__ = ["Solver", "SolverLU", "Pardiso", "Mumps"]

pymatsolver-0.3.0/pymatsolver/direct/mumps.py

@@ -0,0 +1,122 @@
+from pymatsolver.solvers import Base
+try:
+    from mumps import Context
+    _available = True
+except ImportError:
+    Context = None
+    _available = False
+
+class Mumps(Base):
+    """The MUMPS direct solver.
+
+    This solver uses the python-mumps wrappers to factorize a sparse matrix, and use that factorization for solving.
+
+    Parameters
+    ----------
+    A
+        Matrix to solve with.
+    ordering : str, default 'metis'
+        Which ordering algorithm to use. See the `python-mumps` documentation for more details.
+    is_symmetric : bool, optional
+        Whether the matrix is symmetric. By default, it will perform some simple tests to check for symmetry, and
+        default to ``False`` if those fail.
+    is_positive_definite : bool, optional
+        Whether the matrix is positive definite.
+    check_accuracy : bool, optional
+        Whether to check the accuracy of the solution.
+    check_rtol : float, optional
+        The relative tolerance to check against for accuracy.
+    check_atol : float, optional
+        The absolute tolerance to check against for accuracy.
+    accuracy_tol : float, optional
+        Relative accuracy tolerance.
+        .. deprecated:: 0.3.0
+            `accuracy_tol` will be removed in pymatsolver 0.4.0. Use `check_rtol` and `check_atol` instead.
+    **kwargs
+        Extra keyword arguments. If there are any left here a warning will be raised.
+    """
+    _transposed = False
+
+    def __init__(self, A, ordering=None, is_symmetric=None, is_positive_definite=False, check_accuracy=False, check_rtol=1e-6, check_atol=0, accuracy_tol=None, **kwargs):
+        if not _available:
+            raise ImportError(
+                "The Mumps solver requires the python-mumps package to be installed."
+            )
+        is_hermitian = kwargs.pop('is_hermitian', False)
+        super().__init__(A, is_symmetric=is_symmetric, is_positive_definite=is_positive_definite, is_hermitian=is_hermitian, check_accuracy=check_accuracy, check_rtol=check_rtol, check_atol=check_atol, accuracy_tol=accuracy_tol, **kwargs)
+        if ordering is None:
+            ordering = "metis"
+        self.ordering = ordering
+        self.solver = Context()
+        self._set_A(self.A)
+
+    def _set_A(self, A):
+        self.solver.set_matrix(
+            A,
+            symmetric=self.is_symmetric,
+        )
+
+    @property
+    def ordering(self):
+        """The ordering algorithm to use.
+
+        Returns
+        -------
+        str
+        """
+        return self._ordering
+
+    @ordering.setter
+    def ordering(self, value):
+        self._ordering = str(value)
+
+    @property
+    def _factored(self):
+        return self.solver.factored
+
+    def get_attributes(self):
+        attrs = super().get_attributes()
+        attrs['ordering'] = self.ordering
+        return attrs
+
+    def transpose(self):
+        trans_obj = Mumps.__new__(Mumps)
+        trans_obj._A = self.A
+        for attr, value in self.get_attributes().items():
+            setattr(trans_obj, attr, value)
+        trans_obj.solver = self.solver
+        trans_obj._transposed = not self._transposed
+        return trans_obj
+
+    def factor(self, A=None):
+        """(Re)factor the A matrix.
+
+        Parameters
+        ----------
+        A : scipy.sparse.spmatrix
+            The matrix to be factorized. If a previous factorization has been performed, this will
+            reuse the previous factorization's analysis.
+        """
+        reuse_analysis = self._factored
+        do_factor = not self._factored
+        if A is not None and A is not self.A:
+            # if it was previously factored then re-use the analysis.
+            self._set_A(A)
+            self._A = A
+            do_factor = True
+        if do_factor:
+            pivot_tol = 0.0 if self.is_positive_definite else 0.01
+            self.solver.factor(
+                ordering=self.ordering, reuse_analysis=reuse_analysis, pivot_tol=pivot_tol
+            )
+
+    def _solve_multiple(self, rhs):
+        self.factor()
+        if self._transposed:
+            self.solver.mumps_instance.icntl[9] = 0
+        else:
+            self.solver.mumps_instance.icntl[9] = 1
+        sol = self.solver.solve(rhs)
+        return sol
+
+    _solve_single = _solve_multiple

pymatsolver-0.3.0/pymatsolver/direct/pardiso.py

@@ -0,0 +1,138 @@
+from pymatsolver.solvers import Base
+try:
+    from pydiso.mkl_solver import MKLPardisoSolver
+    from pydiso.mkl_solver import set_mkl_pardiso_threads, get_mkl_pardiso_max_threads
+    _available = True
+except ImportError:
+    _available = False
+
+class Pardiso(Base):
+    """The Pardiso direct solver.
+
+    This solver uses the `pydiso` Intel MKL wrapper to factorize a sparse matrix, and use that
+    factorization for solving.
+
+    Parameters
+    ----------
+    A : scipy.sparse.spmatrix
+        Matrix to solve with.
+    n_threads : int, optional
+        Number of threads to use for the `Pardiso` routine in Intel's MKL.
+    is_symmetric : bool, optional
+        Whether the matrix is symmetric. By default, it will perform some simple tests to check for symmetry, and
+        default to ``False`` if those fail.
+    is_positive_definite : bool, optional
+        Whether the matrix is positive definite.
+    is_hermitian : bool, optional
+        Whether the matrix is hermitian. By default, it will perform some simple tests to check, and default to
+        ``False`` if those fail.
+    check_accuracy : bool, optional
+        Whether to check the accuracy of the solution.
+    check_rtol : float, optional
+        The relative tolerance to check against for accuracy.
+    check_atol : float, optional
+        The absolute tolerance to check against for accuracy.
+    accuracy_tol : float, optional
+        Relative accuracy tolerance.
+        .. deprecated:: 0.3.0
+            `accuracy_tol` will be removed in pymatsolver 0.4.0. Use `check_rtol` and `check_atol` instead.
+    **kwargs
+        Extra keyword arguments. If there are any left here a warning will be raised.
+    """
+
+    _transposed = False
+
+    def __init__(self, A, n_threads=None, is_symmetric=None, is_positive_definite=False, is_hermitian=None, check_accuracy=False, check_rtol=1e-6, check_atol=0, accuracy_tol=None, **kwargs):
+        if not _available:
+            raise ImportError("Pardiso solver requires the pydiso package to be installed.")
+        super().__init__(A, is_symmetric=is_symmetric, is_positive_definite=is_positive_definite, is_hermitian=is_hermitian, check_accuracy=check_accuracy, check_rtol=check_rtol, check_atol=check_atol, accuracy_tol=accuracy_tol, **kwargs)
+        self.solver = MKLPardisoSolver(
+            self.A,
+            matrix_type=self._matrixType(),
+            factor=False
+        )
+        if n_threads is not None:
+            self.n_threads = n_threads
+
+    def _matrixType(self):
+        """
+            Set basic matrix type:
+
+            Real::
+
+                 1:  structurally symmetric
+                 2:  symmetric positive definite
+                -2:  symmetric indefinite
+                11:  nonsymmetric
+
+            Complex::
+
+                 6:  symmetric
+                 4:  hermitian positive definite
+                -4:  hermitian indefinite
+                 3:  structurally symmetric
+                13:  nonsymmetric
+
+        """
+        if self.is_real:
+            if self.is_symmetric:
+                if self.is_positive_definite:
+                    return 2
+                else:
+                    return -2
+            else:
+                return 11
+        else:
+            if self.is_symmetric:
+                return 6
+            elif self.is_hermitian:
+                if self.is_positive_definite:
+                    return 4
+                else:
+                    return -4
+            else:
+                return 13
+
+    def factor(self, A=None):
+        """(Re)factor the A matrix.
+
+        Parameters
+        ----------
+        A : scipy.sparse.spmatrix
+            The matrix to be factorized. If a previous factorization has been performed, this will
+            reuse the previous factorization's analysis.
+        """
+        if A is not None and self.A is not A:
+            self._A = A
+            self.solver.refactor(self.A)
+
+    def _solve_multiple(self, rhs):
+        sol = self.solver.solve(rhs, transpose=self._transposed)
+        return sol
+
+    def transpose(self):
+        trans_obj = Pardiso.__new__(Pardiso)
+        trans_obj._A = self.A
+        for attr, value in self.get_attributes().items():
+            setattr(trans_obj, attr, value)
+        trans_obj.solver = self.solver
+        trans_obj._transposed = not self._transposed
+        return trans_obj
+
+    @property
+    def n_threads(self):
+        """Number of threads to use for the Pardiso solver routine.
+
+        This property is global to all Pardiso solver objects for a single python process.
+
+        Returns
+        -------
+        int
+        """
+        return get_mkl_pardiso_max_threads()
+
+    @n_threads.setter
+    def n_threads(self, n_threads):
+        set_mkl_pardiso_threads(n_threads)
+
+    _solve_single = _solve_multiple