# EM Eigensolver

**Repository Path**: cnt-code/em-eigensolver

## Basic Information

- **Project Name**: EM Eigensolver
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-27
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EM Eigensolver — 大规模稀疏厄密非正定特征值求解器

**AI+工业软件赛道 · 中国商飞命题：面向电磁谐振与微波器件仿真的高效、稳定求解方案**

求解有限元（FEM）/矩量法（MoM）离散得到的大规模稀疏厄密**非正定**矩阵特征值问题 `A x = λ x`（十万阶量级）。支持谱内位移（`A − σI` 近奇异）、零附近密集谱（低频击穿）、重特征值（简并模式）等电磁谐振场景的困难情形；全程不稠密化 `n × n` 算子。核心为纯 Python + NumPy，无闭源组件。

## 提交物索引（对照赛题交付要求）

| 赛题交付要求 | 本仓库对应 |
| --- | --- |
| a. 方案说明文档 | `docs/09-电磁谐振特征值求解器.pdf`（`.md` 同源）+ `SOLUTION.md` |
| b. 可运行原型 | `python/`（CLI 入口：`python -m em_eigensolver.cli`，numpy/scipy 格式输入输出） |
| c. 样例数据与基准 | `examples/data/em-cavity-degenerate.mtx` + `bench/em-eigensolver-*.json`（不同谱分布、k、σ 实测） |
| d. 故障场景与验证 | 近奇异位移 / 零附近密集谱 / 重特征值 / 内存受限的处置与验证，见文档第五节与 `bench/` |
| e. 可复现材料 | `python/` + `requirements.txt` + 下方复现步骤 + `repro.json` 复现凭证（`--repro` 生成） |
| f. 演示视频 | B 站：【电磁谐振特征值求解器（EM Eigensolver）：多算法引擎的 Web 集成方案】`https://www.bilibili.com/video/BV1Wqau6DEmg/` |

## 演示与可视化

![求解完成后的 2D 求解报告（内置简并示例，稠密直解路径）](docs/assets/screenshots/plugins/em-eigensolver/solve-report.png)

![3D 模式场：内置简并示例的第 4 个模式](docs/assets/screenshots/plugins/em-eigensolver/mode3d-degenerate.png)

演示视频（B 站）：[【电磁谐振特征值求解器（EM Eigensolver）：多算法引擎的 Web 集成方案】](https://www.bilibili.com/video/BV1Wqau6DEmg/)

## 关键验证结果

来源：`bench/em-eigensolver-results.json`（2026-09-25 实测，8 线程 CPython + scipy 1.15.3）。

| 场景 | 实测结果 |
| --- | --- |
| 十万阶极端特征值（`cavity_large`，n=102400，nnz=510720，厚重启 Lanczos） | 相对残差 **4.28e-09 ≤ 1e-8**；25 外迭代、1207 matvec；**25.15 s**；峰值内存 **57.4 MB** |
| 十万阶谱内位移（σ=0.5，位移逆 Lanczos） | 相对残差 **7.39e-06 ≤ 2e-5**（位移逆路径的有效容差下限，见文档 §8.3）；9 轮收敛 |
| 行块多线程 matvec（8 线程） | 十万阶加速 **1.41×**（3.79 ms → 2.68 ms/次） |
| 规模扫描 | grid-32×32 → 320×320（n=1024 → 102400）全部收敛，残差均 ≤ 1e-8 量级 |
| 对抗基准与压力测试 | `bench/em-eigensolver-validate.json`（对照稠密 LAPACK）、`stress.json`、`block-matvec.json` |

## 快速复现（纯 Python）

```bash
pip install -r python/requirements.txt

cd python                                 # 内核包在 python/ 下，以下命令均从该目录运行
python tests/test_all.py                  # 26 项测试：csr / IO / MINRES / 三内核（对照稠密 LAPACK）/ 样例 / 门面 / CLI
python -m em_eigensolver.cli --sample cavity_small --k 6                # 内置样例求解
python -m em_eigensolver.cli --input ../examples/data/em-cavity-degenerate.mtx --k 6   # 外部矩阵（.mtx/.npz/.npy）
```

生成复现凭证（矩阵 SHA-256 指纹 + 参数哈希 + 代码快照 + 结果摘要）：

```bash
cd python
python -m em_eigensolver.cli --sample cavity_large --k 6 --repro ../repro.json
```

## 核心机制（摘要）

- **三个迭代内核 + 受控直解兜底**：厚重启 Lanczos（Krylov-Schur，保留 k 个 Ritz 向量+末向量）、块 LOBPCG（`span{X,R,P}` 三块 Rayleigh-Ritz）、Jacobi-Davidson（投影校正方程 + 收缩锁定）；`n ≤ dense_threshold`（默认 800）小问题走 `numpy.linalg.eigh` 直解，**受控且有硬上界**
- **非正定处理**：不定系统由 MINRES 解 `(A − σI)⁻¹`（无需预条件化分解）；自适应位移策略（内层速率触发、步长倍增、轨迹记录）规避近奇异位移
- **重特征值**：块迭代 + JD 收缩双重判据，`degenerate_pair` 样例每个特征值至少二重
- **零附近密集谱**：`cluster_zero` 样例 720 阶中 153 个 `|λ| < 0.05`，默认位移恰好落在谱内部
- **真实残差认证**：每个周期用真实 matvec 重算 `‖Ay − λy‖/max|λ|`，全部小于容差才算收敛
- **从不稠密化**：`n × n` 算子恒保持稀疏；唯一稠密分解作用于 ≤ `basis_dim` 的投影矩阵；稠密输入即刻稀疏化且有 `n² ≤ 4×10⁶` 护栏
- **无硬编码**：所有阈值均为配置字段；结果经独立复现凭证可审计

## 独立参赛声明

本项目为独立参赛作品（中国商飞电磁命题）。本文档与 `SOLUTION.md`、`docs/09-电磁谐振特征值求解器.pdf`（`.md` 同源）共同构成方案交付物；`python/` 目录下的求解内核**自包含**（numpy 必需、scipy 可选），可直接独立运行与复现，浏览器结果与 CLI 结果一致。本仓库与其他赛题提交无重复投递关系。

- 仓库：`https://gitee.com/cnt-code/em-eigensolver`

## 目录结构

```
├── SOLUTION.md                 # 插件方案说明
├── docs/                       # 提交用方案文档（PDF + md 同源）
│   └── 09-电磁谐振特征值求解器.pdf / .md
├── bench/                      # 实测结果归档（4 个 JSON）
│   ├── em-eigensolver-results.json
│   ├── em-eigensolver-validate.json
│   ├── em-eigensolver-stress.json
│   └── em-eigensolver-block-matvec.json
├── examples/data/              # 样例矩阵
│   └── em-cavity-degenerate.mtx   # 600×600 块对角重特征值结构
└── python/                     # 自包含求解内核
    ├── em_eigensolver/         # 包：csr / io_matrix / minres / lanczos / lobpcg / jacdavid / solver / samples / sweep / repro / cli / driver / backend
    ├── tests/test_all.py       # 26 项测试
    ├── benchmarks/             # perf_bench.py + validate_correctness.py
    ├── config.example.json
    └── requirements.txt        # numpy（必需）+ scipy（可选）
```

## 许可

MIT。详见根目录 `LICENSE`。