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

8.9 KiB
Raw Blame History

输入输出

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 同步输出。