Initial MDHelper implementation

This commit is contained in:
shenw
2026-05-25 17:12:00 +08:00
commit 50b15b02c7
45 changed files with 11654 additions and 0 deletions
+314
View File
@@ -0,0 +1,314 @@
# 配置文件
M3Frame 使用统一配置数据模型读取不同格式的参数文件。当前 XML 最完整,JSON/YAML 作为同一数据模型的可选入口逐步完善。
## 推荐格式
新案例优先使用 XML:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<M3FrameSPHSimulation version="1.0" name="case">
...
</M3FrameSPHSimulation>
```
同一份配置也可以由 JSON/YAML 表示,但当前示例和 benchmark 仍以 XML 为主。建议等 XML 案例稳定后,再用脚本批量生成 JSON/YAML 参数组。
## 配置层级
常见配置文件:
| 文件 | 作用 |
|---|---|
| `pipeline.xml` | 统一任务流。 |
| `cad.xml` | 几何建模。 |
| `meshing.xml` | FEM 网格划分。 |
| `particle_meshing.xml` | SPH 粒子划分。 |
| `materials.xml` | 材料库或材料覆盖。 |
| `sph_solver.xml` | SPH 求解控制。 |
| `fem_solver.xml` | FEM 求解控制。 |
| `post.xml` | 后处理控制。 |
推荐目录:
```text
case/
pipeline.xml
config/
cad.xml
meshing.xml 或 particle_meshing.xml
materials.xml
sph_solver.xml 或 fem_solver.xml
post.xml
outputs/
```
`pipeline.xml` 放在案例根目录,其他配置文件放入 `config/`。这样复制、归档和批量运行案例时更清晰。
## 路径约定
- Pipeline 中的阶段路径通常相对 `pipeline.xml` 所在目录。
- CAD、meshing、solver 内部路径可使用项目根目录相对路径。
- 建议案例路径写完整,例如 `examples/sph/benchmarks/case/outputs/...`,减少工作目录差异带来的问题。
内部 `ConfigDocument::resolve_path()` 会把相对路径解析到配置文件所在目录。因此同一层级的引用可写成:
```xml
<Stage kind="geometry" path="config/cad.xml" />
```
配置文件内部输出路径推荐写清楚目标目录:
```xml
<Export path="outputs/particles/water.vtu" />
```
如果程序从项目根目录运行,建议案例中的路径保持项目相对路径或相对当前配置文件路径的一致性,不要混用多种风格。
## 参数命名建议
- 使用小写蛇形命名:`reference_density`、`speed_of_sound`。
- 布尔值使用 `true/false`。
- 单位采用 SI 制。
- 多选项采用明确字符串:`riemann_rusanov`、`adami_ghost`、`tet4`。
不推荐:
- 同一个参数同时使用多个别名。
- 在一个 XML 文件中混合驼峰命名和蛇形命名。
- 用没有单位提示的缩写参数,例如 `v`、`p0`、`k`。
- 把输出路径写到源码目录或临时目录。
## 数值与单位
所有求解器默认按 SI 单位解释参数:
| 物理量 | 推荐单位 |
|---|---|
| 长度 | `m` |
| 质量 | `kg` |
| 时间 | `s` |
| 密度 | `kg/m^3` |
| 压力/应力 | `Pa` |
| 速度 | `m/s` |
| 表面张力 | `N/m` |
| 黏度 | `Pa*s` 或 `m^2/s`,以具体参数说明为准 |
小尺度案例需要同步缩小粒子间距、平滑长度、质量和时间步。不要只改几何尺寸,否则容易出现压力过大、液滴膨胀或粒子聚集。
## XML、JSON、YAML 的关系
内部统一为 `io::ConfigDocument` / `io::ConfigNode`:
```text
xml/json/yaml 文件
-> io 读取器
-> ConfigDocument
-> geometry/fem/sph/material 模块读取参数
```
模块代码应读取配置数据模型,而不是直接绑定某一种文件格式。
当前 IO 文件分工:
| 文件 | 职责 |
|---|---|
| `io/xml.h` | XML 读写。 |
| `io/json.h` | JSON 读写。 |
| `io/yaml.h` | YAML 读写。 |
| `io/config.h` | 格式无关配置树和统一读取入口。 |
| `io/config_schema.h` | 配置字段校验工具。 |
统一读取入口会按扩展名自动选择格式:
| 扩展名 | 读取器 |
|---|---|
| `.xml` 或无扩展名 | XML |
| `.json` | JSON |
| `.yml` / `.yaml` | YAML |
不支持的扩展名会抛出配置错误。
## ConfigDocument 与 ConfigNode
`ConfigDocument` 表示一个配置文件,主要包含:
| 成员 | 说明 |
|---|---|
| `path` | 配置文件路径。 |
| `format` | 文件格式,例如 `xml/json/yaml`。 |
| `root` | 根节点。 |
| `base_directory()` | 配置文件所在目录。 |
| `resolve_path()` | 将相对路径解析为相对配置文件目录的路径。 |
| `find()` / `require()` | 按点分路径查找节点。 |
| `get_string/get_int/get_real/get_bool` | 读取带默认值的参数。 |
| `get_vec3` | 读取 `x/y/z` 三分量。 |
`ConfigNode` 是格式无关节点,支持:
| 类型 | 说明 |
|---|---|
| `Null` | 空值。 |
| `String` | 字符串。 |
| `Integer` | 整数。 |
| `Real` | 浮点数。 |
| `Boolean` | 布尔值。 |
| `Array` | 数组。 |
| `Object` | 对象或 XML 元素。 |
XML 元素会转换为对象节点:
- 元素名保存在 `_tag`。
- 文本内容保存在 `_text`。
- XML 属性转换为普通标量字段。
- 同名子元素会转换为数组。
例如:
```xml
<Task id="fluid" source="water" spacing="0.01" />
```
会被模块按类似对象读取:
```text
Task._tag = "Task"
Task.id = "fluid"
Task.source = "water"
Task.spacing = "0.01"
```
模块通常使用:
```cpp
element.attr("id", "");
element.attr_real("spacing", 0.01);
element.attr_bool("enabled", true);
```
而不是手动解析 XML 字符串。
## 类型转换规则
统一配置模型会在读取属性时做基础类型转换:
| 目标类型 | 可接受输入 |
|---|---|
| string | 字符串、整数、浮点、布尔。 |
| int | 整数、浮点、数字字符串、布尔。 |
| real | 整数、浮点、数字字符串、布尔。 |
| bool | `true/false`、`1/0`、`yes/no`、`on/off`。 |
建议 XML 中仍显式写标准值:
```xml
enabled="true"
max_steps="1000"
dt="1.0e-5"
```
如果字符串无法转换为目标类型,读取器会抛出 `ConfigError`。
## XML、JSON、YAML 等价示例
XML:
```xml
<Defaults spacing="0.01" density="1000" role="fluid" />
```
JSON:
```json
{
"Defaults": {
"spacing": 0.01,
"density": 1000,
"role": "fluid"
}
}
```
YAML:
```yaml
Defaults:
spacing: 0.01
density: 1000
role: "fluid"
```
注意:XML 的元素属性天然是字符串,进入 `ConfigNode` 后由读取函数转换成数值或布尔;JSON/YAML 可以保留数字和布尔的原生类型。
## 通用属性读取规则
同一个参数建议只在一个层级定义;如果同时出现在 `Defaults` 和具体 `Task` 中,通常以具体 `Task` 为准。
示例:
```xml
<Defaults spacing="0.01" smoothing_length="0.013" />
<Task id="fine_region" spacing="0.005" smoothing_length="0.0065" />
```
这里 `fine_region` 使用更细的局部设置,其余任务继续使用默认值。
常见覆盖顺序:
```text
程序默认值
-> Defaults
-> Task 或局部节点属性
-> 求解器运行时修正
```
例如粒子划分中:
```xml
<Defaults spacing="0.01" material="7" role="fluid" />
<Task id="wall" source="wall_box" spacing="0.005" material="8" role="boundary" />
```
`wall` 使用自己的 `spacing/material/role`,其他任务继续使用默认设置。
## 配置校验
`io/config_schema.h` 提供轻量 schema 校验:
- `require(path, type)`:必填字段。
- `optional(path, type)`:可选字段。
- `allowed_values`:可选值约束。
建议关键入口在执行前至少校验:
- 根节点名称。
- 必填路径。
- 求解器类型。
- 输出目录。
- 时间步、步数、粒子/网格输入文件。
配置校验的目标不是替代完整物理检查,而是尽早发现拼写错误和缺失字段。
## 兼容性建议
虽然框架支持 XML、JSON 和 YAML 的统一配置模型,当前工程案例仍推荐使用 XML。原因是已有示例、文档和解析路径最完整,适合调试;JSON/YAML 更适合后续由脚本生成批量参数。
## 推荐实践
- 新案例使用 `config/` 存放配置文件。
- 配置文件内写清楚单位相关参数。
- 新增关键词时同步更新对应模块手册。
- 保留旧关键词时,在文档中标注为历史别名。
- benchmark 不应依赖隐式默认路径,输入输出路径应显式写入。
- 批量参数扫描优先由脚本生成配置文件,不要在 C++ benchmark 中硬编码大量参数。
## 常见错误
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 找不到配置文件 | `path` 相对目录理解错误 | 优先按 `pipeline.xml` 或当前配置文件目录检查。 |
| 布尔参数不起作用 | 写成了非标准字符串 | 使用 `true/false`。 |
| 数值读取失败 | 参数中带单位或非法字符 | 数值字段只写数字,单位写在文档或注释中。 |
| JSON/YAML 案例行为和 XML 不一致 | 层级或数组结构不等价 | 先用 XML 验证,再迁移到 JSON/YAML。 |
| 参数被默认值覆盖 | 写在了错误层级 | 检查 `Defaults` 与任务级属性的覆盖关系。 |