# comac-eigensolver

**Repository Path**: wangyue2006/comac-eigensolver

## Basic Information

- **Project Name**: comac-eigensolver
- **Description**: 2026 上海开源软件应用创新大赛 · AI+工业软件赛道 · 中国商飞赛题作品：面向电磁谐振与微波器件仿真的高效、稳定稀疏特征值求解方案——十万阶非正定厄密稀疏矩阵的 shift-invert + 自适应位移求解器（Python，42 项单测，E1~E5 实验数据可复跑）
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-12
- **Last Updated**: 2026-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# comac-eigensolver

> 仓库地址：<https://gitee.com/wangyue2006/comac-eigensolver>

面向电磁谐振与微波器件仿真的**高效、稳定稀疏厄密特征值求解方案**
（2026 上海开源大赛 · AI+工业软件赛道 · 中国商飞命题）。

针对**十万阶非正定/不定厄密稀疏矩阵**的目标频段特征对求解，
统一组织矩阵读取、预处理、核心迭代、收敛控制与结果输出。

## 安装

```bash
# Python >= 3.10, numpy >= 1.24, scipy >= 1.11
python3 -m pip install --user -e .        # 或 pip install -e .
python3 -m pytest tests/ -q               # 42 项单测
```

多线程：底层 BLAS（OpenBLAS/MKL）由 `OPENBLAS_NUM_THREADS` / `OMP_NUM_THREADS` /
`MKL_NUM_THREADS` 控制；SuperLU 分解在 scipy 中为单线程（见实验报告 E5）。

GPU：已在 Tesla V100 (sm_70, cupy 14.2.0) 完成 GPU 加速实测（《GPU实验报告.md》）：
纯稀疏(块)矩阵乘吞吐收益显著（n≥10⁵ 块乘 **21–46×**，无预条件块迭代 2.3–6.7×），
但 cuSOLVER 稀疏 LU 分解/回代不敌单线程 SuperLU（块回代慢 3.5×），且 cupy `eigsh`
无 `sigma`/`OPinv` —— **位移反演主路径保持 CPU 是当前实测最优**，GPU 结构性机会在
纯 matvec 型算法（多项式/Chebyshev 滤波预条件），属后续方向。

## 命令行用法

```bash
# 1) 生成 2D FDFD TMz 电磁谐振腔矩阵（n = nx*ny，非正定厄密，nnz≈5n）
comac-gen fdfd --nx 316 --ny 316 --shift 25 \
    --defect 0.4 0.4 0.6 0.6 12.0 -o cavity_1e5.npz

# 2) 求目标频段 σ=0 附近 k=10 个特征对（shift-invert + 自适应位移）
comac-eigensolve cavity_1e5.npz --k 10 --sigma 0 --tol 1e-9 -o result.json

# 3) 生成可控谱随机矩阵（簇聚在目标频段，可钉一个 σ 处精确特征值）
comac-gen random --n 5000 --cluster-sigma 100 --cluster-k 6 \
    --pin-value 100 -o pin.npz
comac-eigensolve pin.npz --k 6 --sigma 100 --tol 1e-10 -o res.json

# 对照模式
comac-eigensolve A.npz --mode normal  --band smallest --k 10   # ARPACK 直接迭代
comac-eigensolve A.npz --mode lobpcg  --band smallest --k 10   # LOBPCG 对照

# 三角存储（约省一半存储；残差/normal 模式全程无需恢复完整矩阵）
comac-gen fdfd --nx 224 --ny 224 -o A.npz --triangle
comac-eigensolve A.npz --keep-triangle --k 10 --sigma 0
```

Python API：

```python
from comac_eigensolver import fdfd_tm_resonator, SolveOptions, solve_eigenproblem

A, meta = fdfd_tm_resonator(316, 316, shift=25.0,
                            defect={"x0": .4, "y0": .4, "x1": .6, "y1": .6, "eps_r": 12.0})
res = solve_eigenproblem(A, SolveOptions(k=10, sigma=0.0, tol=1e-9))
print(res.max_residual, res.wall_time_s, res.sigmas_tried)
```

## 输出规范（JSON）

`problem`（n/nnz/厄密偏差/是否三角存储）· `options` · `result`
（converged、eigenvalues、**residuals = ‖Ax−λx‖/‖x‖**、算子应用计数、
factor/iterate/wall 耗时）· `adaptive`（sigmas_tried、触发事件明细）·
`resources`（峰值 RSS=ru_maxrss、tracemalloc 峰值）· `environment`。
返回码：0 成功；3 残差未达标；4 输入/求解错误。

## 与命题要求的对应

| 命题要求 | 本实现 | 代码位置 |
|---|---|---|
| 1. numpy/scipy 输入、高效稀疏存储、按需恢复三角/完整 | `.npz`(完整/三角)/`.mtx` 读取；CSR 存储；`TriangleHermitian` 三角视图：matvec/残差不恢复完整矩阵，仅 shift-invert 分解时按需恢复 `(A−σI)` | `io.py`, `preprocess.py` |
| 2. 适配非正定/不定厄密的 Krylov/现代迭代算法 | ARPACK implicitly-restarted Lanczos（`eigsh`，Krylov-Schur 同族）shift-invert 封装；LOBPCG 对照路径；复厄密支持 | `solver.py` |
| 3. σ 接近特征值 → A−σI 近奇异 → 自适应位移 | 奇异分解捕获（SuperLU "exactly singular"）、回代残差病态检测、残差停滞检测 → 几何级数微调 σ（`shift_delta0`×10^attempt），微调后仍命中目标频段 | `solver.py` `_solve_shift_invert` |
| 4. 收敛性控制 | ARPACK tol 逐级加严（复用 LU）→ 扩 ncv/maxiter → 位移微调；最终以 ‖Ax−λx‖/‖x‖ 验收；电磁谐振模式由 FDFD 模型+目标频段 σ 精确捕获（含跨零谱/缺陷模） | `solver.py`, `matrices.py` |
| 5. 资源性能 | 稀疏全程不稠密化（仅 LU 填充）；三角存储省一半；BLAS 多线程（env 控制）；峰值 RSS/时间随规模实测（实验报告）；**GPU 加速实验**（V100/cupy 实测：块稀疏乘最高 46×，直接法位移反演链路无收益 → 主路径 CPU+多线程为最优组合，报告见《GPU实验报告.md》） | `monitor.py`, `io.py` |

## 包结构

```
comac_eigensolver/
├── io.py          # 读取 .npz/.mtx、三角存储/恢复、TriangleHermitian 视图、厄密校验
├── preprocess.py  # 格式规范化、厄密校验/强制对称化、dtype 优化
├── matrices.py    # 可控谱随机厄密矩阵 + 2D FDFD TMz 谐振腔模型（非正定）
├── solver.py      # eigsh shift-invert 封装、自适应位移、收敛升级链、LOBPCG
├── monitor.py     # 时间 / tracemalloc / ru_maxrss 资源监控
├── output.py      # JSON 报告组装
└── cli.py         # comac-eigensolve / comac-gen 命令行
tests/             # 42 项 pytest：厄密校验、三角往返、残差、频段命中、自适应触发、CLI 端到端
experiments/       # 规模阶梯/模式对比/自适应案例/多线程 实验脚本与真实数据
```

说明：仓库中未提交 `.venv/`、`.pytest_cache/` 与 `experiments/data/` 下的矩阵 npz 与
逐条运行 JSON（体积原因），仅保留汇总 `experiments/data/summary.json`；
全部 E1–E5 实验可本地复跑：`python3 experiments/run_experiments.py`（约 3 分钟，
结果与《实验报告.md》中数字一致）。

## 测试

```bash
python3 -m pytest tests/ -q        # 42 passed
```

覆盖：厄密性校验（strict/average）、三角存取往返与三角 matvec 等价性、
`‖Ax−λx‖/‖x‖` 残差验证、目标频段命中（对照稠密 eigh 参考谱）、
**自适应位移触发**（σ 精确压特征值：singular_factorization 事件、几何步长增长、
关闭自适应则失败）、FDFD 离散谱与解析谱一致、缺陷模下移、CLI 端到端。

## License

Apache-2.0

## 演示视频

[comac-求解器演示（3:55，中文语音解说）](https://www.bilibili.com/video/BV1bPpq6yEcU/)