Complete V5 acceptance milestone
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# FemLite 0.4.8 开发者手册
|
||||
# FemLite 0.5.x 开发者手册
|
||||
|
||||
日期:2026-06-24
|
||||
日期:2026-06-26
|
||||
|
||||
## 1. 目的
|
||||
|
||||
本文档面向 FemLite 开发者,说明代码结构、构建测试、模块职责、接口扩展、编码约束和发布检查流程。
|
||||
|
||||
FemLite 核心代码采用 Fortran 95 非面向对象风格,使用集中式 `fem_database` 保存模型、状态和求解数据。当前版本为 0.4.8。
|
||||
FemLite 核心代码采用 Fortran 95 非面向对象风格,使用集中式 `fem_database` 保存模型、状态和求解数据。当前版本线为 0.5.x。
|
||||
|
||||
## 2. 开发原则
|
||||
|
||||
@@ -84,9 +84,16 @@ src/interface C ABI 和 Fortran-C bridge
|
||||
| `fem_database` | 集中式全局数组、分配、初始化、校验和释放 |
|
||||
| `fem_database_surface` | surface/contact 目标和 facet 查询 helper |
|
||||
| `fem_material_j2` | J2 和 Johnson-Cook 相关材料更新 |
|
||||
| `fem_material_mohr_coulomb` | Mohr-Coulomb 返回映射、张拉截断、分支状态和工程切线 |
|
||||
| `fem_material_mc_driver` | Mohr-Coulomb 单点/路径 driver 和诊断汇总 |
|
||||
| `fem_material_mc_envelope` | Mohr-Coulomb 包络、margin 和 safety ratio helper |
|
||||
| `fem_strength_reduction*` | 强度折减参数、trial 搜索状态和报告输出 |
|
||||
| `fem_element_stiffness` | 实体/壳单元静力刚度 |
|
||||
| `fem_geometric_stiffness` | 线性屈曲几何刚度 helper,当前覆盖梁柱几何刚度 |
|
||||
| `fem_element_internal` | 单元内力 |
|
||||
| `fem_solver_implicit` | 静力、隐式 Newmark、非线性 Newton 主流程 |
|
||||
| `fem_eigensolver` | 内部 dense 对称 Jacobi 和 SPD 广义特征值求解 |
|
||||
| `fem_buckling_solver` | 线性屈曲 dense solve、几何刚度符号、Euler 解析载荷和模态 helper |
|
||||
| `fem_contact` | 接触公开入口和刚性平面接触 |
|
||||
| `fem_contact_*` | contact pair 状态、目标、几何、搜索、摩擦、力、切线和输出 |
|
||||
| `fem_output_csv` | 历史、节点、单元、反力和接触 CSV |
|
||||
@@ -216,13 +223,18 @@ fem_contact_output.f90 contact CSV 字段辅助
|
||||
- `fem_assembly_csr.f90`:DOF 获取、CSR 图案和装配。
|
||||
- `fem_linear_solver_dispatch.f90`:线性求解器统一入口、配置、统计和 method 分发。
|
||||
- `fem_linear_solver_iterative.f90`:CG、BiCGSTAB、GMRES 和 none/Jacobi 预条件。
|
||||
- `fem_linear_solver_external*.f90`:外部 backend registry、能力查询、request/direct/file-exchange adapter、CSR/MatrixMarket handoff、命令模板展开和 residual audit。
|
||||
- `fem_solver_implicit.f90`:静力、隐式 Newmark、非线性 Newton。
|
||||
|
||||
V4.6 起,隐式求解器内部不再直调 CG,而是通过 `linear_solver_solve` 分发。当前内部支持 CG、BiCGSTAB 和 GMRES;V5 外部路径支持 request 诊断、参考 direct 后端和 file-exchange 后端。新增线性求解器时应先在 `fem_linsol_ext_registry` 登记 backend id、名称、可用性、能力位和不可用原因,再在 adapter 层实现求解,并补充 registry、request、dispatch 和 C ABI 测试。file-exchange 命令模板由 `fem_linsol_ext_file_cmd` 展开,测试或适配工具放在 `tools/`,不要放入 `src/`。
|
||||
V4.6 起,隐式求解器内部不再直调 CG,而是通过 `linear_solver_solve` 分发。当前内部支持 CG、BiCGSTAB 和 GMRES;V5 当前模块要求保持稀疏求解器无第三方依赖,不导出外部求解器 method、backend、外部进程交互或 C ABI 接口。旧外部 method 数值必须在配置边界返回错误并保持当前设置不变。分发层在每次求解前调用 CSR diagnostics 记录矩阵分类,并在求解前后记录初始残差、最终残差和最终相对残差;新增线性求解能力时优先扩展 `fem_linear_solver_iterative`、CSR 诊断和预条件器。如确需第三方 solver,必须在当前模块之外重新立项。测试工具放在 `tools/`,不要放入 `src/`。
|
||||
|
||||
强度折减相关模块分层如下:`fem_strength_reduction` 保存参数折减、bracket 更新和失稳指标;`fem_strength_reduction_driver` 保存 trial 搜索状态、上下界、收敛系数和历史记录;`fem_strength_reduction_report` 只负责 CSV/summary 输出。结构求解器接入边坡强度折减时,应把结构 trial 的残差、位移范数、塑性区比例和收敛失败标志传给 driver,不要在材料更新内部直接控制全局安全系数搜索。
|
||||
|
||||
V5.5 线性屈曲相关模块分层如下:`fem_geometric_stiffness` 只生成单元级几何刚度矩阵;`fem_eigensolver` 只负责小规模 dense 特征值算法、模态归一化和残差;`fem_buckling_solver` 只组合屈曲问题入口、几何刚度符号约定和解析 helper。当前广义特征值入口要求参考几何刚度矩阵 SPD,适合解析基准和小规模工程验收;大规模稀疏屈曲求解仍需后续内部算法扩展,不能通过第三方库或外部求解器绕过当前模块边界。
|
||||
|
||||
V5.6 滚压相关模块分层如下:`fem_rigid_roller` 负责刚体辊位姿、接触点相对速度、经典 Coulomb 牵引和正则化牵引;`fem_roller_schedule` 负责平移/下压/角速度时间调度;`fem_roll_metrics` 负责压力、摩擦功率、力矩、残余位移和回弹比例等过程指标。滚压接触扩展应继续复用通用接触与摩擦路径,不应在 solver 中新增只服务于单一示例的快捷通道。`roller_regularized_traction` 使用切向相对速度和 `tanh(slip/reference_speed)` 平滑因子,使角速度在小滑移正则化区间改变牵引幅值;修改该公式时必须同步更新 `test_rigid_roller`、滚压 benchmark checker 和算法文档。
|
||||
|
||||
V5.7 cohesive 相关模块分层如下:`fem_cohesive_law` 只负责牵引-分离、混合模态能量、损伤起始/增长、完全脱粘、压缩分支和 secant stiffness;`fem_cohesive_state` 只负责积分点 damage、最大开口、最大有效分离、能量、status 和 trial/rollback/commit/restart;`fem_cohesive_metrics` 只负责数量、面积和能量汇总。修改 cohesive damage 或能量公式时必须同步更新 `test_cohesive_contact`、算法文档和接口文档。球-膜示例升级时应复用这些生产模块;checker 和 benchmark 编排留在 `examples/` 或 `tools/benchmarks`,不要放入 `src`。
|
||||
|
||||
新增求解路径时应明确:
|
||||
|
||||
- 是否需要质量矩阵。
|
||||
@@ -246,6 +258,15 @@ V4.7 壳稳定和壳塑性维护约定:
|
||||
- 当前 J2 弯曲塑性使用代表性外纤维应变近似,不是完整厚度方向积分;任何多层 section integration 扩展都必须保留 trial/rollback 的状态一致性。
|
||||
- 壳 benchmark smoke 优先放在 `example_smoke` CTest 分组,长跑或网格收敛结果不提交全量 CSV/VTK。
|
||||
|
||||
V5.4 Mohr-Coulomb 维护约定:
|
||||
|
||||
- `fem_material_mohr_coulomb` 只负责材料点应力更新、张拉截断、分支编码和工程切线,不负责全局强度折减搜索。
|
||||
- `statev(11)` 保存分支号,`statev(12:13)` 保存最终剪切/张拉屈服值,`statev(22)` 保存最近一次塑性增量,`statev(26)` 保存当前强度折减系数。
|
||||
- `fem_material_mc_driver` 负责单步和路径级诊断,包括 substeps、branch count、limited 状态、final branch、plastic total 和 tangent 对角统计。
|
||||
- `fem_material_mc_envelope` 负责包络 margin 和 safety ratio 计算,供材料点测试、结构 benchmark checker 或报告层复用。
|
||||
- 强度折减搜索继续通过 `fem_strength_reduction_driver` 接收结构 trial 指标;不要在材料更新例程中直接控制全局安全系数 bracket。
|
||||
- 当前 Mohr-Coulomb 切线是工程算法切线,不是完整棱边/角点一致切线。修改返回映射时必须同步更新材料点验收、算法文档和切线限制说明。
|
||||
|
||||
## 10. 输出扩展
|
||||
|
||||
输出文件由 `src/output` 管理:
|
||||
@@ -322,10 +343,60 @@ ctest --test-dir build-win-gcc-16 -R "^(contact|contact_omp1|contact_omp4|restar
|
||||
- 模块测试:数据库、facet、接触、输出、restart、INP。
|
||||
- 接口测试:C ABI、Python debug。
|
||||
- CLI 测试:静力、隐式 Newmark 等命令行入口。
|
||||
- 示例 smoke:shell patch、Scordelis-Lo、pressure pulse、rigid sphere impact。
|
||||
- 示例 smoke:shell patch、Scordelis-Lo、pressure pulse、rigid sphere impact;需要专用数值指标的示例可通过 `tools/testing/run_example_smoke.py --check-script` 调用示例目录内的 Python checker。
|
||||
- 性能测试:`perf_p1`、`perf_contact_pair`、`perf_contact_pair_omp_consistency`。
|
||||
- Benchmark 编排工具:`tools/benchmarks/strength_reduction_benchmark.f90` 链接
|
||||
`femlite_core`,用于 `examples/strengthReduction` 生成安全系数 history、
|
||||
summary、塑性区和位移探针;这类测试/benchmark orchestration 不应放入
|
||||
`src/`。
|
||||
- Benchmark 编排工具:`tools/benchmarks/euler_column_buckling_benchmark.f90`
|
||||
链接 `femlite_core`,用于 `examples/euler_column_buckling` 装配 Euler 柱
|
||||
梁弯曲刚度和生产几何刚度,调用 `buckling_dense_solve`,并输出屈曲
|
||||
summary 与一阶模态 CSV;这类工具同样保留在 `tools/benchmarks`。
|
||||
- Benchmark 编排工具:`tools/benchmarks/corrugated_shell_buckling_benchmark.f90`
|
||||
链接 `femlite_core`,用于 `examples/buckling_corrugated_shell` 构造紧凑
|
||||
周期波纹壳屈曲矩阵,调用 `buckling_dense_solve`、`fem_cyclic_symmetry`
|
||||
和 `modal_write_csv`,并输出 summary、wave sweep、modal CSV 和 profile。
|
||||
该工具是 V5.5 benchmark 编排,不是主 `femlite` 的通用 `*BUCKLING`
|
||||
step 实现。
|
||||
- Benchmark 编排工具:`tools/benchmarks/roll_forming_kinematics_benchmark.f90`
|
||||
链接 `femlite_core`,用于 `examples/roll_forming` 读取
|
||||
`*ROLLER KINEMATICS` benchmark 输入,驱动生产滚压位姿、运动调度、
|
||||
接触运动学、正则化牵引和 roll metrics,并输出 history 与 summary。
|
||||
该工具是 V5.6 benchmark 编排,不是主 `femlite` 的通用滚压成形 step。
|
||||
- Benchmark 编排工具:`tools/benchmarks/roll_forming_springback_benchmark.f90`
|
||||
链接 `femlite_core`,用于 `examples/roll_forming` 读取
|
||||
`*ROLL FORMING SPRINGBACK` benchmark 输入,驱动生产滚压位姿、正则化
|
||||
牵引、roll metrics 和 J2 小应变材料点更新,并输出 springback history、
|
||||
summary 与 plastic zone。该工具是 V5.6 benchmark 编排,不是主
|
||||
`femlite` 的通用滚压成形 step。
|
||||
- Benchmark 编排工具:`tools/benchmarks/ball_adhesion_cohesive_benchmark.f90`
|
||||
链接 `femlite_core`,用于 `examples/ball_adhesion_decohesion` 读取
|
||||
`*BALL ADHESION COHESIVE` benchmark 输入,将粘附区离散为同心环,驱动
|
||||
生产 cohesive law/state/metrics,并输出 force-displacement history、
|
||||
summary 与 decohesion profile。该工具是 V5.7 compact benchmark 编排,
|
||||
不是主 `femlite` 的通用 cohesive contact step。
|
||||
- Benchmark 编排工具:`tools/benchmarks/dynamic_grain_container_benchmark.f90`
|
||||
链接 `femlite_core`,用于
|
||||
`examples/Dynamic_Grain_Packing_of_a_Flexible_Container` 读取
|
||||
`*DYNAMIC GRAIN CONTAINER` benchmark 输入,加载无 `*DLOAD` 的柔性容器结构
|
||||
输入,调用生产 particle/FEM coupling、显式结构步和粒子 step,并输出
|
||||
grain container history 与 summary。该工具是 V5.8 benchmark 编排,不是主
|
||||
`femlite` 的通用颗粒工况 step。
|
||||
- V5.8 颗粒基础验收通过 `test_particle_acceptance` 覆盖,测试只调用
|
||||
`fem_particle_state`、`fem_particle_contact`、`fem_particle_step`、
|
||||
`fem_particle_facet_coupling` 和 `fem_particle_facet_step` 等生产模块。
|
||||
`pstep_diag_values` 是质量、动量、动能、步耗散能和最大重叠的 Fortran
|
||||
诊断出口;facet 侧力平衡通过 `pfacet_force_balance` 验证。
|
||||
动态颗粒容器 benchmark 的编排工具为
|
||||
`tools/benchmarks/dynamic_grain_container_benchmark.f90`,它每步调用
|
||||
`particle_fem_apply_all` 写回 `fsph`,再执行 `fem_advance_explicit` 和
|
||||
`pstep_advance`。checker 位于
|
||||
`examples/Dynamic_Grain_Packing_of_a_Flexible_Container`,用于验证无 pressure
|
||||
surrogate、映射节点力、容器位移和能量。后续 benchmark 编排和 checker 应继续
|
||||
放在 `tools/` 或 `examples/`,不要放入 `src/`。
|
||||
|
||||
0.4.8 基线 CTest 已覆盖 V4.1 至 V4.8 的接触、隐式、壳、示例和发布检查项;V4.8 后硬化继续加入 GMRES、node analytical contact smoke、P1 contact 性能 smoke,以及所有文档型 `examples/` 目录的可执行案例和双击脚本检查。当前 Windows GCC 16 记录为 66/66 passed。
|
||||
0.4.8 基线 CTest 已覆盖 V4.1 至 V4.8 的接触、隐式、壳、示例和发布检查项;V5 当前继续加入内部 solver 诊断、no-external-solver 回归、node analytical contact smoke、P1 contact 性能 smoke、所有文档型 `examples/` 目录的可执行案例和双击脚本检查、非匹配 two-block contact benchmark、非匹配 large-sliding mortar-friction benchmark、shell-shell/shell-solid contact benchmark、Mohr-Coulomb 材料点/driver/envelope 验收、strength reduction benchmark、Euler column buckling benchmark、corrugated shell cyclic buckling benchmark、roll forming kinematics benchmark、roll forming springback benchmark、cohesive 单积分点验收、ball adhesion cohesive benchmark、particle acceptance primitives 和 dynamic grain container particle benchmark。当前 Windows GCC 16 Release 记录为 CTest 106/106 passed。
|
||||
|
||||
## 14. 源码规模门禁
|
||||
|
||||
@@ -382,6 +453,7 @@ V4.8 起,`examples_layout` CTest 会检查 `examples/` 一级目录:有文
|
||||
- 临时 gmsh/cache 文件。
|
||||
|
||||
若需要保留结果,应保留小型 summary 或抽样结果,并在 README 中说明生成命令和误差指标。
|
||||
基准级示例的检查逻辑应保留在对应 `examples/<case>/` 目录中,CTest 可以通过 `tools/testing/run_example_smoke.py --check-script <repo-relative-checker>` 调用,也可以直接调用示例目录内 checker 运行专用 benchmark 工具;这类测试辅助代码不要放入 `src/`。
|
||||
|
||||
## 17. 发布检查
|
||||
|
||||
@@ -411,4 +483,4 @@ V4.8 起,`examples_layout` CTest 会检查 `examples/` 一级目录:有文
|
||||
- 摩擦正则化参数体系。
|
||||
- 大规模接触收敛控制。
|
||||
- 更多壳塑性和隐式动力长跑基准。
|
||||
- 大规模性能、并行和外部稀疏求解器接口。
|
||||
- 大规模性能、并行和内部稀疏求解器/预条件器强化。
|
||||
|
||||
Reference in New Issue
Block a user