606 lines
22 KiB
Markdown
606 lines
22 KiB
Markdown
# OpticsFEM 二维光学有限元程序 — 开发与使用手册
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 文档版本 | v1.0 |
|
||
| 编制日期 | 2026-06-03 |
|
||
| 适用代码 | `opticsfem-master/` |
|
||
| 适用平台 | Windows x64，Visual Studio 2026（18）/ MSVC |
|
||
| 关联文档 | `OpticsFEM_LASPCEM_接口规范.md` |
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [概述](#1-概述)
|
||
2. [从源代码到可执行文件](#2-从源代码到可执行文件)
|
||
3. [软件架构与模块划分](#3-软件架构与模块划分)
|
||
4. [程序执行流程](#4-程序执行流程)
|
||
5. [数据流与对象模型](#5-数据流与对象模型)
|
||
6. [对外 API 规范](#6-对外-api-规范)
|
||
7. [输入与输出文件规范](#7-输入与输出文件规范)
|
||
8. [构建与部署](#8-构建与部署)
|
||
9. [算例运行指南](#9-算例运行指南)
|
||
10. [代码阅读路径](#10-代码阅读路径)
|
||
11. [求解器依赖说明](#11-求解器依赖说明)
|
||
12. [常见问题与排查](#12-常见问题与排查)
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
### 1.1 程序定位
|
||
|
||
OpticsFEM 是一套基于 C++ 实现的**二维矢量有限元（FEM）光学电磁仿真内核**，采用 Nedelec 边元离散麦克斯韦方程，支持以下三类问题：
|
||
|
||
| FemType | 问题类型 | 核心类 |
|
||
|---------|----------|--------|
|
||
| 0 | 本征模式（EigenMode） | `OpticsFEM_2D_EigenMode` |
|
||
| 1 | 本征频率（EigenFreq） | `OpticsFEM_2D_EigenFreq` |
|
||
| 2 | 散射（Scatter，按波长） | `OpticsFEM_2D_Scatter` |
|
||
| 3 | 散射（Scatter，按频率） | `OpticsFEM_2D_Scatter` |
|
||
|
||
程序通过 **JSON 字符串** 描述物理模型、材料参数、边界条件及求解配置；通过 **`.dat` 文本文件** 描述三角网格。计算结果以文本文件形式输出至指定目录。
|
||
|
||
### 1.2 入口程序与可执行文件的关系
|
||
|
||
`test/Test_Main.cpp` 并非完整程序，而是**可执行文件的入口模块**。其职责限于：
|
||
|
||
1. 从本地文件系统读取 JSON 配置文件；
|
||
2. 构造 `OpticsFEMData` 结构体；
|
||
3. 调用统一 API `OpticsFEM_API::OpticsFEM_All()` 触发完整求解流程。
|
||
|
||
可执行文件 `OpticsFEM.exe` 由 CMake 将 `Test_Main.cpp` 与项目中全部业务源文件（约 70 余个 `.cpp` 单元）**编译并链接**为单一二进制产物。操作系统启动进程时，自 `main()` 函数开始执行；后续全部计算逻辑由 `FEM_Interface.cpp` 及其调用的各功能模块完成。
|
||
|
||
### 1.3 设计原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| 单一 API 入口 | 外部调用方仅需调用 `OpticsFEM_All()`，无需感知内部分支 |
|
||
| JSON 为配置语言 | 物理、材料、边界、求解参数均通过 JSON 字段传递 |
|
||
| 前后端解耦 | `Test_Main.cpp` 可替换为 GUI、脚本或 DLL 宿主，接口不变 |
|
||
| 模块化组装 | 网格、物理、材料、组装、求解、后处理分层实现 |
|
||
|
||
---
|
||
|
||
## 2. 从源代码到可执行文件
|
||
|
||
### 2.1 构建系统
|
||
|
||
项目采用 **CMake** 管理构建，配置文件为 `opticsfem-master/CMakeLists.txt`。目标产物定义如下：
|
||
|
||
```cmake
|
||
add_executable(OpticsFEM
|
||
"test/Test_Main.cpp"
|
||
${PARSER} ${COMMON} ${GAUSS} ${BF}
|
||
${MESH} ${MATERIAL} ${PHY}
|
||
${SOLVER} ${POST} ${KERNEL}
|
||
${TEST} ${INTERFACE}
|
||
"post/Post_GetEb.cpp"
|
||
)
|
||
target_compile_definitions(OpticsFEM PRIVATE EIGENSOLVER_STATIC)
|
||
set(CMAKE_CXX_STANDARD 17)
|
||
```
|
||
|
||
### 2.2 编译链接流程
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ 源文件层 │
|
||
│ Test_Main.cpp, FEM_Interface.cpp, Mesh_Interface.cpp, ... │
|
||
└────────────────────────────┬─────────────────────────────────────┘
|
||
│ cmake .. -G "Visual Studio 18 2026" -A x64
|
||
▼
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ 工程生成层 │
|
||
│ build/OpticsFEM.vcxproj, build/Project.slnx │
|
||
└────────────────────────────┬─────────────────────────────────────┘
|
||
│ cmake --build . --config Release
|
||
▼
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ 编译层（Translation） │
|
||
│ 每个 .cpp → 对应 .obj 目标文件 │
|
||
└────────────────────────────┬─────────────────────────────────────┘
|
||
│ 链接（Linking）
|
||
▼
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ 产物层 │
|
||
│ build/Release/OpticsFEM.exe │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**编译（Compile）**：将各翻译单元（`.cpp`）独立转换为目标文件（`.obj`）。`#include` 头文件仅提供声明，不参与链接。
|
||
|
||
**链接（Link）**：合并全部 `.obj`，解析跨文件符号引用，以 `Test_Main.cpp` 中的 `main()` 作为进程入口，生成最终 `.exe`。
|
||
|
||
### 2.3 第三方依赖
|
||
|
||
| 依赖 | 位置 | 用途 |
|
||
|------|------|------|
|
||
| Eigen | `opticsfem-master/Eigen/` | 稠密/稀疏矩阵运算 |
|
||
| nlohmann/json | `opticsfem-master/nlohmann/` | JSON 解析 |
|
||
| muparser 派生库 | `opticsfem-master/parser/` | BELE 等边界表达式求值 |
|
||
|
||
### 2.4 关于 Test_Main.cpp 中未使用的变量
|
||
|
||
`Test_Main.cpp` 中声明的 `Phy_WaveOpticsModel`、`MaterialLib`、`Mesh_2D` 等对象在 `main()` 内**未被直接使用**。实际对象实例化与数据注入在 `FEM_Interface.cpp::OpticsFEM_All()` 中完成。上述声明为历史遗留或调试用途；注释块（第 39–58 行）保留了手动分步调用流程的旧版写法，现行标准路径为 `OpticsFEM_All()` 一站式调用。
|
||
|
||
---
|
||
|
||
## 3. 软件架构与模块划分
|
||
|
||
### 3.1 目录结构与职责
|
||
|
||
```
|
||
opticsfem-master/
|
||
├── test/
|
||
│ ├── Test_Main.cpp # 进程入口；读取 JSON 文件
|
||
│ ├── Test_ReadData.cpp # JSON → Phy / Material 解析实现
|
||
│ └── Test_OutputData.cpp # 调试输出
|
||
├── Interface/
|
||
│ ├── FEM_Interface.h # 对外 API 声明
|
||
│ └── FEM_Interface.cpp # FemType 路由与全流程调度
|
||
├── phy/ # 物理模型：边界条件、激励
|
||
├── material/ # 材料库：ε、μ、σ、n、k
|
||
├── mesh/ # 网格：.dat 读取与拓扑查询
|
||
├── kernel/ # FEM 组装：方程与边界积分
|
||
├── solver/ # 数值求解：线性方程组 / 特征值
|
||
├── post/ # 后处理：DOF → 顶点场 → 文件输出
|
||
├── function/ # Nedelec 基函数、高斯积分
|
||
├── parser/ # 数学表达式解析器
|
||
└── Eigen/ # 线性代数库（第三方）
|
||
```
|
||
|
||
### 3.2 模块依赖关系
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph entry [入口层]
|
||
TM[Test_Main.cpp]
|
||
API[FEM_Interface.cpp]
|
||
end
|
||
|
||
subgraph io [数据读入层]
|
||
PHY[phy]
|
||
MAT[material]
|
||
MSH[mesh]
|
||
end
|
||
|
||
subgraph core [计算核心层]
|
||
KRN[kernel]
|
||
SLV[solver]
|
||
end
|
||
|
||
subgraph output [输出层]
|
||
PST[post]
|
||
end
|
||
|
||
TM --> API
|
||
API --> PHY
|
||
API --> MAT
|
||
API --> MSH
|
||
API --> KRN
|
||
KRN --> SLV
|
||
KRN --> PST
|
||
SLV --> PST
|
||
PHY --> KRN
|
||
MAT --> KRN
|
||
MSH --> KRN
|
||
MSH --> PST
|
||
PHY --> PST
|
||
```
|
||
|
||
### 3.3 核心类层次（二维）
|
||
|
||
| 类名 | 职责 |
|
||
|------|------|
|
||
| `Phy_WaveOpticsModel` | 存储边界类型、BELE/PML/EF/SBC 等边界数据 |
|
||
| `MaterialLib` | 存储各物理域材料参数 |
|
||
| `Mesh_2D` | 存储顶点、边、三角形及域编号 |
|
||
| `OpticsFEM_2D_Scatter` | 散射问题组装、求解、后处理调度 |
|
||
| `Solver_LdaDom` | 散射线性方程组求解接口 |
|
||
| `Post_2D_Scatter` | 散射结果电场插值与输出 |
|
||
|
||
---
|
||
|
||
## 4. 程序执行流程
|
||
|
||
### 4.1 顶层调用序列
|
||
|
||
以 `FemType = 2`（散射，bele 算例）为例，完整调用序列为：
|
||
|
||
```
|
||
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()
|
||
├─ OpticsFEM_2D_Scatter::Run()
|
||
└─ OpticsFEM_2D_Scatter::Post(outFile)
|
||
```
|
||
|
||
### 4.2 Assemble 阶段内部流程
|
||
|
||
`OpticsFEM_2D_Scatter::Assemble()`（`kernel/Assemble_kernel.cpp`）执行以下步骤：
|
||
|
||
1. **确定矩阵类型**：根据 PML、SBC、复材料等条件判定采用实数或复数稀疏矩阵；
|
||
2. **体积积分**：`Assemble_WaveEquation()` — 在各三角形单元上积分麦克斯韦弱形式；
|
||
3. **边界积分**（按 JSON 配置条件触发）：
|
||
- `Assemble_PEC_ELE()` — 理想导体 / 电边界
|
||
- `Assemble_PBC()` — 周期边界
|
||
- `Assemble_BELE()` — 边界等效源（bele 算例）
|
||
- `Assemble_PML()` — 完美匹配层
|
||
- `Assemble_Port()` — 端口激励
|
||
- 等
|
||
4. **约束处理**：对 Dirichlet 型边界自由度施加罚函数或消元。
|
||
|
||
输出：稀疏矩阵 **A**、右端向量 **b**、预处理矩阵 **P**。
|
||
|
||
### 4.3 Run 阶段
|
||
|
||
```cpp
|
||
void OpticsFEM_2D_Scatter::Run()
|
||
{
|
||
_mSolver->SetParam(&_mA_complex, &_mB_complex, &_mP_complex);
|
||
_mSolver->Run(&_mX);
|
||
}
|
||
```
|
||
|
||
`Solver_LdaDom::Run()` 调用 `solveComplexLinearEqu()`（`solver/interface.cpp`），将 CSR 格式矩阵写入临时文件，并启动外部求解器 `complex/complexsolver.exe` 完成迭代求解。解向量经预处理矩阵变换后存入 `_mX`。
|
||
|
||
### 4.4 Post 阶段
|
||
|
||
```cpp
|
||
void OpticsFEM_2D_Scatter::Post(string file)
|
||
{
|
||
_mPost->GetMesh(_mMesh);
|
||
_mPost->GetSolver(_mSolver);
|
||
_mPost->GetPhy(_mPhy);
|
||
_mPost->GetResult(&_mX);
|
||
_mPost->GetElectric(); // 边 DOF → 顶点 Ex/Ey/Ez
|
||
_mPost->OutputData(file); // 写入 OutFile/
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 数据流与对象模型
|
||
|
||
### 5.1 端到端数据流
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph inputs [外部输入]
|
||
J["bele.json\n(JSON 字符串)"]
|
||
D["project_3.dat\n(网格文件)"]
|
||
end
|
||
|
||
subgraph parsed [内存对象]
|
||
P["Phy_WaveOpticsModel\n边界/激励"]
|
||
M["MaterialLib\n材料参数"]
|
||
G["Mesh_2D\n网格拓扑"]
|
||
end
|
||
|
||
subgraph linear [离散方程]
|
||
A["稀疏矩阵 A"]
|
||
B["右端向量 b"]
|
||
X["解向量 x"]
|
||
end
|
||
|
||
subgraph files [文件输出]
|
||
O["OutFile/Ex, Ey, Ez, normE"]
|
||
end
|
||
|
||
J -->|Test_ReadData| P
|
||
J -->|Test_ReadData| M
|
||
J -->|MeshFile 字段| D
|
||
D -->|GetMesh| G
|
||
P --> A
|
||
M --> A
|
||
G --> A
|
||
P --> B
|
||
A --> X
|
||
B --> X
|
||
X --> O
|
||
G --> O
|
||
```
|
||
|
||
### 5.2 JSON 字段到内存对象的映射
|
||
|
||
| JSON 字段组 | 目标对象 | 解析函数 |
|
||
|-------------|----------|----------|
|
||
| `FemType`, `EletricType`, `BoundaryFlag`, `bele`, `ef`, `pml`, `sbc`, … | `Phy_WaveOpticsModel` | `Phy_WaveOpticsModel::Test_ReadData()` |
|
||
| `NbrDomain`, `epsilonrR/I`, `murR/I`, `n`, `k`, `sigma`, … | `MaterialLib` | `MaterialLib::Test_ReadData()` |
|
||
| `MeshFile` | 网格文件路径 | `Mesh_2D::GetMesh()` |
|
||
| `lambda` / `freq`, `NbrMode`, `searchValue`, … | 求解器参数 | `Solver_*::GetSolver()` |
|
||
|
||
### 5.3 bele 算例配置摘要
|
||
|
||
| 配置项 | 值 | 含义 |
|
||
|--------|-----|------|
|
||
| `FemType` | 2 | 散射问题 |
|
||
| `EletricType` | 2 | 求解完整电场 E |
|
||
| `lambda` | 1 | 真空波长 |
|
||
| `bele.index` | [4] | 边界域 4 施加 BELE |
|
||
| `bele.Eby` | `sin(2*pi*x)` | 边界切向电场解析表达式 |
|
||
| `ef` | 边界 1 电场激励 | 等效 Dirichlet 激励 |
|
||
| `pml` | 4 个吸收层 | PML 参数 |
|
||
| `MeshFile` | `project_3.dat` | 网格文件 |
|
||
| `OutFile` | `./OutFile` | 输出目录 |
|
||
|
||
---
|
||
|
||
## 6. 对外 API 规范
|
||
|
||
### 6.1 数据结构
|
||
|
||
```cpp
|
||
struct OpticsFEMData {
|
||
double test1; // 保留字段
|
||
double test2; // 保留字段
|
||
char* data; // UTF-8 JSON 字符串（单行或紧凑格式）
|
||
};
|
||
```
|
||
|
||
### 6.2 接口函数
|
||
|
||
```cpp
|
||
class OpticsFEM_API {
|
||
public:
|
||
// 完整求解流程：读配置 → 组装 → 求解 → 后处理
|
||
static int OpticsFEM_All(OpticsFEMData data);
|
||
|
||
// 连通性测试：向 OutFile 写入 "test success"
|
||
int OpticsFEM_Test(OpticsFEMData data);
|
||
};
|
||
```
|
||
|
||
### 6.3 返回值
|
||
|
||
| 返回值 | 含义 |
|
||
|--------|------|
|
||
| 0 | `FemType` 无法识别 |
|
||
| 1 | 本征模式完成 |
|
||
| 2 | 本征频率完成 |
|
||
| 3 | 散射完成 |
|
||
|
||
### 6.4 集成方式
|
||
|
||
**方式 A — 独立可执行文件（当前 `Test_Main.cpp` 模式）**
|
||
|
||
从文件读取 JSON，调用 API，适用于本地验证与回归测试。
|
||
|
||
**方式 B — 动态库宿主（注释代码预留）**
|
||
|
||
`FEM_Interface.h` 底部预留 `extern "C"` 导出声明，可将内核编译为 DLL 供前端或其他语言调用。
|
||
|
||
---
|
||
|
||
## 7. 输入与输出文件规范
|
||
|
||
### 7.1 JSON 配置文件
|
||
|
||
- **格式**：单行 UTF-8 JSON 或紧凑 JSON；
|
||
- **读取方式**：`Test_Main.cpp` 使用 `getline()` 读取整行；
|
||
- **必填公共字段**：`FemType`, `NbrBoundary`, `BoundaryFlag`, `NbrDomain`, `MeshFile`, `OutFile`；
|
||
- **边界扩展字段**（可选，按 `js.contains` 判定）：`bele`, `ef`, `pml`, `sbc`, `mag`, `scd`, `pbc`, `mpd`, `epd`, `port`, `beam`。
|
||
|
||
详细字段定义参见 `OpticsFEM_LASPCEM_接口规范.md` 第 2.3 节。
|
||
|
||
### 7.2 二维网格 `.dat` 文件
|
||
|
||
由 `Mesh_2D::GetMesh()`（`mesh/Mesh_Interface.cpp`）顺序解析，字段顺序为：
|
||
|
||
```
|
||
NbrVertex → Vertex → NbrEdge → Edge → NbrTri → Tri
|
||
→ EdgeOfTri → DomainOfTri → NbrEdges → CoonOfEdges
|
||
→ DomainOfEdges → normal → CopyOfEdges → ...
|
||
```
|
||
|
||
顶点坐标为二维 `(x, y)`，第三分量在读取时置零。
|
||
|
||
### 7.3 输出文件
|
||
|
||
散射问题（`Post_2D_Scatter::OutputData`）在 `OutFile` 目录下生成：
|
||
|
||
| 文件名 | 内容 |
|
||
|--------|------|
|
||
| `Ex` | 各顶点 Ex 分量（实部 虚部，逐行） |
|
||
| `Ey` | 各顶点 Ey 分量 |
|
||
| `Ez` | 各顶点 Ez 分量 |
|
||
| `normE` | 各顶点电场模 |
|
||
|
||
本征问题额外输出 `neff` 或 `freq` 文件。
|
||
|
||
---
|
||
|
||
## 8. 构建与部署
|
||
|
||
### 8.1 环境要求
|
||
|
||
| 组件 | 要求 |
|
||
|------|------|
|
||
| 操作系统 | Windows 10/11 x64 |
|
||
| 编译器 | Visual Studio 2026（18）Community，工作负载「使用 C++ 的桌面开发」 |
|
||
| 构建工具 | CMake ≥ 3.8（VS 自带或独立安装） |
|
||
| C++ 标准 | C++17 |
|
||
|
||
### 8.2 构建命令
|
||
|
||
```powershell
|
||
# 配置 CMake 路径（若未加入系统 PATH）
|
||
$env:Path += ";C:\Program Files\Microsoft Visual Studio\18\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin"
|
||
|
||
cd opticsfem-master
|
||
mkdir build -Force
|
||
cd build
|
||
|
||
cmake .. -G "Visual Studio 18 2026" -A x64
|
||
cmake --build . --config Release
|
||
```
|
||
|
||
产物路径：`build/Release/OpticsFEM.exe`
|
||
|
||
### 8.3 运行时目录结构
|
||
|
||
散射算例（bele）最小部署结构：
|
||
|
||
```
|
||
Release/
|
||
├── OpticsFEM.exe
|
||
├── bele.json # 输入配置（文件名与 Test_Main.cpp 中 fd.open 一致）
|
||
├── project_3.dat # 网格（与 JSON 中 MeshFile 一致）
|
||
└── complex/
|
||
└── complexsolver.exe # 外部线性求解器（运行时必需）
|
||
```
|
||
|
||
本征算例另需：
|
||
|
||
```
|
||
real_solver/real # 或 real_solver 目录下对应可执行文件
|
||
complex_solver/complex
|
||
```
|
||
|
||
### 8.4 关于 eigen_solver 静态链接
|
||
|
||
当前工程已将 `solver/eigen_solver.cpp` 编入可执行文件，并通过宏 `EIGENSOLVER_STATIC` 取消 DLL 导入/导出修饰，**不再依赖** `lib/eigensolver.lib`。该模块服务于本征模式/本征频率问题（`realEigenSolver` / `complexEigenSolver`），运行时仍依赖 `real_solver/` 与 `complex_solver/` 目录下的外部可执行文件。
|
||
|
||
---
|
||
|
||
## 9. 算例运行指南
|
||
|
||
### 9.1 标准运行步骤
|
||
|
||
**步骤 1 — 编译**
|
||
|
||
执行第 8.2 节构建命令，确认生成 `OpticsFEM.exe`。
|
||
|
||
**步骤 2 — 配置入口 JSON 文件名**
|
||
|
||
编辑 `test/Test_Main.cpp` 第 28 行：
|
||
|
||
```cpp
|
||
fd.open("bele.json"); // 改为目标算例 JSON 文件名
|
||
```
|
||
|
||
修改后须重新编译。
|
||
|
||
**步骤 3 — 部署输入文件**
|
||
|
||
将 JSON 及 `MeshFile` 指定的 `.dat` 文件复制至 `build/Release/` 目录。
|
||
|
||
**步骤 4 — 部署外部求解器**
|
||
|
||
将 `complex/complexsolver.exe` 置于 `Release/complex/` 目录（路径相对于工作目录）。
|
||
|
||
**步骤 5 — 执行**
|
||
|
||
```powershell
|
||
cd build/Release
|
||
.\OpticsFEM.exe
|
||
```
|
||
|
||
**步骤 6 — 验证输出**
|
||
|
||
检查 `OutFile/` 目录是否生成 `Ex`、`Ey`、`Ez`、`normE`。
|
||
|
||
### 9.2 切换算例
|
||
|
||
| 操作 | 说明 |
|
||
|------|------|
|
||
| 更换 JSON | 修改 `Test_Main.cpp` 中 `fd.open()` 文件名，或使用同名复制 |
|
||
| 更换网格 | 确保 JSON 中 `MeshFile` 字段与实际 `.dat` 文件名一致 |
|
||
| 更换问题类型 | 修改 JSON 中 `FemType`；程序自动路由至对应求解分支 |
|
||
|
||
测试数据集位于 `测试数据集/`， subdirectory 名称即边界/物理类型（如 `bele/`、`scd/`、`pml_xy/`）。
|
||
|
||
---
|
||
|
||
## 10. 代码阅读路径
|
||
|
||
建议按以下顺序阅读，以建立自入口至输出的完整认知：
|
||
|
||
| 序号 | 文件 | 阅读目标 |
|
||
|------|------|----------|
|
||
| 1 | `test/Test_Main.cpp` | 进程入口、JSON 文件读取 |
|
||
| 2 | `Interface/FEM_Interface.cpp` | FemType 路由、三阶段调度 |
|
||
| 3 | `test/Test_ReadData.cpp` | JSON 字段解析逻辑 |
|
||
| 4 | `mesh/Mesh_Interface.cpp` | `.dat` 网格格式 |
|
||
| 5 | `kernel/Assemble_kernel.cpp` | Assemble / Run / Post 总控 |
|
||
| 6 | `kernel/Assemble_Scatter_2D_Boundary.cpp` | BELE / PML / EF 等边界组装 |
|
||
| 7 | `kernel/Assemble_Scatter_Equation.cpp` | 体积方程组装 |
|
||
| 8 | `solver/Solver_Interface.cpp` | 求解器参数与 Run 实现 |
|
||
| 9 | `solver/interface.cpp` | 外部求解器调用封装 |
|
||
| 10 | `post/Post_Output.cpp` | 结果文件格式 |
|
||
|
||
### 调试建议
|
||
|
||
- 在 `FEM_Interface.cpp` 各 `FemType` 分支入口设置断点，确认路由正确；
|
||
- 在 `Assemble()` 返回后检查矩阵非零元数量（`Test_OutputMatrix()` 已在散射分支调用）；
|
||
- 在 `Post()` 返回后检查 `OutFile/` 目录。
|
||
|
||
---
|
||
|
||
## 11. 求解器依赖说明
|
||
|
||
### 11.1 求解器分层
|
||
|
||
| 层级 | 模块 | 适用问题 | 运行时依赖 |
|
||
|------|------|----------|------------|
|
||
| 特征值求解 | `eigen_solver.cpp` | FemType 0, 1 | `real_solver/real`, `complex_solver/complex` |
|
||
| 线性方程组（实） | `interface.cpp::solveRealLinearEqu` | 实散射 | `real/realsolver.exe` |
|
||
| 线性方程组（复） | `interface.cpp::solveComplexLinearEqu` | 复散射（bele） | `complex/complexsolver.exe` |
|
||
|
||
### 11.2 外部求解器调用机制
|
||
|
||
`interface.cpp` 采用**文件交换**方式与外部求解器通信：
|
||
|
||
1. 将 CSR 格式矩阵、右端项写入当前目录临时文件；
|
||
2. 通过 `system()` 调用外部 `.exe`；
|
||
3. 读取解向量临时文件；
|
||
4. 清理临时文件。
|
||
|
||
因此，外部求解器必须与 `OpticsFEM.exe` **工作目录相对路径**正确对应，且具备可执行权限。
|
||
|
||
---
|
||
|
||
## 12. 常见问题与排查
|
||
|
||
| 现象 | 可能原因 | 处理措施 |
|
||
|------|----------|----------|
|
||
| `cmake` 无法识别 | CMake 未加入 PATH | 使用 VS 自带 CMake 完整路径，或配置环境变量 |
|
||
| `LNK1181: eigensolver.lib` | 旧版 CMakeLists 仍链接外部库 | 确认已启用 `EIGENSOLVER_STATIC` 并编入 `eigen_solver.cpp` |
|
||
| 运行无输出、无 OutFile | 缺少 `complexsolver.exe` 或路径错误 | 检查 `complex/` 目录及工作目录 |
|
||
| 无法打开 `bele.json` | 工作目录不含 JSON | 在 `Release/` 目录下运行，或复制输入文件 |
|
||
| 无法打开 `project_3.dat` | `MeshFile` 路径不匹配 | 确保 `.dat` 与 exe 同目录，或修正 JSON |
|
||
| 编译警告 C4819 | Eigen 头文件编码 | 不影响功能，可忽略 |
|
||
| `FemType` 返回 0 打印 err | JSON 缺少或错误 `FemType` 字段 | 检查 JSON 完整性 |
|
||
|
||
---
|
||
|
||
## 附录 A：FemType 路由对照表
|
||
|
||
| FemType | 求解器类 | 后处理类 | 关键 JSON 参数 |
|
||
|---------|----------|----------|----------------|
|
||
| 0 | `Solver_EigenMode` | `Post_2D_EigenMode` | `lambda0`, `NbrMode`, `searchValue` |
|
||
| 1 | `Solver_EigenFreq` | `Post_2D_EigenFreq` | `lambda0`, `NbrMode`, `searchValue` |
|
||
| 2 | `Solver_LdaDom` | `Post_2D_Scatter` | `lambda`, 边界字段 |
|
||
| 3 | `Solver_LdaDom` | `Post_2D_Scatter` | `freq`, 边界字段 |
|
||
|
||
---
|
||
|
||
## 附录 B：文档修订记录
|
||
|
||
| 版本 | 日期 | 修订内容 |
|
||
|------|------|----------|
|
||
| v1.0 | 2026-06-03 | 初版：构建流程、架构、数据流、部署与算例指南 |
|
||
|
||
---
|
||
|
||
*本文档基于 `opticsfem-master` 当前代码状态编制，若 CMakeLists 或 API 发生变更，请同步更新相应章节。*
|