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

7.6 KiB
Raw Blame History

M3Frame 用户手册

M3Frame 是面向多物理数值仿真的研究型计算框架,当前重点覆盖:

  • SPH:流体、自由面、表面张力、多相流、固体破碎、开放边界和壁面边界。
  • FEM:实体、梁、板壳、接触、多孔介质、静力学、准静态和动力学流程。
  • Geometry/Meshing:XML 驱动的 CAD 建模、几何导出、体网格划分和 SPH 粒子划分。
  • Pipeline:用一个 pipeline.xml 串联几何、离散、材料、求解、耦合和后处理。

适用范围

本手册面向三类用户:

  • 使用者:通过配置文件运行已有 SPH/FEM/耦合案例。
  • 案例开发者:建立新的 benchmark、工程算例或参数对比算例。
  • 模块开发者:扩展 CAD、网格、材料、本构、求解器、后处理和 pipeline 阶段。

如果只想运行案例,优先阅读“推荐使用方式”和“标准运行流程”;如果要扩展代码,再阅读各模块手册和 docs/coding_conventions.md。

推荐使用方式

新案例优先采用纯配置文件控制:

case/
  pipeline.xml
  config/
    cad.xml
    meshing.xml 或 particle_meshing.xml
    sph_solver.xml 或 fem_solver.xml
  outputs/

其中:

路径 作用
pipeline.xml 案例总入口,按阶段调度几何、离散、求解和后处理。
config/ 保存几何、网格、粒子、材料、求解器和后处理配置。
outputs/ 保存几何文件、网格/粒子文件、求解结果、日志和报告。

运行方式:

.\cmake-build-cuda13\Release\M3Frame.exe path\to\pipeline.xml

benchmark 程序建议只负责读取结果、对比解析解、写报告,不再承担几何建模或求解流程。

标准运行流程

一个完整案例通常按以下顺序执行:

cad.xml
  -> meshing.xml 或 particle_meshing.xml
  -> materials.xml 可选
  -> sph_solver.xml 或 fem_solver.xml
  -> post.xml 可选
  -> benchmark_*.cpp 可选

对应的 pipeline.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 案例只需把粒子划分和求解器替换为:

<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

输出文件约定

推荐输出结构:

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. 快速开始
  2. 安装与编译
  3. Pipeline 流程
  4. 几何建模
  5. 网格与粒子划分
  6. SPH 求解器 或 FEM 求解器
  7. 常见问题

进一步阅读:

重要约定

  • 文档以中文为主,代码、参数名和文件名保留英文。
  • 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。
动力学结果异常 质量矩阵、阻尼、接触参数、时间步和输出频率。

更详细的处理方法见 常见问题。