8.9 KiB
8.9 KiB
FemLite 0.5.3 Development Plan
日期:2026-07-01
适用对象:FemLite 0.5.3 开发、评审、测试与阶段验收。
1. 版本定位
FemLite 0.5.3 定位为:
接触与非线性诊断加固版
0.5.2 已经形成较宽的算法覆盖面:内部 Krylov 求解器、非线性静力/Newmark、 Riks/continuation 有界路径、Mohr-Coulomb、紧凑接触 benchmark、屈曲/循环对称 有界子集、finite-strain S4 有界路径、cohesive 单点/compact benchmark 和 颗粒-FEM 耦合 benchmark 均已有回归证据。
0.5.3 不再优先横向增加新功能名,而是把非线性、接触、restart、cutback、 线性求解失败和诊断输出做成更稳定的一套纵向闭环。核心目标是:
- 失败时能明确说明失败原因。
- 接触状态和残差能分解、记录、复现。
- restart/cutback 后 trial/commit/rollback 语义更可信。
- 接触 benchmark 从“能跑”推进到“能解释”。
2. 范围边界
2.1 0.5.3 应交付
- 统一 cutback / nonlinear failure reason 编码。
- 统一 nonlinear residual breakdown 的基础字段和输出。
- 接触状态机字段标准化。
- 接触 gap/slip/multiplier residual 诊断增强。
- contact restart-after-increment audit。
- mortar/friction tangent audit 增强。
- OpenMP 接触路径一致性增强。
- 线性求解器在非线性场景下的失败状态和矩阵分类诊断增强。
- 文档、测试、benchmark checker 同步更新。
2.2 0.5.3 不交付
以下内容保留为后续版本,不作为 0.5.3 阻塞项:
- 完整工业级 AL/mortar 一致切线重写。
- 完整 shell preload-to-buckling
K_G。 - C3D10/C3D20 initial-stress
K_G。 - 通用 mixed-control Riks/arc-length 框架。
- finite-strain J2、完整 layer-wise shell plasticity。
- cohesive contact 主流程。
- cyclic 自动配对和非零 harmonic wave。
- DEM/FEM subcycling、大规模 DEM 长跑。
- 完整 roll forming 生产工艺流。
3. 开发原则
- 优先做小闭环,不做跨多个主流程的大改造。
- 诊断字段必须有测试或 checker 消费,避免只写日志不验收。
- 新状态字段必须考虑 restart、cutback、trial/commit/rollback。
- 不把 compact benchmark 宣称成完整工业能力。
- 不为了 0.5.3 改写已有 V5.12 DEFERRED 决策。
4. 任务清单
4.1 NL-1:统一 cutback / failure reason taxonomy
目标:把非线性失败原因从零散状态码推进为可解释的分类。
建议新增或整理的原因类别:
- 线性求解失败。
- Newton 残差不降。
- correction norm 过大。
- line search 失败。
- trust-region reject。
- 接触 active set 震荡。
- 接触投影失败。
- 接触穿透过大。
- 摩擦 stick/slip 反复切换。
- 材料 return mapping 失败。
- Riks/arc constraint 失败。
- MPC/约束残差过大。
- step 最小步长耗尽。
验收:
solver_implicit覆盖至少 3 类 failure reason。implicit_inp覆盖 INP 路径下 reason 字段保持稳定。- CSV 或 summary 输出包含 reason id/name。
4.2 NL-2:nonlinear residual breakdown
目标:把单一 residual 扩展为可解释分量。
0.5.3 建议先覆盖:
- total residual norm。
- internal/external force residual。
- contact gap residual。
- contact slip residual。
- MPC/constraint residual。
- arc-length residual。
- material local failure count。
验收:
- 非线性静力和 Newmark-Newton 至少输出 total、constraint、contact 三类字段。
- spherical-cap / contact benchmark checker 能读取并验证字段存在。
- 字段缺失时 checker 应失败。
4.3 CT-1:接触状态机字段标准化
目标:为接触点或接触贡献建立稳定状态名称。
建议状态:
open
closed-stick
closed-slip
closed-restick
separating
failed-projection
0.5.3 不要求完整状态机重写,但应做到:
- 当前接触历史能映射到上述状态或其稳定子集。
- CSV/report 输出每类状态计数。
- restart 后状态计数一致。
验收:
restart覆盖 active/open、stick/slip、released/separating 的读写一致性。- contact benchmark summary 输出状态计数。
4.4 CT-2:gap / slip / multiplier residual 诊断增强
目标:让接触不收敛时能看出是法向、切向还是乘子问题。
建议字段:
- max penetration。
- mean gap。
- gap L2 norm。
- slip increment norm。
- slip residual。
- normal multiplier residual。
- tangential/friction residual。
- active set flip count。
- failed projection count。
- AL augmentation count。
验收:
contact_mortar_report或相关测试覆盖新增字段。example_contact_two_blocks_compression_benchmark和example_contact_block_sliding_benchmark的 checker 至少消费部分字段。
4.5 CT-3:mortar/friction tangent audit 增强
目标:继续使用有限差分审计,而不是直接大规模重写一致切线。
建议增强:
- normal-only tangent audit。
- friction stick tangent audit。
- friction slip tangent audit。
- rigid translation residual。
- row/column balance。
- energy probe。
- relative FD error summary。
验收:
contact_mortar_tangent覆盖 normal/stick/slip 三类审计。- 输出可区分 tangent error、rigid residual、energy residual。
4.6 CT-4:OpenMP 接触路径一致性增强
目标:继续确保并行路径不改变接触统计和力学结果。
建议覆盖:
- force path。
- tangent path。
- candidate cache path。
- 多 step active set path。
- 1/2/4 线程统计一致性。
验收:
perf_contact_pair_omp_consistency从 1/4 线程扩展到 1/2/4 或保留 1/4 但增加状态计数字段。- checker 比较非计时统计、接触力、active set、gap/slip 诊断。
4.7 LS-1:线性求解器非线性场景诊断
目标:线性求解器服务非线性,而不是增加 solver 名字。
建议增强:
- 矩阵分类:SPD、symmetric indefinite、unsymmetric、constraint-like、 contact-augmented、Riks-augmented。
- solver selected reason。
- fallback reason。
- preconditioner breakdown reason。
- final relative residual 和 nonlinear reason 关联。
验收:
linear_solver_cg覆盖失败状态和分类字段。solver_implicit能把线性失败映射到 nonlinear failure reason。
4.8 DOC-1:文档与 benchmark 矩阵同步
需要同步更新:
docs/v5_development_plan.mddocs/v5_benchmark_matrix.mddocs/v5_acceptance_report.mddocs/04_mathematical_model_and_algorithms.mddocs/05_interface_control_document.mddocs/06_test_and_verification_plan.mddocs/07_user_manual.mddocs/08_developer_manual.md- 相关 examples README 和 checker 输出说明。
5. 建议执行顺序
- NL-1:先统一 reason taxonomy,建立最小公共字段。
- LS-1:把线性失败映射到 nonlinear failure reason。
- CT-1:接触状态计数字段标准化。
- CT-2:gap/slip/multiplier residual 诊断增强。
- CT-3:mortar/friction tangent audit 增强。
- CT-4:OpenMP 接触路径一致性增强。
- NL-2:补 residual breakdown 到主输出和 checker。
- DOC-1:最后统一文档、矩阵和验收报告。
6. 0.5.3 验收建议
最小验收命令建议:
cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^(solver_implicit|implicit_inp|linear_solver_cg|restart|contact_mortar_report|contact_mortar_tangent|contact_multiplier_report|perf_contact_pair_omp_consistency)$" --output-on-failure
ctest --test-dir build-codex-gcc -R "^(example_contact_two_blocks_compression_benchmark|example_contact_block_sliding_benchmark|example_shell_shell_contact_benchmark|example_shell_solid_contact_benchmark)$" --output-on-failure
ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure
通过标准:
- 0.5.2 的 V5 acceptance 子集不回退。
- 新增 nonlinear/contact 诊断字段由测试或 checker 校验。
- 接触 restart 和 OpenMP 路径统计一致。
- 失败案例能输出明确 reason,而不是只给通用 solver error。
- 文档明确说明 0.5.3 仍不宣称完整工业级 AL/mortar 一致切线。
7. 风险与控制
| 风险 | 控制 |
|---|---|
| 诊断字段膨胀但无人消费 | 每个新增字段必须有测试或 checker |
| 接触状态机改动过大导致主流程不稳 | 0.5.3 只做状态映射和诊断,不重写完整接触求解器 |
| 与 Riks/cohesive/DEM 混线 | 这些能力只消费公共诊断接口,不作为 0.5.3 主开发目标 |
| benchmark 指标频繁变动 | 新增字段优先检查存在性、单调性、非负性和一致性,避免过早锁死复杂数值 |
| 文档口径再次扩大 | 明确保留 DEFERRED 边界,不把完整工业能力写成 PASS |
8. 推荐结论
0.5.3 应优先完成:
非线性失败原因可解释 + 接触状态/残差可诊断 + restart/OpenMP 路径可复现
这会直接提高后续 0.5.4+ 的壳预载屈曲、Riks 泛化、cohesive 主流程、 材料一致切线和 DEM/FEM 长路径开发成功率。