# FemLite 0.5.3 Development Plan 日期:2026-07-01 适用对象:FemLite 0.5.3 开发、评审、测试与阶段验收。 ## 1. 版本定位 FemLite 0.5.3 定位为: ```text 接触与非线性诊断加固版 ``` 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:接触状态机字段标准化 目标:为接触点或接触贡献建立稳定状态名称。 建议状态: ```text 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 验收建议 最小验收命令建议: ```powershell 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 应优先完成: ```text 非线性失败原因可解释 + 接触状态/残差可诊断 + restart/OpenMP 路径可复现 ``` 这会直接提高后续 0.5.4+ 的壳预载屈曲、Riks 泛化、cohesive 主流程、 材料一致切线和 DEM/FEM 长路径开发成功率。