# 输入输出 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 ``` 这类输出适合 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 同步输出。 |