# OpticsFEM 二维到三维扩展工作总结

> 一阶 Nedelec 边元 · 散射问题与本征频率问题仿真  
> 西安电子科技大学 · 合作课题 · 2026年6月

---

## 一、项目背景与目标

原有 **OpticsFEM** 程序基于二维三角形网格与一阶 Nedelec 边元，通过 JSON 配置驱动，支持 FemType 0–3（2D 本征模式、本征频率、散射等）。

**本次工作目标：**

1. 在保持模块化架构（mesh / material / phy / kernel / solver / post）的前提下，扩展至 **三维四面体网格**；
2. 实现 **三维一阶散射问题**（SBC 散射边界条件）的完整 C++ 仿真；
3. 实现 **三维一阶本征频率问题** 的矩阵组装，并与 MATLAB 参考代码数值对齐；
4. 对标 MATLAB 目录：`matlab 3D一阶散射问题`、`matlab 3D一阶本征问题/3D一阶本征问题2`。

**算例模型：** SBC 立方体散射结构，共用网格 `SBCmesh.dat`，双介质 εr = 1.0 / 1.5，参考波长 λ₀ = 0.8 m。

---

## 二、软件架构（OpticsFEM3D）

```
Test_Main.cpp
    └── FEM_Interface.cpp（FemType 路由）
            ├── mesh/Mesh_3D        ← SBCmesh.dat
            ├── material / phy      ← JSON 材料与边界
            ├── kernel              ← 矩阵组装
            ├── solver              ← 求解接口层
            ├── complexsolver.exe   ← 复数稀疏线性求解（散射）
            └── post                ← 电场重构与输出
```

| 构建目录 | 用途 | 配置文件 |
|----------|------|----------|
| `scat3D/` | FemType=4 散射 | `sbc3d.json` |
| `eigen3D/` | FemType=5 本征 | `eigen3d.json` |

---

## 三、二维与三维扩展对照

| 维度 | FemType | 问题类型 | 网格类 | 控制方程 | C++ 状态 |
|------|---------|----------|--------|----------|----------|
| 2D | 0 / 1 | 本征模式 / 频率 | `Mesh_2D` | A·x = λ·B·x | 遗留接口 |
| 2D | 2 / 3 | 散射 | `Mesh_2D` | A·x = b | 遗留接口 |
| **3D** | **4** | **一阶散射 SBC** | **`Mesh_3D`** | **A·x = b** | **完整闭环** |
| **3D** | **5** | **一阶本征频率** | **`Mesh_3D`** | **A·x = λ·B·x** | **组装+导出** |

---

## 四、三维散射问题（FemType = 4）

### 4.1 物理与方程

- 时谐麦克斯韦方程，一阶 Nedelec 边元离散；
- 线性系统：**A·x = b**
  - A = curl-curl 刚度 − k₀²ε 质量项 + SBC 出射边界贡献；
  - b 来自入射边界 assembly_inc。

### 4.2 与 MATLAB 流程对齐

| 步骤 | MATLAB | C++ |
|------|--------|-----|
| 体积分 | `assembly_equ` | `Assemble_WaveEquation` |
| 出射 SBC | `assembly_out` | `Assemble_SBC` |
| 入射激励 | `assembly_inc` | `Assemble_SBC`（入射项） |
| 求解 | `solver.A \ solver.b` | `complexsolver.exe` |
| 后处理 | `get_ele2` | `Post_3D_Scatter::GetElectric` |

### 4.3 主要新增代码

- `kernel/Assemble_Scatter_Equation.cpp` — 3D 四面体体积积分
- `kernel/Assemble_Scatter_3D_Boundary.cpp` — SBC、PEC/ELE 边界
- `kernel/Assemble_kernel.cpp` — `OpticsFEM_3D_Scatter` 总控
- `complex/complexsolver.cpp` — Eigen SparseLU 复数求解器
- `post/Post_CalEletric.cpp` — 3D 电场重构

### 4.4 运行与验证

```powershell
cmake -B scat3D -G "Visual Studio 18 2026" -A x64
cmake --build scat3D --config Release
Copy-Item sbc3d.json, SBCmesh.dat scat3D\Release\
cd scat3D\Release
.\OpticsFEM.exe
```

- 返回码：`OpticsFEM_All returned 4`
- 求解规模：n ≈ 43632，nnz ≈ 696k
- 残差：|r| ≈ 6.2×10⁻¹³（SparseLU）
- 输出：`OutFile/normE`、`Ex`、`Ey`、`Ez`
- 可与 COMSOL 在 z=0.5 m 切面对比（`compare/compare_normE_zslice.m`）

---

## 五、三维本征频率问题（FemType = 5）

### 5.1 物理与方程

- 广义本征问题：**A·x = λ·B·x**
  - A = curl-curl（刚度矩阵）；
  - B = ε 质量矩阵；
  - λ = k₀²，与本征频率相关。

### 5.2 边界条件

- 全 PMC（`BoundaryFlag` 全 0），与 MATLAB `3D一阶本征问题2` 一致。

### 5.3 与 MATLAB 流程对齐

| 步骤 | MATLAB | C++ |
|------|--------|-----|
| 体积分 A/B | `assembly_equ` | `Assemble_WaveEquation` |
| 矩阵导出 | `export_ab_matrix` | `Test_OutputMatrix` |
| 求解 | `eigs(A,B,...)` | **待接入 C++** |
| 后处理 | `get_ele` | **Post_3D_EigenFreq 待实现** |

### 5.4 主要新增代码

- `kernel/Assemble_EigenFreq_Equation.cpp` — 3D A/B 体积分
- `kernel/Assemble_EigenFreq_Boundary.cpp` — PEC/PBC 边界
- `kernel/Assemble_kernel.cpp` — `OpticsFEM_3D_EigenFreq`

### 5.5 运行与验证

```powershell
cmake -B eigen3D -G "Visual Studio 18 2026" -A x64
cmake --build eigen3D --config Release
# Test_Main.cpp 改为读取 eigen3d.json 后重新编译
Copy-Item eigen3d.json, SBCmesh.dat eigen3D\Release\
cd eigen3D\Release
.\OpticsFEM.exe
```

- 返回码：`OpticsFEM_All returned 5`
- 输出：`OutFile/Ai,Aj,Av`、`Bi,Bj,Bv`（COO 格式，0-based）
- **验证结果：** C++ 导出的 `Av.txt` 等与 MATLAB `OutFile` **逐行一致**（约 1.29×10⁶ 非零元）

---

## 六、求解器体系

| 组件 | 角色 |
|------|------|
| `solver/Solver_Interface.cpp` | 上层 C++ 类（Solver_LdaDom 等） |
| `solver/interface.cpp` | 矩阵 ↔ .dat 文件 ↔ 启动外部 exe |
| `complex/complexsolver.exe` | **散射实际数值求解**（Eigen SparseLU） |
| `solver/eigen_solver.cpp` | 2D 本征外部求解器桥接（仓库未含二进制） |
| MATLAB `eigs` | 3D 本征当前验证与求解手段 |

---

## 七、完成情况汇总

### 已完成

| 项目 | 散射 (FemType=4) | 本征 (FemType=5) |
|------|----------------|------------------|
| 3D 网格读取 | ✅ Mesh_3D + SBCmesh.dat | ✅ |
| 体积分组装 | ✅ | ✅ A + B |
| 边界处理 | ✅ SBC + PEC | ✅ PMC |
| 线性/本征求解 | ✅ complexsolver | ⚠️ MATLAB eigs |
| 后处理输出 | ✅ normE/Ex/Ey/Ez | ⚠️ 仅矩阵导出 |
| 文档与构建 | ✅ README + scat3D | ✅ eigen3D |
| 数值验证 | ✅ 残差 + COMSOL 脚本 | ✅ 矩阵与 MATLAB 一致 |

### 待完成

- FemType=5：`Run()` 接入 `Solver_EigenFreq`，`Post_3D_EigenFreq` 场重构
- PBC、二阶基、更多边界类型（MATLAB 中已有，C++ 待扩展）
- `Test_Main.cpp` 支持命令行指定 JSON，避免每次改代码重编译

---

## 八、总结

本次工作将 OpticsFEM 从 **2D 一阶边元** 成功扩展至 **3D 四面体一阶 Nedelec**，新增 FemType **4（散射）** 与 **5（本征频率）**：

1. **散射问题** 已实现 C++ 端到端仿真（组装 → complexsolver → 后处理），数值可靠；
2. **本征问题** 已完成与 MATLAB 严格对齐的 **A/B 矩阵组装与导出**，为后续 C++ 本征求解器接入打下基础；
3. 工程上采用 **双构建目录**、**CMake 集成 complexsolver**、完整 README 与 COMSOL 对比工具，便于协作与验收。

---

*配套 PPT：`OpticsFEM_2D_to_3D_Summary.pptx`（同目录，运行 `python generate_summary_ppt.py` 可重新生成）*