Initial MDHelper implementation
This commit is contained in:
@@ -0,0 +1,200 @@
|
||||
# M3Frame 用户手册
|
||||
|
||||
M3Frame 是面向多物理数值仿真的研究型计算框架,当前重点覆盖:
|
||||
|
||||
- SPH:流体、自由面、表面张力、多相流、固体破碎、开放边界和壁面边界。
|
||||
- FEM:实体、梁、板壳、接触、多孔介质、静力学、准静态和动力学流程。
|
||||
- Geometry/Meshing:XML 驱动的 CAD 建模、几何导出、体网格划分和 SPH 粒子划分。
|
||||
- Pipeline:用一个 `pipeline.xml` 串联几何、离散、材料、求解、耦合和后处理。
|
||||
|
||||
## 适用范围
|
||||
|
||||
本手册面向三类用户:
|
||||
|
||||
- 使用者:通过配置文件运行已有 SPH/FEM/耦合案例。
|
||||
- 案例开发者:建立新的 benchmark、工程算例或参数对比算例。
|
||||
- 模块开发者:扩展 CAD、网格、材料、本构、求解器、后处理和 pipeline 阶段。
|
||||
|
||||
如果只想运行案例,优先阅读“推荐使用方式”和“标准运行流程”;如果要扩展代码,再阅读各模块手册和 `docs/coding_conventions.md`。
|
||||
|
||||
## 推荐使用方式
|
||||
|
||||
新案例优先采用纯配置文件控制:
|
||||
|
||||
```text
|
||||
case/
|
||||
pipeline.xml
|
||||
config/
|
||||
cad.xml
|
||||
meshing.xml 或 particle_meshing.xml
|
||||
sph_solver.xml 或 fem_solver.xml
|
||||
outputs/
|
||||
```
|
||||
|
||||
其中:
|
||||
|
||||
| 路径 | 作用 |
|
||||
|---|---|
|
||||
| `pipeline.xml` | 案例总入口,按阶段调度几何、离散、求解和后处理。 |
|
||||
| `config/` | 保存几何、网格、粒子、材料、求解器和后处理配置。 |
|
||||
| `outputs/` | 保存几何文件、网格/粒子文件、求解结果、日志和报告。 |
|
||||
|
||||
运行方式:
|
||||
|
||||
```powershell
|
||||
.\cmake-build-cuda13\Release\M3Frame.exe path\to\pipeline.xml
|
||||
```
|
||||
|
||||
benchmark 程序建议只负责读取结果、对比解析解、写报告,不再承担几何建模或求解流程。
|
||||
|
||||
## 标准运行流程
|
||||
|
||||
一个完整案例通常按以下顺序执行:
|
||||
|
||||
```text
|
||||
cad.xml
|
||||
-> meshing.xml 或 particle_meshing.xml
|
||||
-> materials.xml 可选
|
||||
-> sph_solver.xml 或 fem_solver.xml
|
||||
-> post.xml 可选
|
||||
-> benchmark_*.cpp 可选
|
||||
```
|
||||
|
||||
对应的 `pipeline.xml` 示例:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<M3FramePipeline version="1.0" name="case_name" continue_on_failure="false">
|
||||
<Stages>
|
||||
<Stage kind="geometry" name="cad" path="config/cad.xml" />
|
||||
<Stage kind="meshing" mesh_type="particle" name="particles" path="config/particle_meshing.xml" />
|
||||
<Stage kind="solver" solver="sph" name="sph" path="config/sph_solver.xml" />
|
||||
</Stages>
|
||||
</M3FramePipeline>
|
||||
```
|
||||
|
||||
FEM 案例只需把粒子划分和求解器替换为:
|
||||
|
||||
```xml
|
||||
<Stage kind="meshing" mesh_type="volume" name="mesh" path="config/meshing.xml" />
|
||||
<Stage kind="solver" solver="fem" name="fem" path="config/fem_solver.xml" />
|
||||
```
|
||||
|
||||
## 配置文件职责
|
||||
|
||||
| 文件 | 主要内容 | 常见输出 |
|
||||
|---|---|---|
|
||||
| `cad.xml` | 点、线、面、体、布尔操作、几何导出。 | `.stl`、`.obj`、`.stp` |
|
||||
| `meshing.xml` | 曲线、曲面、体网格生成参数。 | FEM 用 `.vtu` 网格 |
|
||||
| `particle_meshing.xml` | SPH 粒子采样、材料 id、角色、边界 id。 | SPH 用 `.vtu` 粒子集 |
|
||||
| `materials.xml` | 材料参数、状态方程、本构模型。 | 材料表或运行时材料库 |
|
||||
| `sph_solver.xml` | SPH 模型、边界、时间步、输出、监控。 | `.pvd`、`.vtu`、`.log`、`.csv` |
|
||||
| `fem_solver.xml` | FEM 单元、载荷、约束、非线性、动力学、输出。 | `.pvd`、`.vtu`、`.log`、`.csv` |
|
||||
| `post.xml` | 结果拆分、派生量计算、报告输出。 | 后处理 `.vtu`、`.csv` |
|
||||
|
||||
## 输出文件约定
|
||||
|
||||
推荐输出结构:
|
||||
|
||||
```text
|
||||
outputs/
|
||||
cad/
|
||||
mesh/ 或 particles/
|
||||
sph/ 或 fem/
|
||||
post/
|
||||
logs/
|
||||
reports/
|
||||
```
|
||||
|
||||
常见文件说明:
|
||||
|
||||
| 文件 | 用途 |
|
||||
|---|---|
|
||||
| `.pvd` | ParaView 时间序列入口,优先打开它。 |
|
||||
| `.vtu` | 单步网格、粒子或物理量场。 |
|
||||
| `.csv` | 时间历程、误差评估、反力、能量、质量守恒等报告。 |
|
||||
| `.log` | 求解器监控、告警、收敛信息。 |
|
||||
|
||||
长时间计算建议每次写出 `.vtu` 后同步更新 `.pvd`,这样即使中途停止,也能查看已有结果。
|
||||
|
||||
## 新案例创建步骤
|
||||
|
||||
1. 复制一个相近案例目录,清空 `outputs/`。
|
||||
2. 修改 `config/cad.xml`,只运行几何阶段,检查 `.stl/.obj`。
|
||||
3. 修改 `config/meshing.xml` 或 `config/particle_meshing.xml`,检查 `.vtu`。
|
||||
4. 修改材料和求解器配置,先设置很少步数,例如 `max_steps="10"`。
|
||||
5. 确认日志、PVD、VTU 正常后,再增加计算时间和输出间隔。
|
||||
6. 如需验证解析解,额外编写 `benchmark_*.cpp`,只读取结果文件并输出报告。
|
||||
|
||||
## SPH 使用提示
|
||||
|
||||
SPH 案例首先检查粒子集:
|
||||
|
||||
- 水体粒子、壁面粒子、虚粒子是否能按 `role` 区分。
|
||||
- 边界粒子是否有 2 到 3 层厚度,角点和棱边是否连续。
|
||||
- 周期方向是否使用周期边界,而不是实体壁面。
|
||||
- `spacing`、`smoothing_length`、`mass`、`reference_density` 是否匹配。
|
||||
|
||||
常见调参顺序:
|
||||
|
||||
1. 先固定几何和粒子划分。
|
||||
2. 再调状态方程和人工声速。
|
||||
3. 再调物理黏性、人工黏性、XSPH、Delta-SPH。
|
||||
4. 最后调边界外推、粒子正则化和后处理。
|
||||
|
||||
## FEM 使用提示
|
||||
|
||||
FEM 案例首先检查网格和边界:
|
||||
|
||||
- 单元类型是否与求解器设置一致,例如 `tet4`、`hex8`、`beam`、`shell`。
|
||||
- 网格是否有负 Jacobian、sliver 或严重畸变。
|
||||
- 约束是否足够消除刚体模态。
|
||||
- 载荷方向、面积积分和反力平衡是否正确。
|
||||
|
||||
非线性和动力学案例建议先从线弹性小步长运行,再逐步打开大变形、接触、塑性、损伤、孔压耦合或 GPU 加速。
|
||||
|
||||
## 阅读路径
|
||||
|
||||
初次使用建议按以下顺序阅读:
|
||||
|
||||
1. [快速开始](quick_start.md)
|
||||
2. [安装与编译](installation.md)
|
||||
3. [Pipeline 流程](pipeline.md)
|
||||
4. [几何建模](geometry_manual.md)
|
||||
5. [网格与粒子划分](meshing_manual.md)
|
||||
6. [SPH 求解器](sph_manual.md) 或 [FEM 求解器](fem_manual.md)
|
||||
7. [常见问题](troubleshooting.md)
|
||||
|
||||
进一步阅读:
|
||||
|
||||
- [配置文件](configuration.md):XML/JSON/YAML 和统一配置模型。
|
||||
- [材料库](material_manual.md):材料参数、本构、状态方程。
|
||||
- [输入输出](io_manual.md):VTU/PVD/CSV/log。
|
||||
- [示例与 benchmark](examples_manual.md):案例组织和验证方式。
|
||||
- [项目结构](project_structure.md):模块职责边界。
|
||||
- [术语表](glossary.md):常见缩写和算法名称。
|
||||
|
||||
## 重要约定
|
||||
|
||||
- 文档以中文为主,代码、参数名和文件名保留英文。
|
||||
- XML 是当前推荐配置格式,JSON/YAML 通过统一配置模型逐步兼容。
|
||||
- 所有相对路径优先以配置文件所在目录或项目根目录解析,具体由对应执行入口说明。
|
||||
- 结果文件优先使用 `PVD + VTU`,时间历程监测数据优先使用 `CSV` 和文本日志。
|
||||
- 案例配置文件统一放入 `config/`,求解结果统一放入 `outputs/`。
|
||||
- benchmark 程序不得替代 pipeline 执行建模、离散和求解流程。
|
||||
|
||||
## 排错入口
|
||||
|
||||
遇到问题时建议按以下顺序定位:
|
||||
|
||||
| 现象 | 首先检查 |
|
||||
|---|---|
|
||||
| 找不到 XML 文件 | `pipeline.xml` 中 `Stage path` 是否相对当前案例目录。 |
|
||||
| 没有输出结果 | `Output` 路径、写权限、`output_interval` 和日志。 |
|
||||
| ParaView 读不了 VTU | PointData/CellData 数组长度是否匹配。 |
|
||||
| SPH 粒子飞出边界 | 边界粒子层数、壁面类型、时间步和压力范围。 |
|
||||
| SPH 粒子聚集 | 人工黏性、XSPH、粒子正则化、表面张力和密度滤波。 |
|
||||
| FEM 求解发散 | 约束、载荷步长、单元质量、材料切线和 line search。 |
|
||||
| 动力学结果异常 | 质量矩阵、阻尼、接触参数、时间步和输出频率。 |
|
||||
|
||||
更详细的处理方法见 [常见问题](troubleshooting.md)。
|
||||
Reference in New Issue
Block a user