1060 lines
40 KiB
Markdown
1060 lines
40 KiB
Markdown
# OpticsFEM 完整使用说明与代码介绍
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 文档版本 | v3.0 |
|
||
| 编制日期 | 2026-06-09 |
|
||
| 适用代码 | **`3D opticsfem-master/`**（三维版，主算例 FemType=4 散射 + FemType=5 本征频率） |
|
||
| 适用平台 | Windows x64，**Visual Studio 2026（18）**，MSVC |
|
||
| 关联文档 | `compare/README.md`（COMSOL 对比）、上级目录 2D 版 `opticsfem-master/` |
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [程序概述](#1-程序概述)
|
||
2. [目录与文件总览](#2-目录与文件总览)
|
||
3. [各模块代码详解](#3-各模块代码详解)
|
||
4. [软件架构与执行流程](#4-软件架构与执行流程)
|
||
5. [完整使用说明](#5-完整使用说明)
|
||
6. [输入输出文件规范](#6-输入输出文件规范)
|
||
7. [对外 API 与集成方式](#7-对外-api-与集成方式)
|
||
8. [测试算例与数据集](#8-测试算例与数据集)
|
||
9. [代码阅读路径](#9-代码阅读路径)
|
||
10. [常见问题排查](#10-常见问题排查)
|
||
|
||
---
|
||
|
||
## 1. 程序概述
|
||
|
||
### 1.1 程序定位
|
||
|
||
**OpticsFEM3D** 是一套基于 C++ 实现的**三维矢量有限元（FEM）光学电磁仿真内核**。程序采用 **一阶 Nedelec 边元** 离散麦克斯韦方程，通过 JSON 配置物理模型、材料与边界条件，通过 `.dat` 文本文件读入四面体网格，计算结果以文本文件输出。
|
||
|
||
> **当前三维主算例**：
|
||
> - **FemType = 4**：三维 SBC 散射，`sbc3d.json`，网格 `SBCmesh.dat`，完整求解流程。
|
||
> - **FemType = 5**：三维本征频率，`eigen3d.json`，同一网格，当前完成 A/B 矩阵组装与导出。
|
||
|
||
### 1.2 支持的问题类型
|
||
|
||
| FemType | 问题类型 | 驱动类 | 网格 | 求解器 | 后处理 | 状态 |
|
||
|---------|----------|--------|------|--------|--------|------|
|
||
| 0 | 本征模式（2D 遗留） | `OpticsFEM_2D_EigenMode` | `Mesh_2D` | `Solver_EigenMode` | `Post_2D_EigenMode` | 遗留 |
|
||
| 1 | 本征频率（2D 遗留） | `OpticsFEM_2D_EigenFreq` | `Mesh_2D` | `Solver_EigenFreq` | `Post_2D_EigenFreq` | 遗留 |
|
||
| 2 | 2D 散射（按波长 λ） | `OpticsFEM_2D_Scatter` | `Mesh_2D` | `Solver_LdaDom` | `Post_2D_Scatter` | 遗留 |
|
||
| 3 | 2D 散射（按频率 f） | `OpticsFEM_2D_Scatter` | `Mesh_2D` | `Solver_LdaDom` | `Post_2D_Scatter` | 遗留 |
|
||
| **4** | **3D 一阶散射（SBC，按 λ）** | **`OpticsFEM_3D_Scatter`** | **`Mesh_3D`** | **`Solver_LdaDom`** | **`Post_3D_Scatter`** | **完整** |
|
||
| **5** | **3D 一阶本征频率** | **`OpticsFEM_3D_EigenFreq`** | **`Mesh_3D`** | **`Solver_EigenFreq`** | **`Post_3D_EigenFreq`** | **组装+矩阵导出** |
|
||
|
||
### 1.3 设计原则
|
||
|
||
- **单一 API 入口**：外部只需调用 `OpticsFEM_All()`，无需感知内部分支。
|
||
- **JSON 为配置语言**：物理、材料、边界、求解参数均通过 JSON 传递。
|
||
- **前后端解耦**：`Test_Main.cpp` 可替换为 GUI、脚本或 DLL 宿主，接口不变。
|
||
- **模块化分层**：网格 → 物理/材料 → 组装 → 求解 → 后处理，各层独立。
|
||
|
||
### 1.4 第三方依赖（源码内嵌）
|
||
|
||
| 依赖 | 路径 | 用途 |
|
||
|------|------|------|
|
||
| Eigen | `Eigen/` | 稠密/稀疏矩阵运算（337 个头文件，header-only） |
|
||
| nlohmann/json | `nlohmann/` | JSON 解析 |
|
||
| muparserX 派生库 | `parser/` | BELE、SBC、端口等边界表达式求值 |
|
||
|
||
### 1.5 运行时外部依赖
|
||
|
||
| FemType | 依赖 | 说明 |
|
||
|---------|------|------|
|
||
| **4（3D 散射）** | `complex/complexsolver.exe` | **CMake 自动编译**（Eigen SparseLU），求解 **A·x=b** |
|
||
| **5（3D 本征频率）** | 暂无（矩阵导出阶段） | 当前仅 `Assemble` + `Test_OutputMatrix`；完整求解需 `real_solver/`、`complex_solver/` |
|
||
| 0–3（2D 遗留） | `complex/complexsolver.exe` 等 | 本征问题另需 `real_solver/`、`complex_solver/` |
|
||
|
||
散射求解器通过**临时 `.dat` 文件**与主程序交换 CSR 格式矩阵，由 `system()` 启动。
|
||
|
||
---
|
||
|
||
## 2. 目录与文件总览
|
||
|
||
```
|
||
3D opticsfem-master/
|
||
├── CMakeLists.txt # CMake：OpticsFEM + complexsolver
|
||
├── CMakeSettings.json # VS CMake 设置（x64-Release）
|
||
├── sbc3d.json # ★ FemType=4 散射算例配置
|
||
├── eigen3d.json # ★ FemType=5 本征频率算例配置
|
||
├── SBCmesh.dat # ★ 三维四面体网格（散射与本征共用）
|
||
├── Interface/ # 对外 API（FemType 路由）
|
||
├── test/ # Test_Main.cpp 入口、JSON 解析
|
||
├── complex/ # complexsolver 源码（Eigen 稀疏求解）
|
||
├── compare/ # MATLAB：COMSOL vs OpticsFEM 切面对比
|
||
├── phy/ # 物理模型与边界条件
|
||
├── material/ # 材料库
|
||
├── mesh/ # Mesh_2D + Mesh_3D 读写
|
||
├── kernel/ # 2D/3D 组装（散射 SBC + 本征 A/B）
|
||
├── solver/ # 数值求解器接口
|
||
├── post/ # Post_3D_Scatter / Post_3D_EigenFreq
|
||
├── function/ # Nedelec 基函数与高斯积分
|
||
├── common/ # 公共常量
|
||
├── parser/ # 表达式解析器
|
||
├── nlohmann/ # JSON 库
|
||
├── Eigen/ # 线性代数库
|
||
├── scat3D/ # 推荐：FemType=4 本地 CMake 构建（不上传）
|
||
└── eigen3D/ # 推荐：FemType=5 本地 CMake 构建（不上传）
|
||
```
|
||
|
||
**源码统计（不含 scat3D/、eigen3D/、build/ 等构建目录）：**
|
||
|
||
| 类别 | 数量 | 说明 |
|
||
|------|------|------|
|
||
| 业务源文件 `.cpp` | 约 35 个 | 组装、求解、后处理等核心逻辑 |
|
||
| 业务头文件 `.h` | 约 20 个 | 类声明与接口 |
|
||
| parser 模块 | 约 89 个 | muparserX 表达式引擎 |
|
||
| Eigen 第三方 | 337 个 | 仅头文件，不参与业务修改 |
|
||
| **合计参与编译** | 约 70+ `.cpp` | 链接为单一 `OpticsFEM.exe` |
|
||
|
||
---
|
||
|
||
## 3. 各模块代码详解
|
||
|
||
### 3.1 Interface/ — 对外 API
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `FEM_Interface.h` | 定义 `OpticsFEMData` 结构体与 `OpticsFEM_API` 类；预留 `extern "C"` DLL 导出注释 |
|
||
| `FEM_Interface.cpp` | **核心调度器**：解析 JSON 中 `FemType`，创建对应 FEM 驱动/求解器/后处理对象，执行 Assemble → Run → Post 全流程 |
|
||
|
||
**关键函数：**
|
||
|
||
```cpp
|
||
struct OpticsFEMData {
|
||
double test1; // 保留字段
|
||
double test2; // 保留字段
|
||
char* data; // UTF-8 JSON 字符串
|
||
};
|
||
|
||
class OpticsFEM_API {
|
||
public:
|
||
static int OpticsFEM_All(OpticsFEMData data); // 完整求解
|
||
int OpticsFEM_Test(OpticsFEMData data); // 连通性测试
|
||
};
|
||
```
|
||
|
||
**返回值：** 0 = FemType 无法识别；1 = 2D 本征模式；2 = 2D 本征频率；3 = 2D 散射；**4 = 3D 散射完成**；**5 = 3D 本征频率矩阵导出完成**。
|
||
|
||
---
|
||
|
||
### 3.2 test/ — 入口与数据解析
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `Test_Main.cpp` | 进程 `main()` 入口：从 JSON 文件（默认 `sbc3d.json`）读取整行 JSON，封装为 `OpticsFEMData`，调用 `OpticsFEM_All()`。本征算例改为 `eigen3d.json` 后须重新编译 |
|
||
| `Test_ReadData.cpp` | 实现 `Phy_WaveOpticsModel::Test_ReadData()` 与 `MaterialLib::Test_ReadData()`，将 JSON 字段映射到内存对象 |
|
||
| `Test_OutputData.cpp` | 调试用途：将组装后的稀疏矩阵 A/B/P 输出到文本文件 |
|
||
| `interfaceClass.h` | 遗留的 `FemInput` 结构体，记录预期配置字段（当前 JSON 路径未直接使用） |
|
||
|
||
**注意：** `Test_Main.cpp` 中声明的 `Phy_WaveOpticsModel`、`MaterialLib` 等对象在 `main()` 内未被直接使用；实际实例化在 `FEM_Interface.cpp` 中完成。注释块（第 39–58 行）保留了手动分步调用的旧版写法。
|
||
|
||
---
|
||
|
||
### 3.3 phy/ — 物理模型与边界条件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `Phy_Base.h` | `Phy_WaveOpticsModel` 类声明：存储 PMC/PEC/PBC/PML/SBC/ELE/MAG/SCD/MPD/EPD/BELE/端口/高斯光束等边界数据及访问接口 |
|
||
| `Phy_Base.cpp` | 构造函数与各边界查询 getter 实现 |
|
||
| `Phy_Interface.cpp` | `GetPhy()` 占位桩 |
|
||
|
||
**BoundaryFlag 编码（`Test_ReadData.cpp`）：**
|
||
|
||
| 值 | 边界类型 |
|
||
|----|----------|
|
||
| 0 | PMC（理想磁导体） |
|
||
| 1 | PEC（理想电导体） |
|
||
| 2 | SBC（散射边界条件） |
|
||
| 3 | ELE（电场 Dirichlet 边界） |
|
||
| 4 | PBC（周期边界，成对计数） |
|
||
| 8 | MAG（磁场边界） |
|
||
| 9 | SCD（面电流密度） |
|
||
|
||
**支持的 JSON 边界扩展块：** `sbc`、`ef`、`mag`、`scd`、`pbc`、`mpd`、`epd`、`bele`、`pml`、`port`、`beam`（均为可选，按 `js.contains()` 判定是否解析）。
|
||
|
||
---
|
||
|
||
### 3.4 material/ — 材料库
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `Material_Base.h` | `Material`（单材料张量属性）与 `MaterialLib`（按物理域索引的材料库） |
|
||
| `Material_Base.cpp` | 材料属性 setter/getter |
|
||
| `Material_Interface.cpp` | `MaterialLib::SetMat()`、`SetNumberMat()`，材料类型分发（各向同性 ε/μ 或 n,k 折射率） |
|
||
|
||
**材料 JSON 字段：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `NbrDomain` | int | 物理域数量 |
|
||
| `matType` | int[] | 0 = ε/μ 张量；1 = n,k 折射率 |
|
||
| `epsilonrR/I` | double[] | 相对介电常数实部/虚部 |
|
||
| `murR/I` | double[] | 相对磁导率 |
|
||
| `sigma` | double[] | 电导率 |
|
||
| `chiheR/I`, `chiehR/I` | double[] | 磁电耦合张量 |
|
||
| `n`, `k` | double[] | 折射率（matType=1 时，ε = (n+ik)²） |
|
||
|
||
---
|
||
|
||
### 3.5 mesh/ — 网格
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `Mesh_Base.h` | `Mesh_2D`（三角形、边、边界域）与 `Mesh_3D`（四面体、棱柱，部分实现）数据结构及查询 API |
|
||
| `Mesh_Base.cpp` | 顶点、边、单元、域编号等基本访问器 |
|
||
| `Mesh_Interface.cpp` | `Mesh_2D::GetMesh()`：顺序解析 `.dat` 网格文件 |
|
||
| `Mesh_Find.cpp` | 域/PBC 索引查找：边/节点所属域、PBC 源/目标映射 |
|
||
|
||
**Mesh_3D** 已接入 `FemType=4`（散射）与 `FemType=5`（本征频率），读入 `SBCmesh.dat` 等三维四面体网格。
|
||
|
||
---
|
||
|
||
### 3.6 kernel/ — FEM 组装
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `Assemble_Base.h` | 声明全部 `OpticsFEM_*` 驱动类（2D 本征模式/频率/散射，3D 本征频率/散射） |
|
||
| `Assemble_Base.cpp` | 依赖注入（`GetMaterial`、`GetMesh` 等），各驱动的 `Run()`/`Post()` 实现 |
|
||
| `Assemble_kernel.cpp` | 各问题类型顶层 `Assemble()`：实/复矩阵选择、DOF 规模、边界分发 |
|
||
| `Assemble_EigenMode_Equation.cpp` | 2D 本征模式体积积分（curl-curl + 质量矩阵） |
|
||
| `Assemble_EigenMode_Boundary.cpp` | 本征模式 PEC/PBC 约束 |
|
||
| `Assemble_EigenFreq_Equation.cpp` | 2D/3D 本征频率体积积分 |
|
||
| `Assemble_EigenFreq_Boundary.cpp` | 本征频率 PEC/PBC |
|
||
| `Assemble_Scatter_Equation.cpp` | 散射问题驱动麦克斯韦弱形式体积积分 |
|
||
| `Assemble_Scatter_2D_Boundary.cpp` | 2D 边界项：SBC、BELE、PML、PEC/ELE、PBC、端口、MPD/EPD、MAG、SCD |
|
||
| `Assemble_Scatter_3D_Boundary.cpp` | 3D 边界组装（SBC、PEC/ELE，部分实现） |
|
||
|
||
**Assemble 阶段输出：** 稀疏矩阵 **A**、右端向量 **b**、预处理矩阵 **P**（实数或复数，由 PML/SBC/复材料等条件自动判定）。
|
||
|
||
---
|
||
|
||
### 3.7 solver/ — 数值求解
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `Solver_Base.h` | `Solver_EigenMode`、`Solver_EigenFreq`、`Solver_LdaDom` 类及稀疏矩阵参数结构 |
|
||
| `Solver_Base.cpp` | 简单 getter（`GetNbrMode`、`GetLda0`、`GetElectricType` 等） |
|
||
| `Solver_Interface.cpp` | JSON 求解参数解析，`SetParam`/`Run` 实现，调用特征值或线性求解器 |
|
||
| `eigen_solver.h` | 广义特征值求解 C API 声明（实/复 CSR 格式） |
|
||
| `eigen_solver.cpp` | 将矩阵写入 `./real_solver/` 或 `./complex_solver/` 临时文件，启动外部特征值求解器，读回结果 |
|
||
| `interface.h` | `solveRealLinearEqu`、`solveComplexLinearEqu` 声明 |
|
||
| `interface.cpp` | 通过临时 `.dat` 文件调用 `complex/complexsolver.exe` 等外部线性求解器 |
|
||
| `framework.h` | Windows DLL 风格求解器接口头 |
|
||
|
||
**求解器分层：**
|
||
|
||
| 层级 | 模块 | 适用问题 | 运行时依赖 |
|
||
|------|------|----------|------------|
|
||
| 特征值 | `eigen_solver.cpp` | FemType 0, 1 | `real_solver/real`, `complex_solver/complex` |
|
||
| 线性（实） | `interface.cpp` | 实散射 | `real/realsolver.exe` |
|
||
| 线性（复） | `interface.cpp` | 复散射 | `complex/complexsolver.exe` |
|
||
|
||
当前工程通过宏 `EIGENSOLVER_STATIC` 将 `eigen_solver.cpp` 静态编入可执行文件，**不再依赖** `lib/eigensolver.lib`。
|
||
|
||
---
|
||
|
||
### 3.8 post/ — 后处理
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `Post_Base.h` | `Post_2D_EigenMode`、`Post_2D_EigenFreq`、`Post_2D_Scatter` 及 3D 后处理类声明 |
|
||
| `Post_Base.cpp` | `GetMesh`/`GetSolver`/`GetResult`/`GetPhy` 接线 |
|
||
| `Post_CalEletric.cpp` | 利用 Nedelec 基函数将边/顶点 DOF 重构为顶点 Ex/Ey/Ez |
|
||
| `Post_GetEb.cpp` | 在网格顶点处用 muparser 求值 BELE 解析背景场 |
|
||
| `Post_Output.cpp` | 写入 `neff`/`freq`/`Ex`/`Ey`/`Ez`/`normE` 文本文件 |
|
||
| `Post_Power.cpp` | `GetPower()` 占位（本征模式返回 0） |
|
||
|
||
---
|
||
|
||
### 3.9 function/ — 基函数与高斯积分
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `BF.h` / `BF.cpp` | `BF` 分发类：按单元类型选择并求值基函数 |
|
||
| `BF_Line.cpp` | 一维 Lagrange 基函数及梯度/curl |
|
||
| `BF_Triangle.cpp` | 二维三角形 Lagrange 与 Nedelec（1 阶）基函数及 curl |
|
||
| `BF_Quadrangle.cpp` | 二维四边形 Lagrange/Nedelec 基函数 |
|
||
| `BF_Tetrahedron.cpp` | 三维四面体 Nedelec 基函数及 curl |
|
||
| `BF_Prism.cpp` | 三维棱柱 Nedelec 基函数及 curl |
|
||
| `Gauss.h` / `Gauss.cpp` | `Gauss` 类：按单元类型与阶次选择积分规则 |
|
||
| `Gauss_Line.h` | 线段高斯点/权重 |
|
||
| `Gauss_Triangle.h` | 三角形高斯点/权重 |
|
||
| `Gauss_Quadrangle.h` | 四边形高斯点/权重 |
|
||
| `Gauss_Tetrahedron.h` | 四面体高斯点/权重 |
|
||
| `Gauss_Prism.h` | 棱柱高斯点/权重 |
|
||
|
||
---
|
||
|
||
### 3.10 common/ — 公共定义
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `define.h` | 几何/网格/基函数/材料/物理常量（`c_const`、`Pi`、单元类型、边界标志等） |
|
||
| `util.h` / `util.cpp` | 数值 clamp、快速排序、唯一索引等网格/组装辅助工具 |
|
||
|
||
---
|
||
|
||
### 3.11 parser/ — 数学表达式解析器（muparserX）
|
||
|
||
共约 **89 个** `.cpp`/`.h` 文件，为 vendored **muparserX** 分支，用于求值 BELE、SBC、端口等边界上的字符串表达式（如 `"sin(2*pi*x)"`）。
|
||
|
||
| 分组 | 代表文件 | 作用 |
|
||
|------|----------|------|
|
||
| 核心引擎 | `mpParser.*`, `mpParserBase.*`, `mpRPN.*`, `mpTokenReader.*`, `mpScriptTokens.*` | 表达式 → RPN → 求值 |
|
||
| 值系统 | `mpValue.*`, `mpValueCache.*`, `mpVariable.*`, `mpValReader.*` | 类型化值存储、变量、缓存 |
|
||
| 函数库 | `mpFuncCommon/Cmplx/NonCmplx/Matrix/Str.*` | 内置数学/字符串/矩阵函数 |
|
||
| 运算符 | `mpOprtBinCommon/Assign/Shortcut/Cmplx/NonCmplx/Matrix/Index/PostfixCommon.*` | 二元/一元/后缀运算符 |
|
||
| 注册包 | `mpPackageCommon/Cmplx/NonCmplx/Matrix/Str/Unit.*` | 函数与运算符注册 |
|
||
| 插件接口 | `mpICallback.*`, `mpIOprt.*`, `mpIPackage.*`, `mpIValue.*`, `mpIToken.*`, `mpIValReader.*` | 扩展接口 |
|
||
| 辅助 | `mpError.*`, `mpIfThenElse.*`, `mpMatrix.*`, `mpTest.*`, `mpDefines.h`, `mpCompat.h`, `mpFwdDecl.h`, `mpTypes.h`, `mpStack.h`, `suSortPred.h`, `suStringTokens.h`, `utGeneric.h` | 错误处理、条件分支、矩阵类型、诊断 |
|
||
|
||
**一般用户无需修改此模块。**
|
||
|
||
---
|
||
|
||
### 3.12 nlohmann/ — JSON 库
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `json.hpp` | nlohmann JSON 单头文件完整实现 |
|
||
| `json_fwd.hpp` | 前向声明，加速编译 |
|
||
|
||
---
|
||
|
||
### 3.13 Eigen/ — 线性代数库
|
||
|
||
337 个头文件，header-only 第三方库。主要模块：`Core`、`Dense`、`Sparse`、`SparseCore`、`Eigenvalues`、`LU`、`QR`、`SVD`、`Geometry` 等。全项目矩阵运算与稀疏组装均依赖 Eigen。
|
||
|
||
**一般用户无需修改此模块。**
|
||
|
||
---
|
||
|
||
### 3.14 根目录构建文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `CMakeLists.txt` | 定义 `OpticsFEM` 可执行目标，列出全部源文件分组（PARSER/COMMON/GAUSS/BF/MESH/MATERIAL/PHY/SOLVER/POST/KERNEL/TEST/INTERFACE），设置 C++17 与 `EIGENSOLVER_STATIC` |
|
||
| `CMakeSettings.json` | Visual Studio 中 CMake 配置（生成器、架构等） |
|
||
|
||
---
|
||
|
||
## 4. 软件架构与执行流程
|
||
|
||
### 4.1 模块依赖关系
|
||
|
||
```
|
||
Test_Main.cpp
|
||
│
|
||
▼
|
||
FEM_Interface.cpp ──► Phy / Material / Mesh（读入）
|
||
│
|
||
├── FemType 0 ──► OpticsFEM_2D_EigenMode ──► Solver_EigenMode ──► Post_2D_EigenMode
|
||
├── FemType 1 ──► OpticsFEM_2D_EigenFreq ──► Solver_EigenFreq ──► Post_2D_EigenFreq
|
||
├── FemType 2/3 ► OpticsFEM_2D_Scatter ──► Solver_LdaDom ──► Post_2D_Scatter
|
||
├── FemType 4 ──► OpticsFEM_3D_Scatter ──► Solver_LdaDom ──► Post_3D_Scatter
|
||
└── FemType 5 ──► OpticsFEM_3D_EigenFreq ──► Solver_EigenFreq ──► Post_3D_EigenFreq
|
||
│
|
||
└── Mesh_3D ← SBCmesh.dat
|
||
│
|
||
├── kernel（Assemble：体积 + 边界积分）
|
||
├── function（BF + Gauss 数值积分）
|
||
└── parser（边界表达式求值）
|
||
```
|
||
|
||
### 4.2 完整调用序列（FemType=4，三维 SBC 散射）
|
||
|
||
```
|
||
Test_Main.cpp
|
||
└─ 读取 sbc3d.json
|
||
└─ OpticsFEM_All(data)
|
||
└─ [FemType == 4]
|
||
├─ Phy / Material ← JSON（含 sbc 块）
|
||
├─ Mesh_3D::GetMesh("SBCmesh.dat")
|
||
├─ OpticsFEM_3D_Scatter::Assemble()
|
||
│ ├─ Assemble_WaveEquation()
|
||
│ └─ Assemble_SBC() SBCType 0 出射 + 1 入射
|
||
├─ Run() → complex/complexsolver.exe
|
||
└─ Post("OutFile") → Ex, Ey, Ez, normE
|
||
```
|
||
|
||
### 4.2b 完整调用序列（FemType=5，三维本征频率）
|
||
|
||
```
|
||
Test_Main.cpp
|
||
└─ 读取 eigen3d.json
|
||
└─ OpticsFEM_All(data)
|
||
└─ [FemType == 5]
|
||
├─ Phy / Material ← JSON（PMC/PEC/PBC 边界）
|
||
├─ Mesh_3D::GetMesh("SBCmesh.dat")
|
||
├─ OpticsFEM_3D_EigenFreq::Assemble()
|
||
│ ├─ Assemble_WaveEquation() A=curl-curl, B=ε·质量
|
||
│ └─ Assemble_PEC_PBC() 边界约束矩阵 P
|
||
└─ Test_OutputMatrix("OutFile") → Ai/Aj/Av, Bi/Bj/Bv
|
||
（Run/Post 待接入：eigs 求 λ，再重构 Ex/Ey/Ez/freq）
|
||
```
|
||
|
||
### 4.3 完整调用序列（FemType=2，二维散射，遗留）
|
||
|
||
```
|
||
main()
|
||
└─ OpticsFEM_API::OpticsFEM_All(data)
|
||
├─ json::parse(data.data)
|
||
├─ Phy_WaveOpticsModel::Test_ReadData(str)
|
||
├─ MaterialLib::Test_ReadData(str)
|
||
├─ Mesh_2D::GetMesh(meshFile, str)
|
||
└─ [FemType == 2]
|
||
├─ Solver_LdaDom::GetSolver(str)
|
||
├─ OpticsFEM_2D_Scatter::GetMaterial / GetMesh / GetPhy / GetSolver / GetPost
|
||
├─ OpticsFEM_2D_Scatter::Assemble()
|
||
│ ├─ Assemble_WaveEquation() 体积积分
|
||
│ ├─ Assemble_PEC_ELE() 理想导体/电边界
|
||
│ ├─ Assemble_PBC() 周期边界
|
||
│ ├─ Assemble_BELE() 边界等效源
|
||
│ ├─ Assemble_PML() 完美匹配层
|
||
│ └─ Assemble_Port() 等 端口激励
|
||
├─ OpticsFEM_2D_Scatter::Run()
|
||
│ └─ Solver_LdaDom::Run() → solveComplexLinearEqu()
|
||
└─ OpticsFEM_2D_Scatter::Post(outFile)
|
||
├─ GetElectric() DOF → 顶点 Ex/Ey/Ez
|
||
└─ OutputData() 写入 OutFile/
|
||
```
|
||
|
||
### 4.4 数据流
|
||
|
||
**FemType = 4（三维散射）：**
|
||
|
||
```
|
||
sbc3d.json ──► Phy（sbc 边界/入射场）
|
||
──► MaterialLib（epsilonrR 等）
|
||
SBCmesh.dat ──► Mesh_3D（四面体 + 三角边界）
|
||
──► Assemble ──► 稀疏矩阵 A, 向量 b
|
||
──► complexsolver ──► 解向量 x
|
||
──► Post ──► OutFile/Ex, Ey, Ez, normE
|
||
```
|
||
|
||
**FemType = 5（三维本征频率）：**
|
||
|
||
```
|
||
eigen3d.json ──► Phy（PMC/PEC/PBC）
|
||
──► MaterialLib
|
||
SBCmesh.dat ──► Mesh_3D
|
||
──► Assemble ──► 稀疏矩阵 A（刚度）, B（质量）
|
||
──► Test_OutputMatrix ──► OutFile/Ai,Aj,Av,Bi,Bj,Bv
|
||
（后续 Run: eigs(A,B) → λ=k₀²；Post → freq, Ex/Ey/Ez）
|
||
```
|
||
|
||
**物理对应关系：** 散射体积分 `A_scatter ≈ A_eigen − k₀²·B_eigen`（同一网格与 Nedelec 基函数下）。
|
||
|
||
**FemType = 2（2D 遗留）：**
|
||
|
||
```
|
||
bele.json ──► Phy_WaveOpticsModel（边界/激励）
|
||
──► MaterialLib（材料参数）
|
||
──► MeshFile 路径
|
||
project_3.dat ──► Mesh_2D（网格拓扑）
|
||
──► Assemble ──► 稀疏矩阵 A, 向量 b
|
||
──► Solver ──► 解向量 x
|
||
──► Post ──► OutFile/Ex, Ey, Ez, normE
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 完整使用说明
|
||
|
||
### 5.1 环境要求
|
||
|
||
| 组件 | 要求 |
|
||
|------|------|
|
||
| 操作系统 | Windows 10/11 x64 |
|
||
| 编译器 | Visual Studio 2026（18），工作负载「使用 C++ 的桌面开发」 |
|
||
| 构建工具 | CMake ≥ 3.8（VS 自带，见下方 PATH） |
|
||
| C++ 标准 | C++17 |
|
||
|
||
### 5.2 编译步骤
|
||
|
||
推荐使用**两个独立构建目录**，避免散射与本征互相覆盖 exe 和 OutFile：
|
||
|
||
```powershell
|
||
# 若 cmake 不在 PATH 中，追加 VS 2026 自带 CMake 路径
|
||
$env:Path += ";C:\Program Files\Microsoft Visual Studio\18\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin"
|
||
|
||
cd "3D opticsfem-master"
|
||
|
||
# FemType=4 散射
|
||
cmake -B scat3D -G "Visual Studio 18 2026" -A x64
|
||
cmake --build scat3D --config Release
|
||
|
||
# FemType=5 本征频率
|
||
cmake -B eigen3D -G "Visual Studio 18 2026" -A x64
|
||
cmake --build eigen3D --config Release
|
||
```
|
||
|
||
**产物路径：**
|
||
|
||
- `scat3D/Release/OpticsFEM.exe` + `scat3D/Release/complex/complexsolver.exe`
|
||
- `eigen3D/Release/OpticsFEM.exe`
|
||
|
||
也可使用单一 `build/` 目录（见 `CMakeSettings.json`），但切换算例时需重新编译并注意 OutFile 覆盖。
|
||
|
||
### 5.3 运行前准备（FemType = 4，三维散射）
|
||
|
||
#### 步骤 1：指定 JSON 配置文件
|
||
|
||
`test/Test_Main.cpp` 默认读取 **`sbc3d.json`**：
|
||
|
||
```cpp
|
||
std::ifstream fd("sbc3d.json");
|
||
```
|
||
|
||
更换算例时修改文件名；修改后须**重新编译 scat3D**。
|
||
|
||
#### 步骤 2：部署输入文件
|
||
|
||
将 JSON 及 `MeshFile` 指定的网格文件复制到 **`scat3D/Release/`**（与 exe 同目录）：
|
||
|
||
```powershell
|
||
Copy-Item sbc3d.json, SBCmesh.dat -Destination scat3D\Release\
|
||
```
|
||
|
||
#### 步骤 3：确认求解器
|
||
|
||
```
|
||
scat3D/Release/
|
||
├── OpticsFEM.exe
|
||
├── sbc3d.json
|
||
├── SBCmesh.dat
|
||
└── complex/
|
||
└── complexsolver.exe ← cmake --build 后自动生成
|
||
```
|
||
|
||
#### 步骤 4：执行
|
||
|
||
```powershell
|
||
cd scat3D/Release
|
||
.\OpticsFEM.exe
|
||
```
|
||
|
||
控制台应打印 `OpticsFEM_All returned 4`。
|
||
|
||
#### 步骤 5：查看结果
|
||
|
||
检查 `OutFile/` 是否生成：`Ex`、`Ey`、`Ez`、`normE`。
|
||
|
||
---
|
||
|
||
### 5.3c 运行前准备（FemType = 5，三维本征频率）
|
||
|
||
#### 步骤 1：指定 JSON 配置文件
|
||
|
||
编辑 `test/Test_Main.cpp`：
|
||
|
||
```cpp
|
||
std::ifstream fd("eigen3d.json");
|
||
```
|
||
|
||
修改后须**重新编译 eigen3D**（可与 scat3D 并存，互不干扰）。
|
||
|
||
#### 步骤 2：部署输入文件
|
||
|
||
```powershell
|
||
Copy-Item eigen3d.json, SBCmesh.dat -Destination eigen3D\Release\
|
||
```
|
||
|
||
#### 步骤 3：执行
|
||
|
||
```powershell
|
||
cd eigen3D/Release
|
||
.\OpticsFEM.exe
|
||
```
|
||
|
||
控制台应打印 `OpticsFEM_All returned 5`。
|
||
|
||
#### 步骤 4：查看矩阵输出
|
||
|
||
`OutFile/` 下导出 A/B 稀疏矩阵 COO（0-based）：
|
||
|
||
| 文件 | 含义 |
|
||
|------|------|
|
||
| `Ai.txt`, `Aj.txt`, `Av.txt` | 刚度矩阵 A |
|
||
| `Bi.txt`, `Bj.txt`, `Bv.txt` | 质量矩阵 B（ε 加权） |
|
||
|
||
可与 MATLAB `3D一阶本征问题2` 中 `export_ab_matrix.m` 输出对比验证。
|
||
|
||
> **当前限制**：`Run()`（广义特征值求解）与 `Post()`（场重构、freq 输出）尚未接入 `FEM_Interface.cpp` 的 FemType=5 分支。
|
||
|
||
---
|
||
|
||
### 5.3b 运行前准备（FemType 0–3，2D 遗留）
|
||
|
||
#### 步骤 1：指定 JSON 配置文件
|
||
|
||
编辑 `test/Test_Main.cpp` 中 `fd.open(...)` 的文件名。
|
||
|
||
#### 步骤 2：部署输入文件
|
||
|
||
将 JSON 及 JSON 中 `MeshFile` 指定的 `.dat` 网格文件复制到 `build/Release/` 目录（与 `OpticsFEM.exe` 同目录）。
|
||
|
||
#### 步骤 3：部署外部求解器
|
||
|
||
**散射算例（FemType 2/3/4）最小目录：**
|
||
|
||
```
|
||
Release/
|
||
├── OpticsFEM.exe
|
||
├── *.json # sbc3d.json（FemType=4）或 bele.json（FemType=2）
|
||
├── *.dat # SBCmesh.dat 或 project_3.dat
|
||
└── complex/
|
||
└── complexsolver.exe
|
||
```
|
||
|
||
**本征算例（FemType 0/1）另需：**
|
||
|
||
```
|
||
Release/
|
||
├── real_solver/real # 实数特征值求解器
|
||
└── complex_solver/complex # 复数特征值求解器
|
||
```
|
||
|
||
#### 步骤 4：执行
|
||
|
||
```powershell
|
||
cd build/Release
|
||
.\OpticsFEM.exe
|
||
```
|
||
|
||
#### 步骤 5：查看结果
|
||
|
||
检查 JSON 中 `OutFile` 指定目录（默认 `./OutFile`）是否生成：
|
||
|
||
- 散射：`Ex`、`Ey`、`Ez`、`normE`
|
||
- 本征模式：上述文件 + `neff`
|
||
- 本征频率：上述文件 + `freq`
|
||
|
||
### 5.4 切换算例
|
||
|
||
| 操作 | 方法 |
|
||
|------|------|
|
||
| 更换 JSON | 修改 `Test_Main.cpp` 中 `fd.open()` 文件名，或将目标 JSON 复制为当前文件名 |
|
||
| 更换网格 | 确保 JSON 中 `MeshFile` 与实际 `.dat` 文件名一致 |
|
||
| 更换问题类型 | 修改 JSON 中 `FemType`（0/1/2/3/4/5），程序自动路由 |
|
||
|
||
### 5.5 快速验证（sbc3d 三维 SBC 散射）
|
||
|
||
1. 编译 `scat3D` Release（见 5.2 节）
|
||
2. 确认 `Test_Main.cpp` 读取 `sbc3d.json`，复制 `sbc3d.json`、`SBCmesh.dat` 到 `scat3D/Release/`
|
||
3. 确认 `sbc3d.json` 中 `"FemType": 4`
|
||
4. 运行 `OpticsFEM.exe`
|
||
5. 检查 `OutFile/` 下四个场文件
|
||
|
||
与 COMSOL 对比见 `compare/README.md`。
|
||
|
||
### 5.5b 快速验证（eigen3d 三维本征频率）
|
||
|
||
1. 编译 `eigen3D` Release，`Test_Main.cpp` 改为读取 `eigen3d.json`
|
||
2. 复制 `eigen3d.json`、`SBCmesh.dat` 到 `eigen3D/Release/`
|
||
3. 确认 `"FemType": 5`
|
||
4. 运行 `OpticsFEM.exe`，应返回 5
|
||
5. 检查 `OutFile/` 下 `Ai/Aj/Av`、`Bi/Bj/Bv` 六个文件
|
||
|
||
### 5.6 快速验证（bele 二维算例，遗留）
|
||
|
||
1. 从 `../测试数据集/bele/` 复制 `bele.json` 和 `project_3.dat` 到 `build/Release/`
|
||
2. 修改 `Test_Main.cpp` 中 `fd.open("bele.json")`，重新编译
|
||
3. 部署 `complex/complexsolver.exe`
|
||
4. 运行 `OpticsFEM.exe`
|
||
5. 检查 `OutFile/` 下四个场文件
|
||
|
||
### 5.7 集成到其他程序
|
||
|
||
**方式 A — 独立可执行文件（当前模式）**
|
||
|
||
从文件读取 JSON，调用 API，适合本地验证。
|
||
|
||
**方式 B — 动态库（预留）**
|
||
|
||
取消 `FEM_Interface.h` 底部 `extern "C"` 注释，将 CMakeLists 中 `add_library(OpticsFEM SHARED ...)` 启用，编译为 DLL 供 C#/Python 等调用。
|
||
|
||
**方式 C — 直接调用 API**
|
||
|
||
```cpp
|
||
#include "Interface/FEM_Interface.h"
|
||
|
||
std::string jsonStr = "..."; // 紧凑 JSON 字符串
|
||
OpticsFEMData data;
|
||
data.test1 = 0;
|
||
data.test2 = 0;
|
||
data.data = (char*)jsonStr.data();
|
||
|
||
int ret = OpticsFEM_API::OpticsFEM_All(data);
|
||
// ret: 1=2D本征模式, 2=2D本征频率, 3=2D散射, 4=3D散射, 5=3D本征矩阵导出, 0=错误
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 输入输出文件规范
|
||
|
||
### 6.1 JSON 配置文件
|
||
|
||
- **格式**：单行 UTF-8 紧凑 JSON（`getline()` 读整行）
|
||
- **必填公共字段**：`FemType`, `NbrBoundary`, `BoundaryFlag`, `NbrDomain`, `MeshFile`, `OutFile`
|
||
|
||
#### 公共字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `FemType` | int | 0=2D本征模式, 1=2D本征频率, 2=2D散射(λ), 3=2D散射(f), **4=3D散射(λ)**, **5=3D本征频率** |
|
||
| `NbrBoundary` | int | 边界数量（3D 为三角面边界条数；2D 为边界面条数） |
|
||
| `BoundaryFlag` | int[] | 每条边界的类型编码（见 3.3 节） |
|
||
| `NbrDomain` | int | 材料物理域数量 |
|
||
| `MeshFile` | string | 网格 `.dat` 文件路径 |
|
||
| `OutFile` | string | 结果输出目录 |
|
||
| `EletricType` | int | 0=Et, 1=Ez, 2=完整 E（散射/本征频率） |
|
||
|
||
#### 本征问题专用字段
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `NbrMode` | 求解模态数量（FemType 0/1/5） |
|
||
| `searchValue` | 特征值搜索目标（FemType 0/1/5） |
|
||
| `searchType`, `solverType`, `maxIterNum`, `tol`, `tolType` | 特征值求解器参数（FemType 5 JSON 已预留） |
|
||
| `lambda0` | 参考波长（FemType 0/5） |
|
||
|
||
#### 散射问题专用字段
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `lambda` | 真空波长（FemType=2 或 **4**） |
|
||
| `freq` | 频率 GHz（FemType=3，内部换算 λ = 0.299792458/freq） |
|
||
|
||
#### 边界扩展块（2D 遗留，FemType 0–3 可选）
|
||
|
||
| 块名 | 主要字段 | 用途 |
|
||
|------|----------|------|
|
||
| `bele` | `index`, `Ebx/y/z`, `curlEbx/y/z` | 背景等效场边界 |
|
||
| `ef` | `index`, `E0x/y/z` | 电场 Dirichlet 激励 |
|
||
| `pml` | `index`, `PMLType`, `PMLData` | 完美匹配层 |
|
||
| `sbc` | `SBCType`, `Index`, `E0x/y/z`, `kx/y/z` | 散射边界（**FemType=4 必填**） |
|
||
| `pbc` | `srcIndex`, `dstIndex`, `phiR`, `phiI` | 周期边界 |
|
||
| `port` | `PORTinc`, `PORTout`, `Einc`, `Eout` | 波导端口 |
|
||
|
||
#### sbc3d 算例 JSON 摘要（FemType = 4）
|
||
|
||
```json
|
||
{
|
||
"FemType": 4,
|
||
"EletricType": 2,
|
||
"lambda": 0.8,
|
||
"NbrBoundary": 14,
|
||
"BoundaryFlag": [0, 2, 2, ...],
|
||
"sbc": {
|
||
"Index": [1, 2, 3, 4, 5, 14],
|
||
"SBCType": [0, 0, 0, 1, 0, 0],
|
||
"E0x": ["1", "1", "1", "1", "1", "1"],
|
||
"E0y": ["0", "0", "0", "0", "0", "0"],
|
||
"E0z": ["0", "0", "0", "0", "0", "0"],
|
||
"kx": [0, 0, 0, 0, 0, 0],
|
||
"ky": [0, 0, 0, 0, 0, 0],
|
||
"kz": [0, 0, 0, 0, 0, 0]
|
||
},
|
||
"NbrDomain": 2,
|
||
"domainType": [2, 2],
|
||
"matType": [0, 0],
|
||
"epsilonrR": [1.0, 1.5],
|
||
"epsilonrI": [0.0, 0.0],
|
||
"MeshFile": "SBCmesh.dat",
|
||
"OutFile": "./OutFile"
|
||
}
|
||
```
|
||
|
||
**SBCType 含义（FemType=4）：**
|
||
|
||
| 值 | 含义 |
|
||
|----|------|
|
||
| 0 | 出射 SBC（吸收边界） |
|
||
| 1 | 入射 SBC（平面波激励，用 `E0x/y/z` 指定） |
|
||
|
||
**BoundaryFlag 编码（三角面边界）：** 0=PMC, 1=PEC, **2=SBC**, 3=ELE, 4=PBC, …
|
||
|
||
#### eigen3d 算例 JSON 摘要（FemType = 5）
|
||
|
||
```json
|
||
{
|
||
"FemType": 5,
|
||
"EletricType": 2,
|
||
"NbrBoundary": 14,
|
||
"BoundaryFlag": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
|
||
"NbrDomain": 2,
|
||
"matType": [0, 0],
|
||
"epsilonrR": [1.0, 1.5],
|
||
"epsilonrI": [0.0, 0.0],
|
||
"murR": [1.0, 1.0],
|
||
"MeshFile": "SBCmesh.dat",
|
||
"OutFile": "./OutFile",
|
||
"NbrMode": 6,
|
||
"searchType": 0,
|
||
"searchValue": 374740572.5,
|
||
"lambda0": 0.8
|
||
}
|
||
```
|
||
|
||
本算例为全 PMC 边界（`BoundaryFlag` 全 0），与 MATLAB `3D一阶本征问题2` 对齐。方程 **A·x = λ·B·x**，λ = k₀²。
|
||
|
||
#### SBCmesh.dat 网格格式（Mesh_3D）
|
||
|
||
文本格式，按块顺序读取（1-based 索引，读入后转 0-based）：
|
||
|
||
| 块名 | 内容 |
|
||
|------|------|
|
||
| `NbrVertex` / `Vertex` | 顶点坐标 (x,y,z) |
|
||
| `NbrTet` / `Tet` | 四面体顶点连接 |
|
||
| `DomainOfTet` | 体域编号 |
|
||
| `NbrEdge` / `Edge` | 边列表 |
|
||
| `EdgeOfTet` | 四面体六条边局部编号 |
|
||
| `NbrTri` / `Tri` | 三角边界元 |
|
||
| `DomainOfTri` | 边界面域编号 |
|
||
| `ConnOfTri` | 三角面与边的连接 |
|
||
| `NbrQuad` / `Quad` | 四边形面元（若有） |
|
||
|
||
#### bele 算例 JSON 摘要（FemType = 2，2D 遗留）
|
||
|
||
```json
|
||
{
|
||
"FemType": 2,
|
||
"EletricType": 2,
|
||
"lambda": 1,
|
||
"NbrBoundary": 13,
|
||
"BoundaryFlag": [0, 0, 3, 0, ...],
|
||
"bele": {
|
||
"index": [4],
|
||
"Eby": "sin(2*pi*x)",
|
||
"Ebz": "cos(2*pi*x)"
|
||
},
|
||
"ef": { "index": [1], "E0y": ["0.5"], "E0z": ["0.3"] },
|
||
"pml": { "index": [1,2,3,5], "PMLType": [1,1,1,1], ... },
|
||
"NbrDomain": 5,
|
||
"matType": [0,0,0,0,0],
|
||
"epsilonrR": [1.0, 1.0, 1.0, 1.0, 1.0],
|
||
"MeshFile": "project_3.dat",
|
||
"OutFile": "./OutFile"
|
||
}
|
||
```
|
||
|
||
详细字段定义参见上级目录 `OpticsFEM_LASPCEM_接口规范.md`。
|
||
|
||
---
|
||
|
||
### 6.2 三维网格 SBCmesh.dat（Mesh_3D，FemType = 4 / 5）
|
||
|
||
见上文 [SBCmesh.dat 网格格式](#sbcmeshdat-网格格式mesh_3d)。
|
||
|
||
### 6.3 二维网格 `.dat` 文件（Mesh_2D，FemType 0–3）
|
||
|
||
由 `Mesh_2D::GetMesh()` 顺序解析，字段顺序固定：
|
||
|
||
```
|
||
NbrVertex
|
||
Vertex （每行 x y，z 读入时置 0）
|
||
NbrEdge
|
||
Edge （每行 顶点索引0 顶点索引1）
|
||
NbrTri
|
||
Tri （每行 顶点索引0 1 2）
|
||
EdgeOfTri （每三角形 3 条边索引）
|
||
DomainOfTri （每三角形物理域编号，文件内 0-based，读入后 +1）
|
||
NbrEdges
|
||
CoonOfEdges （边界边连接信息）
|
||
DomainOfEdges （边界边所属域）
|
||
normal （边界法向，块大小由 JSON 中 NbrBoundary 决定）
|
||
NbrCopyOfEdges
|
||
CopyOfEdges
|
||
NbrCopyOfVertexs
|
||
CopyOfVertexs
|
||
```
|
||
|
||
---
|
||
|
||
### 6.3 输出文件格式
|
||
|
||
#### 散射问题（`Post_2D_Scatter::OutputData`）
|
||
|
||
| 文件名 | 格式 | 内容 |
|
||
|--------|------|------|
|
||
| `Ex` | 首行 `//`，随后每行 `实部 虚部` | 各顶点 Ex |
|
||
| `Ey` | 同上 | 各顶点 Ey |
|
||
| `Ez` | 同上 | 各顶点 Ez |
|
||
| `normE` | 首行 `//`，随后每行一个浮点数 | 各顶点 \|E\| |
|
||
|
||
#### 本征模式
|
||
|
||
额外输出 `neff`：每行 `实部 虚部`（有效折射率）。多模态时 `Ex/Ey/Ez/normE` 以 `//` 分隔各模态块。
|
||
|
||
#### 本征频率
|
||
|
||
额外输出 `freq`：每行 `实部 虚部`（特征频率）。
|
||
|
||
---
|
||
|
||
## 7. 对外 API 与集成方式
|
||
|
||
### 7.1 数据结构
|
||
|
||
```cpp
|
||
struct OpticsFEMData {
|
||
double test1; // 保留
|
||
double test2; // 保留
|
||
char* data; // 指向 UTF-8 JSON 字符串（需保证生命周期覆盖调用期间）
|
||
};
|
||
```
|
||
|
||
### 7.2 接口函数
|
||
|
||
| 函数 | 说明 | 返回值 |
|
||
|------|------|--------|
|
||
| `OpticsFEM_All(data)` | 读配置 → 组装 → 求解 → 后处理 | 0/1/2/3 |
|
||
| `OpticsFEM_Test(data)` | 向 `OutFile + "test"` 写入 `"test success"` | 1 |
|
||
|
||
### 7.3 DLL 导出（预留）
|
||
|
||
`FEM_Interface.h` 底部注释代码可在编译为 SHARED 库时启用：
|
||
|
||
```cpp
|
||
extern "C" {
|
||
_declspec(dllexport) int OpticsFEM_ALL(OpticsFEMData data) {
|
||
return OpticsFEM_API::OpticsFEM_All(data);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 测试算例与数据集
|
||
|
||
测试数据位于上级目录 **`测试数据集/`**，源码树内**不包含**算例文件。
|
||
|
||
### 8.1 散射边界条件算例
|
||
|
||
| 文件夹 | JSON | 网格 | 测试内容 |
|
||
|--------|------|------|----------|
|
||
| `bele/` | `bele.json` | `project_3.dat` | 背景等效场边界 + PML |
|
||
| `pml_xy/` | `pml_xy.json` | `project_1.dat` | XY 方向 PML |
|
||
| `epd/` | `epd.json` | `project_4.dat` | 电偶极子源 |
|
||
| `mpd/` | `mpd.json` | `project_4.dat` | 磁偶极子源 |
|
||
| `mag/` | `mag.json` | `project_4.dat` | 磁场边界 |
|
||
| `scd/` | `scd.json` | `project_4.dat` | 面电流密度 |
|
||
| `port/` | `port.json` | `meshData_Port.txt` | 波导端口 |
|
||
|
||
### 8.2 波导/光纤本征模算例
|
||
|
||
| 文件夹 | 说明 |
|
||
|--------|------|
|
||
| `条形波导/case1` | 条形波导本征模 |
|
||
| `脊波导/case2` | 脊波导 |
|
||
| `槽波导/case3` | 槽波导 |
|
||
| `SPP波导/case4` | 表面等离激元波导 |
|
||
| `光子晶体波导/case5` | 光子晶体波导 |
|
||
| `阶跃折射率光纤/case6` | 阶跃折射率光纤 |
|
||
| `空芯光纤/case7` | 空芯光纤 |
|
||
| `多模光纤/case8` | 多模光纤 |
|
||
| `多芯光纤/case9` | 多芯光纤 |
|
||
| `光子晶体光纤/case10` | 光子晶体光纤 |
|
||
| `一维光子晶体/case11` | 一维光子晶体 |
|
||
| `方格光子晶体/case12` | 方格光子晶体 |
|
||
| `衍射光栅/case13` | 衍射光栅 |
|
||
| `表面等离激元线光栅/case14` | SPP 线光栅 |
|
||
| `scatter_modal/` | 散射模态 |
|
||
|
||
每个本征算例通常包含：`caseN.json`（或 `mesh.json`）、`project_*.dat` 网格，部分含 `.brep` 几何源文件。
|
||
|
||
---
|
||
|
||
## 9. 代码阅读路径
|
||
|
||
建议按以下顺序阅读，建立从入口到输出的完整认知：
|
||
|
||
| 序号 | 文件 | 阅读目标 |
|
||
|------|------|----------|
|
||
| 1 | `test/Test_Main.cpp` | 入口，默认读 `sbc3d.json`（本征改为 `eigen3d.json`） |
|
||
| 2 | `Interface/FEM_Interface.cpp` | FemType 路由（**4→3D散射**, **5→3D本征**） |
|
||
| 3 | `test/Test_ReadData.cpp` | JSON → Phy/Material（含 `sbc` 块） |
|
||
| 4 | `mesh/Mesh_Interface.cpp` | `Mesh_3D::GetMesh` 读 SBCmesh.dat |
|
||
| 5 | `kernel/Assemble_kernel.cpp` | `OpticsFEM_3D_Scatter` / `OpticsFEM_3D_EigenFreq` 总控 |
|
||
| 6 | `kernel/Assemble_Scatter_3D_Boundary.cpp` | 3D SBC 边界积分（FemType=4） |
|
||
| 7 | `kernel/Assemble_Scatter_Equation.cpp` | 散射四面体体积方程（FemType=4） |
|
||
| 8 | `kernel/Assemble_EigenFreq_Equation.cpp` | 本征 A/B 体积积分（FemType=5） |
|
||
| 9 | `kernel/Assemble_EigenFreq_Boundary.cpp` | 本征 PEC/PBC（FemType=5） |
|
||
| 10 | `complex/complexsolver.cpp` | Eigen 稀疏线性求解（FemType=4） |
|
||
| 11 | `post/Post_CalEletric.cpp` | `Post_3D_Scatter::GetElectric` |
|
||
| 12 | `post/Post_Output.cpp` | 写入 OutFile |
|
||
|
||
### 调试建议
|
||
|
||
- 在 `FEM_Interface.cpp` 各 `FemType` 分支入口设断点，确认路由正确。
|
||
- 散射分支已调用 `Test_OutputMatrix()`，可在 Assemble 后检查矩阵非零元。
|
||
- Post 完成后检查 `OutFile/` 目录内容。
|
||
|
||
---
|
||
|
||
## 10. 常见问题排查
|
||
|
||
| 现象 | 可能原因 | 处理措施 |
|
||
|------|----------|----------|
|
||
| `cmake` 无法识别 | CMake 未加入 PATH | 使用 VS 自带 CMake 完整路径 |
|
||
| `LNK1181: eigensolver.lib` | 旧版仍链接外部库 | 确认 `EIGENSOLVER_STATIC` 已启用 |
|
||
| 运行无输出、无 OutFile | 缺少 `complexsolver.exe` 或路径错误 | 检查 `complex/` 目录及工作目录 |
|
||
| 无法打开 `sbc3d.json` | 工作目录不含 JSON | 复制到 `Release/` 或在其中运行 |
|
||
| 无法打开 `SBCmesh.dat` | `MeshFile` 路径不匹配 | 确保 `.dat` 与 exe 同目录 |
|
||
| 无法打开 `eigen3d.json` | 本征算例 JSON 缺失 | 复制到 `eigen3D/Release/` 并确认 Test_Main 文件名 |
|
||
| 控制台打印 `err` | JSON 缺少或错误 `FemType` | 检查 JSON 完整性 |
|
||
| 编译警告 C4819 | Eigen 头文件编码 | 不影响功能，可忽略 |
|
||
| BELE 表达式报错 | 表达式语法错误或变量未定义 | 检查 muparser 支持的函数（如 `sin`, `pi`, `x`） |
|
||
|
||
---
|
||
|
||
## 附录 A：核心类关系图
|
||
|
||
```
|
||
OpticsFEM_API
|
||
├── Phy_WaveOpticsModel ← JSON 边界/激励
|
||
├── MaterialLib ← JSON 材料
|
||
├── Mesh_3D ← SBCmesh.dat（FemType=4/5）
|
||
├── OpticsFEM_3D_Scatter ← FemType=4：A·x=b
|
||
│ ├── Assemble（体积 + SBC）
|
||
│ ├── Solver_LdaDom → complexsolver
|
||
│ └── Post_3D_Scatter → Ex/Ey/Ez/normE
|
||
└── OpticsFEM_3D_EigenFreq ← FemType=5：A·x=λB·x
|
||
├── Assemble（A 刚度 + B 质量 + PEC/PBC）
|
||
├── Test_OutputMatrix → Ai/Aj/Av, Bi/Bj/Bv
|
||
└── （待接）Solver_EigenFreq → Post_3D_EigenFreq
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 B：FemType 与 JSON 关键参数对照
|
||
|
||
| FemType | 关键 JSON 参数 | 输出特征量 |
|
||
|---------|----------------|------------|
|
||
| 0 | `lambda0`, `NbrMode`, `searchValue` | `neff`, Ex/Ey/Ez |
|
||
| 1 | `lambda0`, `NbrMode`, `searchValue`, `EletricType` | `freq`, Ex/Ey/Ez |
|
||
| 2 | `lambda`, 边界块 | Ex/Ey/Ez/normE |
|
||
| 3 | `freq`, 边界块 | Ex/Ey/Ez/normE |
|
||
| **4** | **`lambda`, `sbc` 块, `SBCmesh.dat`** | **Ex/Ey/Ez/normE** |
|
||
| **5** | **`NbrMode`, `searchValue`, `lambda0`, `SBCmesh.dat`** | **Ai/Aj/Av, Bi/Bj/Bv**（当前）；后续 **freq, Ex/Ey/Ez** |
|
||
|
||
---
|
||
|
||
## 附录 C：文档修订记录
|
||
|
||
| 版本 | 日期 | 修订内容 |
|
||
|------|------|----------|
|
||
| v3.0 | 2026-06-09 | 新增 FemType=5 三维本征频率；scat3D/eigen3D 双构建目录；eigen3d.json；A/B 矩阵导出 |
|
||
| v2.0 | 2026-06-08 | 适配 3D 版：FemType=4、sbc3d 算例、SBCmesh 格式、CMake complexsolver |
|
||
| v1.0 | 2026-06-03 | 初版（2D opticsfem-master） |
|
||
|
||
---
|
||
|
||
*本文档基于 `3D opticsfem-master` 当前代码状态编制。三维主算例：`sbc3d.json`（散射 FemType=4）+ `eigen3d.json`（本征 FemType=5），共用 `SBCmesh.dat`。*
|