# OpticsFEM 3D 光学仿真扩展实施计划

> 目标：参照 2D `opticsfem-master` 完整能力，在 `3D opticsfem-master` 中实现全部三维光学问题仿真。  
> 重点：**边界条件** + **本征频率/本征模式**。  
> 验证基准：`三维matlab代码/` 各算例的 JSON + `.dat` + 矩阵/场输出。

---

## 现状摘要（2026-06）

| FemType | 问题 | 2D | 3D C++ |
|---------|------|----|--------|
| 0 | 本征模式 (neff) | ✅ | ❌ 无类 |
| 1 | 本征频率 | ✅ | ⚠️ FemType=5 仅组装+矩阵导出 |
| 2/3 | 散射 | ✅ 全边界 | ⚠️ FemType=4 仅 SBC |
| — | 二阶 Nedelec | — | ❌ MATLAB 有参考 |

3D 散射 DOF：**纯边元**（`NbrEdge`）；2D 散射 DOF：`NbrVertex + NbrEdge`（混合）。

---

## 分阶段计划

### 阶段 0 — 工程基础（并行）

| 序号 | 任务 | 参照 2D | 验证 |
|------|------|---------|------|
| 0.1 | `Test_Main` 支持命令行/环境变量指定 JSON | — | 切换算例无需重编译 |
| 0.2 | 完善 `export_phy_to_json.m`（PBC/PEC 块） | `Test_ReadData.cpp` | JSON 与 C++ 解析一致 |
| 0.3 | 统一 `EnsureOutputDir`、错误码返回 | — | 运行日志可读 |

### 阶段 1 — 本征频率闭环 ⭐ 当前执行

| 序号 | 任务 | 参照 2D 文件 | 验证 |
|------|------|--------------|------|
| 1.1 | `OpticsFEM_3D_EigenFreq::Assemble` 补 P 矩阵投影 `P^T A P` | `Assemble_kernel.cpp` 2D EigenFreq | 与 MATLAB `Av/Bv` 一致（已有） |
| 1.2 | 新增 `Run()` / `Post()` | 2D EigenFreq | `eigen3d.json` + `SBCmesh.dat` |
| 1.3 | `Post_3D_EigenFreq::GetElectric/OutputData` | `Post_3D_Scatter` + 2D EigenFreq | 输出 `freq/Ex/Ey/Ez/normE` |
| 1.4 | `FEM_Interface` FemType=5 完整链路 | FemType=1 | 返回码 5 |

### 阶段 2 — 散射基础边界 ✅ 已完成

| 序号 | 任务 | 参照 2D 文件 | 验证 |
|------|------|--------------|------|
| 2.1 | `Assemble_PEC_ELE()` 3D 实现（边 DOF 消元） | `Assemble_Scatter_2D_Boundary.cpp` | 含 PEC 的散射算例 |
| 2.2 | 接入 `OpticsFEM_3D_Scatter::Assemble()` | 2D Scatter Assemble | — |
| 2.3 | ELE 激励（Dirichlet 边条件） | 2D `Assemble_PEC_ELE` | `ef` JSON 块 |

### 阶段 3 — 周期边界 PBC

| 序号 | 任务 | 参照 | 验证 |
|------|------|------|------|
| 3.1 | `Mesh_3D::GetIndexOfPBC()` 实现 | 2D `Mesh_Find.cpp` | `PBCmesh.dat` |
| 3.2 | 3D 散射 `Assemble_PBC()` | 2D + MATLAB `main_singlePBC.m` | 单周期散射 ✅ |
| 3.3 | 3D 双周期 PBC（散射+本征） | MATLAB `assembly_pbc_double.m` | `doublePBC_scatter.json` ✅ |
| 3.4 | JSON 导出 PBC 块 | `export_phy_to_json.m` | `PBCmesh.json` |

### 阶段 4 — 源项与背景场边界

| 序号 | 任务 | 参照 2D | 验证 |
|------|------|---------|------|
| 4.1 | `Assemble_BELE()` 3D 体积分+ PML 面积分 | `Assemble_Scatter_2D_Boundary.cpp` | bele 类算例 |
| 4.2 | `Assemble_MAG()` | 同上 | mag.json |
| 4.3 | `Assemble_SCD()` | 同上 | scd.json |
| 4.4 | `Assemble_MPD()` / `Assemble_EPD()` | 同上 | mpd/epd.json |
| 4.5 | `Post_GetEb()` 3D 背景场（BELE 后处理） | `Post_GetEb.cpp` | — |

### 阶段 5 — 吸收层与端口

| 序号 | 任务 | 说明 | 验证 |
|------|------|------|------|
| 5.1 | 3D PML 体积分/边界 | 2D PML 拉伸坐标推广到四面体 | pml 算例 |
| 5.2 | 3D Port 散射 | 2D Port 480 行逻辑，3D 面模态 | port 算例 |
| 5.3 | Beam 高斯光束 | 2D beam JSON | — |

### 阶段 6 — 本征模式 & 高阶（扩展）

| 序号 | 任务 | 说明 |
|------|------|------|
| 6.1 | `OpticsFEM_3D_EigenMode` 新类 | 3D 波导 neff，参照 2D EigenMode |
| 6.2 | 二阶 Nedelec 基函数 | 参照 MATLAB `3D二阶基+散射边界条件` |
| 6.3 | 棱柱/四边形边界网格读取 | `Mesh_Interface.cpp` 补全 |

---

## FemType 路由规划（目标态）

| FemType | 问题 | 网格 |
|---------|------|------|
| 0 | 2D 本征模式 | Mesh_2D |
| 1 | 2D 本征频率 | Mesh_2D |
| 2/3 | 2D 散射 | Mesh_2D |
| **4** | **3D 散射** | Mesh_3D |
| **5** | **3D 本征频率** | Mesh_3D |
| **6** | **3D 本征模式**（规划） | Mesh_3D |

---

## 执行顺序与依赖

```
阶段1 本征频率闭环
    ↓
阶段2 PEC/ELE ──→ 阶段3 PBC ──→ 阶段4 BELE/源项
                                    ↓
                              阶段5 PML/Port
                                    ↓
                              阶段6 本征模式/二阶
```

---

## 文档修订

| 版本 | 日期 | 内容 |
|------|------|------|
| v1.0 | 2026-06-18 | 初版计划，启动阶段1 |