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

201 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)。