306 lines
8.9 KiB
Markdown
306 lines
8.9 KiB
Markdown
# 输入输出
|
||
|
||
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 同步输出。 |
|