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

280 lines
8.9 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.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 长路径开发成功率。