hsolve Python 接口¶
进程内 Python API:直接接收 numpy / scipy 矩阵,返回 numpy 特征值与特征向量(交付物 b
「numpy / scipy 矩阵输入,numpy / scipy 输出」)。实现:python/src/module.cpp(pybind11 扩展
hsolve._hsolve)、python/src/csr_convert.hpp(输入转换)、python/hsolve/__init__.py(纯
Python 前端)。求解本身就是 hs::solve——与命令行 hsolve 同一条路径、同一份配置格式。
1. 构建与导入¶
tools/dev/build.sh release # 找到 pybind11(环境内 3.1)时自动构建 Python 模块
PYTHONPATH=build/release/python python -c "import hsolve; print(hsolve.version())"
- 产物在
build/<preset>/python/hsolve/(__init__.py+_hsolve.cpython-*.so),无需安装。 - CMake 选项
HSOLVE_BUILD_PYTHON:找到 pybind11 时默认 ON;-DHSOLVE_BUILD_PYTHON=OFF关闭, 显式 ON 而缺 pybind11 时报错。debug 预设带 ASan/UBSan,普通 python 须预加载运行库才能导入:LD_PRELOAD=$CONDA_PREFIX/lib/libasan.so.8:$CONDA_PREFIX/lib/libubsan.so.1 ASAN_OPTIONS=detect_leaks=0 HSOLVE_PYTHON_DIR=build/debug/python python -m pytest tests/py/test_python_binding.py(2026-10-11 实测 62 项全过、无 sanitizer 报告,约 5 分钟);日常使用 release。 - 依赖:numpy;scipy 仅在传入 scipy 稀疏矩阵或调用
load_matrix时需要。 - 测试:
python -m pytest tests/py/test_python_binding.py(tools/dev/test.sh release也会运行); 默认从build/release/python导入,HSOLVE_PYTHON_DIR=<dir>指定其它构建;未构建时整个文件跳过。 - BLAS hook(P5,
docs/BLAS.md、docs/DESIGN.md§3.8):命令行hsolve默认链入了 hook(route all, 16 线程端到端 1.05–1.16×,收益在回代),Python 扩展模块没有。要在 Python 中得到同样的路由,在解释器前 预加载同一构建的libhsolve_blashook.so(f56e9c6 起可用):
LD_PRELOAD=$PWD/build/release/libhsolve_blashook.so HS_BLAS_ROUTE=all \
PYTHONPATH=build/release/python python3 -c "import hsolve; r = hsolve.solve('A.npz', config='config.json'); print(r.report['success'])"
扩展模块、MUMPS 与 OpenBLAS 在 Python 下由 dlopen(RTLD_LOCAL) 打开;预加载的 hook 仍排在它们的符号
查找之前,并自己在这些已加载的库里找到真实的 BLAS 例程。同一进程中 numpy / scipy 的 BLAS 调用也经过
hook(转发,或像 MUMPS 的调用一样改道;路由对任何调用方都正确)。HS_BLAS_ROUTE 不设时取构建默认值
(HSOLVE_BLAS_ROUTE_DEFAULT,默认 all),HS_BLAS_ROUTE=off 为纯转发。只验证了正确性,Python 下的
加速未单独计时。
- MUMPS(P9 集成,docs/DESIGN.md §3.4):扩展模块与命令行链接同一个 MUMPS——默认构建(HS_MUMPS=source)
是由仓库内 third_party/mumps/ 源码包加 L0 分块补丁编译的 MUMPS 5.8.2,其 lib/ 排在模块 RPATH 的最前面,
先于环境的 conda-forge mumps-seq(库名与 soname 相同),默认块参数为 P9 的(运行时 HS_MUMPS_BLOCKING=mumps
恢复 MUMPS 自己的);HS_MUMPS=env tools/dev/build.sh release 改用环境的 MUMPS。hsolve.build_info() 写出
所用的 MUMPS(mumps=mumps-5.8.2-<key> 或 mumps=env)与默认块参数;tests/py/test_mumps_build.py 在全新
解释器中求解后检查 /proc/self/maps 里映射的正是所配置的库。
2. 快速上手¶
import numpy as np, scipy.sparse as sp, hsolve
# HEP:A x = λ x,σ 附近最近的 6 个
res = hsolve.solve(A, sigma=0.3, k=6)
res.eigenvalues # float64 (m,),按离 σ 由近到远
res.eigenvectors # (n, m) Fortran 序;A 复数时 complex128
res.report["success"] # 每对后向误差 ≤ tol 且(HEP/GHEP)惯性证书通过
# GHEP / GHIEP(B 不定):同一个调用,问题类型由 B 的惯性自动判定
res = hsolve.solve(A, B, sigma=-2.5e5, k=10)
res.complex_eigenvalues # 仅 B 不定且出现真复特征值时非空,complex128 (c,)
res.complex_eigenvectors # complex128 (n, c)
# 其它目标
hsolve.solve(A, lower=0.5, upper=0.7) # 区间内全部(mode 自动推断为 interval)
hsolve.solve(A, mode="smallest", k=4) # 代数最小(标准问题)
hsolve.solve(A, mode="largest", k=4)
# 测例目录 / 配置文件:与 CLI 完全相同的读入流水线
res = hsolve.solve("case/A.npz", "case/B.npz", config="case/config.json")
A = hsolve.load_matrix("case/A.npz") # scipy.sparse.csr_array,值与列索引不拷贝
3. API¶
hsolve.solve(A, B=None, *, sigma=None, k=6, mode='nearest', lower=None, upper=None, tol=1e-10, config=None, threads=0, verbose=0, storage='auto') -> SolveResult¶
| 参数 | 含义 |
|---|---|
A, B |
scipy 稀疏矩阵/数组(csr、csc、coo 直接转换;bsr、dia、lil、dok 经 .tocsr()),稠密 numpy 数组(含 np.matrix、任意步长视图),或 .npz/.npy/.mtx 文件路径。B=None 即 B = I |
sigma |
nearest 模式的位移;给出且未给 mode 时 mode 取 nearest |
k |
特征对个数(nearest / smallest / largest) |
mode |
nearest | interval | smallest | largest;省略时:给了 lower/upper → interval,给了 sigma → nearest,否则取 config(默认 nearest)。同时给 sigma 与 lower/upper 而不给 mode 报错 |
lower, upper |
interval 模式的闭区间 |
tol |
接受阈值:每对后向误差 η ≤ tol(docs/DESIGN.md §4.5) |
config |
dict 或 config.json 路径(docs/FORMATS.md §2 的全部键;未知键报错)。显式传入的关键字参数覆盖它,未传的关键字不覆盖 |
threads |
OpenMP 线程数,0 = OMP_NUM_THREADS / 全部可用;调用结束后恢复进程原线程设置 |
verbose |
0 静默,1 进度事件,2 调试;写到进程的 stderr(C 层,Jupyter 中显示在终端) |
storage |
auto(某个严格三角为空时视为三角存储并镜像,与 CLI 相同)| full | upper | lower(声明只存该三角,另一三角出现元素报错);同时作用于 A 与 B |
SolveResult 字段:
| 字段 | 内容 |
|---|---|
eigenvalues |
float64 (m,),实特征值,按目标排序(nearest:离 σ 由近到远;interval / smallest:升序;largest:降序) |
eigenvectors |
(n, m),Fortran 序;A 或 B 为复数 dtype(内存数组的 dtype,或文件中存储的值类型)时 complex128——虚部全为零、按实数求解时也是——否则 float64;HEP/GHEP 为 B-正交归一,GHIEP 为 2-范数归一 |
complex_eigenvalues, complex_eigenvectors |
GHIEP 的真复特征对,complex128 (c,) 与 (n, c);通常为空 |
report |
dict,与 CLI report.json 相同的键(docs/FORMATS.md §3);输入预处理的说明以 "input: A: ..." 追加到 report["warnings"] |
config |
dict,本次生效的完整配置——存成 config.json 即可用 CLI 或 solve(config=...) 复现 |
success |
属性,等于 report["success"] |
未达标(success == False)时发出 hsolve.HsolveWarning,并照常返回结果(与 CLI 退出码 1 对应)。
其它函数¶
hsolve.load_matrix(path, *, storage='auto', hermitian_tol=1e-10, return_info=False):用 C++ 读入器 (与 CLI 相同:合并重复项、丢弃精确零、三角恢复、厄密检查与厄密化、零虚部复数降为实数)读文件, 返回scipy.sparse.csr_array:data与indices(int32)直接引用 C++ 缓冲区(不拷贝),indptr是 n+1 个元素的 int32 副本(C++ 行指针随即释放)。原因:scipy 的 csr_array 要求 indptr 与 indices 同一种索引类型,只要有一个是 int64 就把另一个也拷成 int64;直接交出 int64 行指针会让它把全部列索引 拷一遍,而 C++ 的 int32 原件仍被占用(每个非零元 12 B 而非 4 B)。n 或 nnz 超出 int32 时 indices 为 一份 int64 副本(scipy 本来也要做这次拷贝;C++ 原件随即释放),indptr 引用 C++ 缓冲区。实测见 §8。return_info=True另返回{source_format, storage, hermitian_defect, notes}。hsolve.default_config():全部配置键的默认值(dict)。hsolve.version()/hsolve.__version__、hsolve.build_info()。
异常¶
hs::Error 的错误码映射为 HsolveError 子类(属性 code 为错误码字符串),并同时继承最贴切的
Python 内置异常,except ValueError 等惯用写法照常生效:
| code | 类 | 也是 | 典型原因 |
|---|---|---|---|
invalid_input |
InvalidInputError |
ValueError |
k ≤ 0 或 k > n、非方阵、A/B 阶数不同、非有限值(含重复项求和溢出)、越界索引、未知配置键、非法 mode/storage |
io |
HsolveIOError |
OSError |
矩阵或配置文件不存在/损坏 |
not_hermitian |
NotHermitianError |
ValueError |
‖M−Mᴴ‖_F/‖M‖_F > hermitian_tol |
unsupported |
UnsupportedError |
NotImplementedError |
当前版本不支持的组合(如 B 不定时的 interval) |
factorization_failed |
FactorizationFailedError |
RuntimeError |
MUMPS 失败 |
singular |
SingularError |
ArithmeticError |
σ 处及其附近 A−σB 都奇异 |
out_of_memory_budget |
OutOfMemoryBudgetError |
MemoryError |
预测内存超 memory_budget_gb(未分配) |
not_converged |
NotConvergedError |
RuntimeError |
— |
internal |
InternalError |
RuntimeError |
内部不变量被破坏(缺陷,请报告) |
参数类型错误(如 k=2.5、sigma='0.5'、config=42、传入 LinearOperator)抛 TypeError:实数参数
(sigma/lower/upper/tol/hermitian_tol)接受 int、float、numpy 整数/浮点标量与 0 维数组,整数参数
(k/threads/verbose)接受 int 与 numpy 整数,字符串一律不接受。
测试 test_every_error_code_has_its_class 用 C++ 枚举导出的码表核对上表 9 个类,并逐个检查翻译。
4. 输入:格式、类型与拷贝¶
每个矩阵一次遍历转换为求解器的 hs::CsrMatrix(拥有内存的 CSR:int64 行指针、int32 列索引),
dtype 转换在这次写入中完成;稀疏输入从不稠密化。
| 输入 | 转换 | 额外拷贝 |
|---|---|---|
| csr(行内已排序) | 逐行直接复制 | 1 次(写入 CsrMatrix) |
| csr(行内乱序/重复) | 仅这些行排序(稳定)+ 合并 | 1 次 |
| csc | 不转置:csc 数组即 Aᵀ 的 CSR,取共轭得 Aᴴ;Aᴴ 与 A 的厄密部分 (A+Aᴴ)/2 与厄密缺陷完全相同,而求解器只用这两者(A 精确厄密时 Aᴴ 与 A 逐位相等) | 1 次 |
| coo | 按行计数排序直接写入 CSR 数组,再逐行排序 / 合并 | 1 次 |
| 稠密 ndarray(C/F 序或任意步长) | 计数一遍,复制非零元(精确零视为不存在,同 CLI 的 .npy) |
1 次(仅非零元) |
| bsr / dia / lil / dok | scipy .tocsr() 后同 csr |
2 次 |
| 文件路径 | hs::load_matrix(同 CLI) |
0 次(读入即 CsrMatrix) |
- 值 dtype:float32/64、complex64/128 直接读取(float32 → double 精确);整数/布尔/float16/longdouble 先由 numpy 转为 float64(longdouble 有舍入);索引 int32/int64 直接读取,其它整型转 int64。
- 实/复分派:A 或 B 含非零虚部 → 复数求解(实的一方在转换中提升,不另拷贝);复数 dtype 但虚部 全为零 → 按实数求解(更快,与 CLI 读文件的行为一致),特征向量仍以 complex128 返回——文件路径 输入同样如此(文件中存的是复数类型即可)。
- 形状在转换之前按调用者给出的方向检查(
A is not square (30x20)、B has order 31, A has 30): csc 在内部是 Aᴴ,三角输入先要镜像,但报错不会出现转置后的形状或内部函数名。 - 规范化与
hs::load_matrix相同:重复项求和、求和后的精确零丢弃、inf/nan 报InvalidInputError(有限的重复项求和溢出成 inf 也一样,load_matrix 同样在求和之后检查);三角存储按storage恢复; 之后由hs::solve做厄密检查:P5 起与hs::load_matrix同一规则——缺陷 ‖M−Mᴴ‖_F/‖M‖_F 用缩放平方和 计算(任意量级都准确),超hermitian_tol报NotHermitianError,按逐元素精确比较不是精确厄密时取 厄密部分;全零矩阵与非有限值报InvalidInputError(docs/DESIGN.md§3.6-1)。P4 时内存输入用未缩放 的平方和,元素模超出约 1e±154 时与路径输入结果不同,这一差异已消除。 - 内存:调用期间 scipy 持有的输入与求解器的 CsrMatrix 并存(≈ 输入大小 + 1 份 CSR);转换后的 矩阵在结果返回 Python 前释放。
5. 输出¶
eigenvectors/complex_eigenvectors不拷贝:numpy 数组直接拥有 C++ 的特征向量缓冲区 (v.base是一个 PyCapsule,数组可写,生命周期由 Python 管理)。- 特征值是长度 m 的小数组(复制)。
report/config由 JSON 解析为 dict。
6. GIL 与线程¶
- 转换与求解期间释放 GIL:其它 Python 线程照常运行(测试
test_gil_is_released_during_solve)。 - 同一进程内的多个
solve调用串行执行(进程级互斥锁,在释放 GIL 之后获取):单次求解已用满 所配置的核,且 MUMPS 顺序版(libseq)未声明多实例并发安全。load_matrix可并发。 threads>0只作用于本次调用,之后恢复进程原来的 OpenMP 线程数。- 求解中按 Ctrl-C:信号在本次求解返回后才生效。
- 在调用期间不要修改传入的数组(与 numpy 释放 GIL 的其它函数相同的约定)。
7. 与命令行的一致性¶
- 配置:同一 schema、同一校验器(
hs::parse_config);result.config可直接存为config.json。 - 路径输入走与 CLI 相同的
hs::load_matrix(hermitian_tol取自配置);内存输入按同样的规则 规范化,厄密检查也相同(§4)。测试(tests/py/test_python_binding.py) 中 22 种实矩阵输入(csr/csc/coo 的 matrix 与 array 版本、int64 索引、乱序 + 重复项、显式零、 bsr/lil、稠密 C/F 序与步长视图、三角存储……)与 9 种复矩阵输入在deterministic=true下得到 逐位相同的特征值与特征向量。
8. 实测开销¶
方法可复现:bench/pybind_convert.cpp(转换内核)、python/bench/overhead.py(端到端),均经
tools/run/guard.py --cores 38,39(2 核,2026-10-11,release 构建)。
转换内核(build/release/bench_pybind_convert 100 5:三维 7 点 Laplacian,n = 1e6,nnz = 6.94e6,
中位数):「下限」是任何拥有内存的 CsrMatrix 都要付的代价(分配 + 置零 + memcpy 索引/值 + 行指针加宽)。
| 输入 | 时间 (s) | 相对下限 |
|---|---|---|
| 下限(memcpy) | 0.036 | 1.00 |
| csr int32/f64 | 0.048 | 1.34 |
| csc int32/f64(不转置) | 0.049 | 1.36 |
| csr int64/f64 | 0.050 | 1.38 |
| csr int32/f32 | 0.049 | 1.36 |
| csr complex128(虚部全零:扫描 + 转实数) | 0.063 | 1.77 |
| csr 每行逆序(逐行排序) | 0.105 | 2.94 |
| coo 行有序 | 0.064 | 1.79 |
| coo 随机打乱 | 0.290 | 8.09 |
参照:库函数 hs::csr_from_coo(同一打乱三元组,int64) |
0.257 | 7.16 |
| csr 上三角 + 镜像 | 0.172 | 4.80 |
负结果(如实记录):打乱的 coo 比 hs::csr_from_coo 慢 13%。分段计时表明随机散射占主导
(写两个数组 0.165 s,写成 (列, 值) 对数组 0.100 s);改用对数组可省约 65 ms,但峰值内存每个非零元
多 16 B,因此保留省内存的写法。逐行排序把 std::stable_sort(每次调用分配临时缓冲)换成插入排序:
0.118 → 0.105 s(逆序行),coo 打乱 0.317 → 0.290 s。
端到端(python/bench/overhead.py CASE --mode memory|path,与 CLI 同 guard 设置;「开销」=
solve() 墙钟 − 报告中求解器自身的 time_total_s,两次重复的范围):
| 测例 | n / nnz(A) | CLI 墙钟 / 求解 (s) | 内存输入开销 (s) | 路径输入开销 (s) | 峰值 GiB:CLI / 内存 / 路径 |
|---|---|---|---|---|---|
| cav2d-rect-pert-1e5(GHEP) | 99459 / 0.50M | 0.97 / 0.82 | 0.006–0.013 | 0.056–0.066 | 0.12 / 0.18 / 0.17 |
| wg-square-1e5(GHIEP) | 99225 / 0.37M | 1.97 / 1.83 | 0.010–0.019 | 0.049–0.059 | 0.28 / 0.36 / 0.34 |
| syn-near-singular-complex-1e5(复 HEP) | 100000 / 2.40M | 5.08 / 4.67 | 0.032–0.041 | 0.316–0.344 | 0.40 / 0.50 / 0.46 |
| yee-pec-box-1e5(GHEP) | 109744 / 1.39M | 9.34 / 9.16 | 0.038–0.046 | 0.177–0.191 | 0.71 / 0.78 / 0.76 |
- 内存输入:转换 + 结果交接占求解时间的 0.4–1.6%。路径输入的开销是读 npz(CLI 同样要付)。
- 峰值差:Python 解释器 + numpy/scipy 约 0.07 GiB(
import scipy.sparse, hsolve实测),内存输入另含 scipy 持有的那份矩阵。两次重复的特征值差 ≤ 1e-13(默认非确定性模式,见deterministic)。 - 重复项求和溢出检查(只在有重复项的列上多一次
isfinite)不改变转换耗时:上表的bench_pybind_convert 100 5与修改前的二进制交替各跑 3 次(2026-10-11),各项中位数之比 0.92–1.09, 在本机此时 ±10% 的噪声内(逐行排序 1.00,coo 打乱 0.92)。
load_matrix 返回的矩阵所占内存(python/bench/load_memory.py PATH --mode hsolve|scipy,每种各一个
进程,经 guard,2 核,2026-10-11;读入并 gc 后 RSS 的增长,两次重复;「改前」为 int64 indptr 版本):
| A.npz | n / nnz | 改前 (MiB) | 现在 (MiB) | scipy.sparse.load_npz (MiB) |
三个数组本身 (MiB) |
|---|---|---|---|---|---|
| yee-pec-box-1e5(实) | 109744 / 1.39M | 30.7, 30.7 | 17.0, 18.2 | 18.7, 18.6 | 16.3 |
| syn-near-singular-complex-1e5(复) | 100000 / 2.40M | 66.8, 68.2 | 46.9, 46.9 | 47.1, 47.0 | 46.2 |
| wg-square-1e6(实) | 998001 / 3.74M | 80.6, 80.6 | 48.3, 47.2 | 48.4, 49.5 | 46.6 |
现在与 scipy 自己读文件持平。改前列索引占 12 B/nnz(scipy 拷成的 int64 副本 8 B,加仍被占用的 int32 原件 4 B),现在 4 B/nnz;行指针由每行 8 B 降为 4 B——合计与实测差值一致(如 wg-square-1e6: 3.74M × 8 B + 1e6 × 4 B ≈ 32 MiB)。读入耗时不变(0.06 / 0.37 / 0.15 s)。
9. 限制¶
- 需要显式矩阵(要分解),不接受
LinearOperator。 - 目标模式的支持范围随 driver:B 不定时只支持 nearest;interval / smallest / largest 要求 B 正定或 B = I。
- 完备性检验的方法(
certificate)只能经config设定(无对应关键字参数),见docs/FORMATS.md§2。 - 不同线程中的求解串行执行(见 §6)。