Files
FemLite/docs/v5_development_plan.md
T
shenw 38623b518a
FemLite CI / build-test (push) Has been cancelled
Start V5 development baseline
2026-06-25 12:50:13 +08:00

668 lines
34 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.
# FemLite 0.5.x 第五版开发计划
文档状态:第五版开发建议稿
日期:2026-06-25
适用对象:FemLite 0.5.0 至 0.5.x 开发、评审、测试与阶段验收
## 1. 文档目的
本文档定义 FemLite 第五版的开发定位、阶段划分、技术路线、验收准则和风险控制。
第五版以 0.4.8 第四版阶段验收基线为起点,在保持第一版至第四版已验收能力不回退的前提下,集中补齐第四版验收报告中明确列为后续范围的工业级能力:
- 完整工业级 mortar / augmented Lagrangian 接触约束求解器。
- 外部第三方稀疏线性求解器后端。
- 完整 Mohr-Coulomb 材料、张拉截断和强度折减流程。
- 真实高保真滚压成形。
- 球-膜粘附/脱粘 cohesive 接触。
- 线性屈曲特征值分析。
- 循环对称边界和扇区模态分析。
- 颗粒流-膜/柔性容器双向耦合。
第五版的核心不是继续增加可运行 smoke,而是将第四版中的缩减示例升级为真实算法、真实状态变量、真实输出和真实验收指标支撑的工程能力。
## 2. 第五版定位
FemLite 0.5.x 定位为:
```text
工业级接触约束 + 外部稀疏求解 + 岩土塑性 + 高保真工程基准版
```
第五版应满足以下原则:
- 分阶段开发,但阶段结果不得以 mini 实现、demo 实现或仅 smoke 替代核心验收。
- 可以保留第四版近似路径作为 debug fallback,但不得把 fallback 作为第五版工业能力的完成依据。
- 每个新增核心能力必须包含算法文档、详细设计、接口说明、用户手册、开发者手册、单元测试、集成测试和至少一个独立示例目录。
- 每个高保真 benchmark 必须给出可检查的数值指标,例如收敛阶、残差、能量、反力曲线、临界载荷、极限承载力、接触压力分布或参考解误差。
- 示例仍统一放在 `examples/` 下,每个案例一个独立文件夹,包含 README、输入文件、双击运行脚本和必要的结果检查脚本。
- 大型结果文件不得直接提交到 git;只提交小型参考结果、抽样指标、检查脚本和生成说明。
## 3. 开发基线
0.4.8 已具备:
- 显式动力学、静力学、隐式 Newmark 和非线性 Newmark-Newton 主流程。
- C3D4、C3D8、C3D10、C3D20 实体单元和 S3、S4、S6、S8 壳单元基础能力。
- 各向同性线弹性、J2/J2_JC 小应变弹塑性和壳代表性 section plasticity。
- 面-面 contact pair 的投影裁剪面积、多 master 分摊、mortar 权重、Coulomb/正则化 Coulomb 摩擦历史、stick/slip 输出和 restart 保存。
- node-based surface 到 analytical rigid plane 的接触路径。
- active set、augmented penalty、接触 gap/mortar residual 诊断。
- BVH 接触搜索、候选缓存、OpenMP 并行搜索和并行一致性回归。
- 内部 CG、BiCGSTAB、GMRES 和 none/Jacobi 预条件器。
- CSV、VTK、restart、C ABI、Python 调试接口和示例 smoke 矩阵。
- Windows GCC 16 下第四版阶段验收测试 66/66 通过。
第四版明确未完成且进入第五版的内容:
- 当前接触仍不是完整 mortar/augmented Lagrangian 约束求解器;法向乘子仍以接触对级增强罚为主。
- 外部第三方稀疏求解器路径仍返回 unsupported。
- Mohr-Coulomb、张拉截断、非关联流动和强度折减仍未作为核心材料流程实现。
- 滚压成形、球黏附/脱粘、波纹壳屈曲、循环对称和颗粒装填案例仍是可执行缩减基准。
- 线性屈曲、循环对称、颗粒流-膜双向耦合仍缺少核心求解器支持。
### 3.1 基于当前代码的落地检查
第五版开发前必须先承认当前代码结构的真实落点。以下模块不是抽象规划,而是第五版会直接修改或需要先拆分的代码位置:
| 能力 | 当前代码位置 | 当前状态 | 第五版落地要求 |
|---|---|---|---|
| 线性求解器 | `src/solver/fem_linear_solver_cg.f90`、`src/base/fem_control.f90` | 单个模块同时承担 solver dispatch、CG、BiCGSTAB、GMRES;`LSOLVER_EXTERNAL` 可配置但求解时返回 unsupported | V5.2 先拆出 dispatch、iterative solver 和 external adapter;保持现有 API 兼容,再新增后端能力查询 |
| CSR 矩阵 | `src/solver/fem_sparse_csr.f90` | 内部 CSR 支持装配、取值和 matvec | V5.2 增加只读 CSR 导出/转换层,明确 0-based/1-based 索引、对称性和矩阵类型元数据 |
| 隐式求解调用点 | `src/solver/fem_solver_implicit.f90` | 线性静力、非线性静力和 Newmark 路径均直接调用 `linear_solver_solve` | 外部 solver 验收必须覆盖这些调用点,不只覆盖孤立矩阵测试 |
| 接触状态 | `src/boundary/fem_contact_state.f90`、`src/boundary/fem_contact_history.f90` | 当前有 pair 级 augmented lambda 和 mortar 积分点摩擦历史 | V5.3 新增积分点/约束级法向乘子历史,并纳入 trial/rollback/commit 和 restart |
| 接触力/切线 | `src/boundary/fem_contact_force.f90`、`src/boundary/fem_contact_tangent.f90` | 已包含 mortar 权重、摩擦和切线近似,文件规模已接近或超过大文件警戒线 | V5.3 不得继续把完整 AL 逻辑直接堆入这两个文件,应新增 constraint/multiplier/tangent 子模块并由现有入口薄封装调用 |
| 材料数据库 | `src/mesh/fem_database_state.f90`、`src/mesh/fem_database.f90` | 材料参数以数组形式保存,校验仅接受 `ELASTIC`、`J2`、`J2_JC` | V5.4 增加 Mohr-Coulomb 参数数组、合法性校验、状态变量布局和输出字段 |
| 材料算法 | `src/material/fem_material_j2.f90`、`src/element/fem_element_internal.f90`、`src/element/fem_element_stiffness.f90` | 当前弹塑性分发围绕 J2/J2_JC | V5.4 新增独立 `fem_material_mohr_coulomb`,并接入内力、刚度、trial 状态和单元状态分发 |
| 输入解析 | `src/input/fem_inp_reader.f90`、`src/input/fem_inp_helpers.f90` | 已解析 J2/J2_JC、surface/contact 子集;analytical surface 当前以平面为主 | V5.4-V5.7 需要新增 Mohr-Coulomb、强度折减、圆柱/刚体辊、cohesive law 和颗粒参数输入 |
| C ABI | `include/femlite_c_api.h`、`src/interface/fem_c_api.c` | 已有 solver 设置/统计、contact 统计和 SPH 载荷映射接口 | V5.2-V5.8 需新增 solver 后端能力、接触乘子/cohesive/颗粒诊断接口,并保持旧 ABI 可用 |
| 耦合接口 | `src/coupling/fem_coupling.f90`、`fsph` 全局力向量 | 当前是边界 facet 导出和外部 SPH 载荷映射,不是颗粒求解器 | V5.8 必须新增颗粒状态、邻域搜索和时间推进模块,不能把现有 SPH 载荷映射宣称为颗粒耦合完成 |
| 高保真示例 | `examples/roll_forming`、`examples/ball_adhesion_decohesion`、`examples/buckling_corrugated_shell`、`examples/Dynamic_Grain_Packing_of_a_Flexible_Container` | 均为 V4.8 可执行缩减基准或 smoke | V5.6-V5.8 必须新增或替换为真实高保真输入、检查脚本和参考指标;原 smoke 可保留为快速回归 |
因此,第五版的第一批代码工作不应直接写大型算法,而应先完成求解器、接触、材料和耦合四条主线的接口拆分和数据结构扩展。否则后续能力会被迫写成新的局部近似,无法达到第五版“不再 mini 化”的要求。
## 4. 版本与分支策略
建议分支:
- `main`:保持已发布稳定版本。
- `dev/v0.5`:第五版主开发分支。
- `feature/v5-sparse-backends`:外部稀疏求解器后端。
- `feature/v5-mortar-al`:完整 mortar / augmented Lagrangian 接触。
- `feature/v5-mohr-coulomb`:Mohr-Coulomb 材料与强度折减。
- `feature/v5-buckling-cyclic`:线性屈曲和循环对称。
- `feature/v5-roll-forming`:高保真滚压成形。
- `feature/v5-cohesive-adhesion`:粘附/脱粘 cohesive 接触。
- `feature/v5-grain-coupling`:颗粒流-膜/容器双向耦合。
- `feature/v5-benchmarks-release`:第五版 benchmark、文档和验收发布。
版本号策略:
- `0.5.0`:第五版开发起点,提升项目版本号,建立 V5 计划、首页 README 和 V4.8 验收基线说明。
- `0.5.1`:第五版架构冻结、V4 deferred 项登记和验收矩阵建立。
- `0.5.2`:外部稀疏求解器后端完成。
- `0.5.3`:完整工业级 mortar / augmented Lagrangian 接触完成。
- `0.5.4`:完整 Mohr-Coulomb 和强度折减完成。
- `0.5.5`:线性屈曲和循环对称完成。
- `0.5.6`:真实高保真滚压成形完成。
- `0.5.7`:球-膜粘附/脱粘 cohesive 接触完成。
- `0.5.8`:颗粒流-膜/柔性容器双向耦合完成。
- `0.5.9`:高保真 benchmark、性能长跑和多平台回归完成。
- `0.5.10`:第五版验收报告、文档同步和发布检查完成。
发布前必须更新:
- CMake 项目版本。
- Fortran 版本常量。
- `docs/v5_acceptance_report.md`。
- 需求、架构、详细设计、数学算法、接口、测试、用户手册和开发者手册。
- 示例 README、运行脚本、检查脚本和 CTest 接入。
## 5. 第五版阶段划分
| 阶段 | 名称 | 主要内容 | 完成标志 |
|---|---|---|---|
| V5.1 | 架构冻结与验收矩阵 | V4 deferred 项清单、接口设计、风险分级、benchmark 矩阵 | `docs/v5_development_plan.md` 和 V5 验收矩阵完成 |
| V5.2 | 外部稀疏求解器 | C/Fortran 适配层、CMake 可选依赖、CSR 转换、失败诊断 | 至少一个外部后端可用于静力/隐式求解 |
| V5.3 | 完整 mortar 接触 | 积分点乘子、AL 更新、active set、一致切线、摩擦耦合 | 面-面大滑移接触 benchmark 收敛且压力分布可验证 |
| V5.4 | Mohr-Coulomb | 非关联流动、张拉截断、角点返回、一致切线、强度折减 | 材料点、三轴、边坡强度折减 benchmark 通过 |
| V5.5 | 屈曲与循环对称 | 几何刚度、广义特征值、模态输出、扇区边界映射 | 波纹壳屈曲和循环扇区模态 benchmark 通过 |
| V5.6 | 高保真滚压成形 | 刚体辊运动、旋转、摩擦、塑性成形、回弹指标 | roll forming 真实案例替换 V4 surrogate |
| V5.7 | 粘附/脱粘 cohesive 接触 | 法向/切向 cohesive law、损伤演化、能量输出 | ball adhesion/decohesion 真实案例通过 |
| V5.8 | 颗粒耦合 | 颗粒-颗粒、颗粒-膜、载荷映射、双向耦合时间推进 | dynamic grain container 真实双向案例通过 |
| V5.9 | Benchmark 与性能 | 高保真示例矩阵、长跑、并行和多平台回归 | V5 benchmark CTest/长跑矩阵稳定 |
| V5.10 | 验收与发布 | 验收报告、文档同步、包检查、版本发布 | 形成 0.5.x 第五版阶段验收版 |
## 6. V5.1 架构冻结与验收矩阵
目标:
- 将第四版验收报告中的后续限制转化为第五版可执行开发项。
- 在写代码前冻结核心接口边界,避免后续阶段反复推翻数据结构。
- 为第五版定义“完整实现”的最低标准,禁止用缩减 smoke 替代验收。
建议实现内容:
1. 建立 V5 deferred 项登记表:
- 完整 mortar / AL 接触。
- 外部稀疏求解器。
- Mohr-Coulomb 和强度折减。
- 线性屈曲和循环对称。
- 高保真滚压、球黏附、颗粒耦合。
2. 冻结新增接口:
- 线性求解器后端枚举和能力查询。
- 接触乘子/历史变量/restart 格式。
- 材料状态变量布局。
- 特征值求解器和模态输出接口。
- 颗粒耦合外力和接触映射接口。
3. 明确 fallback 策略:
- V4 penalty/mortar 权重路径保留为 debug fallback。
- 内部 CG/BiCGSTAB/GMRES 保留为无外部库构建的默认路径。
- V4 缩减示例保留为 smoke,但不得作为 V5 完成依据。
4. 建立测试等级:
- `smoke`:小规模可执行路径检查。
- `regression`:数值指标回归。
- `benchmark`:参考解或公开基准对比。
- `longrun`:性能、稳定性和内存泄漏长跑。
5. 完成代码迁移准备:
- 线性求解器模块拆分方案。
- 接触 AL/multiplier 历史数据结构方案。
- Mohr-Coulomb 材料数据库扩展方案。
- 刚体辊、cohesive 和颗粒输入关键字方案。
- C ABI 向后兼容策略。
验收条件:
- 新增 `docs/v5_development_plan.md`。
- 新增或更新第五版测试矩阵文档。
- 每个 V5 能力都有明确的设计文档、测试入口和验收指标。
- 完成 `src/solver`、`src/boundary`、`src/material`、`src/coupling`、`src/input` 和 `include` 的 V5 代码落点清单。
- `ctest` 中保留 V1-V4 已验收测试且无回退。
## 7. V5.2 外部稀疏求解器后端
目标:
- 将第四版预留的 `LSOLVER_EXTERNAL` 从 unsupported 推进为真实可用后端。
- 支撑后续 mortar、屈曲、滚压和颗粒耦合的大规模非对称/病态线性系统。
推荐技术路线:
当前代码适配要求:
- `fem_linear_solver_cg.f90` 当前模块名已不能准确表达职责。V5.2 应优先拆分为:
- `fem_linear_solver_dispatch`:保留 `linear_solver_solve/configure/get_stats` 对外入口。
- `fem_linear_solver_iterative`:承载 CG、BiCGSTAB、GMRES 和预条件器。
- `fem_linear_solver_external`:承载外部库 adapter、能力查询和 unavailable 路径。
- `LSOLVER_EXTERNAL` 当前已有枚举值,不能改变数值以免破坏 C ABI;新增后端类型应使用新的 backend 枚举或配置字段。
- 现有 `test_linear_solver_cg` 中 external unsupported 回归需要拆成两个测试:未启用外部库时返回 unavailable;启用外部库时真实求解。
- `fem_solver_implicit` 中所有 `linear_solver_solve` 调用都必须保持无需知道具体后端。
1. 后端选择:
- 第一优先:SuperLU 或 MUMPS,便于开源构建和 CI 验证。
- 第二优先:MKL Pardiso,作为 Windows/Intel 高性能可选路径。
- 所有后端通过统一 adapter 层接入,不让核心 solver 直接依赖第三方头文件。
2. CSR 适配:
- 明确 0-based/1-based 索引转换。
- 支持对称、非对称、正定、不定矩阵能力声明。
- 明确实数双精度为首要支持类型。
3. CMake 集成:
- `FEMLITE_ENABLE_SUPERLU`。
- `FEMLITE_ENABLE_MUMPS`。
- `FEMLITE_ENABLE_MKL_PARDISO`。
- 未找到依赖时给出清晰 warning 或 error,不影响默认内部求解器构建。
4. 运行时接口:
- 支持设置 method、preconditioner/backend。
- 支持查询实际启用后端、factorization 状态、迭代或直接求解统计。
- 后端不可用时返回明确状态,禁止静默回退。
5. 验证:
- SPD、非对称、病态、接触切线、约束系统矩阵测试。
- 与内部 CG/BiCGSTAB/GMRES 的残差一致性比较。
验收条件:
- 至少一个外部稀疏求解器后端在本地可构建并通过 CTest。
- `LSOLVER_EXTERNAL` 不再返回 unsupported。
- 外部后端能完成至少一个静力、一个隐式动力和一个接触非线性算例。
- 外部后端失败时有错误码、错误消息和文档说明。
风险控制:
- 第五版不要求所有平台同时启用所有后端。
- 默认构建必须仍可不依赖第三方库完成。
- 外部库 license、二进制分发和 CI 可用性必须在发布文档中说明。
## 8. V5.3 完整工业级 Mortar / Augmented Lagrangian 接触
目标:
- 将第四版 penalty + mortar 权重 + 接触对级增强罚升级为完整工程级 mortar / augmented Lagrangian 约束求解器。
- 支持大滑移、多 master、多 slave、摩擦耦合和可收敛的非线性一致切线。
当前代码适配要求:
- `contact_pair_aug_lambda` 当前是接触对级状态,V5.3 需要新增积分点或约束级乘子槽,不能复用 pair 级标量冒充完整 AL。
- `fem_contact_force.f90` 和 `fem_contact_tangent.f90` 已承载大量几何、力和切线逻辑。V5.3 应新增 `fem_contact_constraint`、`fem_contact_multiplier`、`fem_contact_mortar_al` 等职责单一模块。
- 当前 `fem_contact_history` 已保存摩擦历史,V5.3 应扩展为统一接触历史仓库,保存法向乘子、切向牵引、active set、stick/slip 和 cohesive 状态的版本化记录。
- restart 文件格式需要再次升级,且必须兼容 V4 restart 中已有 contact history 段。
- node-based surface 到一般 element master 的路径当前仍有限制,完整 mortar 验收前必须明确 node-surface 是支持、转换为 facet 约束,还是作为独立后续项。
建议实现内容:
1. Mortar 离散:
- slave/master 投影交叠域稳健裁剪。
- mortar 积分点、形函数、法向和切向基统一数据结构。
- 非匹配网格接触压力分布检查。
- 节点法向、面法向和壳侧向语义一致处理。
2. 约束变量:
- 法向接触乘子从 pair 级推进到 mortar 积分点或约束自由度级。
- 切向摩擦历史与法向乘子同一积分点槽管理。
- active/inactive/stick/slip/open 状态进入 trial/rollback/commit。
3. Augmented Lagrangian:
- 法向乘子更新。
- 接触穿透硬收敛准则。
- penalty 参数自适应或用户可控策略。
- active set 切换与 cutback 协同。
4. 一致切线:
- 法向约束切线。
- 切向 stick/slip 算法切线。
- 几何项和接触法向变化项的工程级处理。
- 非对称切线可进入外部稀疏求解器。
5. 并行和 restart:
- 乘子历史 deterministic merge。
- OpenMP 装配一致性。
- restart 保存完整接触历史、乘子和 active set。
6. 输出:
- 接触压力、切向牵引、gap、滑移、摩擦功、AL 乘子、active 状态。
- 输出体量可控,支持积分点抽样和 summary。
验收条件:
- 两块体非匹配网格压缩接触压力分布与参考解误差可控。
- 大滑移摩擦接触在隐式非线性求解中稳定收敛。
- 壳-实体、壳-壳、实体-实体至少各一个 benchmark 通过。
- OpenMP 1 线程和多线程结果在容差内一致。
- restart 后接触历史和乘子连续。
## 9. V5.4 完整 Mohr-Coulomb 与强度折减
目标:
- 实现可用于岩土工程基准的完整 Mohr-Coulomb 材料。
- 将 V4 strengthReduction 示例从 J2 surrogate 升级为真实 Mohr-Coulomb 强度折减案例。
当前代码适配要求:
- `fem_database_state` 目前没有 Mohr-Coulomb 参数数组。V5.4 至少需要新增摩擦角、黏聚力、膨胀角、张拉强度、残余参数和强度折减系数相关字段。
- `validate_materials` 当前只接受 `ELASTIC/J2/J2_JC`,需要新增 `MOHR_COULOMB` 分支和严格参数校验。
- `fem_material_j2` 不应继续膨胀为通用塑性模块,应新增独立 `fem_material_mohr_coulomb.f90`。
- `fem_element_internal` 和 `fem_element_stiffness` 中现有 J2/J2_JC 分发需要抽象为材料更新接口,避免把 Mohr-Coulomb 分支散落在单元实现内部。
- inp 解析需要新增 Mohr-Coulomb 关键字子集,并在不支持完整 Abaqus 语法时给出明确 warning/error。
建议实现内容:
1. 材料模型:
- Mohr-Coulomb 屈服面。
- 非关联流动法则。
- 摩擦角、黏聚力、膨胀角。
- 张拉截断。
- 平面、棱边和角点返回映射。
- consistent tangent 或可验证的工程切线。
2. 状态变量:
- 塑性应变。
- 等效塑性应变或剪切塑性指标。
- 当前屈服面分支。
- 张拉破坏或剪切破坏状态。
3. 强度折减:
- 自动折减摩擦角和黏聚力。
- 安全系数二分/弧长式搜索。
- 失稳判据:不收敛、位移突变、塑性区贯通或残差退化。
- 输出安全系数、塑性区和位移曲线。
4. 输入支持:
- Abaqus 风格材料关键字子集或 FemLite 自有关键字。
- 支持关联/非关联参数。
- 支持单位和参数合法性检查。
验收条件:
- 单积分点三轴压缩、三轴拉伸和纯剪测试通过。
- 张拉截断路径有独立回归。
- 边坡强度折减 benchmark 给出稳定安全系数。
- Mohr-Coulomb 与 J2/J2_JC 既有路径互不回退。
风险控制:
- 角点返回是主要数值风险,必须先做材料点测试,再进入结构算例。
- 初期可提供 substepping,但最终验收必须记录 substep 次数和收敛状态。
## 10. V5.5 线性屈曲与循环对称
目标:
- 实现线性屈曲特征值分析,将静力预载后的几何刚度纳入广义特征值问题。
- 实现循环对称边界,使扇区模型可用于周期结构屈曲和模态分析。
当前代码适配要求:
- 当前 `src/solver` 没有特征值求解器模块,V5.5 应新增 `fem_eigensolver` 或同等职责模块,并复用 V5.2 的外部 solver adapter。
- 当前单元刚度路径没有独立几何刚度装配入口,V5.5 需要新增 `fem_element_geometric_stiffness` 或在现有单元刚度接口中增加清晰分发。
- 循环对称不能只用 MPC penalty 近似完成;必须定义扇区边界节点配对、坐标旋转、壳转角映射和约束装配方式。
- CLI/inp 需要新增 buckling step、预载 step、特征阶数和循环波数输入路径。
建议实现内容:
1. 线性屈曲:
- 静力预载平衡状态保存。
- 几何刚度 `K_G` 装配。
- 广义特征值问题 `K phi = -lambda K_G phi`。
- 特征值求解器接口,可优先使用外部 sparse eigensolver。
- 屈曲模态 VTK/CSV 输出。
2. 循环对称:
- 扇区边界节点配对。
- 坐标旋转映射。
- 周向波数/节径输入。
- 实数等效约束或复数接口预留。
- 与壳单元转角自由度兼容。
3. 示例升级:
- `examples/buckling_corrugated_shell` 从静力 preload smoke 升级为真实屈曲特征值案例。
- 增加完整模型与扇区循环模型对比。
验收条件:
- Euler 梁或柱屈曲解析解误差满足阈值。
- 平板/圆柱壳屈曲 benchmark 通过。
- 波纹壳循环扇区模型与完整模型前若干阶临界载荷一致。
- 模态输出可视化方向和归一化稳定。
风险控制:
- 特征值求解依赖外部库,V5.2 应先打通外部 solver adapter。
- 循环对称涉及转动自由度和坐标映射,必须覆盖实体和壳两类边界。
## 11. V5.6 真实高保真滚压成形
目标:
- 将 `examples/roll_forming` 从弹性接触 surrogate 升级为包含刚体辊旋转、摩擦、塑性成形和回弹指标的真实滚压成形 benchmark。
当前代码适配要求:
- 当前 analytical surface 主要支持平面,真实滚压需要圆柱刚体面或离散刚体辊,并支持随时间旋转和平移。
- 当前接触相对速度需要接入刚体辊角速度贡献,否则摩擦牵引不能代表滚动成形。
- 滚压流程需要多 step 和 restart/卸载语义;如果现有 inp step 语义不足,V5.6 必须先补输入控制。
- 真实滚压依赖 V5.3 mortar/摩擦和 V5.2 外部 solver;不得在 V5.6 中重新写一条专用接触捷径。
建议实现内容:
1. 刚体辊:
- analytical 或离散刚体圆柱面。
- prescribed rotation、translation 和下压位移。
- 辊-板接触法向、切向速度和摩擦功输出。
2. 工件塑性:
- J2/J2_JC 或后续板材硬化模型。
- 大滑移摩擦接触。
- 残余应力和回弹位移输出。
3. 工艺流程:
- 下压。
- 滚动进给。
- 卸载回弹。
- 分步重启动作。
4. 验证指标:
- 成形力-位移曲线。
- 接触压力带宽。
- 塑性区分布。
- 回弹量。
验收条件:
- 真实刚体辊旋转参与接触相对速度计算。
- 塑性成形和卸载回弹均可运行。
- 与参考文档参数一致的独立 example 通过检查脚本。
- 接触能量、塑性功和外力功无明显非物理跳变。
## 12. V5.7 球-膜粘附/脱粘 Cohesive 接触
目标:
- 将 `examples/ball_adhesion_decohesion` 从球-膜压入 smoke 升级为真实粘附/脱粘 cohesive 接触案例。
当前代码适配要求:
- 当前接触历史保存摩擦滑移和摩擦功,不保存 cohesive 损伤;V5.7 必须新增损伤变量、最大开口、粘附能量和脱粘状态。
- Cohesive 不能只作为材料模型实现;它需要接触积分点状态、接触切换规则、切线和 restart。
- 输出层需要新增 cohesive summary 和可选积分点抽样,避免默认 CSV 体量失控。
- 与 V5.3 共用的接触历史仓库必须提前预留 cohesive 字段,避免 V5.7 再次改 restart 格式。
建议实现内容:
1. Cohesive law:
- 法向牵引-分离关系。
- 切向牵引-滑移关系。
- 混合模态损伤演化。
- 粘附启动、损伤增长和完全脱粘。
2. 接触切换:
- 压缩时普通接触。
- 拉开时 cohesive traction。
- 完全脱粘后重新接触路径。
3. 状态变量:
- 损伤变量。
- 最大开口位移。
- 粘附能量。
- 脱粘标志。
4. 输出:
- 粘附区面积。
- cohesive 能量。
- 最大开口。
- 脱粘前沿。
验收条件:
- 单 cohesive 积分点加载-卸载-脱粘测试通过。
- 球-膜粘附案例给出力-位移滞回曲线。
- cohesive 能量耗散非负。
- restart 后损伤变量连续。
## 13. V5.8 颗粒流-膜/柔性容器双向耦合
目标:
- 将 `examples/Dynamic_Grain_Packing_of_a_Flexible_Container` 从压力-地面接触 surrogate 升级为真实颗粒装填与柔性膜/容器双向耦合案例。
当前代码适配要求:
- 当前 `fem_coupling` 只提供边界 facet 导出和外部 SPH 载荷映射,`fsph` 是全局力向量,不包含颗粒位置、速度、质量、半径或接触历史。
- V5.8 应新增独立颗粒状态模块,例如 `src/particle/fem_particle_state.f90`、`src/particle/fem_particle_search.f90` 和 `src/particle/fem_particle_contact.f90`,再通过 coupling 层把颗粒力映射到 FEM。
- 颗粒时间推进应有独立诊断:颗粒数量、接触对数量、最大重叠、动能、耗散能和耦合力范数。
- C ABI 可保留现有 SPH 外力接口,但不能把它作为第五版颗粒耦合完成项。
推荐技术路线:
1. 颗粒模型:
- 第五版优先实现内置离散球颗粒 DEM-like 模型。
- 支持颗粒质量、半径、速度、角速度和材料参数。
- 支持颗粒-颗粒、颗粒-刚墙、颗粒-膜/壳接触。
2. 接触模型:
- 法向弹簧阻尼。
- 切向摩擦历史。
- 滚动阻尼可选。
- 与 V5 mortar 接触输出风格保持一致。
3. 双向耦合:
- 颗粒对膜施加载荷。
- 膜位移和速度反馈到颗粒边界。
- 支持显式 staggered 时间推进。
- 输出动量、能量和接触统计。
4. 搜索:
- 颗粒邻域网格或 BVH。
- 颗粒-壳 facet 候选搜索。
- 大颗粒数量性能 smoke 和 longrun。
验收条件:
- 颗粒自由落体、颗粒堆积、颗粒-刚墙碰撞基础测试通过。
- 柔性容器受颗粒冲击产生双向响应。
- 颗粒总质量、动量变化和能量耗散可诊断。
- 颗粒耦合示例有独立目录、运行脚本和检查脚本。
风险控制:
- 第五版只承诺离散球颗粒,不承诺任意形状颗粒。
- 如接入外部颗粒求解器,必须通过 adapter 层,不得侵入 FEM 核心时间循环。
## 14. V5.9 高保真 Benchmark、性能和多平台回归
目标:
- 将第五版核心能力统一收束到 benchmark 矩阵,而不是散落在单个示例中。
- 验证外部 solver、mortar、材料、屈曲、循环对称、滚压、cohesive 和颗粒耦合在多平台下不回退。
建议 benchmark 矩阵:
| 目录 | 第五版目标 | 验收指标 |
|---|---|---|
| `examples/contact_two_blocks_compression` | 非匹配网格 mortar 压缩 | 压力分布、gap、AL 乘子收敛 |
| `examples/contact_block_sliding` | 大滑移摩擦 mortar | stick/slip、摩擦功、切向反力 |
| `examples/shell_solid_connection` | 壳-实体接触/连接高保真 | 接触压力、能量、位移连续性 |
| `examples/strengthReduction` | Mohr-Coulomb 强度折减 | 安全系数、塑性区贯通 |
| `examples/buckling_corrugated_shell` | 线性屈曲和循环对称 | 临界载荷、模态形状 |
| `examples/roll_forming` | 真实滚压成形 | 成形力、塑性区、回弹量 |
| `examples/ball_adhesion_decohesion` | cohesive 粘附/脱粘 | 滞回曲线、耗散能、脱粘面积 |
| `examples/Dynamic_Grain_Packing_of_a_Flexible_Container` | 颗粒-膜双向耦合 | 容器位移、颗粒接触统计、能量 |
测试层级:
- 默认 CTest:保留小规模 smoke 和单元测试。
- 扩展 CTest:启用外部库和 benchmark regression。
- 长跑测试:大规模接触、滚压、颗粒和屈曲矩阵。
- 发布前测试:Windows GCC、WSL gfortran、Windows Intel oneAPI ifx/MSVC,按依赖可用性分级记录。
验收条件:
- V1-V4 回归测试全部通过。
- V5 默认 CTest 全部通过。
- 启用外部 solver 的扩展测试通过。
- 所有高保真示例均有 README、输入、运行脚本、检查脚本和文档说明。
- 所有 V4 中标注为 surrogate 的第五版目标案例均替换或补充真实高保真输入。
## 15. V5.10 验收与发布
目标:
- 形成 FemLite 0.5.x 第五版阶段验收版。
- 明确第五版已经完成的工业能力和仍未完成的后续边界。
发布验收环境:
- Windows GCC 16 默认构建。
- WSL gfortran 默认构建。
- Windows Intel oneAPI ifx/MSVC 默认构建。
- 启用外部 solver 的至少一个本地构建。
- 可选:启用 OpenMP 的接触和颗粒性能构建。
发布前必须执行:
```powershell
cmake --build build-win-gcc-16 --config Release
ctest --test-dir build-win-gcc-16 --output-on-failure
```
如外部 solver 构建目录独立,必须额外执行:
```powershell
ctest --test-dir build-v5-external-solver --output-on-failure
```
发布材料:
- `docs/v5_acceptance_report.md`。
- 更新后的 `docs/01_requirements_specification.md`。
- 更新后的 `docs/02_software_architecture_design.md`。
- 更新后的 `docs/03_detailed_design.md`。
- 更新后的 `docs/04_mathematical_model_and_algorithms.md`。
- 更新后的 `docs/05_interface_control_document.md`。
- 更新后的 `docs/06_test_and_verification_plan.md`。
- 更新后的 `docs/07_user_manual.md`。
- 更新后的 `docs/08_developer_manual.md`。
- 第五版 benchmark 示例矩阵。
验收条件:
- `docs/v5_acceptance_report.md` 明确列出 PASS、PARTIAL 和 DEFERRED 项。
- 所有第五版完成项不得以“当前为缩减 surrogate”作为最终状态。
- 每个 DEFERRED 项必须说明原因、风险和对既有能力的影响。
- `main` 合并前必须保证工作区干净、测试结果可复现、文档口径一致。
## 16. 跨阶段工程约束
代码约束:
- 普通过程/函数尽量不超过 100 行,超过 128 行必须登记审查理由和拆分方向。
- 源文件尽量不超过 1500 行,超过 2000 行必须审查是否拆分。
- `source_size` CTest 继续作为本地回归检查项。
- 新增算法优先放入职责清晰的新模块,避免继续膨胀已有大型 solver 或 contact 文件。
数值约束:
- 新增非线性状态必须支持 trial/rollback/commit。
- 新增历史变量必须支持 restart 保存和读取。
- 新增接触、材料、颗粒状态必须有可查询诊断。
- 新增外部依赖必须有 unavailable 路径测试。
- 默认构建不能因为外部依赖缺失而失败,除非用户显式开启对应必需选项。
文档约束:
- 新增算法必须同步记录在数学模型与算法文档中。
- 新增输入关键字、C ABI 或 CLI 参数必须同步记录在接口文档中。
- 新增示例必须同步记录在用户手册和测试文档中。
- 新增 benchmark 的参考指标、容差和限制必须写入 README。
## 17. 第五版验收准则
0.5.x 阶段验收建议满足:
- 0.1.0、0.2.0、0.3.3 和 0.4.8 已验收能力无回退。
- 至少一个外部稀疏求解器后端真实可用。
- 完整 mortar / augmented Lagrangian 接触通过实体、壳、摩擦和 restart benchmark。
- Mohr-Coulomb 材料通过材料点、结构和强度折减 benchmark。
- 线性屈曲特征值分析和循环对称边界通过解析或公开基准。
- 滚压成形案例包含真实刚体辊运动、塑性成形和回弹检查。
- 球黏附/脱粘案例包含 cohesive law、损伤演化和能量检查。
- 颗粒耦合案例包含真实颗粒和柔性容器双向响应。
- examples 下第五版目标案例均为独立文件夹,包含可执行输入和双击运行脚本。
- 所有新增能力均有单元测试、集成测试、示例测试和文档说明。
- 验收报告明确列出尚未完成的后续能力,不夸大第五版范围。
## 18. 风险与缓解
| 风险 | 影响 | 缓解 |
|---|---|---|
| 外部 solver 跨平台依赖复杂 | 构建和发布受阻 | 默认内部 solver 保持可用,外部后端分级启用 |
| Mortar/AL 一致切线难度高 | 非线性接触不收敛 | 先做无摩擦法向约束,再接 stick/slip 和几何项 |
| Mohr-Coulomb 角点返回不稳定 | 岩土算例失败 | 材料点测试先行,substepping 和分支诊断同步实现 |
| 特征值求解依赖外部库 | 屈曲阶段被阻塞 | V5.2 先完成外部 solver adapter,V5.5 复用 adapter |
| 循环对称转角映射复杂 | 壳模型边界错误 | 从实体平移 DOF 开始,再扩展壳转角 DOF |
| 滚压成形计算量大 | 默认测试过慢 | 默认 smoke + 扩展 benchmark + longrun 分层 |
| Cohesive 接触状态切换复杂 | 粘附/普通接触不连续 | 单积分点和单面片测试先行,restart 同步覆盖 |
| 颗粒耦合范围膨胀 | 版本不可控 | 第五版限定离散球颗粒和显式 staggered 双向耦合 |
## 19. 初始执行顺序建议
第五版建议按以下顺序推进:
1. 建立 `dev/v0.5` 分支和 V5 文档/验收矩阵。
2. 完成外部稀疏求解器 adapter。
3. 完成 mortar/AL 接触法向约束。
4. 接入 mortar 摩擦一致切线和 restart。
5. 实现 Mohr-Coulomb 材料点与结构 benchmark。
6. 实现线性屈曲和循环对称。
7. 升级滚压、球黏附和颗粒耦合真实案例。
8. 补齐所有示例、文档、测试和验收报告。
排序理由:
- 外部 solver 是后续大规模非对称系统、特征值和高保真 benchmark 的基础。
- Mortar/AL 是滚压、cohesive、颗粒-膜接触和壳-实体 benchmark 的基础。
- Mohr-Coulomb 相对独立,可在 mortar 主线稳定后并行推进。
- 应用级高保真案例必须建立在核心算法真实可用之后。