安装与运行¶
hsolve 在任何 x86-64 Linux 上几分钟内就能跑起来。三种方式任选其一,每种不超过三条命令:
| 方式 | 适合 | 需要 | 得到 |
|---|---|---|---|
| 容器镜像 | 先看效果;Windows(Docker Desktop) | Docker | 命令行、Python 模块、示例与演示 |
| 二进制包 | 服务器、无 root、离线机器 | glibc ≥ 2.17 的 Linux(CentOS 7 及之后) | 同上,解压即用 |
| 从源码构建 | 开发、修改代码、跑测试 | conda 或 micromamba,能访问 conda-forge | 同上,外加测试与基准工具 |
装好后用自检确认结果正确,再按资源需求估计自己的问题需要多少内存和时间。
1. 容器镜像¶
依次求解 examples/ 的 6 个示例(重特征值、σ 贴近特征值、低频零空间、B 不定的 50 GHz 方波导、复厄密 Bloch
胞元、区间切片),每个结果由独立评测器从原矩阵重算残差、对照参考谱检查漏解,最后打印汇总表。
求解自己的矩阵:把所在目录挂到容器的 /work(-u 让输出文件属于自己):
docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/seuclkzsd/hsolve \
--A A.npz --B B.npz --sigma -0.5 --k 18 --out result
- 入口参数:
demo(全部示例)、selfcheck(两个小示例,见自检)、bash/python3(容器内的 shell 或带hsolve、numpy、scipy 的 Python),其余参数原样交给hsolve命令行;不带参数显示hsolve --help。 - 标签:
1.0.0这样的版本号、1.0(该系列最新)、latest(最新正式版)。镜像由.github/workflows/release.yml在发布时构建,先跑完自检与全部示例才推送。 - 本地构建:在源码目录
docker build -t hsolve .(Dockerfile:conda-forge 工具链编译、打包, 运行层只含二进制包与 Python、numpy、scipy,以普通用户运行)。 - 线程数:默认用容器能用的全部 CPU;用
docker run --cpus N限制容器时,同时给hsolve加--threads N。
2. 二进制包¶
curl -LO https://github.com/seuclkzsd/hsolve/releases/download/v1.0.0/hsolve-1.0.0-linux-x86_64.tar.gz
tar -xzf hsolve-1.0.0-linux-x86_64.tar.gz
hsolve-1.0.0-linux-x86_64/scripts/demo.sh --quick
版本号以 Releases 页为准;同页的 SHA256SUMS 用
sha256sum -c SHA256SUMS 校验下载(在下载目录里运行;该文件只列这一个包)。
包可以放在任意目录、由任意用户使用:bin/hsolve 通过 $ORIGIN 相对路径找到 lib/ 里随包的 MUMPS 5.8.2(含本项目
补丁)、OpenBLAS、METIS、SCOTCH 与 GCC 运行库,不需要 conda、编译器、root 或 LD_LIBRARY_PATH。指令集只要求 x86-64
基线,SIMD 内核运行时按 CPUID 选择(AVX-512 / AVX2 / 通用,见第 6 节)。
| 路径 | 内容 |
|---|---|
bin/hsolve |
命令行求解器(bin/hsolve --help,格式见 FORMATS.md) |
python/hsolve/ |
Python 模块:PYTHONPATH=<包目录>/python python3 -c "import hsolve",需 CPython 3.11 与 numpy(PYTHON.md) |
examples/、scripts/、tools/ |
6 个示例与参考谱、演示脚本、独立评测器 |
licenses/、LICENSE、NOTICE、THIRD_PARTY_NOTICES |
hsolve(Apache-2.0)与随包第三方库的许可证;licenses/THIRD_PARTY_BINARIES.md 逐个列出库的来源、版本与许可证 |
BUILD-INFO.txt |
提交号、编译器与选项、所需最低 glibc、打包时的冒烟测试结果 |
每个发布包在打包时都经过检查:没有 glibc 2.17 以后的符号、hsolve 自身代码里没有未经 CPUID 分派的 AVX 指令、
从别的目录以空环境解压后能求解;发布前还在 CentOS 7、Debian 12、Ubuntu 24.04 的干净容器里跑一遍自检
(tools/release/verify_package.sh)。
3. 从源码构建¶
git clone https://github.com/seuclkzsd/hsolve.git && cd hsolve
conda env create -f env/environment.yml # 或 micromamba create -f env/environment.yml
source env/activate.sh && tools/dev/build.sh && scripts/demo.sh --quick
- 依赖全部来自 conda-forge(
env/environment.yml:GCC 13、CMake、Python 3.11、numpy、 scipy、OpenBLAS、METIS、SCOTCH、pybind11 等,版本固定);MUMPS 5.8.2 由仓库自带的官方源码包third_party/mumps/打上patches/的补丁后编译(第一次约 2 分钟,之后按输入哈希复用)。 tools/dev/build.sh默认构建release预设:可移植的 x86-64 基线,产物在build/release/(命令行hsolve、Python 模块build/release/python/hsolve)。tools/dev/build.sh native为本机指令集编译 (-march=native),产物只能在同代 CPU 上运行;debug预设带 ASan / UBSan。- 测试:
tools/dev/test.sh(C++ 单元测试 ctest + Python 测试 pytest)。持续集成的完整流水线是tools/dev/ci.sh,本地运行与 GitHub Actions 上一致:MUMPS、-Werror构建、指令集检查、 ctest(AVX-512 与模拟的 AVX2 两级)、pytest、示例校验、演示、打包;tools/dev/ci_clone.sh DIR在全新克隆里跑一遍。 - 打包:
tools/release/package.sh生成第 2 节的二进制包(build/package/)。 env/activate.sh也设置资源策略:tools/run/guard.py把构建和测试限制在HS_CORES指定的 CPU 与HS_MEM_GB的内存内(默认:当前 shell 可用的全部 CPU、30 GiB)。
4. 自检¶
| 安装方式 | 命令 |
|---|---|
| 容器镜像 | docker run --rm ghcr.io/seuclkzsd/hsolve selfcheck |
| 二进制包 | hsolve-<版本>-linux-x86_64/scripts/demo.sh --quick |
| 源码构建 | scripts/demo.sh --quick |
自检求解两个小示例——B 不定的 50 GHz 方波导(GHIEP,18 个传播模)与位移距特征值仅 1e-12 的近奇异问题,用独立 评测器复核,再调用一次 Python 接口。正常输出的结尾如下,退出码为 0:
case n problem target found certificate max eta time s check
------------------- ---- ------- ----------------------- ----- ---------------- ------- ------ ---------------
waveguide-50ghz 289 GHIEP nearest 18 to -0.501305 18 - 3.0e-14 0.01 pass (complete)
near-singular-shift 2000 HEP nearest 10 to 0.300198 10 exact pass 10/10 5.7e-12 0.11 pass (complete)
Python API: pass (ok <版本号>)
time s 一列随机器而变(上面是 2 线程的结果);max eta 是从原矩阵重算的最大后向误差(容差 1e-10);check
为 pass (complete) 表示没有漏解与虚报;certificate 是 Sylvester 惯性计数证书(B 不定时不适用,显示 -)。
去掉 --quick 跑全部 6 个示例。独立复核需要 Python 3 与 numpy、scipy;没有时脚本只运行求解器并显示其自身的报告
(success=yes 与证书结论)。
5. 资源需求¶
主要开销是稀疏 LDLᵀ 分解(MUMPS):三维问题的填充远多于二维,内存与时间随规模增长得也快得多。下表是两类典型 电磁问题在 10⁴、10⁵、10⁶ 阶上的实测值,第二张表是 10⁶ 阶问题在较小内存上限下的表现。
| 问题 | n | 非零元 | 峰值内存 | 求解时间,16 线程 | 求解时间,4 线程 | 惯性证书 |
|---|---|---|---|---|---|---|
三维 PEC 谐振腔,GHEP,最近 σ 的 11 个(yee-pec-box-1e4) |
10,064 | 132,808 | 97 MiB | 0.29 s | 0.19 s | 通过 |
三维 PEC 谐振腔,GHEP,最近 σ 的 10 个(yee-pec-box-1e5) |
109,744 | 1,496,184 | 784 MiB | 2.35 s | 3.55 s | 通过 |
三维 PEC 谐振腔,GHEP,最近 σ 的 10 个(yee-pec-box-1e6) |
1,027,733 | 14,208,570 | 11.4 GiB | 66 s | 122 s | 通过 |
二维方波导 50 GHz,GHIEP(B 不定),18 个传播模(wg-square-1e4) |
9,801 | 138,521 | 63 MiB | 0.09 s | 0.09 s | 不适用(B 不定) |
二维方波导 50 GHz,GHIEP(B 不定),18 个传播模(wg-square-1e5) |
99,225 | 1,419,337 | 313 MiB | 0.48 s | 0.64 s | 不适用(B 不定) |
二维方波导 50 GHz,GHIEP(B 不定),18 个传播模(wg-square-1e6) |
998,001 | 14,306,465 | 1.9 GiB | 5.35 s | 7.39 s | 不适用(B 不定) |
| 问题 | 内存上限 | 线程 | 分解方式 | 峰值内存 | 求解时间 |
|---|---|---|---|---|---|
yee-pec-box-1e6 |
8 GiB | 16 | 外存 | 5.9 GiB | 122 s |
yee-pec-box-1e6 |
8 GiB | 4 | 外存 | 5.6 GiB | 175 s |
yee-pec-box-1e6 |
4 GiB | 16 | 拒绝运行(out_of_memory_budget) |
1.1 GiB | - |
yee-pec-box-1e6 |
4 GiB | 4 | 拒绝运行(out_of_memory_budget) |
859 MiB | - |
wg-square-1e6 |
8 GiB | 16 | 内存内 | 1.9 GiB | 5.35 s |
wg-square-1e6 |
8 GiB | 4 | 内存内 | 1.8 GiB | 7.38 s |
wg-square-1e6 |
4 GiB | 16 | 内存内 | 1.9 GiB | 5.34 s |
wg-square-1e6 |
4 GiB | 4 | 内存内 | 1.8 GiB | 7.38 s |
测试条件:2 × Intel Xeon Silver 4314(Ice Lake-SP,2.4 GHz,AVX-512),CentOS 7.9;hsolve 1.0.0 默认的可移植构建,
默认配置(只用算例自带的 config.json),结构识别快速路径关闭:每份报告的 candidate_source 都是 iterative
(通用的位移反演路径);16 线程绑在一个 NUMA 节点的 16 个物理核上,4 线程绑其中 4 个;独占运行;内存上限由
tools/run/guard.py 施加,hsolve 据此自动定内存预算。求解时间是 report.json 的 time_total_s(读入矩阵之后
的全部求解,含残差检查与惯性证书),第一张表取 3 次运行的中位数,第二张表各 1 次;峰值内存是整个进程的峰值 RSS。
算例的生成、全表、原始数据与复现命令见 results/resource-tiers/。
据此可以估计自己的机器:
| 可用内存(进程的上限) | 实测能解的规模 |
|---|---|
| 4 GiB | 10⁶ 阶二维问题(峰值 1.9 GiB);10⁵ 阶三维问题(第一张表中峰值 0.8 GiB;未在 4 GiB 上限下单独运行) |
| 8 GiB | 10⁶ 阶三维问题:自动改用外存分解,峰值 5.9 GiB,16 线程 122 s(内存内为 66 s) |
| 32 GiB | 10⁶ 阶三维问题内存内分解,峰值 11.4 GiB,16 线程 66 s |
线程:10⁵ 阶以上多线程才明显受益(10⁶ 阶三维问题 4 → 16 线程从 122 s 降到 66 s);10⁴ 阶问题 4 线程已经足够。
hsolve 在分析阶段就预估分解所需内存:内存内放不下时改用外存分解,外存也放不下时在分解之前报
out_of_memory_budget 退出(退出码 2)并给出预估值,例如 4 GiB 上限下的 10⁶ 阶三维问题:
hsolve: error [out_of_memory_budget]: predicted factorization memory 13909 MB (out-of-core 4827 MB) exceeds the budget of 1383.26 MB
内存预算的来源与手动指定见常见问题。
6. 可移植构建与本机优化构建¶
二进制包、容器镜像与默认的源码构建都是可移植构建:编译目标是 x86-64 基线,hsolve 手写的 SIMD 内核以函数级
target 属性编译,运行时按 CPUID 选 AVX-512、AVX2 或通用实现;OpenBLAS 同样在运行时选内核。所以同一个二进制
能在任何 x86-64 CPU 上运行,又能在新 CPU 上用满宽向量指令。
- 速度:在 10⁵ 阶算例上与
-march=native构建交替各跑 10 次。走通用路径的 5 个算例上中位时间之比 0.995–1.006, 几何平均 1.000,差别在噪声以内;屏蔽 AVX-512 路径(模拟只有 AVX2 的 CPU)后,同一二进制慢 0–6%(0.995–1.062, 几何平均 1.028)。同批的第 6 个算例 yee-pec-box-1e5 测量时结构识别快速路径还是默认开启,它的运行都走了这条路径 (1.0 默认关闭),不计入这些数字。条件与原始数据见 results/portable-vs-native/。 - 保证:
tools/release/check_isa.py检查构建产物里所有 AVX 类指令都位于运行时分派之后的函数中;CI 每次都做这项 检查,并在 AVX-512 与模拟的 AVX2 两级上各跑一遍全部 C++ 测试。 - 需要只为本机编译时用
tools/dev/build.sh native(-march=native),产物在build/native/,只能在同代 CPU 上运行。
7. 常见问题¶
GLIBC_2.xx not found:系统的 glibc 早于 2.17(CentOS 6 及更早),二进制包与 conda-forge 工具链都不支持, 请用容器镜像。- 容器写不了挂载目录:加
-u "$(id -u):$(id -g)",让容器以当前用户身份运行。 - 线程:
--threads N(0 = 全部可用 CPU)。hsolve 自己设置 OpenMP 线程数;同时设置了OPENBLAS_NUM_THREADS=1会让分解中的稠密运算只用一个线程,变慢。 - 内存:默认预算由 cgroup、
ulimit、HSOLVE_MEMORY_LIMIT_GB与物理内存中最小者推出(约其 85%), 放不下时分解自动转外存;--memory-budget-gb G指定预算,report.json的memory一节记录用了多少、 来自哪个上限(FORMATS.md)。 - Python 模块的版本:二进制包与镜像里的模块为 CPython 3.11 编译;其他 Python 版本请从源码构建。
- 其他平台:Windows 可在 WSL2 里按 Linux 方式安装,或用 Docker Desktop;目前只提供 x86-64 构建。