本文详解 np.linalg.matrix_rank 中 rtol 参数报错的原因，并提供兼容旧版本 numpy 的手动实现方案，包括 svd 分解与阈值判断的完整代码和注意事项。
本文详解 np.linalg.matrix_rank 中 rtol 参数报错的原因，并提供兼容旧版本 numpy 的手动实现方案，包括 svd 分解与阈值判断的完整代码和注意事项。
np.linalg.matrix_rank(A, rtol=1e-5) 报错 TypeError: matrix_rank() got an unexpected keyword argument 'rtol'，根本原因在于：rtol 参数自 NumPy 1.14.0 版本起才被引入。若你使用的 NumPy 版本低于该版本（例如 1.13.x 或更早），调用时便会因参数不识别而抛出异常。
✅ 验证当前 NumPy 版本的方法：
import numpy as np print(np.__version__) # 如输出 '1.12.1'，则不支持 rtol
✅ 推荐解决方案（兼顾兼容性与准确性）：
使用奇异值分解（SVD）手动实现带相对容差的秩计算。其原理是：对矩阵 A 进行 SVD 分解 A = U @ diag(s) @ Vh，其中 s 是降序排列的奇异值数组；设定相对容差阈值 tol * max(s)，统计大于该阈值的奇异值个数，即为数值秩。
完整可运行示例：
import numpy as np
def matrix_rank_rtol(A, rtol=1e-5):
"""
兼容所有 NumPy 版本的相对容差矩阵秩计算
:param A: 输入二维数组
:param rtol: 相对容差（默认 1e-5）
:return: 数值秩（int）
"""
if A.size == 0:
return 0
u, s, vh = np.linalg.svd(A, full_matrices=False)
# 使用最大奇异值作为基准，避免绝对容差失敏
tol = rtol * s[0] if len(s) > 0 else 0
return int(np.sum(s > tol))
# 示例使用
np.random.seed(42)
A = np.random.randn(5, 4)
rank = matrix_rank_rtol(A, rtol=1e-6)
print(f"Matrix shape: {A.shape}, Numerical rank (rtol=1e-6): {rank}")
⚠️ 注意事项：
- rtol 的语义：np.linalg.matrix_rank(..., rtol=ε) 等价于 s > ε * max(s)，而非 s > ε（后者为绝对容差，易受量纲影响）；
- 空矩阵/退化矩阵：需显式处理 A.size == 0 或全零矩阵情形，避免 s[0] 索引错误；
- 性能考量：SVD 计算复杂度为 O(min(m,n)²·max(m,n))，对超大矩阵建议结合 scipy.linalg.svds（截断 SVD）加速；
- 升级 NumPy（可选）：若环境允许，执行 pip install --upgrade numpy 即可直接使用原生 rtol 参数，无需自定义函数。
综上，手动实现 SVD + 相对阈值判断不仅解决了兼容性问题，也加深了对数值秩本质（由主导奇异值数量决定）的理解，是科学计算中稳健、可解释的实践方式。
