---
name: 3D光学FEM完整实现
overview: 基于现有2D C++ OpticsFEM代码框架和MATLAB 3D参考实现，修复已有3D代码bug并补全所有缺失模块，输出一个商用级别的三维C++光学有限元程序（含本征频率、本征模式、散射三大问题类型），同时产出完整的API定义文档和示例JSON文件。
todos:
  - id: fix-3d-bugs
    content: 修复3D Jacobian矩阵、材料域查询、invMur等关键Bug
    status: pending
  - id: mesh-3d-reader
    content: 实现Mesh_3D::GetMesh() JSON格式3D网格读取器
    status: pending
  - id: eigenfreq-3d
    content: 完善3D本征频率：PEC/PBC边界处理、Run()、Post()
    status: pending
  - id: eigenmode-3d
    content: 新增3D本征模式类（OpticsFEM_3D_EigenMode）完整实现
    status: pending
  - id: scatter-3d-sbc
    content: 实现3D SBC散射边界积分（参考MATLAB assembly_out/inc）
    status: pending
  - id: scatter-3d-bc
    content: 实现3D PEC/PBC/PML/BELE/MAG/SCD/MPD/EPD边界和激励
    status: pending
  - id: scatter-3d-run-post
    content: 实现3D Scatter的Run()和Post()（电场插值+输出）
    status: pending
  - id: api-3d-routing
    content: 扩展FEM_Interface增加3D路由和JSON参数解析
    status: pending
  - id: post-3d
    content: 实现3D后处理：边DOF到顶点电场插值、功率计算、文件输出
    status: pending
  - id: second-order
    content: 实现二阶Nedelec基函数（20 DOF/四面体）和对应组装
    status: pending
  - id: api-doc-json
    content: 编写API定义文档和3个问题类型的示例JSON文件
    status: pending
  - id: validation
    content: 与MATLAB 3D结果对比验证，修正数值问题
    status: pending
isProject: false
---

# 三维C++光学有限元完整实现方案

## 一、现状分析

### 已有基础（可复用）

- 2D完整程序：EigenMode / EigenFreq / Scatter，含完整API、JSON输入、后处理输出
- 3D类骨架已定义：`OpticsFEM_3D_EigenFreq`、`OpticsFEM_3D_Scatter`、`OpticsFEM_3D_Scatter2`（[Assemble_Base.h](opticsfem-master/kernel/Assemble_Base.h) L157-261）
- 3D网格数据结构：`Mesh_3D` 支持四面体+棱柱（[Mesh_Base.h](opticsfem-master/mesh/Mesh_Base.h) L61-128）
- 3D基函数：一阶Nedelec四面体(6 DOF)和棱柱(9 DOF)已实现（[BF_Tetrahedron.cpp](opticsfem-master/function/BF_Tetrahedron.cpp)、[BF_Prism.cpp](opticsfem-master/function/BF_Prism.cpp)）
- 3D体积方程组装：EigenFreq和Scatter的WaveEquation已实现（[Assemble_EigenFreq_Equation.cpp](opticsfem-master/kernel/Assemble_EigenFreq_Equation.cpp) L229-345、[Assemble_Scatter_Equation.cpp](opticsfem-master/kernel/Assemble_Scatter_Equation.cpp) L284-573）
- 3D高斯积分：四面体和棱柱积分点已有

### 必须修复的Bug

1. **Jacobian矩阵错误**：3D EigenFreq/Scatter的Jac计算用了2D模式（z分量硬编码0/1），应为完整3x3:

```cpp
// 当前错误写法 (Assemble_EigenFreq_Equation.cpp L269-271):
Jac(0, 2) = 0.; Jac(1, 2) = 0.; Jac(2, 2) = 1.;

// 正确写法（参考MATLAB）:
Jac(0, 0) = vertex[0](0)-vertex[3](0); Jac(0, 1) = vertex[0](1)-vertex[3](1); Jac(0, 2) = vertex[0](2)-vertex[3](2);
Jac(1, 0) = vertex[1](0)-vertex[3](0); Jac(1, 1) = vertex[1](1)-vertex[3](1); Jac(1, 2) = vertex[1](2)-vertex[3](2);
Jac(2, 0) = vertex[2](0)-vertex[3](0); Jac(2, 1) = vertex[2](1)-vertex[3](1); Jac(2, 2) = vertex[2](2)-vertex[3](2);
```

1. **材料域查询错误**：3D组装中调用 `GetDomainOfTri(n)` 应改为 `GetDomainOfTet(n)`
2. **EigenFreq中 `GetEpsr` 误用为 `invMur`**：L291 `invMur = GetEpsr(domain).inverse()` 应为 `GetMur(domain).inverse()`

### 需要新增的模块

- 3D网格文件读取器（JSON格式）
- 3D EigenMode（本征模式/有效折射率）
- 3D SBC散射边界组装
- 3D PEC/PBC/PML边界条件
- 3D BELE/MAG/SCD/MPD/EPD激励源
- 3D Port端口边界
- 3D求解器集成（Run方法）
- 3D后处理（电场插值、输出）
- 3D API路由和JSON接口
- 二阶Nedelec基函数（可选增强）

---

## 二、架构设计

### 整体架构（对标2D，扩展到3D）

```mermaid
flowchart TB
    subgraph API [API层]
        APIEntry["OpticsFEM_API::OpticsFEM_All()"]
        JSONParser["JSON解析"]
    end
    
    subgraph FEM3D [3D FEM核心]
        EM3D["OpticsFEM_3D_EigenMode"]
        EF3D["OpticsFEM_3D_EigenFreq"]
        SC3D["OpticsFEM_3D_Scatter"]
    end
    
    subgraph Modules [功能模块]
        Mesh3D["Mesh_3D\n四面体+棱柱"]
        Mat["MaterialLib\n各向同性/n-k/各向异性"]
        Phy["Phy_WaveOpticsModel\nPEC/PMC/PBC/SBC/PML/Port"]
        BF["BF 基函数\n一阶/二阶Nedelec"]
        Gauss["Gauss积分\n四面体/三角形/棱柱"]
    end
    
    subgraph Solver [求解器]
        EigenSolver["Solver_EigenMode\nSolver_EigenFreq"]
        LinearSolver["Solver_LdaDom"]
    end
    
    subgraph Post [后处理]
        Post3DEF["Post_3D_EigenFreq"]
        Post3DEM["Post_3D_EigenMode"]
        Post3DSC["Post_3D_Scatter"]
    end
    
    APIEntry --> JSONParser
    JSONParser --> FEM3D
    FEM3D --> Modules
    FEM3D --> Solver
    FEM3D --> Post
```



### 3D DOF编号方案

- **一阶Nedelec**：DOF = NbrEdge（每条边1个DOF）
- **二阶Nedelec**（后续扩展）：DOF = 2*NbrEdge + 2*NbrFace
- 无顶点DOF（纯矢量FEM，区别于2D的Lagrange+Nedelec混合）

### 3D网格JSON格式设计

```json
{
  "NbrVertex": 100,
  "Vertex": [[x1,y1,z1], [x2,y2,z2], ...],
  "NbrEdge": 500,
  "Edge": [[v1,v2], ...],
  "NbrTet": 300,
  "Tet": [[v1,v2,v3,v4], ...],
  "EdgeOfTet": [[e1,e2,e3,e4,e5,e6], ...],
  "DomainOfTet": [1, 2, ...],
  "NbrTri": 200,
  "Tri": [[v1,v2,v3], ...],
  "DomainOfTri": [1, 2, ...],
  "ConnOfTri": [[meshType, tetIdx, faceIdx], ...],
  "NormOfFace": [[nx,ny,nz], ...],
  "CopyOfEdges": [[src, dst], ...],
  "FaceOfTet": [[f1,f2,f3,f4], ...]
}
```

### 3D FEM设置JSON格式设计

```json
{
  "FemType": 4,
  "Dimension": 3,
  "NbrDomain": 3,
  "matType": [0, 0, 1],
  "epsilonrR": [1.0, 2.25, 0], "epsilonrI": [0, 0, 0],
  "murR": [1.0, 1.0, 0], "murI": [0, 0, 0],
  "n": [0, 0, 1.5], "k": [0, 0, 0],
  "sigma": [0, 0, 0],
  "NbrBoundary": 3,
  "BoundaryFlag": [1, 0, 2],
  "lambda": 1.55e-6,
  "MeshFile": "mesh_3d.json",
  "OutFile": "result/",
  "NbrMode": 5,
  "searchType": 0,
  "searchValue": 1.45,
  "solverType": 0,
  "ElementOrder": 1,
  "sbc": { "SBCType": 0, "Index": [2], "E0x": "1", "E0y": "0", "E0z": "0", "kx": "0", "ky": "0", "kz": "k0" },
  "pbc": { "srcIndex": [3], "dstIndex": [4], "phiR": [1.0], "phiI": [0.0] },
  "pml": { "index": [5], "PMLType": 0, "PMLData": [0,1e-6,0,1e-6,0,1e-6] }
}
```

---

## 三、分阶段实施计划

### 阶段1：修复Bug + 基础设施（1-2天）

- 修复3D Jacobian矩阵（EigenFreq和Scatter的WaveEquation）
- 修复材料域查询（`GetDomainOfTri` -> `GetDomainOfTet`）
- 修复 `invMur = GetEpsr().inverse()` -> `GetMur().inverse()`
- 实现 `Mesh_3D::GetMesh()` 从JSON读取3D网格
- 补全3D EigenFreq稀疏矩阵尺寸初始化

### 阶段2：3D本征频率完善（2-3天）

- 完善 `OpticsFEM_3D_EigenFreq::Assemble()` -- PEC/PBC约束矩阵P构建
- 实现 `OpticsFEM_3D_EigenFreq::Run()` -- 调用本征值求解器
- 实现 `Post_3D_EigenFreq` -- 3D电场插值（边DOF到顶点）、输出

### 阶段3：3D本征模式新增（2-3天）

- 新增 `OpticsFEM_3D_EigenMode` 类（类比2D EigenMode，但纯矢量FEM）
- 实现3D本征模式方程组装（A-lambda*B形式）
- 实现Run和Post
- 支持搜索有效折射率

### 阶段4：3D散射问题完善（3-5天）

- 实现 `OpticsFEM_3D_Scatter::Assemble_SBC()` -- 参考MATLAB的 `assembly_out.m` 和 `assembly_inc.m`
  - 三角面上的边界积分：`ik0*n * N_i . (n_hat x (n_hat x N_j))`
  - 入射场右端向量
- 实现 `OpticsFEM_3D_Scatter::Assemble_PEC_ELE()` -- 构建约束矩阵P
- 实现 `OpticsFEM_3D_Scatter::Assemble_PBC()` -- 参考MATLAB的 `assembly_pbc_double.m`
- 实现BELE/MAG/SCD/MPD/EPD激励
- 实现PML（3D各向异性坐标拉伸）
- 实现 `Run()` 和 `Post()`

### 阶段5：API接口+JSON（1-2天）

- 扩展 `FEM_Interface.cpp` 增加3D路由（FemType=4/5/6 对应3D EigenMode/EigenFreq/Scatter，或用 Dimension 字段区分）
- 扩展 `Test_ReadData.cpp` 支持3D特有参数（ElementOrder、3D PML数据等）
- 编写3D网格JSON格式规范
- 编写3D FEM设置JSON格式规范
- 提供3D示例JSON（本征频率、本征模式、散射各一个）

### 阶段6：商用增强（3-5天）

- 二阶Nedelec基函数实现（20 DOF/四面体：12边+8面）
- Port端口边界条件（2D本征模式 + 3D耦合）
- 性能优化：稀疏矩阵预分配、OpenMP并行组装
- 错误处理与日志
- 内存管理改进（替换裸指针为智能指针/RAII）
- 波长扫描支持

### 阶段7：验证与文档（2-3天）

- 与MATLAB结果对比验证（本征频率、散射场）
- API定义文档输出（Markdown格式）
- 示例JSON文件（覆盖全部问题类型和边界条件组合）
- README更新

---

## 四、关键技术要点

### 3D SBC边界积分（参考MATLAB assembly_out.m）

- 在三角面上积分，使用2D Gauss积分点
- 基函数需要从四面体边DOF映射到三角面上
- 通过 `ConnOfTri` 找到所属四面体和面号
- 面上的Nedelec基函数通过参考坐标映射

### 3D PBC周期边界（参考MATLAB assembly_pbc_double.m）

- 匹配源/目标面上的边
- 约束矩阵P：`P(dst_edge, src_edge) = exp(i*k*d)`
- 删除目标面的DOF列
- 角域边的特殊处理

### 3D电场后处理（参考MATLAB get_ele.m）

- 对每个边界三角面，通过 `ConnOfTri` 定位到四面体
- 在四面体顶点处用参考坐标计算Nedelec基函数值
- E = sum(N_j * x_j)，其中x_j为边DOF解向量

---

## 五、文件修改/新增清单

### 修改文件

- [Assemble_EigenFreq_Equation.cpp](opticsfem-master/kernel/Assemble_EigenFreq_Equation.cpp) -- 修Jacobian和材料bug
- [Assemble_Scatter_Equation.cpp](opticsfem-master/kernel/Assemble_Scatter_Equation.cpp) -- 修Jacobian和材料bug
- [Assemble_kernel.cpp](opticsfem-master/kernel/Assemble_kernel.cpp) -- 补全3D EigenFreq/Scatter的Run/Post
- [Assemble_Scatter_3D_Boundary.cpp](opticsfem-master/kernel/Assemble_Scatter_3D_Boundary.cpp) -- 实现SBC/PEC_ELE
- [Assemble_Base.h](opticsfem-master/kernel/Assemble_Base.h) -- 新增3D EigenMode类
- [FEM_Interface.cpp](opticsfem-master/Interface/FEM_Interface.cpp) -- 3D路由
- [Mesh_Base.h](opticsfem-master/mesh/Mesh_Base.h) -- 补全Mesh_3D的GetMesh声明
- [Post_Base.h](opticsfem-master/post/Post_Base.h) -- 补全3D后处理类
- [Test_ReadData.cpp](opticsfem-master/test/Test_ReadData.cpp) -- 3D参数解析
- [CMakeLists.txt](opticsfem-master/CMakeLists.txt) -- 新增源文件

### 新增文件

- `opticsfem-master/mesh/Mesh_3D_Interface.cpp` -- 3D JSON网格读取
- `opticsfem-master/kernel/Assemble_EigenMode_3D_Equation.cpp` -- 3D本征模式体积组装
- `opticsfem-master/kernel/Assemble_EigenMode_3D_Boundary.cpp` -- 3D本征模式边界
- `opticsfem-master/kernel/Assemble_EigenFreq_3D_Boundary.cpp` -- 3D本征频率边界
- `opticsfem-master/post/Post_3D_CalElectric.cpp` -- 3D电场计算
- `opticsfem-master/post/Post_3D_Output.cpp` -- 3D结果输出
- `opticsfem-master/function/BF_Tetrahedron_2nd.cpp` -- 二阶基函数（阶段6）
- `docs/API_3D_FEM.md` -- API定义文档
- `examples/eigenfreq_3d.json` -- 本征频率示例
- `examples/eigenmode_3d.json` -- 本征模式示例
- `examples/scatter_3d.json` -- 散射示例
- `examples/mesh_3d.json` -- 3D网格示例

