final version

2026-03-23 14:38:09 +08:00
parent 7666beda19
commit 03c7a1ab40
15 changed files with 1314 additions and 2495 deletions
@@ -0,0 +1,459 @@
+# EDFM Simulator 软件使用手册
+
+## 1. 软件定位
+
+本软件是一个基于 MATLAB App Designer 的 EDFM 图形化模拟工具，正式界面文件为：
+
+- `gui_support/app/EDFM_Simulator_App.mlapp`
+
+当前项目已经不再以早期 `.m` 代码版界面为主线，后续使用与维护都应以 `.mlapp` 版本为准。
+
+软件的核心用途是：
+
+- 通过图形界面编辑 EDFM 模拟参数
+- 加载模板算例
+- 导入/导出配置
+- 运行模拟
+- 导入/导出结果
+- 查看基础结果和部分后处理图
+
+## 2. 运行前准备
+
+请确保：
+
+- 已安装 MATLAB
+- 工程目录完整
+- MATLAB 当前工作路径切换到工程根目录
+
+示例：
+
+```matlab
+cd('C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305')
+```
+
+## 3. 推荐启动方式
+
+由于正式界面是 `.mlapp`，推荐两种启动方式。
+
+### 方式一：在 App Designer 中直接打开并运行
+
+直接打开：
+
+- `gui_support/app/EDFM_Simulator_App.mlapp`
+
+然后点击 Run。
+
+这是当前最推荐的方式。
+
+### 方式二：在 MATLAB 中直接实例化 App
+
+如果 `.mlapp` 已经在 MATLAB 路径下可见，可以在命令行中运行：
+
+```matlab
+app = EDFM_Simulator_App;
+```
+
+说明：
+
+- 根目录中的 `launch_edfm_simulator_app.m` 目前仍指向早期 `.m` 版 `EDFMSimulatorApp()`，不应再作为正式 GUI 的主入口理解。
+
+## 4. 软件整体结构
+
+界面按原始 `main1.m` 中的逻辑拆分为多个部分，并带有顶部工具栏。
+
+### 顶部工具栏
+
+主要包括：
+
+- `New Config`
+- `Template`
+- `Load Template`
+- `Import Config`
+- `Export Config`
+- `Run`
+- `Import Result`
+- `Export Result`
+- `Status`
+
+### 主页面签
+
+- `Model`
+- `Grid`
+- `Fracture`
+- `Discretization`
+- `Flow`
+- `Wells`
+- `Solover` 或 `Solver`
+- `Run`
+- `Results`
+
+不同版本导出的文字可能略有差异，但功能分组是一致的。
+
+## 5. 推荐使用流程
+
+建议按下面顺序使用。
+
+### 5.1 新建或加载配置
+
+你可以选择以下两种起点：
+
+- 点击 `New Config` 创建空配置
+- 在模板下拉框中选择 `case01` 到 `case07`，然后点击 `Load Template`
+
+如果是第一次使用，建议先加载已有模板，不建议直接从空配置开始。
+
+### 5.2 按页面修改参数
+
+#### Model 页
+
+这里主要设置：
+
+- `ModelFlag`
+- `GridModel`
+- `FlowModel`
+
+其中：
+
+- `FlowModel=1`：气水两相流
+- `FlowModel=2`：油水两相流
+- `FlowModel=3`：组分流
+
+运行时只使用当前选中的流动模型分支。
+
+#### Grid 页
+
+这里填写网格参数：
+
+- `dx`
+- `dy`
+- `dz`
+- `NTG`
+
+这类参数通常使用 MATLAB 表达式录入，例如：
+
+```matlab
+[10 10 10 10]
+```
+
+```matlab
+[5; 5; 5]
+```
+
+#### Fracture 页
+
+这里用于设置裂缝输入方式及裂缝相关参数，例如：
+
+- 输入类型
+- 裂缝工程输入
+- 裂缝线
+- 裂缝高度
+- 是否流动阻隔
+
+#### Discretization 页
+
+这里用于设置离散化参数，例如：
+
+- 边界
+- 无效层
+- 基质参数
+- 裂缝参数
+- 应力敏感参数
+
+#### Flow 页
+
+这里设置：
+
+- 初始压力
+- 初始含水饱和度
+- 初始 `Cs`
+- 初始 `Cb`
+- 与当前流动模型对应的流体参数
+
+注意：
+
+- 三种流动模型互斥
+- GUI 中虽然可能展示多个区块，但运行时只会使用当前 `FlowModel` 对应的数据
+
+#### Wells 页
+
+这是井和排产制度设置页面，当前包含四个关键表格：
+
+- `Well1Table`
+- `Well2Table`
+- `ScheduleTable`
+- `FractureWellLocationTable`
+
+同时还包括：
+
+- `time`
+- `dtmin`
+- `dtmax`
+
+### 5.3 Wells 页四个表如何填写
+
+#### 1. `Well1Table`
+
+通常用于定义常规井。
+
+当前表头含义：
+
+- `well_name`
+- `nperf`
+- `index_xyz`
+- `rw`
+- `skin`
+- `well_type`
+
+其中：
+
+- `index_xyz` 通常是网格索引，如 `[20 10 1; 20 10 2]`
+- `well_type` 对应原始代码中的井类型编号
+
+#### 2. `FractureWellLocationTable`
+
+用于定义压裂井轨迹点或井位坐标。
+
+当前表头含义：
+
+- `x`
+- `y`
+- `z`
+
+#### 3. `Well2Table`
+
+通常用于定义压裂水平井或与裂缝单元相关的井。
+
+当前表头含义：
+
+- `well_name`
+- `nperf`
+- `perfnum`
+- `rw`
+- `skin`
+- `well_type`
+
+#### 4. `ScheduleTable`
+
+用于定义井制度和阶段排产。
+
+当前表头含义：
+
+- `well_name`
+- `state(open/close)`
+- `role(inj/pro)`
+- `control(const_q/const_pwf)`
+- `target_1`
+- `target_2`
+- `Cs_key`
+- `Cs_inj`
+- `Cb_key`
+- `inj_salinity`
+
+结合原始 `main1.m` 注释，可按下面理解填写：
+
+- `state`
+  - `open`
+  - `close`
+- `role`
+  - `inj`
+  - `pro`
+- `control`
+  - `const_q`
+  - `const_pwf`
+- `target_1`
+  - 常用于输入目标流量或目标井底流压
+- `target_2`
+  - 一般与 `target_1` 成对使用
+- `Cs_inj`
+  - 注入表活剂浓度
+- `inj_salinity`
+  - 注入水或压裂液盐浓度，即矿化度
+
+### 5.4 时间步参数
+
+`Wells` 页还需要填写：
+
+- `time`
+- `dtmin`
+- `dtmax`
+
+这三个量通常按阶段一一对应。
+
+建议保证：
+
+- `time` 的阶段数
+- `dtmin` 的阶段数
+- `dtmax` 的阶段数
+- `well_schedules` 的阶段数
+
+四者保持一致。
+
+## 6. 配置导入与导出
+
+### 导出配置
+
+点击 `Export Config` 后，软件会把当前 GUI 数据整理成统一 `config` 结构，并保存为 `.mat` 文件。
+
+该 MAT 文件中应包含变量：
+
+```matlab
+config
+```
+
+### 导入配置
+
+点击 `Import Config`，选择包含 `config` 变量的 `.mat` 文件即可。
+
+## 7. 运行模拟
+
+参数设置完成后：
+
+1. 点击顶部 `Run`
+2. 或在 `Run` 页点击运行按钮
+
+运行时软件会：
+
+1. 从 `.mlapp` 控件读取参数
+2. 通过 `EDFMAppController.m` 写入统一 `config`
+3. 调用 `gui_support/runtime/run_case.m`
+4. 由 `run_case(config)` 组织网格、裂缝、流体、井和 schedule
+5. 最终调用底层求解器
+
+运行日志会显示在 `Run` 页文本框中。
+
+## 8. 查看结果
+
+运行成功后，可在 `Results` 页查看：
+
+- 结果摘要
+- 时间步信息
+- 牛顿迭代信息
+- 基础结果曲线
+
+并可调用部分旧版后处理功能，例如：
+
+- `PlotWellResponse`
+- `Plot2DLayer`
+- `Plot3DDistribution`
+- `PlotPerm`
+- `PlotSPDP`
+
+## 9. 结果导入与导出
+
+### 导出结果
+
+点击 `Export Result`，导出当前结果为 `.mat` 文件。
+
+MAT 文件中应包含变量：
+
+```matlab
+results
+```
+
+### 导入结果
+
+点击 `Import Result`，选择包含 `results` 变量的 `.mat` 文件即可。
+
+## 10. 输入格式说明
+
+当前软件中，很多复杂参数仍然采用 MATLAB 表达式方式输入。
+
+常见格式如下。
+
+### 数值
+
+```matlab
+10
+```
+
+### 向量
+
+```matlab
+[1 2 3]
+```
+
+### 列向量
+
+```matlab
+[1; 2; 3]
+```
+
+### 矩阵
+
+```matlab
+[1 2; 3 4]
+```
+
+### 单元数组
+
+```matlab
+{'w1', 1, [20 10 1], 0.089, 0, 1}
+```
+
+### 多行排产表
+
+```matlab
+{
+    'w1','open','inj','const_pwf',40,40,'Cs_inj',0.5,'Cb_inj',1;
+    'w1','open','pro','const_q',0,0,'',[],'',[]
+}
+```
+
+## 11. 使用建议
+
+建议遵循以下原则：
+
+- 优先从模板开始，而不是手工全新录入
+- 大改参数前先导出一份配置备份
+- 保证 `ScheduleTable` 井名与井定义一致
+- 保证 `time`、`dtmin`、`dtmax` 与阶段 schedule 数一致
+- 修改流体参数时，确认当前 `FlowModel` 是否正确
+
+## 12. 常见问题
+
+### 1. 为什么不建议再用 `.m` 版界面
+
+因为项目已经明确转向 App Designer 的 `.mlapp` 维护方式，`.m` 版只应视为早期过渡实现。
+
+### 2. 导入配置失败怎么办
+
+检查 `.mat` 文件中是否存在变量：
+
+```matlab
+config
+```
+
+### 3. 导入结果失败怎么办
+
+检查 `.mat` 文件中是否存在变量：
+
+```matlab
+results
+```
+
+### 4. 表格里不知道填什么
+
+建议按以下顺序判断：
+
+1. 先看表头
+2. 再看模板默认值
+3. 再看对应算例目录的 `main1.m` 注释
+
+### 5. 改了别的流动模型参数为什么不生效
+
+因为三种流动模型是互斥的，运行时只读取当前选中的 `FlowModel` 分支。
+
+## 13. 当前版本特点
+
+当前版本的重点是：
+
+- 正式界面已经放到 `.mlapp`
+- 业务逻辑主要通过 `EDFMAppController.m` 绑定
+- 运行入口已经统一为 `run_case(config)`
+
+也就是说，使用者可以把它理解为：
+
+- `.mlapp` 负责界面
+- `controller` 负责连接界面与后端
+- `run_case` 负责统一调度求解流程
+