7.6 KiB
7.6 KiB
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,这样即使中途停止,也能查看已有结果。
新案例创建步骤
- 复制一个相近案例目录,清空
outputs/。 - 修改
config/cad.xml,只运行几何阶段,检查.stl/.obj。 - 修改
config/meshing.xml或config/particle_meshing.xml,检查.vtu。 - 修改材料和求解器配置,先设置很少步数,例如
max_steps="10"。 - 确认日志、PVD、VTU 正常后,再增加计算时间和输出间隔。
- 如需验证解析解,额外编写
benchmark_*.cpp,只读取结果文件并输出报告。
SPH 使用提示
SPH 案例首先检查粒子集:
- 水体粒子、壁面粒子、虚粒子是否能按
role区分。 - 边界粒子是否有 2 到 3 层厚度,角点和棱边是否连续。
- 周期方向是否使用周期边界,而不是实体壁面。
spacing、smoothing_length、mass、reference_density是否匹配。
常见调参顺序:
- 先固定几何和粒子划分。
- 再调状态方程和人工声速。
- 再调物理黏性、人工黏性、XSPH、Delta-SPH。
- 最后调边界外推、粒子正则化和后处理。
FEM 使用提示
FEM 案例首先检查网格和边界:
- 单元类型是否与求解器设置一致,例如
tet4、hex8、beam、shell。 - 网格是否有负 Jacobian、sliver 或严重畸变。
- 约束是否足够消除刚体模态。
- 载荷方向、面积积分和反力平衡是否正确。
非线性和动力学案例建议先从线弹性小步长运行,再逐步打开大变形、接触、塑性、损伤、孔压耦合或 GPU 加速。
阅读路径
初次使用建议按以下顺序阅读:
进一步阅读:
- 配置文件:XML/JSON/YAML 和统一配置模型。
- 材料库:材料参数、本构、状态方程。
- 输入输出:VTU/PVD/CSV/log。
- 示例与 benchmark:案例组织和验证方式。
- 项目结构:模块职责边界。
- 术语表:常见缩写和算法名称。
重要约定
- 文档以中文为主,代码、参数名和文件名保留英文。
- 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。 |
| 动力学结果异常 | 质量矩阵、阻尼、接触参数、时间步和输出频率。 |
更详细的处理方法见 常见问题。