sparseqr 1.4.1__tar.gz → 1.5__tar.gz

{sparseqr-1.4.1 → sparseqr-1.5}/PKG-INFO

@@ -1,17 +1,21 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: sparseqr
-Version: 1.4.1
+Version: 1.5
 Summary: Python wrapper for SuiteSparseQR
-Keywords: suitesparse,bindings,wrapper,scipy,numpy,qr-decomposition,qr-factorisation,sparse-matrix,sparse-linear-system,sparse-linear-solver
 Author-email: Yotam Gingold <yotam@yotamgingold.com>
-Requires-Python: >= 3.8
-Description-Content-Type: text/markdown
-Requires-Dist: numpy >1.2
-Requires-Dist: scipy >= 1.0
-Requires-Dist: cffi >= 1.0
-Requires-Dist: setuptools >35
+License-Expression: CC0-1.0
 Project-URL: homepage, https://github.com/yig/PySPQR
 Project-URL: source, https://github.com/yig/PySPQR
+Keywords: suitesparse,bindings,wrapper,scipy,numpy,qr-decomposition,qr-factorisation,sparse-matrix,sparse-linear-system,sparse-linear-solver
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: numpy>1.2
+Requires-Dist: scipy>=1.0
+Requires-Dist: cffi>=1.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
 
 # Python wrapper for SuiteSparseQR
 
@@ -118,38 +122,53 @@ or leave them in their directory and call it as a module.
 
 # Deploy
 
-1. Change the version in:
-
-    ```
-    sparseqr/__init__.py
-    pyproject.toml
-    ```
+1. Change the version in `sparseqr/__init__.py`
 
 2. Update `CHANGELOG.md`
 
-3. Run:
+3. Commit to git. Push to GitHub.
+
+4. Run (in a clean repos, e.g., `git clone . clean; cd clean`):
 
     ```
     flit publish --format sdist
     ```
 
+    Using [uv](https://docs.astral.sh/uv/) and [PyPI API tokens](https://pypi.org/help/#apitoken):
+
+    ```
+    FLIT_USERNAME=__token__ uv tool run --with flit flit publish --format sdist
+    ```
+
 We don't publish binary wheels, because it must be compiled against suite-sparse as a system dependency. We could publish a `none-any` wheel, which would cause compilation to happen the first time the module is imported rather than when it is installed. Is there a point to that?
 
 # Known issues
 
 `pip uninstall sparseqr` won't remove the generated libraries. It will list them with a warning.
 
-# Tested on
+# Tested
+
+GitHub Continuous Integration (CI) tests:
+
+ - Python 3.9, 3.10, 3.11, 3.12, 3.13, 3.14.
+ - macOS, Ubuntu Linux, and Windows.
+ - conda (Windows) and not conda (Linux/macOS). I tested conda on macOS manually at one point.
+
+Test manually with:
+
+```
+python -m pytest
+```
 
- - Python 3.9, 3.13.
- - Conda and not conda.
- - macOS, Ubuntu Linux, and Linux Mint.
+or
 
-    PYTHONPATH='.:$PYTHONPATH' python3 test/test.py
+```
+uv run --extra test pytest
+```
 
 # Dependencies
 
-These are installed via pip:
+These are listed as dependencies and will be installed automatically:
 
 * [SciPy/NumPy](http://www.scipy.org)
 * [cffi](http://cffi.readthedocs.io/)
@@ -161,4 +180,3 @@ These must be installed manually:
 # License
 
 Public Domain [CC0](http://creativecommons.org/publicdomain/zero/1.0/)
-

{sparseqr-1.4.1 → sparseqr-1.5}/README.md

@@ -103,38 +103,53 @@ or leave them in their directory and call it as a module.
 
 # Deploy
 
-1. Change the version in:
-
-    ```
-    sparseqr/__init__.py
-    pyproject.toml
-    ```
+1. Change the version in `sparseqr/__init__.py`
 
 2. Update `CHANGELOG.md`
 
-3. Run:
+3. Commit to git. Push to GitHub.
+
+4. Run (in a clean repos, e.g., `git clone . clean; cd clean`):
 
     ```
     flit publish --format sdist
     ```
 
+    Using [uv](https://docs.astral.sh/uv/) and [PyPI API tokens](https://pypi.org/help/#apitoken):
+
+    ```
+    FLIT_USERNAME=__token__ uv tool run --with flit flit publish --format sdist
+    ```
+
 We don't publish binary wheels, because it must be compiled against suite-sparse as a system dependency. We could publish a `none-any` wheel, which would cause compilation to happen the first time the module is imported rather than when it is installed. Is there a point to that?
 
 # Known issues
 
 `pip uninstall sparseqr` won't remove the generated libraries. It will list them with a warning.
 
-# Tested on
+# Tested
 
- - Python 3.9, 3.13.
- - Conda and not conda.
- - macOS, Ubuntu Linux, and Linux Mint.
+GitHub Continuous Integration (CI) tests:
 
-    PYTHONPATH='.:$PYTHONPATH' python3 test/test.py
+ - Python 3.9, 3.10, 3.11, 3.12, 3.13, 3.14.
+ - macOS, Ubuntu Linux, and Windows.
+ - conda (Windows) and not conda (Linux/macOS). I tested conda on macOS manually at one point.
+
+Test manually with:
+
+```
+python -m pytest
+```
+
+or
+
+```
+uv run --extra test pytest
+```
 
 # Dependencies
 
-These are installed via pip:
+These are listed as dependencies and will be installed automatically:
 
 * [SciPy/NumPy](http://www.scipy.org)
 * [cffi](http://cffi.readthedocs.io/)

{sparseqr-1.4.1 → sparseqr-1.5}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "sparseqr"
-version = "1.4.1"
+dynamic = ["version"]
 description = "Python wrapper for SuiteSparseQR"
 authors = [{name = "Yotam Gingold", email = "yotam@yotamgingold.com"}]
-license = {text = "Public Domain CC0"}
+license = "CC0-1.0"
 readme = "README.md"
 keywords = ["suitesparse", "bindings", "wrapper", "scipy", "numpy", "qr-decomposition", "qr-factorisation", "sparse-matrix", "sparse-linear-system", "sparse-linear-solver"]
 
@@ -12,18 +12,29 @@ requires-python = ">= 3.8"
 dependencies = [
     "numpy >1.2",
     "scipy >= 1.0",
-    "cffi >= 1.0",
-    "setuptools >35",
+    "cffi >= 1.0"
 ]
 
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
 [project.urls]
 homepage = "https://github.com/yig/PySPQR"
 source = "https://github.com/yig/PySPQR"
 
+[tool.pytest.ini_options]
+testpaths = ["test"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v"
+
 [build-system]
 requires = ["setuptools>=61"]
 build-backend = "setuptools.build_meta"
 
+[tool.setuptools.dynamic]
+version = {attr = "sparseqr.__version__"}
+
 #[tool.setuptools.packages.find]
 # include = ["test/*.py", "README.md", "LICENSE.md"]
 #exclude = ["sparseqr/_sparseqr*"]

sparseqr-1.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

{sparseqr-1.4.1 → sparseqr-1.5}/sparseqr/__init__.py

@@ -17,7 +17,7 @@ See the docstrings of the individual functions for details.
 
 from __future__ import absolute_import
 
-__version__ = '1.4.1'
+__version__ = '1.5'
 
 # import the important things into the package's top-level namespace.
 from .sparseqr import qr, rz, solve, permutation_vector_to_matrix, qr_factorize,qmult

{sparseqr-1.4.1 → sparseqr-1.5}/sparseqr/sparseqr.py

@@ -35,7 +35,7 @@ import _cffi_backend
 import scipy.sparse
 import numpy
 
-from .cffi_asarray import asarray
+from .cffi_asarray import asarray, ctype2dtype
 
 '''
 Helpful links for developers:
@@ -72,17 +72,30 @@ When no longer needed, the returned CHOLMOD sparse matrix must be deallocated us
 
     nnz = scipy_A.nnz
 
+    # Check if the sparse matrix has complex entries and adapt cholmod type accordingly
+    is_complex = numpy.issubdtype(scipy_A, complex)
+    cholmod_dtype = lib.CHOLMOD_COMPLEX if is_complex else lib.CHOLMOD_REAL
+
     ## There is a potential performance win if we know A is symmetric and we
     ## can get only the upper or lower triangular elements.
-    chol_A = lib.cholmod_l_allocate_triplet( scipy_A.shape[0], scipy_A.shape[1], nnz, 0, lib.CHOLMOD_REAL, cc )
+    chol_A = lib.cholmod_l_allocate_triplet( scipy_A.shape[0], scipy_A.shape[1], nnz, 0, cholmod_dtype, cc )
 
+    # Cast and copy indices
     Ai = ffi.cast( "SuiteSparse_long*", chol_A.i )
     Aj = ffi.cast( "SuiteSparse_long*", chol_A.j )
-    Avals = ffi.cast( "double*", chol_A.x )
-
     Ai[0:nnz] = scipy_A.row
     Aj[0:nnz] = scipy_A.col
-    Avals[0:nnz] = scipy_A.data
+
+    # Handle values based on dtype
+    Avals = ffi.cast( "double*", chol_A.x )
+    if is_complex:
+        # chol_A.x has size 2*nnz and real and imag parts are interleaved [real, imag, real, imag, ...]
+        array_element_size = ffi.sizeof(ffi.typeof(Avals).item)
+        Avals_view = numpy.frombuffer(ffi.buffer(Avals, 2*nnz * array_element_size), ctype2dtype["double"])
+        Avals_view[0::2] = scipy_A.data.real
+        Avals_view[1::2] = scipy_A.data.imag
+    else:
+        Avals[0:nnz] = scipy_A.data
 
     chol_A.nnz = nnz
 
@@ -125,7 +138,14 @@ def cholmodsparse2scipy( chol_A ):
     ##       doesn't and the cholmod memory fill get freed.
     i = asarray( ffi, Ai, nnz ).copy()
     j = asarray( ffi, Aj, nnz ).copy()
-    data = asarray( ffi, Adata, nnz ).copy()
+
+    if chol_A.xtype == lib.CHOLMOD_COMPLEX:
+        # read real and imag part from the buffer and create view as complex datatype
+        data = asarray(ffi, Adata, 2*nnz).copy()
+        complex_dtype = numpy.dtype(f"c{data.itemsize * 2}")
+        data = data.view(complex_dtype)
+    else:
+        data = asarray(ffi, Adata, nnz).copy()
 
     scipy_A = scipy.sparse.coo_matrix(
         ( data, ( i, j ) ),

{sparseqr-1.4.1 → sparseqr-1.5}/sparseqr/sparseqr_gen.py

@@ -17,6 +17,9 @@ libraries = ['spqr']
 if 'CONDA_PREFIX' in os.environ:
     include_dirs.append( os.path.join(os.environ['CONDA_PREFIX'], 'include', 'suitesparse') )
     library_dirs.append( os.path.join(os.environ['CONDA_PREFIX'], 'lib') )
+    ## For Windows:
+    include_dirs.append( os.path.join(os.environ['CONDA_PREFIX'], 'Library', 'include', 'suitesparse') )
+    library_dirs.append( os.path.join(os.environ['CONDA_PREFIX'], 'Library', 'lib') )
 
 ## Otherwise, add common system-wide directories
 else:
@@ -31,8 +34,9 @@ else:
 
 if platform.system() == 'Windows':
     # https://github.com/yig/PySPQR/issues/6
-    libraries.extend( ['amd','btf','camd','ccolamd','cholmod','colamd','cxsparse'
-'klu','lapack','ldl','lumfpack','metis','suitesparseconfig','libblas'] )
+    ## Update: This list fails for `windows-latest` on GitHub. Some are missing. The only needed library is `cholmod`.
+    # libraries.extend( ['amd','btf','camd','ccolamd','cholmod','colamd','cxsparse', 'klu','lapack','ldl','lumfpack','metis','suitesparseconfig','libblas'] )
+    libraries.extend( ['cholmod'] )
 
 ffibuilder = FFI()
 
@@ -50,7 +54,7 @@ ffibuilder.set_source( "sparseqr._sparseqr",
     library_dirs = library_dirs,
     libraries = libraries )
 
-ffibuilder.cdef("""
+ffibuilder.cdef(r"""
 // The int... is a magic thing which tells the compiler to figure out what the right
 // integer type is.
 typedef int... SuiteSparse_long;

sparseqr-1.5/sparseqr.egg-info/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: sparseqr
+Version: 1.5
+Summary: Python wrapper for SuiteSparseQR
+Author-email: Yotam Gingold <yotam@yotamgingold.com>
+License-Expression: CC0-1.0
+Project-URL: homepage, https://github.com/yig/PySPQR
+Project-URL: source, https://github.com/yig/PySPQR
+Keywords: suitesparse,bindings,wrapper,scipy,numpy,qr-decomposition,qr-factorisation,sparse-matrix,sparse-linear-system,sparse-linear-solver
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: numpy>1.2
+Requires-Dist: scipy>=1.0
+Requires-Dist: cffi>=1.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# Python wrapper for SuiteSparseQR
+
+This module wraps the [SuiteSparseQR](http://faculty.cse.tamu.edu/davis/suitesparse.html)
+decomposition function for use with [SciPy](http://www.scipy.org).
+This is Matlab's sparse `[Q,R,E] = qr()`.
+For some reason, no one ever wrapped that function of SuiteSparseQR for Python.
+
+Also wrapped are the SuiteSparseQR solvers for ``A x = b`` for the cases with sparse `A` and dense or sparse `b`.
+This is especially useful for solving sparse overdetermined linear systems in the least-squares sense.
+Here `A` is of size m-by-n and `b` is m-by-k (storing `k` different right-hand side vectors, each considered separately).
+
+# Usage
+
+```python
+import numpy
+import scipy.sparse.linalg
+import sparseqr
+
+# QR decompose a sparse matrix M such that  Q R = M E
+#
+M = scipy.sparse.rand( 10, 10, density = 0.1 )
+Q, R, E, rank = sparseqr.qr( M )
+print( "Should be approximately zero:", abs( Q*R - M*sparseqr.permutation_vector_to_matrix(E) ).sum() ) 
+
+# Solve many linear systems "M x = b for b in columns(B)"
+#
+B = scipy.sparse.rand( 10, 5, density = 0.1 )  # many RHS, sparse (could also have just one RHS with shape (10,))
+x = sparseqr.solve( M, B, tolerance = 0 )
+
+# Solve an overdetermined linear system  A x = b  in the least-squares sense
+#
+# The same routine also works for the usual non-overdetermined case.
+#
+A = scipy.sparse.rand( 20, 10, density = 0.1 )  # 20 equations, 10 unknowns
+b = numpy.random.random(20)  # one RHS, dense, but could also have many (in shape (20,k))
+x = sparseqr.solve( A, b, tolerance = 0 )
+## Call `rz()`:
+sparseqr.rz( A, b, tolerance = 0 )
+
+# Solve a linear system  M x = B  via QR decomposition
+#
+# This approach is slow due to the explicit construction of Q, but may be
+# useful if a large number of systems need to be solved with the same M.
+#
+M = scipy.sparse.rand( 10, 10, density = 0.1 )
+Q, R, E, rank = sparseqr.qr( M )
+r = rank  # r could be min(M.shape) if M is full-rank
+
+# The system is only solvable if the lower part of Q.T @ B is all zero:
+print( "System is solvable if this is zero (unlikely for a random matrix):", abs( (( Q.tocsc()[:,r:] ).T ).dot( B ) ).sum() )
+
+# Systems with large non-square matrices can benefit from "economy" decomposition.
+M = scipy.sparse.rand( 20, 5, density=0.1 )
+B = scipy.sparse.rand( 20, 5, density = 0.1 )
+Q, R, E, rank = sparseqr.qr( M )
+print("Q shape (should be 20x20):", Q.shape)
+print("R shape (should be 20x5):", R.shape)
+Q, R, E, rank = sparseqr.qr( M, economy=True )
+print("Q shape (should be 20x5):", Q.shape)
+print("R shape (should be 5x5):", R.shape)
+
+
+R = R.tocsr()[:r,:r] #for best performance, spsolve_triangular() wants the Matrix to be in CSR format.
+Q = Q.tocsc()[:,:r] # Use CSC format for fast indexing of columns.
+QB = (Q.T).dot(B).todense()  # spsolve_triangular() need the RHS in array format.
+result = scipy.sparse.linalg.spsolve_triangular(R, QB, lower=False)
+
+# Recover a solution (as a dense array):
+x = numpy.zeros( ( M.shape[1], B.shape[1] ), dtype = result.dtype )
+x[:r] = result
+x[E] = x.copy()
+
+# Recover a solution (as a sparse matrix):
+x = scipy.sparse.vstack( ( result, scipy.sparse.coo_matrix( ( M.shape[1] - rank, B.shape[1] ), dtype = result.dtype ) ) )
+x.row = E[ x.row ]
+```
+
+# Installation
+
+Before installing this module, you must first install [SuiteSparseQR](http://faculty.cse.tamu.edu/davis/suitesparse.html). You can do that via conda (`conda install suitesparse`) or your system's package manager (macOS: `brew install suitesparse`; debian/ubuntu linux: `apt-get install libsuitesparse-dev`).
+
+Now you are ready to install this module.
+
+## Via `pip`
+
+From PyPI:
+
+```bash
+pip install sparseqr
+```
+
+From GitHub:
+
+```bash
+pip install git+https://github.com/yig/PySPQR.git
+```
+
+## Directly
+
+Copy the three `sparseqr/*.py` files next to your source code,
+or leave them in their directory and call it as a module.
+
+
+# Deploy
+
+1. Change the version in `sparseqr/__init__.py`
+
+2. Update `CHANGELOG.md`
+
+3. Commit to git. Push to GitHub.
+
+4. Run (in a clean repos, e.g., `git clone . clean; cd clean`):
+
+    ```
+    flit publish --format sdist
+    ```
+
+    Using [uv](https://docs.astral.sh/uv/) and [PyPI API tokens](https://pypi.org/help/#apitoken):
+
+    ```
+    FLIT_USERNAME=__token__ uv tool run --with flit flit publish --format sdist
+    ```
+
+We don't publish binary wheels, because it must be compiled against suite-sparse as a system dependency. We could publish a `none-any` wheel, which would cause compilation to happen the first time the module is imported rather than when it is installed. Is there a point to that?
+
+# Known issues
+
+`pip uninstall sparseqr` won't remove the generated libraries. It will list them with a warning.
+
+# Tested
+
+GitHub Continuous Integration (CI) tests:
+
+ - Python 3.9, 3.10, 3.11, 3.12, 3.13, 3.14.
+ - macOS, Ubuntu Linux, and Windows.
+ - conda (Windows) and not conda (Linux/macOS). I tested conda on macOS manually at one point.
+
+Test manually with:
+
+```
+python -m pytest
+```
+
+or
+
+```
+uv run --extra test pytest
+```
+
+# Dependencies
+
+These are listed as dependencies and will be installed automatically:
+
+* [SciPy/NumPy](http://www.scipy.org)
+* [cffi](http://cffi.readthedocs.io/)
+
+These must be installed manually:
+
+* [SuiteSparseQR](http://faculty.cse.tamu.edu/davis/suitesparse.html) (macOS: `brew install suitesparse`; debian/ubuntu linux: `apt-get install libsuitesparse-dev`)
+
+# License
+
+Public Domain [CC0](http://creativecommons.org/publicdomain/zero/1.0/)

sparseqr-1.5/sparseqr.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE.md
+README.md
+pyproject.toml
+setup.py
+sparseqr/__init__.py
+sparseqr/cffi_asarray.py
+sparseqr/sparseqr.py
+sparseqr/sparseqr_gen.py
+sparseqr.egg-info/PKG-INFO
+sparseqr.egg-info/SOURCES.txt
+sparseqr.egg-info/dependency_links.txt
+sparseqr.egg-info/requires.txt
+sparseqr.egg-info/top_level.txt
+test/test_complex.py
+test/test_sparseqr.py

sparseqr-1.5/sparseqr.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sparseqr-1.5/sparseqr.egg-info/requires.txt

@@ -0,0 +1,6 @@
+numpy>1.2
+scipy>=1.0
+cffi>=1.0
+
+[test]
+pytest>=7.0

sparseqr-1.5/sparseqr.egg-info/top_level.txt

@@ -0,0 +1 @@
+sparseqr

sparseqr-1.5/test/test_complex.py

@@ -0,0 +1,58 @@
+"""Tests for complex matrix support in sparseqr."""
+
+import numpy as np
+import pytest
+from scipy.sparse import random as sparse_random
+
+import sparseqr
+
+
+def adj(A):
+    """Return the conjugate transpose (adjoint) of a matrix."""
+    return A.conj().T
+
+
+class TestComplexQR:
+    """Tests for QR decomposition of complex matrices."""
+
+    ATOL = 1e-14  # close to machine precision
+
+    def test_complex_qr_unitary_q(self):
+        """Test that Q is unitary for complex matrix (Q @ Q^H = I)."""
+        A = sparse_random(m=120, n=100, density=0.1, dtype=np.complex128, random_state=42)
+        Q, R, P, rank = sparseqr.qr(A)
+
+        QQH = (Q @ adj(Q)).toarray()
+        np.testing.assert_allclose(QQH, np.eye(Q.shape[0]), atol=self.ATOL)
+
+    def test_complex_qr_upper_triangular_r(self):
+        """Test that R is upper triangular for complex matrix."""
+        A = sparse_random(m=120, n=100, density=0.1, dtype=np.complex128, random_state=42)
+        Q, R, P, rank = sparseqr.qr(A)
+
+        lower_triangle = np.tril(R.toarray(), k=-1)
+        np.testing.assert_allclose(lower_triangle, 0, atol=self.ATOL)
+
+    def test_complex_qr_reconstruction(self):
+        """Test that A can be reconstructed from QR decomposition: A = (QR) @ P^T."""
+        A = sparse_random(m=120, n=100, density=0.1, dtype=np.complex128, random_state=42)
+        Q, R, P, rank = sparseqr.qr(A)
+
+        P_matrix = sparseqr.permutation_vector_to_matrix(P)
+        A_reconstructed = (Q @ R) @ P_matrix.T
+        np.testing.assert_allclose(A_reconstructed.toarray(), A.toarray(), atol=self.ATOL)
+
+    @pytest.mark.parametrize("shape", [(50, 50), (100, 50), (50, 100)])
+    def test_complex_qr_various_shapes(self, shape):
+        """Test complex QR on square, tall, and wide matrices."""
+        m, n = shape
+        A = sparse_random(m=m, n=n, density=0.1, dtype=np.complex128, random_state=42)
+        Q, R, P, rank = sparseqr.qr(A)
+
+        P_matrix = sparseqr.permutation_vector_to_matrix(P)
+        A_reconstructed = (Q @ R) @ P_matrix.T
+        np.testing.assert_allclose(A_reconstructed.toarray(), A.toarray(), atol=self.ATOL)
+
+
+if __name__ == '__main__':
+    pytest.main([__file__, '-v'])

sparseqr-1.5/test/test_sparseqr.py

@@ -0,0 +1,313 @@
+"""Tests for sparseqr module.
+
+Run with: pytest test/ -v
+Or simply: python -m pytest
+"""
+
+import numpy as np
+import scipy.sparse
+import pytest
+
+import sparseqr
+
+
+class TestQR:
+    """Tests for sparseqr.qr() function."""
+
+    def test_qr_basic_decomposition(self):
+        """Test that Q*R = M*E for a random sparse matrix."""
+        M = scipy.sparse.rand(10, 10, density=0.1, random_state=42)
+        Q, R, E, rank = sparseqr.qr(M)
+
+        # Q*R should equal M*E
+        E_matrix = sparseqr.permutation_vector_to_matrix(E)
+        residual = abs(Q @ R - M @ E_matrix).sum()
+        assert residual < 1e-10, f"QR decomposition residual too large: {residual}"
+
+    def test_qr_rectangular_tall(self):
+        """Test QR on a tall (overdetermined) matrix."""
+        M = scipy.sparse.rand(20, 10, density=0.1, random_state=42)
+        Q, R, E, rank = sparseqr.qr(M)
+
+        assert Q.shape == (20, 20), f"Q shape wrong: {Q.shape}"
+        assert R.shape == (20, 10), f"R shape wrong: {R.shape}"
+
+        E_matrix = sparseqr.permutation_vector_to_matrix(E)
+        residual = abs(Q @ R - M @ E_matrix).sum()
+        assert residual < 1e-10
+
+    def test_qr_rectangular_wide(self):
+        """Test QR on a wide (underdetermined) matrix."""
+        M = scipy.sparse.rand(10, 20, density=0.1, random_state=42)
+        Q, R, E, rank = sparseqr.qr(M)
+
+        assert Q.shape == (10, 10), f"Q shape wrong: {Q.shape}"
+        assert R.shape == (10, 20), f"R shape wrong: {R.shape}"
+
+    def test_qr_economy_mode(self):
+        """Test economy=True produces smaller Q and R."""
+        M = scipy.sparse.rand(20, 5, density=0.1, random_state=42)
+
+        # Full QR
+        Q_full, R_full, E, rank = sparseqr.qr(M, economy=False)
+        assert Q_full.shape == (20, 20)
+        assert R_full.shape == (20, 5)
+
+        # Economy QR
+        Q_econ, R_econ, E, rank = sparseqr.qr(M, economy=True)
+        assert Q_econ.shape == (20, 5), f"Economy Q shape wrong: {Q_econ.shape}"
+        assert R_econ.shape == (5, 5), f"Economy R shape wrong: {R_econ.shape}"
+
+    def test_qr_identity_matrix(self):
+        """Test QR decomposition of identity matrix."""
+        I = scipy.sparse.eye(5, format='coo')
+        Q, R, E, rank = sparseqr.qr(I)
+
+        assert rank == 5, f"Rank should be 5, got {rank}"
+
+        # Q and R should both be identity (up to permutation)
+        E_matrix = sparseqr.permutation_vector_to_matrix(E)
+        residual = abs(Q @ R - I @ E_matrix).sum()
+        assert residual < 1e-10
+
+    def test_qr_with_tolerance(self):
+        """Test QR with explicit tolerance parameter."""
+        M = scipy.sparse.rand(10, 10, density=0.2, random_state=42)
+        Q, R, E, rank = sparseqr.qr(M, tolerance=0)
+
+        E_matrix = sparseqr.permutation_vector_to_matrix(E)
+        residual = abs(Q @ R - M @ E_matrix).sum()
+        assert residual < 1e-10
+
+
+class TestSolve:
+    """Tests for sparseqr.solve() function."""
+
+    def test_solve_dense_rhs_single(self):
+        """Test solving Ax=b with single dense RHS vector."""
+        # Create a well-conditioned matrix
+        A = scipy.sparse.diags([1, 2, 3, 4, 5], format='coo', dtype=np.float64) + scipy.sparse.rand(5, 5, density=0.1, random_state=42)
+        b = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
+
+        x = sparseqr.solve(A, b, tolerance=0)
+
+        assert x is not None, "solve() returned None"
+        assert x.shape == (5,), f"Solution shape wrong: {x.shape}"
+
+    def test_solve_dense_rhs_multiple(self):
+        """Test solving AX=B with multiple dense RHS vectors."""
+        A = scipy.sparse.diags([1, 2, 3, 4, 5], format='coo', dtype=np.float64) + scipy.sparse.rand(5, 5, density=0.1, random_state=42)
+        B = np.random.RandomState(42).random((5, 3))
+
+        X = sparseqr.solve(A, B, tolerance=0)
+
+        assert X is not None, "solve() returned None"
+        assert X.shape == (5, 3), f"Solution shape wrong: {X.shape}"
+
+    def test_solve_sparse_rhs(self):
+        """Test solving AX=B with sparse RHS."""
+        A = scipy.sparse.diags([1, 2, 3, 4, 5], format='coo', dtype=np.float64) + scipy.sparse.rand(5, 5, density=0.1, random_state=42)
+        B = scipy.sparse.rand(5, 3, density=0.3, random_state=42)
+
+        X = sparseqr.solve(A, B, tolerance=0)
+
+        assert X is not None, "solve() returned None"
+        assert scipy.sparse.issparse(X), "Solution should be sparse for sparse RHS"
+        assert X.shape == (5, 3), f"Solution shape wrong: {X.shape}"
+
+    def test_solve_overdetermined_least_squares(self):
+        """Test least-squares solution for overdetermined system."""
+        # 20 equations, 10 unknowns
+        A = scipy.sparse.rand(20, 10, density=0.2, random_state=42)
+        b = np.random.RandomState(42).random(20)
+
+        x = sparseqr.solve(A, b, tolerance=0)
+
+        assert x is not None, "solve() returned None"
+        assert x.shape == (10,), f"Solution shape wrong: {x.shape}"
+
+    def test_solve_exact_system(self):
+        """Test solving an exact system where Ax=b has exact solution."""
+        # Create a system with known solution
+        A = scipy.sparse.eye(5, format='coo')
+        x_true = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
+        b = A @ x_true
+
+        x = sparseqr.solve(A, b, tolerance=0)
+
+        assert x is not None
+        np.testing.assert_allclose(x, x_true, rtol=1e-10)
+
+
+class TestRZ:
+    """Tests for sparseqr.rz() function."""
+
+    def test_rz_basic(self):
+        """Test rz() returns expected outputs."""
+        A = scipy.sparse.rand(20, 10, density=0.1, random_state=42)
+        b = np.random.RandomState(42).random(20)
+
+        Z, R, E, rank = sparseqr.rz(A, b, tolerance=0)
+
+        assert Z is not None
+        assert R is not None
+        assert isinstance(rank, (int, np.integer))
+
+    def test_rz_output_shapes(self):
+        """Test rz() returns correct shapes."""
+        m, n = 15, 8
+        A = scipy.sparse.rand(m, n, density=0.2, random_state=42)
+        b = np.random.RandomState(42).random(m)
+
+        Z, R, E, rank = sparseqr.rz(A, b, tolerance=0)
+
+        # Z should have n rows (one per unknown)
+        assert Z.shape[0] == n, f"Z rows should be {n}, got {Z.shape[0]}"
+
+
+class TestQRFactorize:
+    """Tests for sparseqr.qr_factorize() and qmult() functions."""
+
+    def test_qr_factorize_basic(self):
+        """Test qr_factorize() returns a factorization object."""
+        M = scipy.sparse.rand(100, 100, density=0.05, random_state=42)
+        QR = sparseqr.qr_factorize(M)
+
+        assert QR is not None
+
+    def test_qmult_basic(self):
+        """Test qmult() with Householder form QR."""
+        M = scipy.sparse.rand(100, 100, density=0.05, random_state=42)
+        QR = sparseqr.qr_factorize(M)
+
+        X = np.zeros((M.shape[0], 1))
+        X[-1, 0] = 1
+
+        Y = sparseqr.qmult(QR, X)
+
+        assert Y.shape == (100, 1), f"Y shape wrong: {Y.shape}"
+
+    def test_qmult_methods(self):
+        """Test different qmult methods (Q'X, QX, XQ', XQ)."""
+        M = scipy.sparse.rand(20, 20, density=0.2, random_state=42)
+        QR = sparseqr.qr_factorize(M)
+
+        X = np.random.RandomState(42).random((20, 1))
+
+        # method=0: Q'X
+        Y0 = sparseqr.qmult(QR, X, method=0)
+        assert Y0.shape == (20, 1)
+
+        # method=1: QX (default)
+        Y1 = sparseqr.qmult(QR, X, method=1)
+        assert Y1.shape == (20, 1)
+
+
+class TestPermutationVectorToMatrix:
+    """Tests for sparseqr.permutation_vector_to_matrix() function."""
+
+    def test_identity_permutation(self):
+        """Test identity permutation [0,1,2,3,4]."""
+        E = np.array([0, 1, 2, 3, 4])
+        P = sparseqr.permutation_vector_to_matrix(E)
+
+        expected = scipy.sparse.eye(5)
+        diff = abs(P - expected).sum()
+        assert diff < 1e-10, "Identity permutation should produce identity matrix"
+
+    def test_swap_permutation(self):
+        """Test a permutation that swaps first and last."""
+        E = np.array([4, 1, 2, 3, 0])
+        P = sparseqr.permutation_vector_to_matrix(E)
+
+        # P[E[k], k] = 1, so P[4,0]=1, P[1,1]=1, P[2,2]=1, P[3,3]=1, P[0,4]=1
+        assert P.shape == (5, 5)
+        assert P.nnz == 5  # exactly 5 non-zeros
+
+        # Convert to dense for easier checking
+        P_dense = P.toarray()
+        assert P_dense[4, 0] == 1
+        assert P_dense[0, 4] == 1
+
+    def test_permutation_orthogonality(self):
+        """Test that permutation matrix is orthogonal (P @ P.T = I)."""
+        E = np.array([2, 0, 4, 1, 3])
+        P = sparseqr.permutation_vector_to_matrix(E)
+
+        result = P @ P.T
+        expected = scipy.sparse.eye(5)
+        diff = abs(result - expected).sum()
+        assert diff < 1e-10
+
+
+class TestEdgeCases:
+    """Tests for edge cases and special matrices."""
+
+    def test_very_sparse_matrix(self):
+        """Test with very sparse matrix."""
+        M = scipy.sparse.rand(50, 50, density=0.01, random_state=42)
+        Q, R, E, rank = sparseqr.qr(M)
+
+        E_matrix = sparseqr.permutation_vector_to_matrix(E)
+        residual = abs(Q @ R - M @ E_matrix).sum()
+        assert residual < 1e-10
+
+    def test_diagonal_matrix(self):
+        """Test with diagonal matrix."""
+        M = scipy.sparse.diags([1, 2, 3, 4, 5], format='coo', dtype=np.float64)
+        Q, R, E, rank = sparseqr.qr(M)
+
+        assert rank == 5
+        E_matrix = sparseqr.permutation_vector_to_matrix(E)
+        residual = abs(Q @ R - M @ E_matrix).sum()
+        assert residual < 1e-10
+
+    def test_single_element_matrix(self):
+        """Test with 1x1 matrix."""
+        M = scipy.sparse.coo_matrix([[3.0]])
+        Q, R, E, rank = sparseqr.qr(M)
+
+        assert rank == 1
+        assert Q.shape == (1, 1)
+        assert R.shape == (1, 1)
+
+    def test_different_sparse_formats(self):
+        """Test that different input formats work (coo, csr, csc)."""
+        base = scipy.sparse.rand(10, 10, density=0.2, random_state=42)
+
+        for fmt in ['coo', 'csr', 'csc', 'lil']:
+            M = base.asformat(fmt)
+            Q, R, E, rank = sparseqr.qr(M)
+            E_matrix = sparseqr.permutation_vector_to_matrix(E)
+            residual = abs(Q @ R - M @ E_matrix).sum()
+            assert residual < 1e-10, f"Failed for format {fmt}"
+
+
+class TestNumericalAccuracy:
+    """Tests for numerical accuracy."""
+
+    def test_orthogonality_of_q(self):
+        """Test that Q is orthogonal (Q.T @ Q ≈ I for the relevant columns)."""
+        M = scipy.sparse.rand(10, 10, density=0.3, random_state=42)
+        Q, R, E, rank = sparseqr.qr(M)
+
+        # For a square matrix with full rank, Q should be orthogonal
+        if rank == 10:
+            QtQ = (Q.T @ Q).toarray()
+            I = np.eye(10)
+            np.testing.assert_allclose(QtQ, I, atol=1e-10)
+
+    def test_upper_triangular_r(self):
+        """Test that R is upper triangular."""
+        M = scipy.sparse.rand(10, 10, density=0.3, random_state=42)
+        Q, R, E, rank = sparseqr.qr(M)
+
+        R_dense = R.toarray()
+        # Check lower triangle is zero (below diagonal)
+        for i in range(R_dense.shape[0]):
+            for j in range(min(i, R_dense.shape[1])):
+                assert abs(R_dense[i, j]) < 1e-10, f"R[{i},{j}] = {R_dense[i,j]} should be zero"
+
+
+if __name__ == '__main__':
+    pytest.main([__file__, '-v'])

sparseqr-1.4.1/.gitignore

@@ -1,3 +0,0 @@
-*.pyc
-*.pyo
-_spqr.*

sparseqr-1.4.1/CHANGELOG.md

@@ -1,57 +0,0 @@
-# Changelog
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
-and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [v1.4.1] - 2025-02-10
-### Fixed
-- An import statement got lost in the 1.4 update.
-
-## [v1.4] - 2025-01-28
-### Fixed
-- Modernized the build system (`pyproject.toml`).
-- Changed the way suite-sparse is found to be more robust.
-
-## [v1.3] - 2025-01-09
-### Added
-- Bindings for `qr_factorize` and `qmult` (thanks to jkrokowski)
-
-### Fixed
-- Compatibility with more environments (more search paths, newer numpy, setuptools dependency)
-- Readme example uses `spsolve_triangular`.
-
-## [v1.2.1] - 2023-04-12
-### Fixed
-- Fixed a memory leak in `qr()` and `rz()`.
-### Changed
-- Bumped minimal Python version to 3.8.
-- `rz()` is called by the test script. Its output is ignored.
-
-## [v1.2] - 2022-05-27
-### Added
-- Added support for partial "economy" decompositions. (Christoph Hansknecht <c.hansknecht@tu-braunschweig.de>): 'The "economy" option can be used in SPQR to compute a QR factorization of a (m x n) matrix with m < n consisting of blocks Q_1, and Q_2, where Q_1 has as shape of (m x n) and Q_2 of (m x k - n). For k = n we get the reduced form, for k = m the full one. For k in between m and n, SPQR yields a block that spans part of the kernel of A. This patch adds this functionality to PySPQR.'
-- Added support for macOS on arm64.
-
-## [v1.1.2] - 2021-08-09
-### Added
-- Added rz recomposition (thanks to Ben Smith <bsmith@apl.washington.edu>)
-- Added support for "economy" decomposition. (Jeffrey Bouas <ignirtoq@gmail.com>)
-### Changed
-- Supports conda environments (thanks to Ben Smith <bsmith@apl.washington.edu> and Sterling Baird <sterling.baird@icloud.com>)
-
-## [v1.0.0] - 2017-08-31
-### Added
- - Installation and packaging using `setuptools`
-### Changed
- - Rename module `spqr` to `sparseqr`
- - Clean up public API: `qr`, `solve`, `permutation_vector_to_matrix`
-
-## [v1.0.0] - 2017-08-31
-### Added
- - Installation and packaging using `setuptools` (thanks to Juha Jeronen <juha.jeronen@tut.fi>)
-### Changed
- - Rename module `spqr` to `sparseqr`
- - Clean up public API: `qr`, `solve`, `permutation_vector_to_matrix`

sparseqr-1.4.1/test/test.py

@@ -1,79 +0,0 @@
-#!/usr/bin/python
-# -*- coding: utf-8 -*-
-
-from __future__ import division, print_function, absolute_import
-
-import numpy
-import scipy.sparse.linalg
-import sparseqr
-
-# QR decompose a sparse matrix M such that  Q R = M E
-#
-M = scipy.sparse.rand( 10, 10, density = 0.1 )
-Q, R, E, rank = sparseqr.qr( M )
-print( "Should be approximately zero:", abs( Q*R - M*sparseqr.permutation_vector_to_matrix(E) ).sum() ) 
-
-# Solve many linear systems "M x = b for b in columns(B)"
-#
-B = scipy.sparse.rand( 10, 5, density = 0.1 )  # many RHS, sparse (could also have just one RHS with shape (10,))
-x = sparseqr.solve( M, B, tolerance = 0 )
-
-# Solve an overdetermined linear system  A x = b  in the least-squares sense
-#
-# The same routine also works for the usual non-overdetermined case.
-#
-A = scipy.sparse.rand( 20, 10, density = 0.1 )  # 20 equations, 10 unknowns
-b = numpy.random.random(20)  # one RHS, dense, but could also have many (in shape (20,k))
-x = sparseqr.solve( A, b, tolerance = 0 )
-## Call `rz()`:
-sparseqr.rz( A, b, tolerance = 0 )
-
-# Solve a linear system  M x = B  via QR decomposition
-#
-# This approach is slow due to the explicit construction of Q, but may be
-# useful if a large number of systems need to be solved with the same M.
-#
-M = scipy.sparse.rand( 10, 10, density = 0.1 )
-Q, R, E, rank = sparseqr.qr( M )
-r = rank  # r could be min(M.shape) if M is full-rank
-
-# The system is only solvable if the lower part of Q.T @ B is all zero:
-print( "System is solvable if this is zero (unlikely for a random matrix):", abs( (( Q.tocsc()[:,r:] ).T ).dot( B ) ).sum() )
-
-# Systems with large non-square matrices can benefit from "economy" decomposition.
-M = scipy.sparse.rand( 20, 5, density=0.1 )
-B = scipy.sparse.rand( 20, 5, density = 0.1 )
-Q, R, E, rank = sparseqr.qr( M )
-print("Q shape (should be 20x20):", Q.shape)
-print("R shape (should be 20x5):", R.shape)
-Q, R, E, rank = sparseqr.qr( M, economy=True )
-print("Q shape (should be 20x5):", Q.shape)
-print("R shape (should be 5x5):", R.shape)
-
-# Use CSC format for fast indexing of columns.
-R = R.tocsc()[:r,:r]
-Q = Q.tocsc()[:,:r]
-QB = (Q.T).dot(B).tocsc()  # for best performance, spsolve() wants the RHS to be in CSC format.
-result = scipy.sparse.linalg.spsolve(R, QB)
-
-# Recover a solution (as a dense array):
-x = numpy.zeros( ( M.shape[1], B.shape[1] ), dtype = result.dtype )
-x[:r] = result.todense()
-x[E] = x.copy()
-
-# Recover a solution (as a sparse matrix):
-x = scipy.sparse.vstack( ( result.tocoo(), scipy.sparse.coo_matrix( ( M.shape[1] - rank, B.shape[1] ), dtype = result.dtype ) ) )
-x.row = E[ x.row ]
-
-#initialize QR Factorization object
-M = scipy.sparse.rand( 100, 100, density=0.05 )
-
-#perform QR factorization, but store in Householder form
-QR= sparseqr.qr_factorize( M )
-X = numpy.zeros((M.shape[0],1))
-#change last entry of the first column to a 1 
-# this allows us to construct only the first column of Q
-X[-1,0]=1 
-
-Y = sparseqr.qmult(QR,X)
-print("Y shape (should be 100x1):",Y.shape)