Files
FemLite/docs/v5.3_development_plan.md
T
shenw 2b7962eb96
FemLite CI / build-test (push) Has been cancelled
Release FemLite 0.5.3
2026-07-01 18:39:18 +08:00

8.9 KiB
Raw Blame History

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.md
  • docs/v5_benchmark_matrix.md
  • docs/v5_acceptance_report.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
  • 相关 examples README 和 checker 输出说明。

5. 建议执行顺序

  1. NL-1:先统一 reason taxonomy,建立最小公共字段。
  2. LS-1:把线性失败映射到 nonlinear failure reason。
  3. CT-1:接触状态计数字段标准化。
  4. CT-2:gap/slip/multiplier residual 诊断增强。
  5. CT-3:mortar/friction tangent audit 增强。
  6. CT-4:OpenMP 接触路径一致性增强。
  7. NL-2:补 residual breakdown 到主输出和 checker。
  8. 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 长路径开发成功率。