8.9 KiB
输入输出
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。
推荐:
配置文件 -> ConfigDocument -> 模块配置结构 -> 运行时对象
不推荐:
模块内部手写 XML 字符串解析
更多配置模型说明见 配置文件。
结果文件
推荐:
- 空间场:
VTU。 - 时间序列:
PVD。 - 时间历程曲线:
CSV。 - 运行诊断:
.log文本文件。
推荐案例输出目录:
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 或报告说明。
反力历史推荐列:
step,time,boundary_name,boundary_id,fx,fy,fz,mx,my,mz
SPH 监测推荐列:
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 输出一次监控信息。
示例日志内容:
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 后处理可按粒子角色或材料拆分:
<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 时间历程格式
推荐格式:
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:
命令行:给用户看当前进度
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 同步输出。 |