642 lines
40 KiB
Markdown
642 lines
40 KiB
Markdown
# 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_tangent_audit_report` | 共享 tangent audit CSV schema、状态词汇和覆盖计数;只做报告归一化 |
|
||
| `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` 测试。
|
||
- 0.6.1 起,`fem_tangent_audit_report` 只提供统一 audit report schema、
|
||
`pass/fail/missing/not-applicable` 状态和覆盖计数;它不表示生产一致切线
|
||
或完整 AL/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.
|
||
|
||
## 21. 0.6.1 Diagnostic Hardening Notes
|
||
|
||
0.6.1 diagnostic additions are append-only:
|
||
|
||
- `nonlinear_lifecycle.csv` extends lifecycle rows with cutback reason,
|
||
residual breakdown, linear solver method/preconditioner/iterations/status,
|
||
residuals and fail class.
|
||
- `contact_XXXXXXXX.csv` extends contact rows with stable state counters
|
||
(`open`, `closed-stick`, `closed-slip`, `closed-restick`, `separating`,
|
||
failed projection) plus gap/slip/friction residual summaries.
|
||
- `continuation_path.csv` extends path rows with `arc_mode`,
|
||
predictor-consistency, load-reversal, turning-point, arc-length and load
|
||
delta fields. These are diagnostics only and do not introduce
|
||
mixed-control continuation.
|
||
- `fem_tangent_audit_report` provides a shared report vocabulary for existing
|
||
tangent audits and missing/not-applicable coverage counters. It is not a
|
||
production consistent-tangent implementation.
|
||
- Restart tests should compare lifecycle/contact/path summaries before and
|
||
after read-back when those summaries are supported by the compact model.
|
||
|
||
Keep larger algorithm rewrites deferred unless a later development plan
|
||
explicitly schedules them.
|