fast-matrix-rank 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jay Rajnikant Patel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,123 @@
1
+ Metadata-Version: 2.4
2
+ Name: fast-matrix-rank
3
+ Version: 0.1.0
4
+ Summary: Fast numerical rank for large sparse square matrices, with SVD fallback.
5
+ Author-email: Jay Patel <your-email@example.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/Jaypatel2611/fast-matrix-rank
8
+ Project-URL: Issues, https://github.com/Jaypatel2611/fast-matrix-rank/issues
9
+ Keywords: matrix rank,sparse,linear algebra,scipy
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
13
+ Requires-Python: >=3.9
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: numpy>=1.23
17
+ Requires-Dist: scipy>=1.11
18
+ Provides-Extra: test
19
+ Requires-Dist: pytest; extra == "test"
20
+ Dynamic: license-file
21
+
22
+ # fast-matrix-rank
23
+
24
+ Fast numerical rank for large **sparse, square, full-rank** matrices, with a safe fallback to SVD for everything else.
25
+
26
+ `numpy.linalg.matrix_rank` needs a dense SVD: O(N³) time and O(N²) memory. For a banded or sparse matrix with N = 100,000 that is impossible (80 GB just to hold it). This package checks rank with a sparse LU factorization (`scipy.sparse.linalg.splu`) instead, and falls back to SVD whenever the LU result cannot be trusted.
27
+
28
+ ## Disclosure
29
+
30
+ This project was partially written with the assistance of Claude, an AI assistant. The code, tests and benchmark script were developed with its help. I reviewed and ran them, and the benchmark numbers in this README were measured on my own machine.
31
+
32
+ ## Install
33
+
34
+ ```bash
35
+ git clone https://github.com/Jaypatel2611/fast-matrix-rank.git
36
+ cd fast-matrix-rank
37
+ pip install -e .
38
+ ```
39
+
40
+ ## Usage
41
+
42
+ ```python
43
+ import numpy as np
44
+ import scipy.sparse as sp
45
+ from fast_matrix_rank import hybrid_matrix_rank, nullity
46
+
47
+ n = 100_000
48
+ A = sp.diags([np.ones(n - 1), 4 * np.ones(n), np.ones(n - 1)], [-1, 0, 1], format="csc")
49
+
50
+ hybrid_matrix_rank(A) # 100000, in tens of milliseconds
51
+ nullity(A) # 0
52
+ ```
53
+
54
+ By default the function may convert a sparse matrix to a dense array when sparse LU cannot decide the rank. To forbid that, pass `allow_dense=False`. The function then raises `RankNotDeterminedError` instead of densifying:
55
+
56
+ ```python
57
+ from fast_matrix_rank import hybrid_matrix_rank, RankNotDeterminedError
58
+
59
+ try:
60
+ r = hybrid_matrix_rank(A, allow_dense=False)
61
+ except RankNotDeterminedError:
62
+ ... # the matrix is singular, badly scaled, or not square
63
+ ```
64
+
65
+ Dense NumPy arrays, `scipy.sparse` matrices and the newer sparse arrays (`csr_array` etc.) are all accepted. Real, integer and complex data work. NaN or Inf raises `ValueError`.
66
+
67
+ ## How it chooses a method
68
+
69
+ | Input | Method |
70
+ |---|---|
71
+ | Square, sparse (density ≤ 15 %), full rank | Sparse LU |
72
+ | Small dense (max dimension ≤ 500) | Gaussian elimination (see note below) |
73
+ | Large dense, rectangular, rank-deficient, ill-conditioned | LAPACK SVD |
74
+
75
+ You can force a method with `method="gauss"` or `method="svd"`. With `allow_dense=False`, any case that would need a dense conversion raises `RankNotDeterminedError`. Dense NumPy input is not affected by this option.
76
+
77
+ ## Benchmarks
78
+
79
+ Measured with `python benchmark.py` on Windows, AMD64 (AuthenticAMD Family 25), Python 3.12.10, NumPy 2.5.4, SciPy 1.18.1. Your numbers will differ, so run it yourself.
80
+
81
+ Sparse tridiagonal, full rank:
82
+
83
+ | N | This package | Dense SVD (`numpy.linalg.matrix_rank`) |
84
+ |---|---|---|
85
+ | 1,000 | 1.61 ms | 0.16 s |
86
+ | 2,000 | 1.72 ms | 1.23 s |
87
+ | 4,000 | 2.70 ms | 14.00 s |
88
+ | 10,000 | 9.3 ms | not run (0.8 GB matrix) |
89
+ | 100,000 | 90 ms | not run (80 GB matrix) |
90
+
91
+ ## Related SciPy functions
92
+
93
+ SciPy has no exact numerical rank for sparse matrices. These existing functions are related:
94
+
95
+ - `scipy.linalg.interpolative.estimate_rank` estimates the rank to a given relative precision using randomized methods. It accepts a `numpy.ndarray` or a `LinearOperator` (so sparse matrices can be used through a wrapper). It returns an estimate, not an exact rank.
96
+ - `scipy.sparse.csgraph.structural_rank` works on sparse matrices but only looks at the sparsity pattern, not the values. It is an upper bound on the numerical rank.
97
+
98
+ This package checks the actual values of a square sparse matrix with sparse LU, and can fall back to SVD (or raise an error with `allow_dense=False`).
99
+
100
+ ## Limitations
101
+
102
+ Please read these before relying on the speedup.
103
+
104
+ - **Only full-rank sparse matrices are fast.** If the LU factorization finds the matrix singular or badly scaled, the code converts to a dense array and runs SVD (or raises `RankNotDeterminedError` if `allow_dense=False`). A rank-deficient sparse matrix therefore costs about the same as plain `matrix_rank` (about 1.34 s vs 1.20 s at N = 2000 in my test).
105
+ - **Rectangular sparse matrices are converted to dense**, or raise an error with `allow_dense=False`.
106
+ - **LU is not rank-revealing.** A clean-looking `U` diagonal does not prove that a matrix is nonsingular. In my tests, about 15 % of random singular tridiagonal matrices (one duplicated row, N = 500) had no small pivot and an early version wrongly reported full rank. The package therefore also estimates the condition number (`scipy.sparse.linalg.onenormest` on the inverse, using the LU factors) and trusts the LU result only when that estimate is safely below 1/tolerance. The estimate is not a proof, so SVD remains the reference for borderline matrices.
107
+ - **The O(N) behaviour applies to banded or low-fill matrices.** General sparse LU can suffer heavy fill-in.
108
+ - **The Gaussian elimination route is not faster than SVD.** In my benchmark it was 2–7× slower than `numpy.linalg.matrix_rank` for N from 50 to 1000. It is kept for transparency and as an option (`method="gauss"`), not as an optimization.
109
+
110
+ ## Tests
111
+
112
+ ```bash
113
+ pip install pytest
114
+ pytest
115
+ ```
116
+
117
+ ## Contributing
118
+
119
+ Issues and pull requests are welcome, especially benchmarks on other hardware and examples of matrices where the LU path gives the wrong rank.
120
+
121
+ ## License
122
+
123
+ MIT. See `LICENSE`.
@@ -0,0 +1,102 @@
1
+ # fast-matrix-rank
2
+
3
+ Fast numerical rank for large **sparse, square, full-rank** matrices, with a safe fallback to SVD for everything else.
4
+
5
+ `numpy.linalg.matrix_rank` needs a dense SVD: O(N³) time and O(N²) memory. For a banded or sparse matrix with N = 100,000 that is impossible (80 GB just to hold it). This package checks rank with a sparse LU factorization (`scipy.sparse.linalg.splu`) instead, and falls back to SVD whenever the LU result cannot be trusted.
6
+
7
+ ## Disclosure
8
+
9
+ This project was partially written with the assistance of Claude, an AI assistant. The code, tests and benchmark script were developed with its help. I reviewed and ran them, and the benchmark numbers in this README were measured on my own machine.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ git clone https://github.com/Jaypatel2611/fast-matrix-rank.git
15
+ cd fast-matrix-rank
16
+ pip install -e .
17
+ ```
18
+
19
+ ## Usage
20
+
21
+ ```python
22
+ import numpy as np
23
+ import scipy.sparse as sp
24
+ from fast_matrix_rank import hybrid_matrix_rank, nullity
25
+
26
+ n = 100_000
27
+ A = sp.diags([np.ones(n - 1), 4 * np.ones(n), np.ones(n - 1)], [-1, 0, 1], format="csc")
28
+
29
+ hybrid_matrix_rank(A) # 100000, in tens of milliseconds
30
+ nullity(A) # 0
31
+ ```
32
+
33
+ By default the function may convert a sparse matrix to a dense array when sparse LU cannot decide the rank. To forbid that, pass `allow_dense=False`. The function then raises `RankNotDeterminedError` instead of densifying:
34
+
35
+ ```python
36
+ from fast_matrix_rank import hybrid_matrix_rank, RankNotDeterminedError
37
+
38
+ try:
39
+ r = hybrid_matrix_rank(A, allow_dense=False)
40
+ except RankNotDeterminedError:
41
+ ... # the matrix is singular, badly scaled, or not square
42
+ ```
43
+
44
+ Dense NumPy arrays, `scipy.sparse` matrices and the newer sparse arrays (`csr_array` etc.) are all accepted. Real, integer and complex data work. NaN or Inf raises `ValueError`.
45
+
46
+ ## How it chooses a method
47
+
48
+ | Input | Method |
49
+ |---|---|
50
+ | Square, sparse (density ≤ 15 %), full rank | Sparse LU |
51
+ | Small dense (max dimension ≤ 500) | Gaussian elimination (see note below) |
52
+ | Large dense, rectangular, rank-deficient, ill-conditioned | LAPACK SVD |
53
+
54
+ You can force a method with `method="gauss"` or `method="svd"`. With `allow_dense=False`, any case that would need a dense conversion raises `RankNotDeterminedError`. Dense NumPy input is not affected by this option.
55
+
56
+ ## Benchmarks
57
+
58
+ Measured with `python benchmark.py` on Windows, AMD64 (AuthenticAMD Family 25), Python 3.12.10, NumPy 2.5.4, SciPy 1.18.1. Your numbers will differ, so run it yourself.
59
+
60
+ Sparse tridiagonal, full rank:
61
+
62
+ | N | This package | Dense SVD (`numpy.linalg.matrix_rank`) |
63
+ |---|---|---|
64
+ | 1,000 | 1.61 ms | 0.16 s |
65
+ | 2,000 | 1.72 ms | 1.23 s |
66
+ | 4,000 | 2.70 ms | 14.00 s |
67
+ | 10,000 | 9.3 ms | not run (0.8 GB matrix) |
68
+ | 100,000 | 90 ms | not run (80 GB matrix) |
69
+
70
+ ## Related SciPy functions
71
+
72
+ SciPy has no exact numerical rank for sparse matrices. These existing functions are related:
73
+
74
+ - `scipy.linalg.interpolative.estimate_rank` estimates the rank to a given relative precision using randomized methods. It accepts a `numpy.ndarray` or a `LinearOperator` (so sparse matrices can be used through a wrapper). It returns an estimate, not an exact rank.
75
+ - `scipy.sparse.csgraph.structural_rank` works on sparse matrices but only looks at the sparsity pattern, not the values. It is an upper bound on the numerical rank.
76
+
77
+ This package checks the actual values of a square sparse matrix with sparse LU, and can fall back to SVD (or raise an error with `allow_dense=False`).
78
+
79
+ ## Limitations
80
+
81
+ Please read these before relying on the speedup.
82
+
83
+ - **Only full-rank sparse matrices are fast.** If the LU factorization finds the matrix singular or badly scaled, the code converts to a dense array and runs SVD (or raises `RankNotDeterminedError` if `allow_dense=False`). A rank-deficient sparse matrix therefore costs about the same as plain `matrix_rank` (about 1.34 s vs 1.20 s at N = 2000 in my test).
84
+ - **Rectangular sparse matrices are converted to dense**, or raise an error with `allow_dense=False`.
85
+ - **LU is not rank-revealing.** A clean-looking `U` diagonal does not prove that a matrix is nonsingular. In my tests, about 15 % of random singular tridiagonal matrices (one duplicated row, N = 500) had no small pivot and an early version wrongly reported full rank. The package therefore also estimates the condition number (`scipy.sparse.linalg.onenormest` on the inverse, using the LU factors) and trusts the LU result only when that estimate is safely below 1/tolerance. The estimate is not a proof, so SVD remains the reference for borderline matrices.
86
+ - **The O(N) behaviour applies to banded or low-fill matrices.** General sparse LU can suffer heavy fill-in.
87
+ - **The Gaussian elimination route is not faster than SVD.** In my benchmark it was 2–7× slower than `numpy.linalg.matrix_rank` for N from 50 to 1000. It is kept for transparency and as an option (`method="gauss"`), not as an optimization.
88
+
89
+ ## Tests
90
+
91
+ ```bash
92
+ pip install pytest
93
+ pytest
94
+ ```
95
+
96
+ ## Contributing
97
+
98
+ Issues and pull requests are welcome, especially benchmarks on other hardware and examples of matrices where the LU path gives the wrong rank.
99
+
100
+ ## License
101
+
102
+ MIT. See `LICENSE`.
@@ -0,0 +1,123 @@
1
+ Metadata-Version: 2.4
2
+ Name: fast-matrix-rank
3
+ Version: 0.1.0
4
+ Summary: Fast numerical rank for large sparse square matrices, with SVD fallback.
5
+ Author-email: Jay Patel <your-email@example.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/Jaypatel2611/fast-matrix-rank
8
+ Project-URL: Issues, https://github.com/Jaypatel2611/fast-matrix-rank/issues
9
+ Keywords: matrix rank,sparse,linear algebra,scipy
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
13
+ Requires-Python: >=3.9
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: numpy>=1.23
17
+ Requires-Dist: scipy>=1.11
18
+ Provides-Extra: test
19
+ Requires-Dist: pytest; extra == "test"
20
+ Dynamic: license-file
21
+
22
+ # fast-matrix-rank
23
+
24
+ Fast numerical rank for large **sparse, square, full-rank** matrices, with a safe fallback to SVD for everything else.
25
+
26
+ `numpy.linalg.matrix_rank` needs a dense SVD: O(N³) time and O(N²) memory. For a banded or sparse matrix with N = 100,000 that is impossible (80 GB just to hold it). This package checks rank with a sparse LU factorization (`scipy.sparse.linalg.splu`) instead, and falls back to SVD whenever the LU result cannot be trusted.
27
+
28
+ ## Disclosure
29
+
30
+ This project was partially written with the assistance of Claude, an AI assistant. The code, tests and benchmark script were developed with its help. I reviewed and ran them, and the benchmark numbers in this README were measured on my own machine.
31
+
32
+ ## Install
33
+
34
+ ```bash
35
+ git clone https://github.com/Jaypatel2611/fast-matrix-rank.git
36
+ cd fast-matrix-rank
37
+ pip install -e .
38
+ ```
39
+
40
+ ## Usage
41
+
42
+ ```python
43
+ import numpy as np
44
+ import scipy.sparse as sp
45
+ from fast_matrix_rank import hybrid_matrix_rank, nullity
46
+
47
+ n = 100_000
48
+ A = sp.diags([np.ones(n - 1), 4 * np.ones(n), np.ones(n - 1)], [-1, 0, 1], format="csc")
49
+
50
+ hybrid_matrix_rank(A) # 100000, in tens of milliseconds
51
+ nullity(A) # 0
52
+ ```
53
+
54
+ By default the function may convert a sparse matrix to a dense array when sparse LU cannot decide the rank. To forbid that, pass `allow_dense=False`. The function then raises `RankNotDeterminedError` instead of densifying:
55
+
56
+ ```python
57
+ from fast_matrix_rank import hybrid_matrix_rank, RankNotDeterminedError
58
+
59
+ try:
60
+ r = hybrid_matrix_rank(A, allow_dense=False)
61
+ except RankNotDeterminedError:
62
+ ... # the matrix is singular, badly scaled, or not square
63
+ ```
64
+
65
+ Dense NumPy arrays, `scipy.sparse` matrices and the newer sparse arrays (`csr_array` etc.) are all accepted. Real, integer and complex data work. NaN or Inf raises `ValueError`.
66
+
67
+ ## How it chooses a method
68
+
69
+ | Input | Method |
70
+ |---|---|
71
+ | Square, sparse (density ≤ 15 %), full rank | Sparse LU |
72
+ | Small dense (max dimension ≤ 500) | Gaussian elimination (see note below) |
73
+ | Large dense, rectangular, rank-deficient, ill-conditioned | LAPACK SVD |
74
+
75
+ You can force a method with `method="gauss"` or `method="svd"`. With `allow_dense=False`, any case that would need a dense conversion raises `RankNotDeterminedError`. Dense NumPy input is not affected by this option.
76
+
77
+ ## Benchmarks
78
+
79
+ Measured with `python benchmark.py` on Windows, AMD64 (AuthenticAMD Family 25), Python 3.12.10, NumPy 2.5.4, SciPy 1.18.1. Your numbers will differ, so run it yourself.
80
+
81
+ Sparse tridiagonal, full rank:
82
+
83
+ | N | This package | Dense SVD (`numpy.linalg.matrix_rank`) |
84
+ |---|---|---|
85
+ | 1,000 | 1.61 ms | 0.16 s |
86
+ | 2,000 | 1.72 ms | 1.23 s |
87
+ | 4,000 | 2.70 ms | 14.00 s |
88
+ | 10,000 | 9.3 ms | not run (0.8 GB matrix) |
89
+ | 100,000 | 90 ms | not run (80 GB matrix) |
90
+
91
+ ## Related SciPy functions
92
+
93
+ SciPy has no exact numerical rank for sparse matrices. These existing functions are related:
94
+
95
+ - `scipy.linalg.interpolative.estimate_rank` estimates the rank to a given relative precision using randomized methods. It accepts a `numpy.ndarray` or a `LinearOperator` (so sparse matrices can be used through a wrapper). It returns an estimate, not an exact rank.
96
+ - `scipy.sparse.csgraph.structural_rank` works on sparse matrices but only looks at the sparsity pattern, not the values. It is an upper bound on the numerical rank.
97
+
98
+ This package checks the actual values of a square sparse matrix with sparse LU, and can fall back to SVD (or raise an error with `allow_dense=False`).
99
+
100
+ ## Limitations
101
+
102
+ Please read these before relying on the speedup.
103
+
104
+ - **Only full-rank sparse matrices are fast.** If the LU factorization finds the matrix singular or badly scaled, the code converts to a dense array and runs SVD (or raises `RankNotDeterminedError` if `allow_dense=False`). A rank-deficient sparse matrix therefore costs about the same as plain `matrix_rank` (about 1.34 s vs 1.20 s at N = 2000 in my test).
105
+ - **Rectangular sparse matrices are converted to dense**, or raise an error with `allow_dense=False`.
106
+ - **LU is not rank-revealing.** A clean-looking `U` diagonal does not prove that a matrix is nonsingular. In my tests, about 15 % of random singular tridiagonal matrices (one duplicated row, N = 500) had no small pivot and an early version wrongly reported full rank. The package therefore also estimates the condition number (`scipy.sparse.linalg.onenormest` on the inverse, using the LU factors) and trusts the LU result only when that estimate is safely below 1/tolerance. The estimate is not a proof, so SVD remains the reference for borderline matrices.
107
+ - **The O(N) behaviour applies to banded or low-fill matrices.** General sparse LU can suffer heavy fill-in.
108
+ - **The Gaussian elimination route is not faster than SVD.** In my benchmark it was 2–7× slower than `numpy.linalg.matrix_rank` for N from 50 to 1000. It is kept for transparency and as an option (`method="gauss"`), not as an optimization.
109
+
110
+ ## Tests
111
+
112
+ ```bash
113
+ pip install pytest
114
+ pytest
115
+ ```
116
+
117
+ ## Contributing
118
+
119
+ Issues and pull requests are welcome, especially benchmarks on other hardware and examples of matrices where the LU path gives the wrong rank.
120
+
121
+ ## License
122
+
123
+ MIT. See `LICENSE`.
@@ -0,0 +1,10 @@
1
+ LICENSE
2
+ README.md
3
+ fast_matrix_rank.py
4
+ pyproject.toml
5
+ fast_matrix_rank.egg-info/PKG-INFO
6
+ fast_matrix_rank.egg-info/SOURCES.txt
7
+ fast_matrix_rank.egg-info/dependency_links.txt
8
+ fast_matrix_rank.egg-info/requires.txt
9
+ fast_matrix_rank.egg-info/top_level.txt
10
+ tests/test_fast_matrix_rank.py
@@ -0,0 +1,5 @@
1
+ numpy>=1.23
2
+ scipy>=1.11
3
+
4
+ [test]
5
+ pytest
@@ -0,0 +1 @@
1
+ fast_matrix_rank
@@ -0,0 +1,224 @@
1
+ """Adaptive matrix rank estimation.
2
+
3
+ Routes a matrix to the cheapest reliable method:
4
+
5
+ * square, sparse, full-rank -> sparse LU (``scipy.sparse.linalg.splu``)
6
+ * small dense -> vectorized Gaussian elimination
7
+ * everything else / any doubt -> LAPACK SVD (``numpy.linalg.matrix_rank``)
8
+
9
+ Limits (by design):
10
+
11
+ * The sparse fast path only helps when the matrix is full rank. A
12
+ rank-deficient or ill-conditioned sparse matrix falls back to *dense* SVD,
13
+ so it costs O(N^3) time and O(N^2) memory.
14
+ * Rectangular sparse matrices are densified.
15
+ * The Gaussian route uses partial pivoting, which is not rank-revealing in
16
+ the worst case. SVD stays the reference for ill-conditioned input.
17
+
18
+ License: MIT
19
+ """
20
+
21
+ from typing import Optional, Union
22
+
23
+ import numpy as np
24
+ import scipy.sparse as sp
25
+ import scipy.sparse.linalg as spla
26
+
27
+ __all__ = [
28
+ "vectorized_gauss_rank",
29
+ "hybrid_matrix_rank",
30
+ "nullity",
31
+ "RankNotDeterminedError",
32
+ ]
33
+
34
+
35
+ class RankNotDeterminedError(RuntimeError):
36
+ """Raised when ``allow_dense=False`` and the rank cannot be decided
37
+ without converting a sparse matrix to a dense array."""
38
+
39
+
40
+ # If min|U_ii| / max|U_ii| is below this, the LU rank is not trusted.
41
+ _LU_RATIO_TRUST = 1e-8
42
+
43
+
44
+ def _default_tol(shape, scale: float, rtol: Optional[float]) -> float:
45
+ eps = float(np.finfo(float).eps)
46
+ return (rtol if rtol is not None else max(shape) * eps) * scale
47
+
48
+
49
+ def _check_finite(values: np.ndarray) -> None:
50
+ if not np.all(np.isfinite(values)):
51
+ raise ValueError("Matrix contains NaN or Inf.")
52
+
53
+
54
+ def vectorized_gauss_rank(A: np.ndarray, rtol: Optional[float] = None) -> int:
55
+ """Rank via Gaussian elimination with partial pivoting.
56
+
57
+ Each elimination step is one NumPy outer-product update.
58
+ """
59
+ A = np.asarray(A)
60
+ if A.ndim != 2:
61
+ raise ValueError(f"Input must be 2D, got {A.ndim}D.")
62
+ m, n = A.shape
63
+ if m == 0 or n == 0:
64
+ return 0
65
+ dtype = np.complex128 if np.iscomplexobj(A) else np.float64
66
+ X = np.array(A, dtype=dtype, copy=True)
67
+ _check_finite(X)
68
+
69
+ a_max = float(np.abs(X).max())
70
+ if a_max == 0.0:
71
+ return 0
72
+ tol = _default_tol((m, n), a_max, rtol)
73
+
74
+ pivot_row = 0
75
+ for col in range(n):
76
+ if pivot_row >= m:
77
+ break
78
+ col_abs = np.abs(X[pivot_row:, col])
79
+ k = int(np.argmax(col_abs))
80
+ if col_abs[k] <= tol:
81
+ continue
82
+ max_row = pivot_row + k
83
+ if max_row != pivot_row:
84
+ X[[pivot_row, max_row]] = X[[max_row, pivot_row]]
85
+ factors = X[pivot_row + 1:, col] / X[pivot_row, col]
86
+ X[pivot_row + 1:, col:] -= factors[:, None] * X[pivot_row, col:]
87
+ pivot_row += 1
88
+ return pivot_row
89
+
90
+
91
+ def _to_dense(A, allow_dense: bool, reason: str) -> np.ndarray:
92
+ """Convert sparse input to dense, or raise if that is not allowed."""
93
+ if not sp.issparse(A):
94
+ return A
95
+ if not allow_dense:
96
+ raise RankNotDeterminedError(
97
+ f"{reason} Pass allow_dense=True to convert to a dense array."
98
+ )
99
+ return A.toarray()
100
+
101
+
102
+ def _svd_rank(A, rtol: Optional[float]) -> int:
103
+ """NumPy's own default tolerance (relative to the largest singular value)."""
104
+ dense = A.toarray() if sp.issparse(A) else np.asarray(A)
105
+ if dense.size == 0:
106
+ return 0
107
+ _check_finite(dense)
108
+ if rtol is None:
109
+ return int(np.linalg.matrix_rank(dense))
110
+ s = np.linalg.svd(dense, compute_uv=False)
111
+ return int(np.sum(s > rtol * s[0])) if s.size and s[0] > 0 else 0
112
+
113
+
114
+ def _cond_ok(A_csc, lu, rtol: Optional[float]) -> bool:
115
+ """True if the estimated 1-norm condition number is safely below 1/tol.
116
+
117
+ Uses ``onenormest`` on the inverse (a few sparse triangular solves), so
118
+ the matrix stays sparse. This is an estimate, not a proof.
119
+ """
120
+ n = A_csc.shape[0]
121
+ eps = float(np.finfo(float).eps)
122
+ limit = 1.0 / (rtol if rtol is not None else n * eps)
123
+ inv = spla.LinearOperator(
124
+ (n, n),
125
+ matvec=lambda x: lu.solve(np.asarray(x)),
126
+ rmatvec=lambda x: lu.solve(np.asarray(x), trans="H"),
127
+ matmat=lambda X: lu.solve(np.asarray(X)),
128
+ rmatmat=lambda X: lu.solve(np.asarray(X), trans="H"),
129
+ dtype=A_csc.dtype,
130
+ )
131
+ try:
132
+ inv_norm = spla.onenormest(inv)
133
+ except Exception: # estimator failure: do not trust LU
134
+ return False
135
+ cond = float(spla.norm(A_csc, 1)) * float(inv_norm)
136
+ return bool(np.isfinite(cond) and cond < limit)
137
+
138
+
139
+ def hybrid_matrix_rank(
140
+ A,
141
+ rtol: Optional[float] = None,
142
+ density_threshold: float = 0.15,
143
+ dense_gauss_cutoff: int = 500,
144
+ method: str = "auto",
145
+ allow_dense: bool = True,
146
+ ) -> int:
147
+ """Numerical rank of a dense or sparse matrix.
148
+
149
+ ``method``: "auto", "gauss", "svd". ``rtol`` is relative to the largest
150
+ singular value on the SVD route and to the largest absolute entry on the
151
+ Gauss/LU routes.
152
+
153
+ ``allow_dense``: if False, a sparse input is never converted to a dense
154
+ array. When the answer cannot be decided with sparse LU alone (singular
155
+ or badly scaled factorization, rectangular or dense-ish input, or a forced
156
+ "gauss"/"svd" method), ``RankNotDeterminedError`` is raised instead.
157
+ Dense NumPy input is not affected.
158
+ """
159
+ if not sp.issparse(A):
160
+ A = np.asarray(A)
161
+ if A.ndim != 2:
162
+ raise ValueError(f"Input must be 2D, got {A.ndim}D.")
163
+ if 0 in A.shape:
164
+ return 0
165
+ m, n = A.shape
166
+
167
+ if method == "svd":
168
+ return _svd_rank(
169
+ _to_dense(A, allow_dense, "method='svd' needs a dense array."), rtol
170
+ )
171
+ if method == "gauss":
172
+ return vectorized_gauss_rank(
173
+ _to_dense(A, allow_dense, "method='gauss' needs a dense array."), rtol
174
+ )
175
+ if method != "auto":
176
+ raise ValueError(f"Unknown method {method!r}.")
177
+
178
+ data = A.data if sp.issparse(A) else A
179
+ _check_finite(data)
180
+
181
+ if sp.issparse(A):
182
+ density = A.nnz / float(m * n)
183
+ else:
184
+ density = np.count_nonzero(A) / float(m * n)
185
+
186
+ # Dense, rectangular or tiny -> no sparse LU.
187
+ if density > density_threshold or m != n or n < 2:
188
+ A = _to_dense(
189
+ A,
190
+ allow_dense,
191
+ "Sparse LU only handles square, sparse matrices.",
192
+ )
193
+ if max(m, n) <= dense_gauss_cutoff:
194
+ return vectorized_gauss_rank(A, rtol)
195
+ return _svd_rank(A, rtol)
196
+
197
+ # Square and sparse: try sparse LU.
198
+ A_csc = sp.csc_matrix(A)
199
+ if A_csc.nnz == 0:
200
+ return 0
201
+ try:
202
+ lu = spla.splu(A_csc, diag_pivot_thresh=1.0)
203
+ except RuntimeError: # "Factor is exactly singular"
204
+ _to_dense(A_csc, allow_dense, "The LU factorization found the matrix singular.")
205
+ return _svd_rank(A_csc, rtol)
206
+
207
+ u_diag = np.abs(lu.U.diagonal())
208
+ u_max = float(u_diag.max())
209
+ # Trust LU only if the pivots look fine AND the estimated condition number
210
+ # says the matrix is safely nonsingular. The pivots alone are not enough:
211
+ # a singular matrix can still have a clean-looking U diagonal.
212
+ if u_max > 0 and float(u_diag.min()) / u_max > _LU_RATIO_TRUST:
213
+ tol = _default_tol((m, n), float(np.abs(A_csc.data).max()), rtol)
214
+ if float(u_diag.min()) > tol and _cond_ok(A_csc, lu, rtol):
215
+ return n
216
+ _to_dense(A_csc, allow_dense, "The LU result is not reliable (poorly scaled pivots).")
217
+ return _svd_rank(A_csc, rtol)
218
+
219
+
220
+ def nullity(A, rtol: Optional[float] = None, allow_dense: bool = True) -> int:
221
+ """Nullity = columns - rank."""
222
+ if not sp.issparse(A):
223
+ A = np.asarray(A)
224
+ return A.shape[1] - hybrid_matrix_rank(A, rtol=rtol, allow_dense=allow_dense)
@@ -0,0 +1,33 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "fast-matrix-rank"
7
+ version = "0.1.0"
8
+ description = "Fast numerical rank for large sparse square matrices, with SVD fallback."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "Jay Patel", email = "your-email@example.com" }]
13
+ classifiers = [
14
+ "Programming Language :: Python :: 3",
15
+ "License :: OSI Approved :: MIT License",
16
+ "Topic :: Scientific/Engineering :: Mathematics",
17
+ ]
18
+ dependencies = ["numpy>=1.23", "scipy>=1.11"]
19
+ keywords = ["matrix rank", "sparse", "linear algebra", "scipy"]
20
+
21
+ [project.optional-dependencies]
22
+ test = ["pytest"]
23
+
24
+ [project.urls]
25
+ Homepage = "https://github.com/Jaypatel2611/fast-matrix-rank"
26
+ Issues = "https://github.com/Jaypatel2611/fast-matrix-rank/issues"
27
+
28
+ [tool.setuptools]
29
+ py-modules = ["fast_matrix_rank"]
30
+
31
+ [tool.pytest.ini_options]
32
+ testpaths = ["tests"]
33
+ pythonpath = ["."]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,131 @@
1
+ import numpy as np
2
+ import pytest
3
+ import scipy.sparse as sp
4
+
5
+ from fast_matrix_rank import (
6
+ RankNotDeterminedError,
7
+ hybrid_matrix_rank,
8
+ nullity,
9
+ vectorized_gauss_rank,
10
+ )
11
+
12
+ rng = np.random.default_rng(0)
13
+
14
+
15
+ def tridiag(n, dup_row=False):
16
+ d = rng.standard_normal(n) + 4.0
17
+ o = rng.standard_normal(n - 1)
18
+ A = sp.diags([o, d, o], [-1, 0, 1], format="lil")
19
+ if dup_row:
20
+ A[5, :] = A[4, :]
21
+ return A.tocsc()
22
+
23
+
24
+ @pytest.mark.parametrize("shape", [(1, 1), (5, 5), (50, 30), (30, 50), (100, 100)])
25
+ def test_dense_random_matches_numpy(shape):
26
+ A = rng.standard_normal(shape)
27
+ assert vectorized_gauss_rank(A) == np.linalg.matrix_rank(A)
28
+ assert hybrid_matrix_rank(A) == np.linalg.matrix_rank(A)
29
+
30
+
31
+ def test_low_rank_dense():
32
+ A = rng.standard_normal((60, 7)) @ rng.standard_normal((7, 80))
33
+ assert hybrid_matrix_rank(A) == 7
34
+ assert nullity(A) == 80 - 7
35
+
36
+
37
+ def test_complex_keeps_imaginary_part():
38
+ A = np.array([[1j, 0], [0, 1j]])
39
+ assert vectorized_gauss_rank(A) == 2
40
+
41
+
42
+ def test_zero_and_empty():
43
+ assert hybrid_matrix_rank(np.zeros((4, 4))) == 0
44
+ assert hybrid_matrix_rank(np.zeros((0, 3))) == 0
45
+ assert hybrid_matrix_rank(sp.csc_matrix((5, 5))) == 0
46
+
47
+
48
+ def test_integer_and_list_input():
49
+ assert hybrid_matrix_rank([[1, 2], [2, 4]]) == 1
50
+
51
+
52
+ @pytest.mark.parametrize("bad", [np.nan, np.inf])
53
+ def test_nan_inf_rejected(bad):
54
+ with pytest.raises(ValueError):
55
+ hybrid_matrix_rank(np.array([[1.0, bad], [2.0, 3.0]]))
56
+ with pytest.raises(ValueError):
57
+ hybrid_matrix_rank(sp.csc_matrix(np.array([[1.0, bad], [2.0, 3.0]])))
58
+
59
+
60
+ def test_not_2d():
61
+ with pytest.raises(ValueError):
62
+ hybrid_matrix_rank(np.zeros(3))
63
+
64
+
65
+ def test_sparse_full_rank():
66
+ assert hybrid_matrix_rank(tridiag(3000)) == 3000
67
+
68
+
69
+ def test_sparse_exactly_singular_does_not_crash():
70
+ A = tridiag(1500, dup_row=True)
71
+ assert hybrid_matrix_rank(A) == np.linalg.matrix_rank(A.toarray()) == 1499
72
+
73
+
74
+ def test_sparse_ill_conditioned_falls_back_to_svd():
75
+ d = np.ones(800)
76
+ d[400] = 1e-14
77
+ A = sp.diags(d).tocsc()
78
+ assert hybrid_matrix_rank(A) == np.linalg.matrix_rank(A.toarray()) == 799
79
+
80
+
81
+ @pytest.mark.parametrize("ctor", [sp.csr_matrix, sp.csr_array, sp.coo_array, sp.csc_array])
82
+ def test_all_sparse_containers(ctor):
83
+ A = ctor(tridiag(1000))
84
+ assert hybrid_matrix_rank(A) == 1000
85
+
86
+
87
+ def test_rectangular_sparse():
88
+ A = sp.random(200, 300, density=0.02, random_state=1, format="csr")
89
+ assert hybrid_matrix_rank(A) == np.linalg.matrix_rank(A.toarray())
90
+
91
+
92
+ def test_method_overrides():
93
+ A = rng.standard_normal((40, 40))
94
+ for m in ("gauss", "svd", "auto"):
95
+ assert hybrid_matrix_rank(A, method=m) == 40
96
+ with pytest.raises(ValueError):
97
+ hybrid_matrix_rank(A, method="nope")
98
+
99
+
100
+ def test_no_dense_full_rank_sparse_still_works():
101
+ assert hybrid_matrix_rank(tridiag(2000), allow_dense=False) == 2000
102
+ assert nullity(tridiag(2000), allow_dense=False) == 0
103
+
104
+
105
+ def test_no_dense_singular_raises():
106
+ with pytest.raises(RankNotDeterminedError):
107
+ hybrid_matrix_rank(tridiag(500, dup_row=True), allow_dense=False)
108
+
109
+
110
+ def test_no_dense_ill_conditioned_raises():
111
+ d = np.ones(300)
112
+ d[100] = 1e-14
113
+ with pytest.raises(RankNotDeterminedError):
114
+ hybrid_matrix_rank(sp.diags(d).tocsc(), allow_dense=False)
115
+
116
+
117
+ def test_no_dense_rectangular_sparse_raises():
118
+ A = sp.random(20, 30, density=0.05, random_state=1, format="csr")
119
+ with pytest.raises(RankNotDeterminedError):
120
+ hybrid_matrix_rank(A, allow_dense=False)
121
+
122
+
123
+ @pytest.mark.parametrize("method", ["gauss", "svd"])
124
+ def test_no_dense_forced_method_on_sparse_raises(method):
125
+ with pytest.raises(RankNotDeterminedError):
126
+ hybrid_matrix_rank(tridiag(50), method=method, allow_dense=False)
127
+
128
+
129
+ def test_no_dense_does_not_affect_dense_input():
130
+ A = rng.standard_normal((30, 30))
131
+ assert hybrid_matrix_rank(A, allow_dense=False) == 30