Files
FemLite/docs/v5_development_plan.md
T

88 KiB
Raw Blame History

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 定位为:

工业级接触约束 + 内部稀疏求解强化 + 岩土塑性 + 高保真工程基准版

第五版应满足以下原则:

  • 分阶段开发,但阶段结果不得以 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、dense pivoting fallback 和 none/Jacobi/Gauss-Seidel/ILU0 预条件器。
  • CSV、VTK、restart、C ABI、Python 调试接口和示例 smoke 矩阵。
  • Windows GCC 16 下第四版阶段验收测试 66/66 通过。

第四版明确未完成且进入第五版的内容:

  • 当前接触仍不是完整 mortar/augmented Lagrangian 约束求解器;法向乘子仍以接触对级增强罚为主。
  • 第三方/外部稀疏求解器明确不进入本模块;相关 method/backend 接口、外部进程工具和 C ABI 符号均不保留,旧编号只能作为非法配置被拒绝。
  • Mohr-Coulomb、张拉截断、非关联流动和强度折减仍未作为核心材料流程实现。
  • 滚压成形、球黏附/脱粘、波纹壳屈曲、循环对称和颗粒装填案例仍是可执行缩减基准。
  • 线性屈曲、循环对称、颗粒流-膜双向耦合仍缺少核心求解器支持。

3.1 基于当前代码的落地检查

第五版开发前必须先承认当前代码结构的真实落点。以下模块不是抽象规划,而是第五版会直接修改或需要先拆分的代码位置:

能力 当前代码位置 当前状态 第五版落地要求
线性求解器 src/solver/fem_linear_solver_cg.f90、src/solver/fem_linear_solver_dense.f90、src/base/fem_control.f90 已形成 solver dispatch、CG、BiCGSTAB、GMRES、dense pivoting fallback、none/Jacobi/Gauss-Seidel/ILU0 预条件、CSR 矩阵分类和残差诊断;外部求解器 method/backend 接口不保留 V5.2 solver 子项已完成;0.5.2 新增 two arches 文献路线见 7.1
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 内部求解器验收必须覆盖这些调用点,不只覆盖孤立矩阵测试
接触状态 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/two_arches、examples/roll_forming、examples/ball_adhesion_decohesion、examples/buckling_corrugated_shell、examples/Dynamic_Grain_Packing_of_a_Flexible_Container two_arches 当前仅完成 PDF 几何、接触激活和动态 micro-step 稳定性检查;其余目录为 V4.8 可执行缩减基准或 smoke examples/two_arches 在 0.5.2 必须升级为文献路线测试案例;V5.6-V5.8 必须新增或替换其他真实高保真输入、检查脚本和参考指标;原 smoke 可保留为快速回归

因此,第五版的第一批代码工作不应直接写大型算法,而应先完成求解器、接触、材料和耦合四条主线的接口拆分和数据结构扩展。否则后续能力会被迫写成新的局部近似,无法达到第五版“不再 mini 化”的要求。

4. 版本与分支策略

建议分支:

  • main:保持已发布稳定版本。
  • dev/v0.5:第五版主开发分支。
  • feature/v5-sparse-solver-hardening:无第三方依赖的内部稀疏求解器强化。
  • 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:内部稀疏求解器强化、no-external-solver 策略完成,并实现 examples/two_arches 对应参考文献的静力 continuation / global equation 路线。
  • 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 内部稀疏求解强化与 two arches 文献路线 dispatch/iterative solver 拆分、CSR 诊断、失败诊断、no-external-solver 策略;双拱壳接触参考文献的静力 continuation/global equation 路线 CG/BiCGSTAB/GMRES 与内部 dense pivoting fallback 可覆盖静力、隐式和非线性修正路径,外部求解器接口不再导出且旧编号被拒绝;examples/two_arches 不再依赖显式动力 micro-step 作为文献路线验收
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 第五版阶段验收版

5.1 开发期进度标记

本计划文档是第五版开发状态的唯一标记入口。状态含义:

标记 含义
PASS 已有实现、测试、文档和验收级 benchmark 证据。
PARTIAL 已有核心实现或测试,但缺少一项或多项第五版验收条件。
DEFERRED 当前不宣称完成;现有 smoke、adapter 或 placeholder 只作为回归覆盖。
NOT STARTED 当前尚未开始形成有效实现或验收材料。

截至 2026-06-26 的开发期状态:

阶段 当前标记 可计入当前进度的证据 达到 PASS 前必须补齐
V5.1 架构冻结与验收矩阵 PARTIAL 本计划、README 和 V1-V4 回归基线已建立。 最终验收矩阵、干净发布分支和 docs/v5_acceptance_report.md。
V5.2 内部稀疏求解强化与 two arches 文献路线 PARTIAL solver dispatch 记录 method、preconditioner、iteration、status、CSR matrix class、initial/final/relative residual;CG/BiCGSTAB/GMRES、内部 dense pivoting fallback、线性静力、隐式 Newmark、非线性接触修正、非线性修正 CG-to-GMRES fallback 和 C ABI 诊断回归通过;外部求解器接口、工具和构建目标已移除;examples/two_arches 已完成 PDF 几何、30/75 壳网格、接触激活和动态 blow-up 防护 checker。 0.5.2 必须补齐文献路线:静力 continuation/global equation、上拱边载荷控制、disp_upper=max_disp*para 约束、load-displacement 路径输出和参考指标 checker;当前 micro-step 不能作为文献结果验收。
V5.3 mortar / AL 接触 PARTIAL 已有接触乘子、mortar AL 点/批量/约束/切线/迭代/报告模块和聚焦测试;非匹配实体压力、大滑移摩擦、shell-shell 和 shell-solid benchmark 已接入 CTest;0.5.1 新增 contact multiplier restart audit 和 mortar tangent matrix audit,并扩展 restart active/released/open 场景。 完整工业级 AL 一致切线、更多非线性长路径和更大规模 OpenMP benchmark 仍需收束。
V5.4 Mohr-Coulomb 与强度折减 PARTIAL 已有 Mohr-Coulomb、包络、材料 driver、强度折减 driver/report 模块和测试;材料点验收覆盖三轴压缩、三轴伸展、纯剪、张拉截断、mixed return、分支号、塑性增量、强度折减残余下限,以及 shear/tension/mixed 活动集算法一致切线有限差分审计;examples/strengthReduction 已按 models.geomech.strength_reduction_method.pdf 升级为 0.75 m 网格 C3D8 坡体 benchmark,覆盖 4 个坡角和 2 个材料工况,输出 path、case summary、plastic zone 和 displacement probe;0.5.2 新增 --nonlinear-chain 真实结构级 trial 路线和 --nl-write-cloud 目标 FOS 云图路线,调用 fem_solve_static_nonlinear 输出真实收敛/失败诊断,并可生成 strength_reduction_cloud_summary.csv 与 result_00001525.vtk;实体 DLOAD, GRAV 已接入生产外载装配;非线性静力 step 已按增量时间缩放全局 load_factor,并新增 static_ramp_load 控制支持固定外载伪时间求解;strengthReduction 上下土体界面已修正为共享节点的 conforming mesh;NC-1 默认 TWO_STAGE_LOAD_STRENGTH 已接入 nonlinear chain 和 target cloud:阶段 A 在 F=1.0 收敛完整重力/外载,阶段 B 固定外载 continuation 强度折减因子;0.75 m cloud 路线还具备内部 BiCGSTAB/ILU0 预条件器、静力割线位移预测器、自适应 continuation 跳步和 accepted segment 后 VTK 刷新,旧路线实测可从 accepted_time=0.003 跳到 0.053 并推进到 0.0905;NC-5 已将 METHOD=MC_SUBSTEPPING_SEMISMOOTH 接入生产 Mohr-Coulomb 材料分发,支持 INP 可配置局部子步,在 statev(27:32) 写入聚合诊断,并已把 MC point/substep/branch/max-yield/max-plastic 汇总到 strengthReduction nonlinear chain/cloud/progress 输出,由 checker 校验。 NC-1 已有路径但仍需降低 0.75 m 全模型长跑成本;NC-5 仍需 longrun 效果证明;最终 FOS=1.525、accepted_time=1.0、PDF 位移/eqps 云图数值复现和 Mohr-Coulomb 结构级长路径审计仍需收束。
V5.5 屈曲与循环对称 PARTIAL 已有几何刚度、特征求解、模态输出、屈曲支持、循环对称模块/测试、Euler 柱解析屈曲 benchmark 和波纹壳紧凑循环屈曲 benchmark;相关 checker 已验证临界载荷、模态残差、K_G 归一化、循环边界残差和循环/全模型一致性。 通用 *BUCKLING step、静力预载后壳/实体几何刚度装配、完整壳 FE 波纹壳高保真模型和循环扇区约束接入主求解流程。
V5.6 高保真滚压成形 PARTIAL 已有刚体圆柱/辊、运动调度、滚压指标、roller kinematics benchmark 和紧凑多层 J2 springback benchmark;示例输出 slip、traction、friction energy、pressure、torque、plastic work、plastic zone、residual displacement 和 springback ratio。 主求解器通用滚压成形 step、完整三维工件网格滚压、restart 驱动多 step 工艺流和更大规模长跑。
V5.7 cohesive 粘附/脱粘 PARTIAL 已有 cohesive law/state/metrics 模块;test_cohesive_contact 覆盖单积分点 bonded loading、mixed-mode damage、unloading、reload、complete decohesion、非负耗散、损伤不可逆和 restart 状态保持;examples/ball_adhesion_decohesion 已新增 compact cohesive ring benchmark,输出力-位移、耗散能和脱粘面积。 主求解器通用 cohesive contact 切换、切线、restart 段和完整球-膜 FE 长跑。
V5.8 颗粒耦合 PASS 已有颗粒状态、搜索、接触、配置、step、facet/FEM coupling 模块和测试;particle_acceptance 覆盖自由落体、墙碰撞、颗粒堆和颗粒-facet 耦合,并通过 pstep_diag_values 查询质量、动量、动能、步耗散能和最大重叠;examples/Dynamic_Grain_Packing_of_a_Flexible_Container 新增真实粒子-柔性容器双向 benchmark。 已完成;当前 Release 全量 CTest 106/106 通过。
V5.9 Benchmark 与性能 PARTIAL 已新增 docs/v5_benchmark_matrix.md,将 V5.2-V5.8 已完成能力映射到 CTest、示例目录、参考指标和容差;已为相关测试追加 v5_acceptance 标签;WSL GNU 13.3 和 Windows IntelLLVM 2026.0/MSVC 19.44 多平台默认回归、v5_acceptance 子集和 OpenMP contact/performance smoke 已通过。 更大规模 longrun、完整性能矩阵和最终验收报告仍需收束。
V5.10 验收与发布 PARTIAL 已新增 docs/v5_acceptance_report.md,记录当前 V5 开发态范围、测试环境、命令、结果、已完成内容、仍需完善内容和暂缓边界;todo.md 已全部标记为 [x];本地 release hygiene 已完成并提交 a01a4fd Complete V5 acceptance milestone;20.1 发布确认已完成,发布确认测试节点 9f577c0 已推送至 main,annotated tag v0.5.0-v5-acceptance-checkpoint 已推送并指向该节点,clean clone Windows GCC 16 Release 全量 CTest 106/106、v5_acceptance 35/35 通过;20.2 多平台复测已完成并记录 WSL、Intel/MSVC 和 OpenMP 结果。 更大规模 longrun 仍建议在最终发布前执行。

V5 benchmark 示例当前标记:

示例目录 当前标记 说明
examples/contact_two_blocks_compression PASS 非匹配 4 个 lower master facets 对 1 个 upper slave facet 的 mortar 压缩 benchmark;检查脚本生成 pressure_profile.csv 并验证压力、gap、weighted gap、multiplier residual、augmented multiplier 和 VTK 输出。
examples/contact_block_sliding PASS 非匹配 4 个 lower master facets 对 1 个 upper slave facet 的大滑移 mortar-friction benchmark;检查脚本生成 sliding_profile.csv 并验证多 master、多 active、stick/slip、累计滑移、摩擦功、切向力和 VTK 输出。
examples/shell_shell_contact PASS S4-to-S4 shell-shell contact benchmark;检查脚本生成 shell_shell_contact_profile.csv 并验证 active contact、force、gap、augmented multiplier、master search 和 VTK 输出。
examples/shell_solid_contact PASS S4 shell slave 对 C3D8 solid master top face 的 shell-solid contact benchmark;检查脚本生成 shell_solid_contact_profile.csv 并验证 active contact、force、gap、augmented multiplier、master search 和 VTK 输出。
examples/shell_solid_connection DEFERRED 当前是共享节点 smoke;尚不是高保真壳-实体接触 benchmark。
examples/two_arches PARTIAL / 0.5.2 TARGET 对应 models.sme.two_arches.pdf 的双拱壳-壳接触测试案例。当前输入仅验证参考几何、壳网格、接触面绑定、1.2 mm 上拱中点位移和显式 micro-step 稳定性;0.5.2 必须将其升级为静力 continuation/global equation 文献路线,输出 load-displacement 路径并由 checker 对比参考指标。
examples/mohr_coulomb_yield_surface PASS Mohr-Coulomb 本构屈服面验证算例;调用生产 fem_material_mc_envelope 和 material_mc_yield_values 生成原始材料与 F=2 折减材料的压缩包络、伸展包络、张拉截断和代表性应力点分类,checker 复核解析公式、强度折减、elastic/shear/tension/mixed 分支覆盖和 summary。
examples/strengthReduction PARTIAL / FOS PASS / NL CLOUD ROUTE 对应 models.geomech.strength_reduction_method.pdf 的 Mohr-Coulomb 强度折减 benchmark;输入记录 L1=85 m、L2=20 m、H1=20 m、H2=10 m、默认 alpha=45 deg、0.75 m 网格和 CONFORMING_INTERFACE=YES,checker 生成并验证 strength_reduction_path.csv、strength_reduction_cases.csv、summary、安全系数 bracket、plastic zone、displacement probe 和上下土体界面共享节点。0.5.2 已新增显式 --nonlinear-chain,对当前输入执行真实 FE 非线性 trial 并输出 strength_reduction_nonlinear_chain.csv/summary;新增 --nl-write-cloud --nl-cloud-factor 1.525 --nl-cloud-step 1525 目标云图路线,输出 strength_reduction_cloud_summary.csv 和含 displacement/eqps 字段的 result_00001525.vtk,checker 会在该 summary 存在时验证云图文件结构和网格计数。cloud 路线可用 --nl-preconditioner ilu0 --nl-no-line-search --nl-tol 1.0e-3 运行 0.75 m 全模型,已验证 partial VTK 中含 13776 nodes、6645 elements、displacement 和 eqps 字段;12 m 粗网格 probe 在 --nl-increments 100 --nl-max-newton 80 下形成过真实 bracket(下界 1.728、上界 2.0736)。当前仍需用 0.75 m 全模型长跑证明 material case 2、alpha=45 deg、FOS=1.525 的约 0.3 m PDF 位移云图完整数值复现;此前线性静力 VTK 位移约 196 m,不得作为参考结果。
examples/euler_column_buckling PASS Euler pinned-pinned column 线性屈曲解析 benchmark;checker 验证一阶临界载荷相对误差、特征残差、phi^T K_G phi 归一化、端部位移约束和模态 CSV 输出。
examples/buckling_corrugated_shell PARTIAL 已从静力 preload smoke 升级为紧凑循环线性屈曲 benchmark;checker 验证 selected wave、critical load、循环/全模型相对误差、循环边界残差、modal CSV 和 profile 输出。它仍不是完整壳 FE 预载屈曲高保真模型。
examples/roll_forming PARTIAL 已新增 roller kinematics benchmark 和紧凑 J2 springback benchmark,验证平移、下压、角速度、正则化牵引、摩擦能、压力、扭矩、塑性功、塑性区、残余位移和回弹比例;原 friction smoke 保留。它已不再只是弹性接触 surrogate,但仍不是完整三维工件滚压长跑模型。
examples/ball_adhesion_decohesion PARTIAL 已新增 compact cohesive ring benchmark,调用生产 cohesive law/state/metrics 并检查峰值拉脱力、滞回、耗散能、损伤和脱粘面积;原接触压入 smoke 保留。它仍不是完整球-膜 FE cohesive 接触长跑。
examples/Dynamic_Grain_Packing_of_a_Flexible_Container PASS 保留旧压力/地面接触 smoke,并新增 V5.8 真实粒子-柔性容器双向 benchmark;checker 验证无 *DLOAD 压力 surrogate、粒子数、粒子-facet 接触、映射节点力、容器位移、质量守恒、有界重叠和非负能量。

5.2 当前已完成内容登记

截至 2026-06-26,本地 main 已形成 V5 acceptance checkpoint:

项 登记内容
本地提交 a01a4fd Complete V5 acceptance milestone
发布确认提交 9f577c0 Fix clean release verification inputs
发布确认标签 v0.5.0-v5-acceptance-checkpoint,annotated tag,指向 9f577c0
正式 0.5.0 标签 v0.5.0,annotated tag,指向 78dc4a6 Complete V5 documentation governance
TODO 状态 todo.md 中原 V5.2 至 V5.10 事项均已用 [x] 标记完成;0.5.2 新增 examples/two_arches 文献路线需在后续 todo 中补项
默认回归 本地原工作树和 clean clone 均记录为 ctest --test-dir build-win-gcc-16 -C Release --output-on-failure 106/106 passed
V5 验收子集 本地原工作树和 clean clone 均记录为 ctest --test-dir build-win-gcc-16 -C Release -L v5_acceptance --output-on-failure 35/35 passed
WSL 多平台复测 Ubuntu 24.04 / GNU Fortran 13.3.0 / GNU C 13.3.0 / CMake 3.28.3,build-wsl-gfortran-v5-20-2 默认 CTest 106/106 passed,v5_acceptance 35/35 passed
Windows Intel 多平台复测 VS DevCmd 17.14.33 / MSVC 19.44.35227.0 / IntelLLVM ifx 2026.0.0,build-win-ifx-v5-20-2 默认 CTest 106/106 passed,v5_acceptance 35/35 passed
OpenMP smoke contact_omp1、contact_omp4 和 perf_contact_pair_omp_consistency 通过;perf_contact_pair.exe 64 1 在 1/4 线程下非计时统计一致
发布卫生 根目录生成结果文件已清理;v0.5.0 正式标签已推送;main 后续开发版本提升至 0.5.1
验收文档 新增 docs/v5_acceptance_report.md 和 docs/v5_benchmark_matrix.md
solver 边界 第三方/外部求解器接口、工具和测试已移除;内部 CG/BiCGSTAB/GMRES 与 dense pivoting fallback 为当前生产 solver 路径
示例边界 benchmark 编排工具位于 tools/benchmarks,示例输入和 checker 位于对应 examples/<case>/ 目录,不进入 src

当前可明确计入完成范围的能力:

  • V5.2 内部 solver 诊断和 no-external-solver 策略已完成;0.5.2 新增的 examples/two_arches 文献路线仍待实现,不计入当前完成范围。
  • V5.3 非匹配实体接触、大滑移摩擦、shell-shell 和 shell-solid benchmark。
  • V5.4 Mohr-Coulomb 材料点验收和 PDF 强度折减 benchmark。
  • V5.5 Euler 柱解析屈曲、波纹壳紧凑循环屈曲和循环对称验证。
  • V5.6 辊运动学、正则化牵引和紧凑 J2 springback benchmark。
  • V5.7 cohesive 单积分点和 ball adhesion/decohesion compact benchmark。
  • V5.8 内置离散球颗粒、颗粒-facet/FEM 映射和动态颗粒柔性容器 benchmark。
  • V5.9 benchmark 矩阵、v5_acceptance CTest 标签和文档矩阵。
  • V5.10 当前验收报告、根目录结果清理、本地提交、release hygiene checkpoint 和 20.2 多平台复测。

6. V5.1 架构冻结与验收矩阵

目标:

  • 将第四版验收报告中的后续限制转化为第五版可执行开发项。
  • 在写代码前冻结核心接口边界,避免后续阶段反复推翻数据结构。
  • 为第五版定义“完整实现”的最低标准,禁止用缩减 smoke 替代验收。

建议实现内容:

  1. 建立 V5 deferred 项登记表:
    • 完整 mortar / AL 接触。
    • 无第三方依赖的内部稀疏求解器强化。
    • Mohr-Coulomb 和强度折减。
    • 线性屈曲和循环对称。
    • 高保真滚压、球黏附、颗粒耦合。
  2. 冻结新增接口:
    • 内部线性求解器 method 枚举、统计和失败诊断。
    • 接触乘子/历史变量/restart 格式。
    • 材料状态变量布局。
    • 特征值求解器和模态输出接口。
    • 颗粒耦合外力和接触映射接口。
  3. 明确 fallback 策略:
    • V4 penalty/mortar 权重路径保留为 debug fallback。
    • 内部 CG/BiCGSTAB/GMRES 与 dense pivoting fallback 是本模块唯一可接受的生产线性求解路径。
    • 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 内部稀疏求解器强化与 two arches 文献路线

目标:

  • 在不引入第三方库、不引入外部求解器进程的前提下强化内部稀疏线性求解能力。
  • 让静力、隐式 Newmark、非线性 Newton 修正方程和接触切线都通过同一内部 dispatch 路径获得一致诊断。
  • 删除外部求解器 method/backend 接口;旧外部 method 数值必须作为非法配置被拒绝,不得静默回退。

推荐技术路线:

当前代码适配要求:

  • 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_dense:承载内部 dense pivoting fallback,用于小中型非线性修正或回归矩阵,不作为外部 sparse-direct 后端。
  • 不保留线性求解外部 adapter、外部进程交互或第三方后端注册表;这些路径若重新需要,应在当前模块之外重新立项。
  • 旧外部 method 数值和已删除的 backend 概念必须在配置边界被拒绝,并确认失败时不修改解向量、不触发 fallback solve。
  • fem_solver_implicit 中所有 linear_solver_solve 调用都必须保持无需知道具体后端。
  1. 内部求解器选择:
    • CG 用于对称正定系统,默认配合 none/Jacobi 预条件器。
    • BiCGSTAB 用于非对称系统,必须记录 breakdown、未收敛和残差状态。
    • GMRES 用于非对称或病态小中型回归系统,必须记录 Arnoldi/最小二乘失败状态。
    • DENSE 用于内部小中型 fallback 和诊断,不作为第三方 sparse-direct 后端。
    • 旧外部 method 数值只返回配置错误,不进入求解分发。
  2. CSR 诊断:
    • 支持对称、非对称、正定、不定矩阵能力声明。
    • 明确实数双精度为首要支持类型。
    • 在求解器统计中保存矩阵分类、初始残差、最终残差、迭代数和状态码。
  3. 构建策略:
    • 不新增任何第三方 solver 依赖选项。
    • 默认 CMake 构建即为完整支持路径。
    • 若未来其他产品线需要外部求解能力,应在独立模块/版本中重新立项,不作为本模块验收条件。
  4. 运行时接口:
    • 支持设置 method 和 preconditioner。
    • 支持查询实际 method、preconditioner、迭代统计、残差和状态。
    • 非 CG/BiCGSTAB/GMRES/DENSE 的 method 值必须返回配置错误,禁止静默回退。
  5. 验证:
    • SPD、非对称、病态、接触切线和约束系统矩阵测试。
    • 线性静力、隐式 Newmark、非线性 Newton 修正和接触/约束路径均通过内部 solver dispatch。

7.1 examples/two_arches 参考文献路线(0.5.2)

0.5.2 需要把 examples/two_arches 从“参考几何 + 接触激活 micro-step”升级为 models.sme.two_arches.pdf 对应的文献路线测试案例。该案例是 V5.2 新增的 静力/约束求解验收压力测试,不得再用显式动力短步数结果替代文献结果。

文献路线必须记录并实现以下内容:

  1. 几何和网格:
    • 上拱半径 Ri_upper=80 mm,下拱半径 Ri_lower=100 mm。
    • 壳宽/厚度 d=3 mm。
    • 上拱弧段 80 deg,下拱弧段 100 deg。
    • 上拱 30 个 mapped shell elements,下拱 75 个 mapped shell elements。
  2. 材料和约束:
    • 下拱 E=40 GPa, nu=0.2, rho=1。
    • 上拱 E=20 GPa, nu=0.3, rho=1。
    • 所有边沿 y 向约束用于模拟二维平面应变并抑制面外变形。
    • 下拱两端固定;上拱两端保留参考文献中的 in-plane 约束和竖向边载荷。
  3. 接触:
    • frictionless shell-shell contact。
    • upper arch 作为 source/slave,lower arch 作为 destination/master。
    • 接触面侧向、法向、active set 和 gap 输出必须由 checker 验证,不能只检查 contact CSV 存在。
  4. 加载/求解路线:
    • 采用静力 continuation 路线,而不是显式动力 micro-step。
    • 实现或提供等价的 global equation:disp_upper - max_disp*para = 0。
    • disp_upper 为上拱中点竖向位移量;max_disp=60 mm。
    • para 按参考路线从 0 增至 1,首轮实现可采用 range(0,0.02,1) 或等价离散 continuation steps。
    • 上拱端部竖向边载荷由全局方程/continuation 参数求得,不能直接把中点位移 当成最终文献路线。
  5. 输出和验收:
    • 输出 two_arches_path.csv,至少包含 para、disp_upper、边载荷因子、 active contact 数、最大 gap/penetration、残差和迭代状态。
    • checker 必须验证几何坐标、30/75 网格、disp_upper=max_disp*para 约束残差、 接触 active set、非负/有界接触功和 load-displacement 曲线路径。
    • 当前 two_arches_benchmark.inp 的 micro-step 只能作为几何/接触绑定回归; 它不得进入 0.5.2 文献路线 PASS 证据。

验收条件:

  • 默认构建不依赖任何第三方稀疏求解器库或外部求解器进程。
  • CG、BiCGSTAB、GMRES 和内部 dense pivoting fallback 覆盖静力、隐式和非线性/contact 修正工作流。
  • 旧外部 method/backend 接口不再导出;旧 method 数值被拒绝,且不修改解向量、不触发 fallback solve。
  • 文档说明 no-external-solver 策略、支持的内部 solver、预条件器和诊断字段。
  • examples/two_arches 作为 0.5.2 对应测试案例,必须通过文献路线 checker; micro-step 结果只能作为前置回归,不得作为文献对比结果。

风险控制:

  • 不通过引入外部求解器掩盖内部求解器缺陷;内部 solver 不收敛时必须暴露真实状态。
  • 对大规模或强非对称系统,优先用矩阵诊断、预条件器改进和问题缩放降低风险。
  • 若未来产品线需要第三方 solver,应另建边界清晰的独立模块,不能改变当前核心默认依赖策略。

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 算法切线。
    • 几何项和接触法向变化项的工程级处理。
    • 非对称切线必须由内部 BiCGSTAB/GMRES 路径或可接受的内部约束处理路径求解。
  5. 并行和 restart:
    • 乘子历史 deterministic merge。
    • OpenMP 装配一致性。
    • restart 保存完整接触历史、乘子和 active set。
  6. 输出:
    • 接触压力、切向牵引、gap、滑移、摩擦功、AL 乘子、active 状态。
    • 输出体量可控,支持积分点抽样和 summary。

验收条件:

  • 两块体非匹配网格压缩接触压力分布与参考解误差可控。
  • 大滑移摩擦接触在隐式非线性求解中稳定收敛。
  • 壳-实体、壳-壳、实体-实体至少各一个 benchmark 通过。
  • OpenMP 1 线程和多线程结果在容差内一致。
  • restart 后接触历史和乘子连续。

当前完成证据:

  • examples/contact_two_blocks_compression 已从匹配两块体 smoke 升级为非匹配 4:1 面-面压缩 benchmark。
  • check_contact_results.py 输出 pressure_profile.csv,并检查 active contact、master facet 覆盖、压力范围、weighted gap、multiplier residual、augmented multiplier 和 VTK 输出。
  • CTest example_contact_two_blocks_compression_benchmark 已接入默认测试图,并在 Windows GCC 16 Release 构建中通过。
  • examples/contact_block_sliding 已从匹配小滑移 smoke 升级为非匹配 4:1 大滑移 mortar-friction benchmark。
  • sliding checker 输出 sliding_profile.csv,并检查多 master、多 active、stick/slip 计数、累计滑移、摩擦功、切向力和 VTK 输出。
  • CTest example_contact_block_sliding_benchmark 已接入默认测试图,并在 Windows GCC 16 Release 构建中通过。
  • examples/shell_shell_contact 和 examples/shell_solid_contact 已新增为独立 benchmark 目录,均包含 README、输入、双击脚本和 checker。
  • CTest example_shell_shell_contact_benchmark 与 example_shell_solid_contact_benchmark 已接入默认测试图,并在 Windows GCC 16 Release 构建中通过。
  • 0.5.1 新增 contact_multiplier_audit,可审计接触乘子 slot 数、active/released/open 状态、重复 key、非法状态、最大 lambda、最大 gap 和 commit/trial 差异; restart 测试已扩展为 active、released、open 三状态 restart 场景。
  • 0.5.1 新增 mortar_tan_audit_matrix 和 mortar_tangent_audit,可审计局部 mortar tangent 的 row/column balance、刚体平移残差、非对称量和能量 probe; contact_mortar_tangent 同时覆盖 stick symmetric 和 slip nonsymmetric 模式。
  • 0.5.1 contact_mult_report_summary 已接入 multiplier audit 字段,摘要输出 duplicate、invalid 和 max commit error,便于 restart 状态治理。
  • 0.5.1 定向命令 ctest --test-dir build-win-gcc-16 -C Release -R "^(contact_mortar_tangent|restart|contact_multiplier_diag|contact_multiplier_report|contact_omp1|contact_omp4|perf_contact_pair_omp_consistency)$" --output-on-failure 已通过,记录为 7/7 passed。

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 次数和收敛状态。

当前完成证据:

  • tests/unit/test_material_mohr_coulomb.f90 覆盖弹性步、剪切返回、张拉截断、mixed return、旋转剪切、三轴压缩、三轴伸展、纯剪、强度折减残余下限和 *MOHR COULOMB 输入解析。
  • tests/unit/test_material_mc_driver.f90 覆盖 Mohr-Coulomb 单步/路径 driver、三轴路径、张拉路径、branch count、limited 状态、plastic total 和 tangent 诊断。
  • tests/unit/test_material_mc_envelope.f90 覆盖 Mohr-Coulomb 包络强度、margin、safety ratio、折减材料和非法输入。
  • 数学算法、详细设计、接口、测试计划、用户手册和开发者手册已记录 Mohr-Coulomb 屈服函数、张拉截断、状态变量、输入格式、driver 诊断和活动集算法一致切线。
  • 0.5.2 将 material_mc_tangent 从 Drucker-Prager 型工程投影切线升级为 shear/tension/mixed 活动集算法一致切线;材料点测试新增有限差分审计,验证 D_alg * Delta epsilon 对实际返回映射应力增量的预测误差。
  • ctest --test-dir build-win-gcc-16 -C Release -R "material_mohr_coulomb|material_mc_driver|material_mc_envelope" --output-on-failure 作为 V5.4 材料点定向验收命令。
  • examples/strengthReduction 已按 models.geomech.strength_reduction_method.pdf 重建:几何为 L1=85 m、L2=20 m、H1=20 m、H2=10 m,默认 alpha=45 deg 输入采用 0.75 m 网格、C3D8 实体、原生 *DLOAD, GRAV 重力体力和 *MOHR COULOMB;参考 CSV 覆盖 alpha=15/25/35/45 deg 与非关联 Davis B、关联流动两种材料工况。
  • tools/benchmarks/strength_reduction_benchmark.f90 调用核心 Mohr-Coulomb 与 strength-reduction driver 模块生成 strength_reduction_path.csv、strength_reduction_cases.csv、summary、塑性区和位移探针;CTest example_strength_reduction_benchmark 已改为专用 benchmark checker,不再生成误导性的线性静力 result_00000001.vtk。当前 FOS 验收为 8 个 PDF 工况全部收敛、最大 FOS 误差 6.9392E-03、86 个 trial、52 个 stable trial、34 个 unstable trial。
  • 0.5.2 新增 --nonlinear-chain 真实非线性强度折减诊断路线:每个 trial 会重置结构状态、设置材料折减、调用 fem_solve_static_nonlinear,并输出 strength_reduction_nonlinear_chain.csv 与 strength_reduction_nonlinear_summary.csv。非线性静力现在按增量时间缩放外载 load_factor,并可通过 static_ramp_load=.false. 在伪时间中固定外载;benchmark 记录 continuation_method、last_dt、accepted_time、correction_norm、线性迭代数、线性残差和线性状态。NC-1 默认方法已把 nonlinear chain 接到两阶段 load-strength continuation:先在强度因子 F=1.0 收敛完整重力/外载,再保留结构状态、固定外载并把强度折减因子 continuation 到 trial 目标。
  • 0.5.2 新增 --nl-write-cloud 目标云图路线:默认按 PDF 关联流动 alpha=45 deg 的 FOS=1.525 写出 strength_reduction_cloud_summary.csv 与 result_00001525.vtk;VTK 文件使用生产 output_vtk_write,包含 nodal displacement 和 cell eqps 字段。0.75 m 路线已补内部 ILU0 预条件器、静力 predictor、自适应 continuation 跳步、每个 accepted segment 后 VTK 刷新,并接入 NC-1 两阶段默认路线;examples/strengthReduction/check_strength_reduction_results.py 在该 summary 存在时会检查云图文件、字段和网格计数。当前小参数 method-1 chain/cloud smoke 可完成并写出 method 1 诊断;中等 0.75 m method-1 cloud 探针 --nl-increments 10 --nl-max-newton 20 --nl-linear-iter 1000 --nl-tol 1.0e-3 --nl-preconditioner ilu0 超过 120 s 后停止,文献全模型的 accepted_time=1.0 参考位移/eqps 云图数值匹配仍需后续 longrun/算法补强证明。
  • ctest --test-dir build-win-gcc-16 -C Release --output-on-failure 在 V5.4 benchmark 接入后 100/100 passed。

10. V5.5 线性屈曲与循环对称

目标:

  • 实现线性屈曲特征值分析,将静力预载后的几何刚度纳入广义特征值问题。
  • 实现循环对称边界,使扇区模型可用于周期结构屈曲和模态分析。

当前代码适配要求:

  • 当前 src/solver 没有特征值求解器模块,V5.5 应新增 fem_eigensolver 或同等职责模块,并复用 V5.2 的内部稀疏矩阵、残差和诊断基础设施。
  • 当前单元刚度路径没有独立几何刚度装配入口,V5.5 需要新增 fem_element_geometric_stiffness 或在现有单元刚度接口中增加清晰分发。
  • 循环对称不能只用 MPC penalty 近似完成;必须定义扇区边界节点配对、坐标旋转、壳转角映射和约束装配方式。
  • CLI/inp 需要新增 buckling step、预载 step、特征阶数和循环波数输入路径。

建议实现内容:

  1. 线性屈曲:
    • 静力预载平衡状态保存。
    • 几何刚度 K_G 装配。
    • 广义特征值问题 K phi = -lambda K_G phi。
    • 小规模内部广义特征值求解器和受限迭代策略。
    • 屈曲模态 VTK/CSV 输出。
  2. 循环对称:
    • 扇区边界节点配对。
    • 坐标旋转映射。
    • 周向波数/节径输入。
    • 实数等效约束或复数接口预留。
    • 与壳单元转角自由度兼容。
  3. 示例升级:
    • examples/buckling_corrugated_shell 从静力 preload smoke 升级为真实屈曲特征值案例。
    • 增加完整模型与扇区循环模型对比。

验收条件:

  • Euler 梁或柱屈曲解析解误差满足阈值。
  • 平板/圆柱壳屈曲 benchmark 通过。
  • 波纹壳循环扇区模型与完整模型前若干阶临界载荷一致。
  • 模态输出可视化方向和归一化稳定。

风险控制:

  • 特征值求解不得依赖外部库;V5.5 需要先建立小规模内部广义特征值算法或明确受限的内部迭代策略。
  • 循环对称涉及转动自由度和坐标映射,必须覆盖实体和壳两类边界。

当前完成证据:

  • src/solver/fem_eigensolver.f90 提供内部对称 Jacobi 特征值求解和 SPD 广义特征值变换,不依赖第三方库或外部求解器。
  • src/solver/fem_buckling_solver.f90 提供 buckling_dense_solve、几何刚度符号处理、Euler 柱解析临界载荷和模态参与系数 helper;密集屈曲求解的 Jacobi 迭代预算已按自由度规模扩展。
  • src/element/fem_geometric_stiffness.f90 提供梁柱几何刚度矩阵,tests/module/test_buckling_support.f90 和 tests/module/test_eigensolver.f90 覆盖几何刚度、Euler 公式、广义特征值和模态归一化基础路径。
  • examples/euler_column_buckling 已新增为独立解析 benchmark 目录,包含输入、README、双击运行脚本和 checker。
  • CTest example_euler_column_buckling_benchmark 已接入默认测试图,并在 Windows GCC 16 Release 构建中通过;当前参考结果为一阶临界载荷相对误差 3.27660856E-05、残差 1.50014805E-11 和 phi^T K_G phi = 1.0。
  • examples/buckling_corrugated_shell 已从 V4.8 静力 preload smoke 的默认 CTest 入口升级为紧凑循环线性屈曲 benchmark。tools/benchmarks/corrugated_shell_buckling_benchmark.f90 调用 buckling_dense_solve、fem_cyclic_symmetry 和 modal_write_csv,输出 summary、wave sweep、modal CSV 和 mode profile。
  • CTest example_buckling_corrugated_shell_benchmark 已接入默认测试图,并在 Windows GCC 16 Release 构建中通过;当前参考结果为 selected wave 4 load 453.031407、critical wave 8 load 393.369677、循环/全模型相对误差 1.25473461E-16 和 modal residual 1.31855319E-12。
  • ctest --test-dir build-win-gcc-16 -C Release --output-on-failure 在 dynamic grain container benchmark 接入后 106/106 passed。

11. V5.6 真实高保真滚压成形

目标:

  • 将 examples/roll_forming 从弹性接触 surrogate 升级为包含刚体辊旋转、摩擦、塑性成形和回弹指标的真实滚压成形 benchmark。

当前代码适配要求:

  • 当前 analytical surface 主要支持平面,真实滚压需要圆柱刚体面或离散刚体辊,并支持随时间旋转和平移。
  • 当前接触相对速度需要接入刚体辊角速度贡献,否则摩擦牵引不能代表滚动成形。
  • 滚压流程需要多 step 和 restart/卸载语义;如果现有 inp step 语义不足,V5.6 必须先补输入控制。
  • 真实滚压依赖 V5.3 mortar/摩擦和 V5.2 内部求解器强化;不得在 V5.6 中重新写一条专用接触捷径。

建议实现内容:

  1. 刚体辊:
    • analytical 或离散刚体圆柱面。
    • prescribed rotation、translation 和下压位移。
    • 辊-板接触法向、切向速度和摩擦功输出。
  2. 工件塑性:
    • J2/J2_JC 或后续板材硬化模型。
    • 大滑移摩擦接触。
    • 残余应力和回弹位移输出。
  3. 工艺流程:
    • 下压。
    • 滚动进给。
    • 卸载回弹。
    • 分步重启动作。
  4. 验证指标:
    • 成形力-位移曲线。
    • 接触压力带宽。
    • 塑性区分布。
    • 回弹量。

验收条件:

  • 真实刚体辊旋转参与接触相对速度计算。
  • 塑性成形和卸载回弹均可运行。
  • 与参考文档参数一致的独立 example 通过检查脚本。
  • 接触能量、塑性功和外力功无明显非物理跳变。

当前完成证据:

  • fem_rigid_roller 已通过 cyl_surface_velocity 将刚体辊角速度叠加到接触点表面速度,并提供 roller_contact_kin 输出 gap、penetration、normal、roll/axial direction、relative velocity、normal speed 和 slip speed。
  • roller_regularized_traction 已新增为生产 helper,用 tanh(slip/reference_speed) 平滑因子让角速度改变正则化切向牵引幅值;保留原 roller_traction_from_mu 的经典 Coulomb 路径。
  • test_rigid_roller 已覆盖 spin/no-spin 对比,验证关闭角速度会改变切向滑移和正则化牵引。
  • examples/roll_forming 已新增 roll_forming_kinematics_benchmark.inp 和 checker,调用 tools/benchmarks/roll_forming_kinematics_benchmark.f90 输出 roller_kinematics_history.csv 与 roller_kinematics_summary.csv。
  • CTest example_roll_forming_kinematics_benchmark 已接入默认测试图,并在 Windows GCC 16 Release 构建中通过;当前参考结果为 mean slip 0.4 with spin vs 0.2 without spin、mean traction 289.208274 with spin vs 228.478247 without spin、max traction delta 60.7300272、friction energy 138.819972 with spin vs 54.8347792 without spin、roller torque 14.4604137。
  • roll_metrics_residual_disp 和 roll_metrics_springback 已加入 fem_roll_metrics,并由 test_rigid_roller 覆盖残余位移和 springback ratio。
  • examples/roll_forming 已新增 roll_forming_springback_benchmark.inp 和 checker,调用 tools/benchmarks/roll_forming_springback_benchmark.f90 输出 springback_history.csv、springback_summary.csv 和 plastic_zone.csv。
  • CTest example_roll_forming_springback_benchmark 已接入默认测试图;当前参考结果为 springback ratio 0.473154068、residual displacement 0.0316107559、plastic work 1.11591736e-05、56/81 个 active plastic points 和 residual moment 绝对值 8.92778801e-11。

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 后损伤变量连续。

当前进展:

  • src/boundary/fem_cohesive_law.f90 已实现法向/切向牵引-分离、混合模态能量、损伤起始、软化到完全脱粘、压缩接触分支和 secant stiffness。
  • src/boundary/fem_cohesive_state.f90 已提供 cohesive 积分点状态槽,保存 damage、trial damage、最大法向开口、最大有效分离、能量和状态,并支持 trial/rollback/commit 与 restart 写读。
  • src/boundary/fem_cohesive_metrics.f90 已汇总 bonded/damaging/failed/compress 数量、最大损伤、最大开口、失效面积比例、cohesive 能量和弹性能。
  • test_cohesive_contact 新增单积分点验收路径:bonded loading -> mixed-mode damage -> unloading -> reload -> complete decohesion;检查非负耗散、损伤和最大分离不可逆、失效牵引清零、metrics 失效面积,以及 restart 后 damage、最大开口、最大有效分离、能量和 failed status 保持。
  • tools/benchmarks/ball_adhesion_cohesive_benchmark.f90 已新增为 V5.7 示例编排工具;它将球-膜粘附区离散为同心环,沿 compression -> unloading -> pull-off 位移路径调用生产 cohesive law/state/metrics,输出 adhesion_history.csv、adhesion_summary.csv 和 decohesion_profile.csv。
  • examples/ball_adhesion_decohesion 已新增 ball_adhesion_cohesive_benchmark.inp、check_cohesive_results.py,并更新 run_case.bat。当前参考结果为 peak pull-off force 119.246023、min compression force -362.051100、dissipated energy 0.451891017、hysteresis area 0.898170568、decohesion area 1.25663706e-03 和 failed fraction 1.0。
  • 定向命令 ctest --test-dir build-win-gcc-16 -C Release -R "cohesive_contact|example_ball_adhesion_cohesive_benchmark|source_size" --output-on-failure 已在 2026-06-26 通过。该示例仍是 compact cohesive benchmark,不是主求解器完整球-膜 FE cohesive 接触长跑。

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。

验收条件:

  • 颗粒自由落体、颗粒堆积、颗粒-刚墙碰撞基础测试通过。
  • 柔性容器受颗粒冲击产生双向响应。
  • 颗粒总质量、动量变化和能量耗散可诊断。
  • 颗粒耦合示例有独立目录、运行脚本和检查脚本。

风险控制:

  • 第五版只承诺离散球颗粒,不承诺任意形状颗粒。
  • 第五版不接入外部颗粒求解器;颗粒时间推进在核心内置模块中实现并保持依赖边界清晰。

当前完成证据:

  • src/particle/fem_particle_state.f90、fem_particle_contact.f90 和 fem_particle_step.f90 已提供离散球颗粒状态、颗粒-颗粒/颗粒-刚墙接触、 显式推进和 step 诊断。
  • pstep_diag_values 将 particle_step_diag 中的质量、动量、动能、耗散功率和 最大重叠转换为 Fortran 可查询的验收诊断,其中步耗散能为 dissipated_power * dt。
  • fem_particle_facet_coupling.f90 和 fem_particle_facet_step.f90 已提供 颗粒-facet 接触、节点载荷分配、接触能量、耗散功率和力范数统计。
  • tools/benchmarks/dynamic_grain_container_benchmark.f90 作为 benchmark 编排工具放在 tools/benchmarks,读取 dynamic_grain_container_benchmark.inp 中的离散球颗粒和接触参数,加载无 *DLOAD 的柔性容器结构输入,通过 particle_fem_apply_all 将颗粒-facet 接触力映射到 FEM fsph,再用显式结构步推进容器响应。
  • examples/Dynamic_Grain_Packing_of_a_Flexible_Container 现在保留旧 pressure/ground smoke,同时新增真实粒子-柔性容器双向 benchmark 输入、 README、双击脚本和 check_grain_container_results.py。checker 拒绝压力 surrogate,并验证粒子数、接触数、映射节点力、容器位移、质量守恒、有界 重叠和非负能量。
  • CTest particle_acceptance 覆盖自由落体、阻尼墙碰撞、三颗粒堆积和 颗粒-facet 载荷平衡;CTest example_dynamic_grain_container_benchmark 覆盖真实粒子-容器双向映射。
  • 定向命令 ctest --test-dir build-win-gcc-16 -C Release -R "example_dynamic_grain_container_benchmark|particle_acceptance|source_size" --output-on-failure 已在 2026-06-26 通过;本次记录粒子数 4、最大 facet contact 4、 mapped_steps=40、最大映射竖向载荷 3.68E+01、中心节点最小位移 -7.29240354E-06 和最大重叠 3.00615680E-03。
  • 全量命令 ctest --test-dir build-win-gcc-16 -C Release --output-on-failure 已在 2026-06-26 通过,记录为 106/106 passed。

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 强度折减 PDF benchmark 8 工况安全系数曲线、Davis B/关联材料对比、塑性区与位移停止准则
examples/buckling_corrugated_shell 线性屈曲和循环对称 临界载荷、模态形状
examples/roll_forming 真实滚压成形 成形力、塑性区、回弹量
examples/ball_adhesion_decohesion cohesive 粘附/脱粘 滞回曲线、耗散能、脱粘面积
examples/Dynamic_Grain_Packing_of_a_Flexible_Container 颗粒-膜双向耦合 容器位移、颗粒接触统计、能量

测试层级:

  • 默认 CTest:保留小规模 smoke 和单元测试。
  • 扩展 CTest:内部 solver 矩阵和 benchmark regression;当前已完成的 V5 核心测试和示例 benchmark 统一追加 v5_acceptance 标签,可通过 ctest --test-dir build-win-gcc-16 -C Release -L v5_acceptance --output-on-failure 运行。
  • 长跑测试:大规模接触、滚压、颗粒和屈曲矩阵。
  • 发布前测试:Windows GCC、WSL gfortran、Windows Intel oneAPI ifx/MSVC,按依赖可用性分级记录。

验收条件:

  • V1-V4 回归测试全部通过。
  • V5 默认 CTest 全部通过。
  • 内部 solver 扩展矩阵测试通过。
  • 所有高保真示例均有 README、输入、运行脚本、检查脚本和文档说明。
  • 所有 V4 中标注为 surrogate 的第五版目标案例均替换或补充真实高保真输入。

当前完成证据:

  • docs/v5_benchmark_matrix.md 已列出 V5.2-V5.8 已完成能力对应的测试层级、 示例目录、CTest 名称、参考指标和容差。
  • CMake 已为当前 V5 验收子集追加 v5_acceptance 标签;扩展验收命令为 ctest --test-dir build-win-gcc-16 -C Release -L v5_acceptance --output-on-failure。 该命令已在 2026-06-26 通过,记录为 35/35 passed。
  • 默认回归仍为 ctest --test-dir build-win-gcc-16 -C Release --output-on-failure; 当前 Windows GCC 16 Release 记录为 106/106 passed。
  • 20.2 多平台复测已在 2026-06-26 完成:
    • WSL Ubuntu 24.04 / GNU Fortran 13.3.0 默认 CTest 106/106 passed, v5_acceptance 35/35 passed。
    • Windows IntelLLVM ifx 2026.0.0 / MSVC 19.44.35227.0 默认 CTest 106/106 passed,v5_acceptance 35/35 passed。
    • Windows GCC 16 OpenMP contact/performance smoke 通过,并记录 1/4 线程 非计时统计一致性。

15. V5.10 验收与发布

目标:

  • 形成 FemLite 0.5.x 第五版阶段验收版。
  • 明确第五版已经完成的工业能力和仍未完成的后续边界。

发布验收环境:

  • Windows GCC 16 默认构建。
  • WSL gfortran 默认构建。
  • Windows Intel oneAPI ifx/MSVC 默认构建。
  • 可选:启用 OpenMP 的接触和颗粒性能构建。

发布前必须执行:

cmake --build build-win-gcc-16 --config Release
ctest --test-dir build-win-gcc-16 --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。
  • docs/v5_benchmark_matrix.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 保存和读取。
  • 新增接触、材料、颗粒状态必须有可查询诊断。
  • 当前模块不得新增第三方求解器依赖或外部求解器接口。
  • 默认构建不能因为可选工具缺失而失败。

文档约束:

  • 新增算法必须同步记录在数学模型与算法文档中。
  • 新增输入关键字、C ABI 或 CLI 参数必须同步记录在接口文档中。
  • 新增示例必须同步记录在用户手册和测试文档中。
  • 新增 benchmark 的参考指标、容差和限制必须写入 README。

17. 第五版验收准则

0.5.x 阶段验收建议满足:

  • 0.1.0、0.2.0、0.3.3 和 0.4.8 已验收能力无回退。
  • 内部 CG/BiCGSTAB/GMRES 求解器和 dense pivoting fallback 覆盖静力、隐式、非线性修正和接触/约束回归;无第三方 solver 依赖。
  • 完整 mortar / augmented Lagrangian 接触通过实体、壳、摩擦和 restart benchmark。
  • Mohr-Coulomb 材料通过材料点、结构和强度折减 benchmark。
  • 线性屈曲特征值分析和循环对称边界通过解析或公开基准。
  • 滚压成形案例包含真实刚体辊运动、塑性成形和回弹检查。
  • 球黏附/脱粘案例包含 cohesive law、损伤演化和能量检查。
  • 颗粒耦合案例包含真实颗粒和柔性容器双向响应。
  • examples 下第五版目标案例均为独立文件夹,包含可执行输入和双击运行脚本。
  • 所有新增能力均有单元测试、集成测试、示例测试和文档说明。
  • 验收报告明确列出尚未完成的后续能力,不夸大第五版范围。

18. 风险与缓解

风险 影响 缓解
误把外部 solver 当作当前模块完成项 破坏无第三方依赖边界 V5.2 明确 no-external-solver 策略,删除外部接口并用旧编号拒绝回归防止反向引入
Mortar/AL 一致切线难度高 非线性接触不收敛 先做无摩擦法向约束,再接 stick/slip 和几何项
Mohr-Coulomb 角点返回不稳定 岩土算例失败 材料点测试先行,substepping 和分支诊断同步实现
内部特征值求解能力有限 屈曲阶段规模受限 先实现小规模内部广义特征值验证,再按矩阵诊断和迭代策略扩展
循环对称转角映射复杂 壳模型边界错误 从实体平移 DOF 开始,再扩展壳转角 DOF
滚压成形计算量大 默认测试过慢 默认 smoke + 扩展 benchmark + longrun 分层
Cohesive 接触状态切换复杂 粘附/普通接触不连续 单积分点和单面片测试先行,restart 同步覆盖
颗粒耦合范围膨胀 版本不可控 第五版限定离散球颗粒和显式 staggered 双向耦合

19. 初始执行顺序建议

第五版建议按以下顺序推进:

  1. 建立 dev/v0.5 分支和 V5 文档/验收矩阵。
  2. 完成内部稀疏求解器强化和 no-external-solver 策略。
  3. 完成 mortar/AL 接触法向约束。
  4. 接入 mortar 摩擦一致切线和 restart。
  5. 实现 Mohr-Coulomb 材料点与结构 benchmark。
  6. 实现线性屈曲和循环对称。
  7. 升级滚压、球黏附和颗粒耦合真实案例。
  8. 补齐所有示例、文档、测试和验收报告。

排序理由:

  • 内部 solver 诊断和稳定性是后续非对称系统、特征值和高保真 benchmark 的基础。
  • Mortar/AL 是滚压、cohesive、颗粒-膜接触和壳-实体 benchmark 的基础。
  • Mohr-Coulomb 相对独立,可在 mortar 主线稳定后并行推进。
  • 应用级高保真案例必须建立在核心算法真实可用之后。

20. 下一步建议

当前本地 checkpoint、20.1 发布确认和 20.2 多平台复测已完成;后续建议转入 工程化补强和更大规模 longrun。

20.1 发布确认

状态:DONE(2026-06-26,Windows GCC 16 clean clone)。

执行记录:

项 结果
发布确认测试节点 9f577c0 Fix clean release verification inputs 已推送至 origin/main
发布标签 v0.5.0-v5-acceptance-checkpoint,annotated tag,已推送至远端并指向 9f577c0
clean clone git clone --depth 1 --branch v0.5.0-v5-acceptance-checkpoint --single-branch ... 成功,checkout 9f577c0
clean build Windows GCC 16.1.0,MinGW Makefiles,Release 构建成功
默认回归 106/106 passed,0 failed
V5 验收子集 35/35 passed,0 failed
发布修复 tools/testing/*.py 已纳入 Git;tools/README.md 移除外部 solver 旧说明;CMake 配置阶段创建测试 scratch 输出目录

clean clone 实际使用的配置命令:

cmake -S . -B build-win-gcc-16 -G "MinGW Makefiles" `
  -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_MAKE_PROGRAM=C:\gcc-16.1.0-64\bin\make.exe `
  -DCMAKE_C_COMPILER=C:\gcc-16.1.0-64\bin\gcc.exe `
  -DCMAKE_Fortran_COMPILER=C:\gcc-16.1.0-64\bin\gfortran.exe
cmake --build build-win-gcc-16 --config Release
ctest --test-dir build-win-gcc-16 -C Release --output-on-failure
ctest --test-dir build-win-gcc-16 -C Release -L v5_acceptance --output-on-failure

20.2 多平台复测

状态:DONE(2026-06-26)。

执行记录:

平台 构建目录 工具链 命令 结果
WSL Ubuntu 24.04 build-wsl-gfortran-v5-20-2 GNU Fortran 13.3.0、GNU C 13.3.0、CMake 3.28.3 ctest --test-dir build-wsl-gfortran-v5-20-2 -C Release --output-on-failure 106/106 passed,55.53 s
WSL Ubuntu 24.04 build-wsl-gfortran-v5-20-2 同上 ctest --test-dir build-wsl-gfortran-v5-20-2 -C Release -L v5_acceptance --output-on-failure 35/35 passed,7.33 s
Windows Intel/MSVC build-win-ifx-v5-20-2 VS DevCmd 17.14.33、MSVC 19.44.35227.0、IntelLLVM ifx 2026.0.0 ctest --test-dir build-win-ifx-v5-20-2 -C Release --output-on-failure 106/106 passed,33.46 s
Windows Intel/MSVC build-win-ifx-v5-20-2 同上 ctest --test-dir build-win-ifx-v5-20-2 -C Release -L v5_acceptance --output-on-failure 35/35 passed,2.60 s
Windows GCC 16 OpenMP build-win-gcc-16 GNU Fortran 16.1.0,OpenMP enabled `ctest --test-dir build-win-gcc-16 -C Release -R "contact_omp1 contact_omp4

OpenMP contact/performance smoke 记录:

项 线程 耗时/计时输出 非计时统计
contact_omp1 1 CTest 0.35 s test_contact.exe PASS
contact_omp4 4 CTest 0.04 s test_contact.exe PASS
perf_contact_pair_omp_consistency checker 内部对比 CTest 0.72 s PASS,active_count=32、search_facets=64、search_masters=32、search_broad=128、search_active=32、bvh_nodes=15、cache_used=32
perf_contact_pair.exe 64 1 1 search_cpu=0.00000E+00、force_cpu=0.00000E+00、tangent_cpu=1.56250E-02、wall_force_cpu=0.000000 active_count=64、search_facets=128、search_masters=64、search_broad=256、search_active=64、bvh_nodes=31、cache_used=64
perf_contact_pair.exe 64 1 4 search_cpu=1.56250E-02、force_cpu=3.12500E-02、tangent_cpu=1.56250E-02、wall_force_cpu=0.031250 与 1 线程样本完全一致

修复和差异说明:

  • WSL 下 7 个 benchmark 初次失败的根因是工具侧 join_path 使用 Windows 反斜杠,Linux 文件系统将其解释为文件名字符;benchmark 工具已统一输出 POSIX 可接受的 / 分隔路径,WSL 和 Windows 均可通过。
  • Windows Intel 初次全量 CTest 报 __acospia 入口点缺失,根因是 oneAPI setvars.bat 将 VTune/Advisor 的 libmmd.dll 排在 compiler runtime 前面; CMake 现对 Windows IntelLLVM CTest 统一 prepend ifx compiler runtime 目录。
  • Intel/MSVC 暴露出 Mohr-Coulomb 包络边界分类在精确边界附近的舍入差异; mc_envelope_classify 已增加 1.0e-10 相对 margin 容差。复测后无未解释 数值差异。

20.3 工程化补强优先级

  1. 0.5.2:优先实现 examples/two_arches 文献路线,补静力 continuation/global equation、上拱边载荷控制、disp_upper=max_disp*para 约束、路径输出和 checker;当前 dynamic micro-step 只保留为几何/接触绑定回归。

  2. V5.3:优先补齐完整 mortar/AL 一致切线、更多 restart 场景和 OpenMP benchmark,目标是把接触主线从 benchmark 完成推进到更接近工业级约束求解。

  3. V5.4:在已新增 --nonlinear-chain 真实 trial 诊断路线、--nl-write-cloud 目标 FOS 云图路线、实体 DLOAD, GRAV、静力外载增量缩放、conforming strengthReduction 网格、Mohr-Coulomb 活动集算法一致切线、ILU0 预条件器、静力 predictor、自适应跳步和 partial VTK 刷新基础上,继续完成 0.75 m 全模型 accepted_time=1.0 longrun、参考位移/eqps 云图数值复现和 结构级长路径审计,使强度折减从 FOS benchmark 走向通用结构流程。 0.5.2 后续待开发算法登记如下,后续实现必须通过 INP 配置文件选择。 NC-0 已完成生产入口 *NONLINEAR CONTINUATION, METHOD=value;若用户未 显式配置,默认使用 METHOD=1。NC-1 已有默认两阶段 load-strength continuation 初版实现,但 0.75 m 全模型长跑尚未完成;NC-2 和 NC-3 已完成生产控制器和测试覆盖;NC-4 已完成直接位移控制 accepted-path 记录/API/CSV,但完整增广弧长方程仍未完成;后续长跑收束仍归入 NC-1/SR-1;NC-5 已完成生产材料点子步接入、INP 控制、 statev(27:32) 诊断和 strengthReduction 结构级 MC 聚合输出,但 longrun 效果证明仍未完成。

    方法编号 暂定名称 目标用途 验收要求
    1 TWO_STAGE_LOAD_STRENGTH 先在 F=1.0 收敛完整重力/外载,再固定外载将强度折减因子从 1.0 continuation 到目标 FOS;作为默认算法。 examples/strengthReduction 默认 INP 不给 METHOD 时走该路线,能够推进到 FOS=1.525 或给出可复现失败诊断。
    2 ADAPTIVE_TARGET_NEWTON 用目标 Newton 迭代数控制 continuation 步长,低迭代增长,高迭代、cutback 或失败后缩小。 高载荷段 cutback 数明显少于当前路线,并在 path CSV 中记录目标步长、实际步长和调整原因。
    3 TRUST_REGION_DAMPED_NEWTON 对高载荷非线性段限制修正范数,并用残差 merit damping 防止 Newton 过冲。 相同输入下残差和位移修正范数有界,失败时输出 trust-region/damping 诊断。
    4 ARC_LENGTH_OR_DISPLACEMENT_CONTROL 处理纯载荷或强度因子 continuation 无法跨越的极限点、snapback 或局部化路径。 至少一个结构非线性路径能输出约束方程残差、弧长/位移控制参数和反力路径。
    5 MC_SUBSTEPPING_SEMISMOOTH 稳定 Mohr-Coulomb 局部积分,覆盖角点附近 substepping、活动集切换和 semismooth 分支处理。 材料点和结构级路径均记录 substep 数、活动分支和局部返回状态,并减少角点附近全局 cutback。

    第一版生产入口按互斥 METHOD= 实现;若后续证明最佳稳定路线需要组合 1+2+5 一类策略,应新增明确的辅助 flags,而不是改变方法编号含义。

    工程进度列表(截至 2026-06-27):

    工程项 当前状态 已有基础/证据 下一步工程动作 完成标记
    NC-0:INP continuation 方法选择器 DONE fem_control 已新增 NLC_* 方法枚举和 nonlinear_continuation_method 默认值;fem_inp_reader/fem_inp_helpers 已支持 *NONLINEAR CONTINUATION, METHOD=value,接受 1..5 和稳定符号名,非法值报输入错误且不修改已有方法;strength_reduction_benchmark 已在 nonlinear chain/cloud/progress 输出中记录方法编号;implicit_inp 和 example_strength_reduction_benchmark 定向测试通过。 后续只在 NC-1 至 NC-5 实现具体算法时扩展方法语义和诊断字段。 省略关键字默认 1;1..5 和符号名可解析;非法值在输入阶段失败;诊断 CSV 记录方法编号;测试覆盖通过。
    NC-1:默认两阶段 load-strength continuation PARTIAL fem_control 新增 static_ramp_load,implicit_solve_nonlinear_static 可在第二阶段固定外载;strength_reduction_benchmark 的 nonlinear chain 和 target cloud 在 METHOD=1 时先做 F=1.0 full-load 平衡,再保留结构状态并把强度折减因子从 1.0 continuation 到 trial/target;chain/cloud/progress 输出继续记录 continuation_method=1。小参数 method-1 chain/cloud smoke 已完成;中等 0.75 m cloud 探针超过 120 s 后停止。 降低阶段 A/B 的 Newton、cutback 和线性求解成本;把 NC-2/NC-3/NC-5 的稳定化策略接到 method 1 或显式组合 flags;形成可重复 longrun 命令。 examples/strengthReduction 默认 INP 使用方法 1;能输出明确失败诊断;尚未完成 FOS=1.525、accepted_time=1.0 和 PDF 云图数值复现。
    NC-2:目标 Newton 数自适应步长 DONE fem_control 已新增 nlc_target_newton、nlc_growth_factor、nlc_shrink_factor 和 target/actual/next increment、Newton 数、adjust reason 诊断;fem_inp_helpers 已解析 METHOD=ADAPTIVE_TARGET_NEWTON、TARGET_NEWTON、GROWTH/GROWTH_FACTOR、SHRINK/SHRINK_FACTOR,非法控制在修改状态前失败;implicit_solve_nonlinear_static 已按目标 Newton 数进行生产步长增长/保持/缩小和 cutback 后缩步;strengthReduction nonlinear chain/cloud/progress CSV 与 checker 已记录并验证自适应诊断;solver_implicit、implicit_inp 和 example_strength_reduction_benchmark 于 2026-06-27 通过。 将 NC-2 作为 NC-1/SR-1 长跑稳定化工具继续组合使用;不再把 benchmark 侧旧跳步规则作为生产控制器。 path/progress CSV 记录目标步长、实际步长、Newton 数、cutback 数和步长调整原因;生产隐式静力路径完成自动测试覆盖。
    NC-3:trust-region / damping Newton DONE fem_control 已新增 trust radius/min/max、trust growth/shrink、merit accept/good ratio 和 last/next radius、damping、merit ratio、rejection count、trust adjust 诊断;fem_inp_helpers 已解析并验证 TRUST_RADIUS、TRUST_MIN_RADIUS、TRUST_MAX_RADIUS、TRUST_GROWTH、TRUST_SHRINK、TRUST_ACCEPT_RATIO、TRUST_GOOD_RATIO;implicit_solve_nonlinear_static 的 Newton 修正在 line search 前被 trust radius 裁剪,残差增加的 damped correction 会返回可复现 solver failure 并进入既有 cutback/rollback;半径按 merit 下降、damping 和 line-search rejection 更新;strengthReduction nonlinear chain/cloud/progress CSV 与 checker 已记录并验证 trust 诊断;solver_implicit、implicit_inp 和 example_strength_reduction_benchmark 于 2026-06-27 通过。 将 NC-3 与 NC-1/SR-1 长跑组合验证;若后续证明需要 1+2+3+5 组合路线,新增显式辅助 flag,不改变 METHOD=3 的互斥语义。 同一输入下修正范数被 radius 限制;失败摘要包含 trust radius、damping 因子、merit ratio 和 rejection count;生产隐式静力路径完成自动测试覆盖。
    NC-4:弧长或位移控制 continuation PARTIAL fem_control 已新增动态 accepted-increment path 表;METHOD=ARC_LENGTH_OR_DISPLACEMENT_CONTROL 在非线性静力 accepted increment 后记录直接 prescribed-displacement 路径,字段包括控制参数、控制 DOF 数、目标/实际位移范数、约束残差、反力、广义反力功、Newton 迭代和收敛状态;fem_api 已提供 path count/row 查询,fem_output_csv 可写 continuation_path.csv;solver_implicit 与 implicit_inp 已覆盖生产路径,定向 CTest 于 2026-06-27 通过;0.5.1 新增生产 fem_shell_corotational,SHELL_GEOMETRIC/GEOMETRIC_SHELL/COROTATIONAL_SHELL/S4_COROTATIONAL INP 布尔控制、S4 corotational 内力路径、刚体对象性、小转角一致性、弹性 algorithmic tangent 有限差分列回归、非对称切线接受、prestress-delta membrane geometric stiffness 回归,并在非 ELASTIC 壳材料请求 corotational tangent 时显式返回材料错误;fem_dload_tangent 已把 shell DLOAD P follower-pressure tangent 接入非线性静力/Newmark Newton 矩阵,并由 test_shell_pressure 做有限差分回归;spherical-cap checker 已校验显式开关,并在可选 nonlinear route 中要求 post-peak load drop 和 restiffening,防止单调小应变曲线被误判为后屈曲通过。examples/spherical_cap_with_central_point_load 已新增 PDF Shell-4 nonlinear diagnostic deck,可由 checker 在 FEMLITE_SPHERICAL_CAP_NONLINEAR=1 时尝试,但当前核心壳后屈曲路径仍因缺少通用 Riks/arc-length 增广方程、塑性/多层壳 algorithmic tangent、完整弯曲/剪切 prestress 项和全部 load-family follower tangent 而以 Newton 非收敛结束,默认 CTest 保持 Shell-16 小应变基线。 继续实现通用 load/displacement/arc-length 增广方程、扩展未知量、约束切线和路径切换;补齐塑性/多层壳 algorithmic tangent、弯曲/剪切初应力项、其他 follower-load tangent、Shell-4/8/16 spherical cap -6.2 m 路径收敛和非单调载荷-位移验收。 至少一个结构路径输出约束残差、控制参数、反力和非单调路径;不能退化为单步线性位移样本;完整弧长/Riks 能通过参考案例。
    NC-5:MC substepping / semismooth 活动集 PARTIAL Mohr-Coulomb shear/tension/mixed 活动集算法一致切线有限差分审计已完成;fem_control 和 fem_inp_helpers 已支持 MC_MIN_SUBSTEPS、MC_MAX_SUBSTEPS、MC_TARGET_STRAIN、MC_YIELD_TOL 和 MC_PLASTIC_LIMIT;METHOD=MC_SUBSTEPPING_SEMISMOOTH 已在生产材料分发中调用 fem_material_mc_driver,并把 accepted/requested substeps、driver status、branch mask、max yield residual 和 max plastic increment 写入 statev(27:32);strengthReduction nonlinear chain/cloud/progress 已汇总 mc_points、mc_updated_points、accepted/requested substeps、limited points、branch mask、max yield residual 和 max plastic step,checker 会拒绝缺失或非法 MC 诊断;test_material_mohr_coulomb、test_implicit_inp 和 example_strength_reduction_benchmark 定向 CTest 通过,额外 nonlinear chain/cloud smoke 已由 checker 验证 optional MC 诊断。 补 0.75 m PDF cloud longrun 对比,证明局部子步能减少角点附近 cutback 或局部返回失败。 材料点与结构级输出均包含 substep 数、活动分支、局部返回状态;角点附近全局 cutback 减少。
    SR-1:0.75 m PDF 云图复现验收 PARTIAL 当前 0.75 m cloud route 已生成 partial VTK,含 13776 nodes、6645 elements、displacement 和 eqps;位移从 9.7294e-4 m 增至 2.9383e-2 m,但未到 PDF 目标约 0.3 m。 以 NC-1 为默认路线,逐步接入 NC-2/NC-3/NC-5,完成 material case 2、alpha=45 deg、FOS=1.525 长路径。 accepted_time=1.0 或固定外载强度因子 F=1.525 完整达成;checker 验证位移云图量级、eqps/plastic zone 和非线性诊断。
  4. V5.5:把屈曲从 benchmark 工具推进到主 femlite 的通用 *BUCKLING step,接入静力预载后的壳/实体几何刚度装配和模态输出。

  5. V5.6:将滚压 kinematics/springback benchmark 的核心路径整合为通用滚压工艺 step,补三维工件网格、restart 多 step 和长跑稳定性。

  6. V5.7:把 cohesive law/state/metrics 接入主接触流程,补普通接触/cohesive 状态切换、切线和 restart 长路径。

  7. V5.8:扩展颗粒邻域搜索性能、大颗粒数 longrun 和能量稳定性检查,但继续保持 不依赖外部颗粒求解器。

0.5.1 已推进内容:

  • V5.3 已新增接触乘子 restart audit 和 mortar tangent matrix audit。
  • restart 已覆盖 contact multiplier active/released/open 三状态写读保持。
  • contact_mortar_tangent 已覆盖 stick 对称切线和 slip 非对称切线的平衡、刚体平移 残差和能量 probe 审计。
  • contact_multiplier_report 已输出 duplicate/invalid/max commit error 审计摘要。

20.4 文档与验收治理

状态:DONE(2026-06-26,治理规则已同步到计划、benchmark 矩阵和验收报告)。

治理目标:

  • 防止 V5 状态在多个文档中重复标记、互相冲突。
  • 防止 smoke、surrogate、debug fallback 被误写成完成的工业能力。
  • 防止 benchmark 工具、示例输入、checker 和生产实现边界混淆。
  • 防止第三方 solver、外部 solver 进程或外部 solver C ABI 常量重新进入核心模块。

单一事实源:

文档 责任 更新触发 验收要求
docs/v5_development_plan.md 唯一状态标记入口,维护 PASS/PARTIAL/DEFERRED/NOT STARTED 和下一步建议 任一 V5 项状态变化、完成发布确认、多平台复测、longrun 或 tag 决策 状态表、完成证据和下一步建议必须一致
docs/v5_benchmark_matrix.md 可执行验收矩阵,维护测试层级、CTest 名称、示例目录、参考指标和容差 新增/修改 benchmark、checker、CTest 标签、平台复测或 longrun 每条 V5 完成项必须可由命令、checker 和指标复现
docs/v5_acceptance_report.md 阶段验收结论,维护测试环境、命令、结果、完成项、限制和用户影响 发布确认、多平台复测、清理 deferred/surrogate 或最终发布准备 不得保留已完成事项作为未完成风险;不得删除仍存在的 PARTIAL 边界
核心设计文档 记录生产算法、接口和用户可见行为 src 新增生产算法、输入关键字、C ABI、输出字段或状态变量 算法文档、接口文档、测试计划、用户手册和开发者手册口径一致

更新顺序:

  1. 代码或示例变更完成后,先运行对应单元、模块或示例 checker。
  2. 若结果改变状态,先更新本文件的阶段状态表和对应 V5 小节。
  3. 再同步 docs/v5_benchmark_matrix.md 的测试入口、指标和容差。
  4. 再同步 docs/v5_acceptance_report.md 的测试环境、执行命令、结果和限制。
  5. 最后执行 git diff --check,并确认没有把生成结果文件或构建目录带入提交。

边界规则:

  • benchmark 输入、checker、双击脚本和 benchmark 编排工具只放在 examples/<case>/ 或 tools/benchmarks;生产功能代码仍进入 src。
  • 方便测试的通用工具可以放在与 src 同级的 tools,但不得作为生产模块依赖。
  • 若一个示例只验证可运行路径,必须标为 smoke;只有带参考指标、checker 和容差的 示例才能进入 V5 benchmark 矩阵。
  • 若一个实现仍依赖缩减模型、紧凑模型或 fallback 路径,必须在状态表保留 PARTIAL/DEFERRED 说明,不得为了发布口径改写为 PASS。
  • 当前核心模块不引入第三方库,不引入第三方 solver,不保留外部 solver backend、 外部 solver 进程或外部 solver C ABI 编号。

当前同步结果:

项 结果
docs/v5_development_plan.md 已登记 20.1 发布确认、20.2 多平台复测和 20.4 治理规则;V5.9/V5.10 仍保留 PARTIAL 以反映 longrun 和部分工程化边界
docs/v5_benchmark_matrix.md 已新增多平台复测矩阵和文档治理边界;Windows GCC、WSL GNU、Windows Intel/MSVC 和 OpenMP smoke 结果已登记
docs/v5_acceptance_report.md 已移除“多平台复测/release hygiene 未完成”的旧口径,保留 longrun、最终 tag 决策和剩余 PARTIAL 能力边界
后续建议 v0.5.0 正式标签已包含 20.2 多平台复测和 20.4 文档治理;下一步在 0.5.1 上优先补更大规模 longrun 和 V5.3-V5.7 的工程化主流程集成