# 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 ``` FEM 案例只需把粒子划分和求解器替换为: ```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)。