Update 3D docs for FemType=4 and VS 2026 CMake

2026-06-08 17:21:00 +08:00 · 2026-06-08 17:21:00 +08:00 · 54279fe532
parent 1abbb6bf71
commit 54279fe532
3 changed files with 312 additions and 126 deletions
--- a/opticsfem-master/CMakeSettings.json
+++ b/opticsfem-master/CMakeSettings.json
@ -1,15 +1,26 @@
 {
  "configurations": [
+    {
+      "name": "x64-Release",
+      "generator": "Visual Studio 18 2026",
+      "configurationType": "Release",
+      "inheritEnvironments": [ "msvc_x64_x64" ],
+      "buildRoot": "${projectDir}\\build",
+      "installRoot": "${projectDir}\\out\\install\\${name}",
+      "cmakeCommandArgs": "-A x64",
+      "buildCommandArgs": "",
+      "ctestCommandArgs": ""
+    },
    {
      "name": "x64-Debug",
-      "generator": "Ninja",
+      "generator": "Visual Studio 18 2026",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x64_x64" ],
-      "buildRoot": "${projectDir}\\build\\${name}",
+      "buildRoot": "${projectDir}\\build",
      "installRoot": "${projectDir}\\out\\install\\${name}",
-      "cmakeCommandArgs": "",
+      "cmakeCommandArgs": "-A x64",
      "buildCommandArgs": "",
      "ctestCommandArgs": ""
    }
  ]
-}
+}
--- a/opticsfem-master/OpticsFEM_完整使用说明与代码介绍.md
+++ b/opticsfem-master/OpticsFEM_完整使用说明与代码介绍.md
@ -2,11 +2,11 @@

 | 项目 | 说明 |
 |------|------|
-| 文档版本 | v1.0 |
-| 编制日期 | 2026-06-03 |
-| 适用代码 | `opticsfem-master/` |
-| 适用平台 | Windows x64，Visual Studio 2022/2026，MSVC |
-| 关联文档 | 上级目录 `OpticsFEM_开发与使用手册.md`、`OpticsFEM_LASPCEM_接口规范.md` |
+| 文档版本 | v2.0 |
+| 编制日期 | 2026-06-08 |
+| 适用代码 | **`3D opticsfem-master/`**（三维版，主算例 FemType=4） |
+| 适用平台 | Windows x64，**Visual Studio 2026（18）**，MSVC |
+| 关联文档 | `compare/README.md`（COMSOL 对比）、上级目录 2D 版 `opticsfem-master/` |

 ---

@ -29,16 +29,19 @@

 ### 1.1 程序定位

-**OpticsFEM** 是一套基于 C++ 实现的**二维矢量有限元（FEM）光学电磁仿真内核**。程序采用 **Nedelec 边元** 离散麦克斯韦方程，通过 JSON 配置物理模型、材料与边界条件，通过 `.dat` 文本文件读入三角网格，计算结果以文本文件输出。
+**OpticsFEM3D** 是一套基于 C++ 实现的**三维矢量有限元（FEM）光学电磁仿真内核**。程序采用 **一阶 Nedelec 边元** 离散麦克斯韦方程，通过 JSON 配置物理模型、材料与边界条件，通过 `.dat` 文本文件读入四面体网格，计算结果以文本文件输出。
+
+> **当前主算例**：`FemType = 4`，三维 SBC 散射，配置文件 `sbc3d.json`，网格 `SBCmesh.dat`。

 ### 1.2 支持的问题类型

-| FemType | 问题类型 | 驱动类 | 求解器 | 后处理 |
-|---------|----------|--------|--------|--------|
-| 0 | 本征模式（EigenMode） | `OpticsFEM_2D_EigenMode` | `Solver_EigenMode` | `Post_2D_EigenMode` |
-| 1 | 本征频率（EigenFreq） | `OpticsFEM_2D_EigenFreq` | `Solver_EigenFreq` | `Post_2D_EigenFreq` |
-| 2 | 散射（按波长 λ） | `OpticsFEM_2D_Scatter` | `Solver_LdaDom` | `Post_2D_Scatter` |
-| 3 | 散射（按频率 f） | `OpticsFEM_2D_Scatter` | `Solver_LdaDom` | `Post_2D_Scatter` |
+| 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`** |

 ### 1.3 设计原则

@ -55,39 +58,41 @@
 | nlohmann/json | `nlohmann/` | JSON 解析 |
 | muparserX 派生库 | `parser/` | BELE、SBC、端口等边界表达式求值 |

-### 1.5 运行时外部依赖（不在源码树中）
+### 1.5 运行时外部依赖

-| 路径 | 用途 |
-|------|------|
-| `complex/complexsolver.exe` | 复数线性方程组求解（散射问题） |
-| `real/realsolver.exe` | 实数线性方程组求解 |
-| `real_solver/real` | 实数广义特征值求解（本征问题） |
-| `complex_solver/complex` | 复数广义特征值求解 |
+| FemType | 依赖 | 说明 |
+|---------|------|------|
+| **4（3D 散射，推荐）** | `complex/complexsolver.exe` | **CMake 会从 `complex/complexsolver.cpp` 自动编译**（Eigen SparseLU），无需 PETSc |
+| 0–3（2D 遗留） | `complex/complexsolver.exe` 等 | 本征问题另需 `real_solver/`、`complex_solver/` |

-外部求解器通过**临时 `.dat` 文件**与主程序交换 CSR 格式矩阵，由 `system()` 启动。
+散射求解器通过**临时 `.dat` 文件**与主程序交换 CSR 格式矩阵，由 `system()` 启动。

 ---

 ## 2. 目录与文件总览

 ```
-opticsfem-master/
-├── CMakeLists.txt              # CMake 构建配置
-├── CMakeSettings.json          # Visual Studio CMake 设置
-├── Interface/                  # 对外 API 层（2 文件）
-├── test/                       # 入口与 JSON 解析（4 文件）
-├── phy/                        # 物理模型与边界条件（3 文件）
-├── material/                   # 材料库（3 文件）
-├── mesh/                       # 网格读写与拓扑查询（4 文件）
-├── kernel/                     # FEM 方程与边界组装（10 文件）
-├── solver/                     # 数值求解器接口（8 文件）
-├── post/                       # 后处理与结果输出（6 文件）
-├── function/                   # Nedelec 基函数与高斯积分（14 文件）
-├── common/                     # 公共常量与工具（3 文件）
-├── parser/                     # 数学表达式解析器（约 89 文件）
-├── nlohmann/                   # JSON 库（2 文件）
-├── Eigen/                      # 线性代数库（337 文件）
-└── build/                      # CMake 构建产物（可忽略）
+3D opticsfem-master/
+├── CMakeLists.txt              # CMake：OpticsFEM + complexsolver
+├── CMakeSettings.json          # VS CMake 设置（x64-Release）
+├── sbc3d.json                  # ★ FemType=4 默认算例配置
+├── 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 组装（含 Assemble_Scatter_3D_Boundary）
+├── solver/                     # 数值求解器接口
+├── post/                       # Post_3D_Scatter 场重构与输出
+├── function/                   # Nedelec 基函数与高斯积分
+├── common/                     # 公共常量
+├── parser/                     # 表达式解析器
+├── nlohmann/                   # JSON 库
+├── Eigen/                      # 线性代数库
+└── build/                      # CMake 构建产物（本地生成，不上传）
 ```

 **源码统计（不含 build/）：**
@ -127,7 +132,7 @@ public:
 };
 ```

-**返回值：** 0 = FemType 无法识别；1 = 本征模式完成；2 = 本征频率完成；3 = 散射完成。
+**返回值：** 0 = FemType 无法识别；1 = 本征模式；2 = 本征频率；3 = 2D 散射；**4 = 3D 散射完成**。

 ---

@ -344,14 +349,33 @@ 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 2/3 ► OpticsFEM_2D_Scatter   ──► Solver_LdaDom     ──► Post_2D_Scatter
+      └── FemType 4 ──► OpticsFEM_3D_Scatter   ──► Solver_LdaDom     ──► Post_3D_Scatter
+                              │
+                              └── Mesh_3D ← SBCmesh.dat
                              │
                              ├── kernel（Assemble：体积 + 边界积分）
                              ├── function（BF + Gauss 数值积分）
                              └── parser（边界表达式求值）
 ```

-### 4.2 完整调用序列（以 FemType=2 散射为例）
+### 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.3 完整调用序列（FemType=2，二维散射，遗留）

 ```
 main()
@ -377,7 +401,20 @@ main()
                  └─ OutputData()                写入 OutFile/
 ```

-### 4.3 数据流
+### 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 = 2（2D 遗留）：**

 ```
 bele.json ──► Phy_WaveOpticsModel（边界/激励）
@ -398,41 +435,84 @@ project_3.dat ──► Mesh_2D（网格拓扑）
 | 组件 | 要求 |
 |------|------|
 | 操作系统 | Windows 10/11 x64 |
-| 编译器 | Visual Studio 2022 或 2026，工作负载「使用 C++ 的桌面开发」 |
-| 构建工具 | CMake ≥ 3.8 |
+| 编译器 | Visual Studio 2026（18），工作负载「使用 C++ 的桌面开发」 |
+| 构建工具 | CMake ≥ 3.8（VS 自带，见下方 PATH） |
 | C++ 标准 | C++17 |

 ### 5.2 编译步骤

 ```powershell
-# 若 cmake 不在 PATH 中，追加 VS 自带 CMake 路径
-$env:Path += ";C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin"
+# 若 cmake 不在 PATH 中，追加 VS 2026 自带 CMake 路径
+$env:Path += ";C:\Program Files\Microsoft Visual Studio\18\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin"

-cd opticsfem-master
+cd "3D opticsfem-master"
 mkdir build -Force
 cd build

-# VS 2022
-cmake .. -G "Visual Studio 17 2022" -A x64
-# 或 VS 2026
 cmake .. -G "Visual Studio 18 2026" -A x64
-
 cmake --build . --config Release
 ```

 **产物路径：** `build/Release/OpticsFEM.exe`

-### 5.3 运行前准备
+**产物路径：**
+
+- `build/Release/OpticsFEM.exe`
+- `build/Release/complex/complexsolver.exe`（FemType=4 必需，CMake 自动编译）
+
+### 5.3 运行前准备（FemType = 4，推荐）

 #### 步骤 1：指定 JSON 配置文件

-编辑 `test/Test_Main.cpp` 第 28 行：
+`test/Test_Main.cpp` 默认读取 **`sbc3d.json`**：

 ```cpp
-fd.open("bele.json");   // 改为目标算例 JSON 文件名
+std::ifstream fd("sbc3d.json");
 ```

-修改后须**重新编译**。
+更换算例时，修改文件名或把目标 JSON 复制为 `sbc3d.json`。修改后须**重新编译**。
+
+#### 步骤 2：部署输入文件
+
+将 JSON 及 `MeshFile` 指定的网格文件复制到 **`build/Release/`**（与 exe 同目录）：
+
+```powershell
+Copy-Item sbc3d.json, SBCmesh.dat -Destination build\Release\
+```
+
+#### 步骤 3：确认求解器
+
+FemType=4 只需：
+
+```
+Release/
+├── OpticsFEM.exe
+├── sbc3d.json
+├── SBCmesh.dat
+└── complex/
+    └── complexsolver.exe    ← cmake --build 后自动生成
+```
+
+#### 步骤 4：执行
+
+```powershell
+cd build/Release
+.\OpticsFEM.exe
+```
+
+控制台应打印 `OpticsFEM_All returned 4`。
+
+#### 步骤 5：查看结果
+
+检查 `OutFile/` 是否生成：`Ex`、`Ey`、`Ez`、`normE`。
+
+---
+
+### 5.3b 运行前准备（FemType 0–3，2D 遗留）
+
+#### 步骤 1：指定 JSON 配置文件
+
+编辑 `test/Test_Main.cpp` 中 `fd.open(...)` 的文件名。

 #### 步骤 2：部署输入文件

@ -440,13 +520,13 @@ fd.open("bele.json");   // 改为目标算例 JSON 文件名

 #### 步骤 3：部署外部求解器

-**散射算例（FemType 2/3）最小目录：**
+**散射算例（FemType 2/3/4）最小目录：**

 ```
 Release/
 ├── OpticsFEM.exe
-├── bele.json
-├── project_3.dat
+├── *.json                    # sbc3d.json（FemType=4）或 bele.json（FemType=2）
+├── *.dat                     # SBCmesh.dat 或 project_3.dat
 └── complex/
    └── complexsolver.exe
 ```
@ -480,17 +560,27 @@ cd build/Release
 |------|------|
 | 更换 JSON | 修改 `Test_Main.cpp` 中 `fd.open()` 文件名，或将目标 JSON 复制为当前文件名 |
 | 更换网格 | 确保 JSON 中 `MeshFile` 与实际 `.dat` 文件名一致 |
-| 更换问题类型 | 修改 JSON 中 `FemType`（0/1/2/3），程序自动路由 |
+| 更换问题类型 | 修改 JSON 中 `FemType`（0/1/2/3/4），程序自动路由 |

-### 5.5 快速验证（bele 算例）
+### 5.5 快速验证（sbc3d 三维 SBC 算例）
+
+1. 编译 Release（见 5.2 节）
+2. 复制 `sbc3d.json`、`SBCmesh.dat` 到 `build/Release/`
+3. 确认 `sbc3d.json` 中 `"FemType": 4`
+4. 运行 `OpticsFEM.exe`
+5. 检查 `OutFile/` 下四个场文件
+
+与 COMSOL 对比见 `compare/README.md`。
+
+### 5.6 快速验证（bele 二维算例，遗留）

 1. 从 `../测试数据集/bele/` 复制 `bele.json` 和 `project_3.dat` 到 `build/Release/`
-2. 确认 `Test_Main.cpp` 中 `fd.open("bele.json")`
+2. 修改 `Test_Main.cpp` 中 `fd.open("bele.json")`，重新编译
 3. 部署 `complex/complexsolver.exe`
 4. 运行 `OpticsFEM.exe`
 5. 检查 `OutFile/` 下四个场文件

-### 5.6 集成到其他程序
+### 5.7 集成到其他程序

 **方式 A — 独立可执行文件（当前模式）**

@ -512,7 +602,7 @@ data.test2 = 0;
 data.data = (char*)jsonStr.data();

 int ret = OpticsFEM_API::OpticsFEM_All(data);
-// ret: 1=本征模式, 2=本征频率, 3=散射, 0=错误
+// ret: 1=本征模式, 2=本征频率, 3=2D散射, 4=3D散射, 0=错误
 ```

 ---
@ -528,8 +618,8 @@ int ret = OpticsFEM_API::OpticsFEM_All(data);

 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `FemType` | int | 0=本征模式, 1=本征频率, 2=散射(λ), 3=散射(f) |
-| `NbrBoundary` | int | 边界边数量 |
+| `FemType` | int | 0=本征模式, 1=本征频率, 2=2D散射(λ), 3=2D散射(f), **4=3D散射(λ)** |
+| `NbrBoundary` | int | 边界数量（3D 为三角面边界条数；2D 为边界面条数） |
 | `BoundaryFlag` | int[] | 每条边界的类型编码（见 3.3 节） |
 | `NbrDomain` | int | 材料物理域数量 |
 | `MeshFile` | string | 网格 `.dat` 文件路径 |
@ -548,26 +638,75 @@ int ret = OpticsFEM_API::OpticsFEM_All(data);

 | 字段 | 说明 |
 |------|------|
-| `lambda` | 真空波长（FemType=2） |
+| `lambda` | 真空波长（FemType=2 或 **4**） |
 | `freq` | 频率 GHz（FemType=3，内部换算 λ = 0.299792458/freq） |

-#### 边界扩展块（可选）
+#### 边界扩展块（2D 遗留，FemType 0–3 可选）

 | 块名 | 主要字段 | 用途 |
 |------|----------|------|
-| `bele` | `index`, `Ebx/y/z`, `curlEbx/y/z`（字符串表达式） | 背景等效场边界 |
+| `bele` | `index`, `Ebx/y/z`, `curlEbx/y/z` | 背景等效场边界 |
 | `ef` | `index`, `E0x/y/z` | 电场 Dirichlet 激励 |
-| `pml` | `index`, `lambda`, `PMLType`, `PMLData`, `PMLBoundaryIndex` | 完美匹配层 |
-| `sbc` | `SBCType`, `Index`, `E0x/y/z`, `kx/y/z` | 散射边界 |
+| `pml` | `index`, `PMLType`, `PMLData` | 完美匹配层 |
+| `sbc` | `SBCType`, `Index`, `E0x/y/z`, `kx/y/z` | 散射边界（**FemType=4 必填**） |
 | `pbc` | `srcIndex`, `dstIndex`, `phiR`, `phiI` | 周期边界 |
-| `mag` | `index`, `H0x/y/z` | 磁场边界 |
-| `scd` | `index`, `J0x/y/z` | 面电流密度 |
-| `mpd` | `index`, `mx/y/z` | 磁偶极子源 |
-| `epd` | `index`, `px/y/z` | 电偶极子源 |
-| `port` | `PORTinc`, `PORTout`, `Einc`, `Eout`, `EincCurl`, `EoutCurl` | 波导端口 |
-| `beam` | `type`, `kx`, `ky` | 高斯光束 |
+| `port` | `PORTinc`, `PORTout`, `Einc`, `Eout` | 波导端口 |

-#### bele 算例 JSON 摘要
+#### 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, …
+
+#### 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
 {
@ -595,7 +734,11 @@ int ret = OpticsFEM_API::OpticsFEM_All(data);

 ---

-### 6.2 二维网格 `.dat` 文件
+### 6.2 三维网格 SBCmesh.dat（Mesh_3D，FemType = 4）
+
+见上文 [SBCmesh.dat 网格格式](#sbcmeshdat-网格格式mesh_3d)。
+
+### 6.3 二维网格 `.dat` 文件（Mesh_2D，FemType 0–3）

 由 `Mesh_2D::GetMesh()` 顺序解析，字段顺序固定：

@ -720,16 +863,16 @@ extern "C" {

 | 序号 | 文件 | 阅读目标 |
 |------|------|----------|
-| 1 | `test/Test_Main.cpp` | 进程入口、JSON 文件读取 |
-| 2 | `Interface/FEM_Interface.cpp` | FemType 路由、三阶段调度 |
-| 3 | `test/Test_ReadData.cpp` | JSON 字段 → Phy/Material 映射 |
-| 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` | 结果文件格式 |
+| 1 | `test/Test_Main.cpp` | 入口，默认读 `sbc3d.json` |
+| 2 | `Interface/FEM_Interface.cpp` | FemType 路由（含 **FemType=4 → 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` 总控 |
+| 6 | `kernel/Assemble_Scatter_3D_Boundary.cpp` | 3D SBC 边界积分 |
+| 7 | `kernel/Assemble_Scatter_Equation.cpp` | 四面体体积方程 |
+| 8 | `complex/complexsolver.cpp` | Eigen 稀疏线性求解 |
+| 9 | `post/Post_CalEletric.cpp` | `Post_3D_Scatter::GetElectric` |
+| 10 | `post/Post_Output.cpp` | 写入 OutFile |

 ### 调试建议

@ -746,8 +889,9 @@ extern "C" {
 | `cmake` 无法识别 | CMake 未加入 PATH | 使用 VS 自带 CMake 完整路径 |
 | `LNK1181: eigensolver.lib` | 旧版仍链接外部库 | 确认 `EIGENSOLVER_STATIC` 已启用 |
 | 运行无输出、无 OutFile | 缺少 `complexsolver.exe` 或路径错误 | 检查 `complex/` 目录及工作目录 |
-| 无法打开 `bele.json` | 工作目录不含 JSON | 在 `Release/` 下运行，或复制输入文件 |
-| 无法打开 `project_3.dat` | `MeshFile` 路径不匹配 | 确保 `.dat` 与 exe 同目录 |
+| 无法打开 `sbc3d.json` | 工作目录不含 JSON | 复制到 `Release/` 或在其中运行 |
+| 无法打开 `SBCmesh.dat` | `MeshFile` 路径不匹配 | 确保 `.dat` 与 exe 同目录 |
+| 无法打开 `bele.json` | 2D 算例文件缺失 | 从 `测试数据集/bele/` 复制 |
 | 控制台打印 `err` | JSON 缺少或错误 `FemType` | 检查 JSON 完整性 |
 | 编译警告 C4819 | Eigen 头文件编码 | 不影响功能，可忽略 |
 | BELE 表达式报错 | 表达式语法错误或变量未定义 | 检查 muparser 支持的函数（如 `sin`, `pi`, `x`） |
@ -759,12 +903,12 @@ extern "C" {
 ```
 OpticsFEM_API
    ├── Phy_WaveOpticsModel  ← JSON 边界/激励
-    ├── MaterialLib          ← JSON 材料（含 Material[]）
-    ├── Mesh_2D              ← .dat 网格
-    └── OpticsFEM_2D_*       ← 问题驱动
-            ├── Assemble（kernel + function + parser）
-            ├── Solver_*     ← 外部求解器
-            └── Post_2D_*    ← 场重构与输出
+    ├── MaterialLib          ← JSON 材料
+    ├── Mesh_3D              ← SBCmesh.dat（FemType=4）
+    └── OpticsFEM_3D_Scatter ← 3D 散射驱动
+            ├── Assemble（体积 + SBC 边界）
+            ├── Solver_LdaDom → complexsolver
+            └── Post_3D_Scatter → OutFile
 ```

 ---
@ -777,6 +921,7 @@ OpticsFEM_API
 | 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** |

 ---

@ -784,8 +929,9 @@ OpticsFEM_API

 | 版本 | 日期 | 修订内容 |
 |------|------|----------|
-| v1.0 | 2026-06-03 | 初版：全文件目录、模块说明、使用指南、I/O 规范、算例索引 |
+| v2.0 | 2026-06-08 | 适配 3D 版：FemType=4、sbc3d 算例、SBCmesh 格式、CMake complexsolver |
+| v1.0 | 2026-06-03 | 初版（2D opticsfem-master） |

 ---

-*本文档基于 `opticsfem-master` 当前代码状态编制。若 CMakeLists、API 或求解器路径发生变更，请同步更新相应章节。*
+*本文档基于 `3D opticsfem-master` 当前代码状态编制。主算例：`sbc3d.json` + `SBCmesh.dat`，FemType=4。*
--- a/opticsfem-master/README.md
+++ b/opticsfem-master/README.md
@ -1,37 +1,66 @@
-# OpticsFEM
+# OpticsFEM3D

-#### 介绍
-光学有限元程序
+三维矢量有限元光学电磁仿真程序（一阶 Nedelec 边元）。

-#### 软件架构
-软件架构说明
+## 支持的问题类型

+| FemType | 说明 | 网格 | 状态 |
+|---------|------|------|------|
+| 0–3 | 二维问题（本征/散射） | `Mesh_2D` | 遗留接口，与 2D 版相同 |
+| **4** | **三维一阶散射（SBC）** | **`Mesh_3D`** | **当前主算例** |

-#### 安装教程
+## 快速开始（FemType = 4）

-1.  xxxx
-2.  xxxx
-3.  xxxx
+### 环境

-#### 使用说明
+- Windows 10/11 x64
+- Visual Studio 2026（18），工作负载：使用 C++ 的桌面开发
+- CMake ≥ 3.8（随 VS 安装）

-1.  xxxx
-2.  xxxx
-3.  xxxx
+### 编译

-#### 参与贡献
+```powershell
+cd "3D opticsfem-master"

-1.  Fork 本仓库
-2.  新建 Feat_xxx 分支
-3.  提交代码
-4.  新建 Pull Request
+# 若 cmake 不在 PATH 中，追加 VS 2026 自带 CMake
+$env:Path += ";C:\Program Files\Microsoft Visual Studio\18\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin"

+mkdir build
+cd build
+cmake .. -G "Visual Studio 18 2026" -A x64
+cmake --build . --config Release
+```

-#### 特技
+产物：

-1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
-2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
-3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
-4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
-5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
-6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)
+- `build/Release/OpticsFEM.exe`
+- `build/Release/complex/complexsolver.exe`（CMake 自动编译）
+
+### 运行 sbc3d 算例
+
+```powershell
+# 复制输入文件到 exe 同目录
+Copy-Item ..\sbc3d.json, ..\SBCmesh.dat -Destination Release\
+
+cd Release
+.\OpticsFEM.exe
+```
+
+结果输出到 `Release/OutFile/`：`Ex`、`Ey`、`Ez`、`normE`。
+
+### 输入文件
+
+| 文件 | 说明 |
+|------|------|
+| `sbc3d.json` | 算例配置，`FemType` 必须为 **4** |
+| `SBCmesh.dat` | 三维四面体网格（顶点、四面体、边、三角边界等） |
+
+## 详细文档
+
+- [OpticsFEM_完整使用说明与代码介绍.md](./OpticsFEM_完整使用说明与代码介绍.md) — 模块说明、JSON 字段、FemType=4 专章
+- [compare/README.md](./compare/README.md) — 与 COMSOL 的 normE 切面对比
+
+## 仓库说明
+
+- 只需上传**源码**；`build/` 由 CMake 本地生成，不必提交。
+- 散射算例（FemType=4）的 `complexsolver.exe` 可由 CMake 从 `complex/complexsolver.cpp` 编译，无需单独 PETSc 版求解器。