Files
FemLite/docs/08_developer_manual.md
T
shenw 175531e24d
FemLite CI / build-test (push) Has been cancelled
Release 0.6.0
2026-07-01 20:44:15 +08:00

615 lines
38 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.x 开发者手册
日期:2026-06-26
## 1. 目的
本文档面向 FemLite 开发者,说明代码结构、构建测试、模块职责、接口扩展、编码约束和发布检查流程。
FemLite 核心代码采用 Fortran 95 非面向对象风格,使用集中式 `fem_database` 保存模型、状态和求解数据。当前版本线为 0.5.x。
## 2. 开发原则
- 保持 Fortran 95 兼容,不使用面向对象类型绑定。
- 优先遵守现有模块边界和数据流。
- 公共接口返回 `ierr`,错误信息通过 `fem_error` 查询。
- 外部编号默认使用 Abaqus 原始编号,内部计算使用数据库映射编号。
- 不支持的 Abaqus keyword 作为 warning 跳过,关键数据缺失或非法数据才 error。
- 新增功能必须配套小型测试;影响共享行为时补充回归测试。
- 如果同一算法同时存在前期遗留简化版和后期补强完整版,必须删除简化版;
只有确需诊断的旧路径可以隔离到非生产调试入口,且不得作为生产 fallback 或验收证据。
- 大型输出和临时结果不进入 git。
## 3. 构建目标
CMake 主要目标:
| 目标 | 类型 | 说明 |
|---|---|---|
| `femlite_core` | 静态库 | Fortran95 核心库 |
| `femlite_c` | 静态库 | C ABI 包装库 |
| `femlite` | 可执行程序 | 命令行入口 |
| `test_*` | 可执行程序 | 单元、模块和接口测试 |
| `perf_p1` | 可执行程序 | P1 显式动力性能测试 |
| `perf_contact_pair` | 可执行程序 | contact pair BVH/缓存性能测试 |
常用构建:
```powershell
cmake -S . -B build-win-gcc-16 -G "MinGW Makefiles" -DCMAKE_Fortran_COMPILER=C:\gcc-16.1.0-64\bin\gfortran.exe -DCMAKE_C_COMPILER=C:\gcc-16.1.0-64\bin\gcc.exe
cmake --build build-win-gcc-16
```
WSL:
```powershell
wsl bash -lc "cd /mnt/d/Codex/FemLite && cmake -S . -B build-wsl"
wsl bash -lc "cd /mnt/d/Codex/FemLite && cmake --build build-wsl"
```
OpenMP:
```powershell
cmake -S . -B build-win-gcc-16 -DFEMLITE_ENABLE_OPENMP=ON
```
OpenMP 当前用于 contact BVH 搜索的可选并行路径。
## 4. 模块结构
核心目录:
```text
src/base 精度、错误、日志、控制、公共 Fortran API
src/input Abaqus inp 子集读取和解析
src/mesh 集中式数据库、surface/contact 查询辅助
src/material 材料模型
src/element 单元拓扑、形函数、积分、质量、内力、刚度
src/solver CSR、线性求解器、装配、静力/隐式求解
src/boundary 边界条件、约束、接触
src/coupling FEM-SPH 边界耦合接口
src/output CSV、VTK、restart 输出
src/interface C ABI 和 Fortran-C bridge
```
重要模块:
| 模块 | 职责 |
|---|---|
| `fem_precision` | 全局精度、维度、版本常量 |
| `fem_error` | 错误码和错误消息 |
| `fem_control` | 时间步、求解控制、输出控制、V4.5 收敛诊断、V4.6 线性求解器状态、V4.7 壳稳定参数和 V5 nonlinear continuation 控制/诊断 |
| `fem_api` | Fortran95 公共 API facade,保留初始化、模型 I/O、求解/输出编排并 re-export API support 模块 |
| `fem_api_state` | 公共 API 初始化状态 |
| `fem_api_coupling` | SPH、contact、surface 和 boundary facet 相关公共 API |
| `fem_api_diagnostics` | 收敛、continuation path、线性求解器和壳稳定公共 API |
| `fem_api_state_access` | 节点运动学/反力/内力和单元状态公共 API |
| `fem_api_stable_dt` | 公共 API 背后的稳定时间步估算 support 模块 |
| `fem_inp_reader` | 两遍 INP 读取主流程 |
| `fem_inp_defs` | INP 模式常量 |
| `fem_inp_helpers` | INP 行解析和 keyword helper |
| `fem_inp_material_parser` | Mohr-Coulomb 等材料专用 INP 数据行解析 |
| `fem_inp_contact_parser` | contact pair/property/friction 专用 INP 解析 |
| `fem_inp_nlc` | `*NONLINEAR CONTINUATION` 方法和控制参数解析 |
| `fem_database` | 集中式全局数组分配、DOF 分配和稳定 public wrapper |
| `fem_database_lookup` | 节点/单元/集合/材料/surface/contact property 查询和 surface face helper |
| `fem_database_lifecycle` | 数据库初始化/释放、contact 历史重置和计数归零 |
| `fem_database_validation` | 完整模型校验、contact property 应用和输入一致性检查 |
| `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_shell_rotation` | V5.11 生产模块:壳节点 finite rotation trial/commit/rollback/restart |
| `fem_shell_finite_kinematics` | V5.11 生产模块:S4 finite membrane strain、director、metric、曲率增量和 MITC shear 采样 |
| `fem_shell_finite_tangent` | V5.11 生产模块:S4 finite-strain B 矩阵、B 线性化、几何/旋转切线和高斯点切线 |
| `fem_shell_finite_element` | V5.11 生产模块:S4 finite-strain 内力/刚度装配、section resultants/tangent 调度和 drilling 能量项 |
| `fem_shell_section` | 壳单层、多层和 layer plastic section resultants/tangent 唯一生产入口 |
| `fem_dload_tangent` | 壳 `DLOAD P` current-geometry follower-pressure tangent 装配 |
| `fem_geometric_stiffness` | 线性屈曲几何刚度 helper,当前覆盖梁柱几何刚度 |
| `fem_element_internal` | 单元内力 |
| `fem_implicit_constraints` | 隐式求解 Dirichlet、Robin、MPC、外载和接触切线施加 |
| `fem_solver_implicit` | 线性静力和隐式/非线性静力 dispatcher |
| `fem_solver_static_nonlinear` | 非线性静力 fixed/adaptive loop、位移控制 path、Riks/arc-length 和静力 Newton 增量 |
| `fem_solver_newmark` | 线性 Newmark 和非线性 Newmark-Newton 时间积分 |
| `fem_eigensolver` | 内部 dense 对称 Jacobi 和 SPD 广义特征值求解 |
| `fem_buckling_solver` | 线性屈曲 dense solve、几何刚度符号、Euler 解析载荷和模态 helper |
| `fem_buckling_column` | Euler 柱 `femlite --buckling` 输入、装配、求解和 CSV 输出生产入口 |
| `fem_contact` | 接触公开入口和刚性平面接触 |
| `fem_contact_*` | contact pair 状态、目标、几何、搜索、摩擦、力、切线、mortar/AL、multiplier 和输出 |
| `fem_contact_multiplier` | mortar/AL 积分点乘子、trial/commit/rollback、restart 和 audit |
| `fem_contact_mortar_tangent` | 局部 mortar tangent、stick/slip 矩阵和 0.5.1 矩阵审计 |
| `fem_output_csv` | 历史、节点、单元、反力和接触 CSV |
| `fem_output_vtk` | Legacy ASCII VTK 输出 |
| `fem_restart` | restart 读写 |
## 5. 数据流
典型命令行流程:
```text
fem_initialize
-> fem_read_inp
-> database_allocate_*
-> inp_fill_model
-> inp_apply_sections
-> database_assign_dofs
-> fem_build_model
-> solver 或 explicit advance
-> fem_write_output
-> fem_finalize
```
输入读取使用两遍策略:
1. 第一遍统计节点、单元、集合、材料、section、载荷、surface 和 contact pair 数量。
2. 分配数据库数组。
3. 第二遍填充数据库。
4. 应用 section,分配 DOF,建立状态变量和 facet 数据。
## 6. 数据库约定
`fem_database` 使用全局 allocatable 数组。开发时需注意:
- `node_id_ext(i)` 和 `elem_id_ext(e)` 保存外部 Abaqus 编号。
- `elem_conn(:,e)` 保存内部节点编号。
- `dof_id(local_dof,node)` 保存全局自由度编号。
- 实体单元只激活平动 DOF;壳单元激活 6 DOF。
- `stress/strain/statev` 按全局高斯点存储。
- 删除单元保留在内存中,通过 `elem_status` 或状态变量标记。
- surface 数据行通过 `surface_owner/surface_target/surface_face` 管理;`surface_owner=0` 表示被 `OP=NEW` 覆盖失效。
新增数据库数组时,应同步检查:
- 分配例程。
- 初始化例程。
- 校验例程。
- finalize 释放。
- restart 或输出是否需要同步。
- API 或 C ABI 是否需要暴露。
## 7. 输入解析扩展
INP 相关文件:
- `fem_inp_reader.f90`:主读取流程。
- `fem_inp_defs.f90`:mode 常量。
- `fem_inp_helpers.f90`:keyword 和 data-line helper。
- `fem_inp_nlc.f90`:`*NONLINEAR CONTINUATION` 方法、Riks/arc-length、
trust-region、MC 子步和 shell geometry 开关解析。
扩展新 keyword 的建议步骤:
1. 在 `fem_inp_defs` 增加 mode 常量。
2. 在第一遍 `count_keyword` 中统计需要的数量。
3. 在数据库中增加对应数组和分配逻辑。
4. 在第二遍 keyword/data-line helper 中解析。
5. 在 `database_validate_model` 或相关校验例程中验证。
6. 增加 `tests/data/*.inp` 和模块测试。
7. 更新接口文档和用户手册。
解析原则:
- keyword 名称在匹配前转大写。
- 参数值可支持空格、大小写和引号时,应加入测试。
- 对无法支持但常见的 inert keyword,可加入 known ignored keyword。
## 8. 接触模块扩展
接触模块已拆分:
```text
fem_contact.f90 公开入口、刚性平面 penalty 接触
fem_contact_state.f90 接触统计、active set、gap residual 和 augmented penalty 状态
fem_contact_target.f90 目标匹配、shared-node、pair 参数
fem_contact_geometry.f90 facet 几何、投影裁剪、mortar 权重
fem_contact_search.f90 空间网格、BVH、候选 master facet
fem_contact_candidate_cache.f90 跨调用 broad candidate 缓存
fem_contact_history.f90 mortar 积分点摩擦历史槽
fem_contact_multiplier.f90 mortar/AL 积分点乘子、restart 和审计
fem_contact_multiplier_report.f90 乘子 CSV/report 摘要
fem_contact_friction.f90 Coulomb/正则化 Coulomb 粘滑历史和摩擦功
fem_contact_force.f90 contact pair 力路径
fem_contact_tangent.f90 contact pair CSR 切线装配
fem_contact_output.f90 contact CSV 字段辅助
fem_contact_mortar_*.f90 mortar/AL 点更新、批处理、约束、迭代、报告和切线
```
扩展接触时优先保持这个边界:
- 搜索逻辑放在 `fem_contact_search`。
- 几何积分放在 `fem_contact_geometry`。
- 法向/切向力分配放在 `fem_contact_force`。
- 切线矩阵装配放在 `fem_contact_tangent`。
- 统计和输出字段放在 `fem_contact_state` 和 `fem_contact_output`。
- 接触搜索统计由 `fem_contact_state` 管理,力路径第一遍候选搜索负责记录;切线路径复用 broad candidate 缓存或搜索 helper 时不重复累计全局搜索统计。
- 接触性能计时由 `fem_contact_state` 管理,当前使用 Fortran `cpu_time`,用于趋势诊断和性能回归,不作为跨平台精确定时基准。
- BVH 力路径使用固定容量的 slave facet 局部 active 候选缓存;缓存溢出时必须回退旧 BVH 遍历施力路径,保证结果不依赖缓存容量。
- `fem_contact_candidate_cache` 保存跨调用 broad candidate 列表;force/tangent 缓存命中只跳过 BVH 构建,仍必须重新计算当前 gap、法向速度和 active 状态。
- 跨调用候选缓存必须在数据库 finalize、contact pair 重分配、facet 拓扑变化、pair 名称/search 参数变化、候选列表溢出或 facet 运动超过失效阈值时失效。
- BVH cached force 路径应先在线程本地准备法向、mortar 权重、接触面积和切向方向,只在 `femlite_contact_force` 临界区内提交摩擦历史、全局力向量、切向历史和 active 状态;BVH force 权重准备阶段的 broad/active 统计使用 OpenMP reduction 在线程内汇总,退出并行区后一次写入全局与 pair 级统计。继续降低锁竞争时,必须保持力向量、接触历史、active 状态和切线近似的一致更新边界。
- BVH 切线路径复用跨调用 broad candidate 缓存和固定容量的 slave facet 局部 active 候选缓存;并行路径应先在线程本地准备法向、mortar 权重和切线块,只在 CSR 合并时进入 `femlite_contact_tangent` 临界区。缓存溢出时必须回退 cached broad candidate 遍历或旧 BVH 遍历切线路径。
- 0.5.1 起,`contact_multiplier_audit` 用于检查 multiplier 槽数、active/released/open
状态、重复键、非法状态、最大 lambda、最大 gap 和 commit/trial 差异;
`contact_mult_report_summary` 输出 duplicate、invalid 和 max commit error。
- 0.5.1 起,`mortar_tan_audit_matrix` 用于检查局部 mortar tangent 的
row/column balance、刚体平移残差、非对称量和能量 probe。新增或修改
mortar tangent 公式时,应先扩展该审计和 `contact_mortar_tangent` 测试。
新增 contact pair 行为应覆盖:
- 串行路径。
- uniform grid 路径。
- BVH 路径。
- force 和 tangent 路径。
- active set、gap residual、augmented penalty 乘子和 release 清零路径。
- 搜索统计的串行、uniform grid、BVH 路径。
- search/force/tangent CPU 时间统计和 contact CSV schema。
- BVH 候选缓存命中、溢出和回退路径。
- 跨调用 broad candidate 缓存的 force/tangent 命中和失效路径。
- contact CSV 输出。
- 输入解析。
## 9. 求解器扩展
求解器核心文件:
- `fem_assembly_csr.f90`:DOF 获取、CSR 图案和装配。
- `fem_dload_tangent.f90`:shell pressure follower-load tangent。
- `fem_linear_solver_dispatch.f90`:线性求解器统一入口、配置、统计和 method 分发。
- `fem_linear_solver_iterative.f90`:CG、BiCGSTAB、GMRES 和
none/Jacobi/Gauss-Seidel/ILU0 预条件。
- `fem_linear_solver_dense.f90`:内部 dense pivoting fallback,用于小中型回归矩阵和非线性修正诊断。
- `fem_implicit_constraints.f90`:Dirichlet、Robin、MPC、follower-load
tangent 和 contact tangent 施加;主求解器只调用该模块入口。
- `fem_solver_implicit_support.f90`:隐式求解共享的收敛诊断、非线性线性方程 fallback、外载/刚度装配、CSR/mass helper 和 trust-region 更新。
- `fem_solver_static_nonlinear.f90`:非线性静力 fixed/adaptive loop、静力 predictor history、直接位移控制 path、载荷型 Riks/arc-length 增广方程和静力 Newton 增量。
- `fem_solver_newmark.f90`:线性 Newmark 和非线性 Newmark-Newton 时间积分;公开入口由 `fem_solver_implicit` 继续 re-export。
- `fem_solver_implicit.f90`:线性静力和隐式/非线性静力 dispatcher,保持既有公开入口。
V4.6 起,隐式求解器内部不再直调 CG,而是通过 `linear_solver_solve` 分发。当前内部支持 CG、BiCGSTAB、GMRES 和 dense pivoting fallback;V5 当前模块要求保持稀疏求解器无第三方依赖,不导出外部求解器 method、backend、外部进程交互或 C ABI 接口。旧外部 method 数值必须在配置边界返回错误并保持当前设置不变。分发层在每次求解前调用 CSR diagnostics 记录矩阵分类,并在求解前后记录初始残差、最终残差和最终相对残差;新增线性求解能力时优先扩展 `fem_linear_solver_iterative`、`fem_linear_solver_dense`、CSR 诊断和预条件器。非线性 Newton 修正可在配置 CG 失败后依次尝试内部 GMRES、BiCGSTAB、dense pivoting 和受限对角正则化 dense pivoting,并在返回前恢复用户配置。如确需第三方 solver,必须在当前模块之外重新立项。测试工具放在 `tools/`,不要放入 `src/`。
Nonlinear continuation 维护约定:`*NONLINEAR CONTINUATION` 的解析留在
`fem_inp_nlc`,通用 keyword/data-line helper 留在 `fem_inp_helpers`;
控制、最近一次诊断和 accepted-increment path 表留在
`fem_control`。NC-2 目标 Newton 步长控制、NC-3 trust-region damped Newton、
NC-4 载荷型 Riks/arc-length 增广方程和直接位移控制 path 记录必须在
`fem_solver_static_nonlinear` 的生产非线性静力路径内实现;Dirichlet/Robin/MPC/
follower-load/contact tangent 的施加边界留在 `fem_implicit_constraints`。
`tools/benchmarks` 只能编排案例、收集 diagnostics 和写 CSV。修改
continuation 参数、诊断字段、path CSV/API 字段或接受/拒绝规则时,必须同步更新
`implicit_inp`、`solver_implicit`、strengthReduction checker、算法文档、接口文档和
用户手册。NC-3 的 `convergence_correction_norm` 必须表示实际应用的
damped/trust-limited 修正范数;NC-4 的目标位移必须使用求解时实际施加的
`load_factor * amplitude * boundary_value`,不能用未缩放的边界输入值代替。NC-5
局部 Mohr-Coulomb 子步控制量也放在 `fem_control`,解析留在 `fem_inp_nlc`;
生产材料分发通过 `fem_material_j2` 进入 `fem_material_mc_driver`,不要在
benchmark 工具里重写材料积分。
S4 几何非线性开关同样属于生产路径。V5.11 稳定接口是
`SHELL_GEOMETRIC=FINITE_STRAIN`/`LINEAR`;旧布尔写法和旧 shell 几何名称已经从稳定
接口中移除,解析层只允许将其作为输入错误拒绝。`FINITE_STRAIN` 当前只支持 S4;
S3/S6/S8 必须在调度层清晰报 unsupported,不能隐式走线性壳。
修改该语义时必须同步 `test_shell_internal`、`test_implicit_inp`、spherical-cap
checker、算法文档、接口文档和用户手册;不要在 `examples/` 或 `tools/` 里实现替代壳
后屈曲逻辑。
强度折减相关模块分层如下:`fem_strength_reduction` 保存参数折减、bracket 更新和失稳指标;`fem_strength_reduction_driver` 保存 trial 搜索状态、上下界、收敛系数和历史记录;`fem_strength_reduction_report` 只负责 CSV/summary 输出。结构求解器接入边坡强度折减时,应把结构 trial 的残差、位移范数、塑性区比例和收敛失败标志传给 driver,不要在材料更新内部直接控制全局安全系数搜索。
V5.5 线性屈曲相关模块分层如下:`fem_geometric_stiffness` 生成单元级几何刚度矩阵,当前包含 truss-style 线几何刚度、Euler 梁柱几何刚度、轴向应力投影 helper,以及 C3D4/C3D8 实体 initial-stress `K_G` 子集;`fem_eigensolver` 只负责小规模 dense 特征值算法、模态归一化和残差;`fem_buckling_solver` 只组合屈曲问题入口、几何刚度符号约定和解析 helper;`fem_buckling_general` 负责普通 INP `*BUCKLING` 的小规模 dense 主流程,复用已装配线弹性 `K`,并支持显式 `*BUCKLING GEOMETRIC LINE` truss-style `K_G`、`*BUCKLING GEOMETRIC LINE, PRELOAD` 的预载派生线刚度子集,以及 `*STATIC` 后直接 `*BUCKLING` 时的 C3D4/C3D8 实体 initial-stress 几何刚度子集;`fem_cyclic_constraints` 将普通 INP `*CYCLIC SYMMETRY` 的 WAVE=0 显式节点对展开为 MPC 罚约束,覆盖 3-DOF 实体节点和 6-DOF 壳节点转角映射;通用 buckling 的 summary 和 modal CSV 通过普通输出目录工作流写出;`fem_buckling_column` 负责 Euler 柱专用 `*BUCKLING COLUMN` 读取、梁柱装配、主 `femlite --buckling` 求解和 CSV 输出。当前广义特征值入口要求参考几何刚度矩阵 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`。
新增求解路径时应明确:
- 是否需要质量矩阵。
- 是否需要刚度或切线矩阵。
- 是否需要 Rayleigh 阻尼。
- 是否需要 trial/rollback。
- 是否写 convergence、reaction、VTK/CSV。
- 是否与 contact、Robin、MPC 切线耦合。
非线性路径必须保护:
- 材料状态 trial/restore。
- 元素删除状态。
- Newmark 运动学量。
- 线搜索失败和步长缩减后的 rollback。
V4.7 壳稳定和壳塑性维护约定:
- drilling 稳定系数、S3 剪切折减系数和最小折减比例放在 `fem_control`,公共接口通过 `fem_api` 和 C ABI 追加,不改变旧函数签名。
- 壳刚度装配后的稳定性统计也放在 `fem_control`,测试中通过 `test_element_stiffness` 和 `test_c_api` 同时覆盖内部变量和外部接口。
- 当前 J2 弯曲塑性使用代表性外纤维应变近似,不是完整厚度方向 plastic
integration。V5.11 已有弹性多层 `*SHELL SECTION, COMPOSITE` 的
`fem_shell_section` ABD/H 矩阵、层级塑性状态和 algorithmic tangent 路径;后续任何
section/material 修改都必须保留 trial/rollback 的状态一致性,并删除被完整实现取代的
临时单层/外纤维近似路径。
- 壳 benchmark smoke 优先放在 `example_smoke` CTest 分组,长跑或网格收敛结果不提交全量 CSV/VTK。
- V5.11 S4 有限应变路径必须直接接管生产几何非线性壳请求:
默认线性 S3/S4/S6/S8 行为不变;`SHELL_GEOMETRIC=FINITE_STRAIN` 对 S4 调度到
`fem_shell_finite_element`,对 S3/S6/S8 显式返回 unsupported。旧 S4
reference/current frame 诊断路径的生产 dispatch、输入别名、模块文件和只服务该路线的
测试入口已删除,不能留下“备用”接口。
`shell_resultant(1:8,gp)` 是正式积分点状态,新增或修改时必须同步 element-state
reset/trial backup/rollback。`fem_shell_section` 是 shell section 矩阵的唯一生产入口;
不要重新引入 `shell_stiffness_props`、`shell_constitutive` 或 `shell4_resultants`
这类并行单层 helper。未支持壳材料仍必须显式报材料错误,不能静默回退旧工程切线。
`fem_shell_rotation` 的 DOF sync 必须使用增量旋转复合语义,不能恢复为“总旋转向量
重新作用到 committed director”的旧写法。载荷型 Riks/arc-length 增广方程、有限转动
committed/trial 状态、S4 finite kinematics、MITC shear 运动学投影、S4 finite
内力/切线、drilling 能量项和多层塑性 section 状态已进入生产路径;但 S3 finite shell、
S6/S8 finite shell、全部 follower-load 类型和真实非单调 spherical-cap 结构验收完成前,
不能在文档或 checker 中标为完整 Shell-4/8/16 postbuckling PASS。
V5.4 Mohr-Coulomb 维护约定:
- `fem_material_mohr_coulomb` 只负责材料点应力更新、张拉截断、分支编码和活动集算法一致切线,不负责全局强度折减搜索。
- `statev(11)` 保存分支号,`statev(12:13)` 保存最终剪切/张拉屈服值,`statev(22)` 保存最近一次塑性增量,`statev(26)` 保存当前强度折减系数。
- `statev(27:32)` 保存方法 5 的 Mohr-Coulomb 聚合诊断:accepted substeps、requested substeps、driver status、branch mask、max yield residual 和 max plastic increment。单步路径也必须写一致的单步诊断,避免方法切换后残留旧状态。
- `fem_material_mc_driver` 负责单步和路径级诊断,包括 substeps、branch count、limited 状态、final branch、plastic total 和 tangent 对角统计;当 `METHOD=MC_SUBSTEPPING_SEMISMOOTH` 时,它也是生产材料点子步入口。
- `fem_material_mc_envelope` 负责包络 margin 和 safety ratio 计算,供材料点测试、结构 benchmark checker 或报告层复用。
- 强度折减搜索继续通过 `fem_strength_reduction_driver` 接收结构 trial 指标;不要在材料更新例程中直接控制全局安全系数 bracket。
- 当前 Mohr-Coulomb 切线固定 shear、tension 或 mixed 活动分支,并对实际返回映射求算法 Jacobian。修改返回映射时必须同步更新材料点有限差分切线审计、算法文档和结构级 nonlinear-chain 诊断。
- strengthReduction 的 nonlinear chain/cloud/progress CSV 需要保留 method、target/actual/next step、adaptive adjust、trust radius、damping、merit ratio 和 rejection count;新增字段时 checker 必须拒绝旧 schema。
## 10. 输出扩展
输出文件由 `src/output` 管理:
- `fem_output_csv` 写 CSV。
- `fem_output_vtk` 写 legacy ASCII VTK。
- `fem_restart` 写 restart;V4.3 restart v2 额外保存 mortar 积分点摩擦历史槽,
0.5.x 继续保存 `CONTACT_MULTIPLIER` 乘子状态段。
新增输出字段时:
1. 更新输出模块。
2. 更新用户手册中的输出说明。
3. 增加 schema 或 smoke 测试。
4. 避免把大型输出文件提交到 git。
新增跨时间步状态时:
1. 明确该状态是否影响继续计算。
2. 若影响继续计算,同步更新 `fem_restart` 写读和 restart 回归。
3. 若暂不支持重启,必须在接口文档和当前限制中说明。
## 11. Fortran API
公共 Fortran API 在 `src/base/fem_api.f90` 中。常用类别:
- 生命周期:`fem_initialize`、`fem_finalize`。
- 输入与构建:`fem_read_inp`、`fem_build_model`。
- 显式:`fem_advance_explicit`、`fem_run_explicit`。
- 静力/隐式:`fem_solve_static_linear`、`fem_solve_static_nonlinear`、`fem_run_implicit_newmark`、`fem_run_newmark_nonlinear`。
- SPH 耦合:`fem_clear_sph_forces`、`fem_apply_sph_nodal_forces`、`fem_get_boundary_facets`、`fem_apply_sph_facet_pressure`、`fem_apply_sph_facet_tractions`。
- 查询:模型规模、当前时间、节点运动学、反力、单元状态、接触 summary、contact diagnostics、contact friction summary 和 contact history stats。
- 输出:`fem_write_output`、`fem_write_restart`、`fem_read_restart`。
新增 API 时:
- 保持 `ierr` 输出参数。
- 不在 API 内直接 `stop`。
- 参数使用明确维度,避免假定外部调用者知道内部数组布局。
- 同步 C ABI 和文档,若仅 Fortran 支持则在接口文档中说明。
## 12. C ABI 与 Python 调试接口
C ABI:
- 头文件:`include/femlite_c_api.h`。
- 实现:`src/interface/fem_c_api.c`。
- Fortran-C bridge:`src/interface/fem_fortran_bridge.f90`。
C ABI 当前暴露初始化、读取、构建、显式推进、SPH 力、facet 查询、节点运动学、contact summary、contact diagnostics、contact friction summary、contact history stats、线性求解器设置/统计和 restart 子集。
Python 调试接口:
- 文件:`Python/femlite_debug.py`。
- 通过 subprocess 调用 `femlite` 可执行程序。
- 当前用于调试模型摘要、显式运行和隐式线性兼容入口。
## 13. 测试体系
运行全量测试:
```powershell
ctest --test-dir build-win-gcc-16 --output-on-failure
```
常用定向测试:
```powershell
ctest --test-dir build-win-gcc-16 -R "^(contact|contact_omp1|contact_omp4|restart|c_api|implicit_inp|source_size)$" --output-on-failure
```
测试分层:
- 单元测试:材料、CSR、线性求解器、单元质量/内力/刚度。
- 模块测试:数据库、facet、接触、输出、restart、INP。
- 接口测试:C ABI、Python debug。
- CLI 测试:静力、隐式 Newmark 等命令行入口。
- 示例 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` 生成 PDF 8 工况
path/cases、summary、塑性区和位移探针;CLI 解析和 nonlinear-chain 选项维护在
`tools/benchmarks/strength_reduction_benchmark_cli.f90`,CSV/summary 命名与报告
格式维护在 `tools/benchmarks/strength_reduction_benchmark_report.f90`。这类
测试/benchmark orchestration 不应放入 `src/`。
- Benchmark 兼容包装:`tools/benchmarks/euler_column_buckling_benchmark.f90`
链接 `femlite_core`,用于 `examples/euler_column_buckling` 调用生产
`buckling_column_run_file`,并打印一阶临界载荷、残差和相对误差。Euler 柱
屈曲算法只维护在 `src/solver/fem_buckling_column.f90`,不得在包装工具中保留
第二套简化装配或特征值求解逻辑。
- 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 的接触、隐式、壳、示例和发布检查项;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、0.5.1 contact multiplier/tangent audit、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. 源码规模门禁
`source_size` CTest 调用:
```powershell
python tools\testing\check_source_size.py . --warn-file-lines 1500 --max-file-lines 2000 --warn-routine-lines 100 --max-routine-lines 128 --exceptions tests\source_size_exceptions.txt
```
规则:
- 普通过程/函数 review target 为 100 行。
- 超过 128 行必须登记 hard-threshold exception。
- 源文件 review target 为 1500 行。
- 超过 2000 行必须登记 hard-threshold exception。
- stale exception 会导致测试失败。
0.4.8 当前无 active hard-threshold exception;软警告不阻断发布。
## 15. 编码规范
- 默认 ASCII,除非文件已有明确中文文档语境。
- Fortran 缩进保持当前风格。
- 变量命名沿用模块现有风格。
- 注释只解释非显然算法或约定。
- 不使用面向对象 Fortran 特性。
- 不把 shell 命令、临时路径或本机绝对路径写入核心源码。
- 不提交 build、results、CSV/VTK 全量结果、restart 和临时文件。
函数和文件拆分建议:
- 新功能先放在职责明确的既有模块。
- 当模块开始跨越多个职责时,按状态、目标、几何、搜索、力、切线、输出等轴线拆分。
- 拆分后优先通过 CMake 依赖顺序、单元测试和 source_size 检查验证。
## 16. 示例维护
示例目录应包含:
- `README.md`。
- 网格/输入生成脚本。
- `.inp` 输入文件。
- 可选结果检查脚本。
- Windows 双击自动运行脚本可命名为 `run_case.bat`;脚本应把结果写入示例目录下的 `results` 子目录,并支持自动检查失败码。
新增基准测试案例应放在 `examples/` 下,并为每个案例建立独立文件夹;旧兼容目录不作为新测试入口。
V4.8 起,`examples_layout` CTest 会检查 `examples/` 一级目录:有文档的目录必须包含至少一个 `.inp`,有 `.inp` 的目录必须包含 `run_case.bat`。文档后缀包含 `.md`、`.pdf`、`.ppt`、`.pptx`、`.txt` 和 `.rst`。
示例目录不应提交:
- 每一步全场 CSV。
- 每一步 VTK。
- contact CSV 全量结果。
- 临时 gmsh/cache 文件。
若需要保留结果,应保留小型 summary 或抽样结果,并在 README 中说明生成命令和误差指标。
基准级示例的检查逻辑应保留在对应 `examples/<case>/` 目录中,CTest 可以通过 `tools/testing/run_example_smoke.py --check-script <repo-relative-checker>` 调用,也可以直接调用示例目录内 checker 运行专用 benchmark 工具;这类测试辅助代码不要放入 `src/`。
## 17. 发布检查
发布前建议步骤:
1. 确认版本号:
- `CMakeLists.txt`
- `src/base/fem_precision.f90`
2. 运行 Windows GCC build 和 CTest。
3. 运行 WSL gfortran build 和 CTest。
4. 运行 Windows Intel ifx build 和 CTest。
5. 运行 `git diff --check`。
6. 运行 `source_size` 和 `examples_layout`。
7. 检查 `git status --ignored --short`,确认 results 和 build 输出未被暂存。
8. 更新 `docs/v*_acceptance_report.md` 和相关接口/测试文档。
9. 提交 git,必要时打 tag 并推送。
0.3.3 发布基线记录见 `docs/v3_acceptance_report.md`。0.4.x 阶段开发和阶段记录见 `docs/v4_development_plan.md`。
## 18. 后续开发重点
建议后续版本重点推进:
- 完整 Abaqus surface 语义。
- 更完整的 analytical rigid surface 和 node-surface contact pair 路径。
- 完整工程级 mortar/augmented Lagrangian 约束求解器。
- 摩擦正则化参数体系。
- 大规模接触收敛控制。
- 更多壳塑性和隐式动力长跑基准。
- 大规模性能、并行和内部稀疏求解器/预条件器强化。
## 19. 0.5.3 Developer Notes
When adding or changing diagnostic fields after 0.5.3:
- Add the storage field, public query or output column together with a module
test, checker or report audit that consumes it.
- Keep old CSV columns stable unless a versioned format change is explicitly
documented.
- Keep restart readers backward compatible; optional diagnostic blocks should
be skipped safely by older scenarios where possible.
- Treat mortar/friction tangent helpers as audit tools until the production
AL/mortar consistent tangent rewrite is explicitly scheduled.
- Do not mark compact contact benchmarks as proof of complete industrial
contact coverage.
## 20. 0.6.0 Lifecycle Developer Notes
When adding a new nonlinear owner state after 0.6.0:
- Record lifecycle events through `fem_nonlinear_lifecycle` instead of creating
a second event vocabulary.
- Use existing event names and add new ids only when a test or output consumer
needs a distinct state.
- Pair every trial-state mutation with an observable commit or rollback audit.
- Extend `nonlinear_lifecycle`, the relevant owner test and one report/output
checker when adding lifecycle fields.
- Keep `continuation_path.csv` append-only for new lifecycle/report columns.
- Add restart state only as an optional block unless a deliberately versioned
format break is approved.
0.6.0 lifecycle hooks are diagnostics and audit infrastructure. Do not use
them to claim delivery of complete AL/mortar consistent tangents,
mixed-control continuation, cohesive contact mainline, harmonic cyclic
nonzero-wave solving, DEM subcycling or production roll-forming workflows.