Files
MDHelper/docs/io_manual.md
T
2026-05-25 17:12:00 +08:00

306 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 输入输出
IO 模块位于 `io/`,负责配置文件、结果文件、日志和时间历程数据。
## 模块职责
`io/` 只负责读写和数据格式,不负责物理模型决策。几何、网格、FEM、SPH、材料和 pipeline 应调用 IO 模块提供的统一接口,而不是在各自模块中重复实现文件解析。
主要文件:
| 文件 | 说明 |
|---|---|
| `io/base.h` | IO 基类和基础接口。 |
| `io/filesystem.h` | 路径、目录创建、文本文件读写。 |
| `io/xml.h` | XML 读写。 |
| `io/json.h` | JSON 读写。 |
| `io/yaml.h` | YAML 读写。 |
| `io/config.h` | XML/JSON/YAML 统一配置数据模型。 |
| `io/config_schema.h` | 配置字段校验。 |
| `io/vtu_types.h` | VTU 数据结构。 |
| `io/vtu_writer.h` | VTU 写出。 |
| `io/vtu_reader.h` | VTU 读入。 |
| `io/pvd.h` | PVD 时间序列写出。 |
| `io/csv.h` | CSV 时间历程和报告。 |
| `io/log.h` | 文本日志和命令行同步输出。 |
| `io/console.h` | 命令行输出和进度打印。 |
| `io/manifest.h` | 运行清单。 |
| `io/io.h` | 常用 IO 聚合头文件。 |
## 配置文件
| 文件 | 说明 |
|---|---|
| `io/xml.h` | XML 读写。 |
| `io/json.h` | JSON 读写入口。 |
| `io/yaml.h` | YAML 读写入口。 |
| `io/config.h` | 公共配置数据模型。 |
模块代码应读取 `ConfigDocument`,避免直接绑定 XML。
推荐:
```text
配置文件 -> ConfigDocument -> 模块配置结构 -> 运行时对象
```
不推荐:
```text
模块内部手写 XML 字符串解析
```
更多配置模型说明见 [配置文件](configuration.md)。
## 结果文件
推荐:
- 空间场:`VTU`。
- 时间序列:`PVD`。
- 时间历程曲线:`CSV`。
- 运行诊断:`.log` 文本文件。
推荐案例输出目录:
```text
outputs/
cad/
mesh/
particles/
sph/
fem/
post/
logs/
reports/
manifest.txt
```
不同案例可以只保留自己需要的子目录。
## VTU/PVD
VTU 支持:
- ASCII。
- appended binary。
- 压缩数据。
- 多 Piece 文件。
ParaView 推荐打开 `.pvd`,而不是逐个打开 `.vtu`。
### VTU 数据组织
VTU 文件保存空间离散场:
| 数据 | 位置 | 示例 |
|---|---|---|
| 节点坐标或粒子坐标 | `Points` | `x/y/z` |
| 单元拓扑 | `Cells` | `Vertex`、`Line2`、`Tri3`、`Tet4`、`Hex8` |
| 节点场或粒子场 | `PointData` | 位移、速度、密度、压力 |
| 单元场 | `CellData` | 应力、应变、材料 id、区域 id |
SPH 粒子通常写成 `Vertex` 单元;FEM 网格写成对应单元拓扑。
### ASCII、Appended Binary 与压缩
| 格式 | 优点 | 适用场景 |
|---|---|---|
| ASCII | 可读、便于调试和版本对比。 | 小案例、单元测试、排错。 |
| Appended binary | 文件更小、读写更快。 | 中等规模算例。 |
| 压缩数据 | 进一步减小文件体积。 | 大规模输出和长期存档。 |
调试阶段优先使用 ASCII;结果稳定后再切换 binary 或压缩输出。
### 多 Piece 文件
MPI 或分片输出时,可把不同分区写成多个 piece,并由 PVD 或后处理统一读取。注意:
- 每个 piece 的点/单元编号只在本文件内有效。
- 跨 piece 的边界或 halo 信息需要由求解器或后处理额外管理。
- 文件命名应包含 rank 或 piece id,避免覆盖。
## CSV
CSV 用于:
- benchmark 误差。
- 反力时间历程。
- 能量平衡。
- 质量守恒。
- 最大位移、速度、加速度。
- 接触穿透量。
首行必须是表头,数值使用 SI 单位。
### CSV 写出规则
`io/csv.h` 提供:
- `CSVFile::write_all()`:一次写出完整表格。
- `CSVFile::append_row()`:追加单行,文件为空时可自动写表头。
- `CSVFile::append_rows()`:追加多行。
- `ReactionHistoryCSV`:反力/力矩时间历程专用表。
数值建议使用高精度科学计数法兼容格式。字段名保持英文,单位写入 README 或报告说明。
反力历史推荐列:
```csv
step,time,boundary_name,boundary_id,fx,fy,fz,mx,my,mz
```
SPH 监测推荐列:
```csv
step,time,dt,particle_count,max_velocity,min_density,max_density,min_pressure,max_pressure,total_mass
```
## 日志
SPH/FEM monitor 应同时打印到命令行和日志文件。日志中至少包含:
- step。
- time。
- dt。
- 粒子数或自由度。
- 最大速度/位移/残差。
- 密度、压力或能量范围。
`io/log.h` 中:
- `TextLogFile` 负责文本日志。
- `MultiplexTextOutput` 同时写命令行和日志文件。
- 日志级别包括 `INFO`、`WARNING`、`ERROR`、`DEBUG`。
日志行会带时间戳,便于长时间计算追踪。推荐求解器每隔 `print_interval` 输出一次监控信息。
示例日志内容:
```text
2026-05-19 12:00:00 [INFO] step=200 time=0.002 dt=1e-5 particles=5200 max_v=1.23
```
命令行和日志文件应尽量输出同一组核心监控量,方便用户在运行时判断计算是否发散。
## PVD 输出约定
时间序列输出应在每次写出 VTU 后同步更新 PVD 文件。长时间计算中如果程序中断,已有结果仍能被 ParaView 正常读取。
建议:
- `output_interval` 不要过小,否则文件数量会迅速膨胀。
- 大规模计算优先保存关键物理量,不要每步输出全部中间变量。
- 后处理需要分组时,可输出多个 PVD,例如 `water.pvd` 和 `wall.pvd`。
PVD 条目至少包含:
| 字段 | 说明 |
|---|---|
| `timestep` | 物理时间。 |
| `file` | 对应 VTU 文件路径。 |
| `part` | 分区编号,单文件通常为 `0`。 |
建议 `file` 使用相对 PVD 文件所在目录的路径,便于整体移动案例目录。
## 粒子分组输出
SPH 后处理可按粒子角色或材料拆分:
```xml
<M3FrameSPHPost name="split_particles">
<Input path="outputs/sph/result_100.vtu" />
<Split field="role">
<Group value="fluid" path="outputs/post/water_100.vtu" />
<Group value="boundary" path="outputs/post/wall_100.vtu" />
</Split>
</M3FrameSPHPost>
```
这类输出适合 dam break、Couette flow、静水箱等同时包含水体和壁面粒子的案例。
## CSV 时间历程格式
推荐格式:
```csv
step,time,dt,max_velocity,min_density,max_density,total_mass
0,0.0,1.0e-5,0.0,1000.0,1000.0,1.0
```
字段名使用英文,单位在 README 或表头注释中说明。数值尽量保持科学计数法兼容,方便 Python、Excel 和 ParaView 读取。
## 文件系统工具
`io/filesystem.h` 提供常用文件工具:
| 接口 | 说明 |
|---|---|
| `FileSystem::exists()` | 判断路径是否存在。 |
| `FileSystem::create_directories()` | 创建目录。 |
| `FileSystem::parent_path()` | 获取父目录。 |
| `FileSystem::extension()` | 获取扩展名。 |
| `FileSystem::ensure_parent_directory()` | 写文件前确保父目录存在。 |
| `TextFile::read_all()` | 读取完整文本。 |
| `TextFile::read_lines()` | 按行读取文本。 |
| `TextFile::write_all()` | 写完整文本。 |
| `TextFile::append_line()` | 追加一行。 |
所有写文件接口都应先确保父目录存在,避免因目录不存在导致运行中断。
## Manifest 运行清单
`io/manifest.h` 提供简单的 key-value 运行清单写出。建议每次 pipeline 运行时记录:
| key | 示例 |
|---|---|
| `case` | `dam_break_pressure` |
| `pipeline` | `pipeline.xml` |
| `backend` | `openmp` |
| `start_time` | `2026-05-19 12:00:00` |
| `input.cad` | `config/cad.xml` |
| `input.solver` | `config/sph_solver.xml` |
| `output.pvd` | `outputs/sph/case.pvd` |
| `git_or_build` | 构建目录或版本描述 |
清单不是数值结果,但对复现实验非常有用。
## Console 与进度显示
`io/console.h` 提供:
- `write()`:命令行写字符串。
- `write_line()`:命令行写一行。
- `error_line()`:错误输出。
- `progress()`:百分比进度条。
长时间任务建议同时使用 console 和 log:
```text
命令行:给用户看当前进度
log:保存完整诊断
```
## 推荐输出策略
| 阶段 | 推荐输出 |
|---|---|
| CAD | `.stl`、`.obj`、必要时 `.stp` |
| Meshing | `.vtu` 网格,带 `boundary_id/material_id/region_id` |
| Particle meshing | `.vtu` 粒子,带 `role/material_id/boundary_id` |
| SPH/FEM 求解 | `.pvd + .vtu` 时间序列 |
| Monitor | `.log` 和 `.csv` |
| Benchmark | `reports/*.csv` |
| Pipeline | `manifest.txt` |
## 常见问题
| 现象 | 可能原因 | 建议 |
|---|---|---|
| 输出文件不存在 | 父目录未创建或路径写错 | 使用 `ensure_parent_directory`,检查相对路径。 |
| ParaView 打不开 VTU | PointData/CellData 长度和点/单元数量不一致 | 检查写出字段数组长度。 |
| PVD 只有少数帧 | `output_interval` 过大或 `max_steps` 太小 | 调整求解器输出控制。 |
| PVD 引用路径失效 | 移动文件后相对路径不匹配 | PVD 和 VTU 保持相对目录结构。 |
| CSV 中文乱码 | 外部软件编码识别问题 | 优先使用英文表头,文件保存为 UTF-8。 |
| 日志没有命令行输出 | 只写了 TextLogFile | 使用 `MultiplexTextOutput` 或求解器 monitor 同步输出。 |