# 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` 负责统一调度求解流程