27 KiB
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。
- 新增功能必须配套小型测试;影响共享行为时补充回归测试。
- 大型输出和临时结果不进入 git。
3. 构建目标
CMake 主要目标:
| 目标 | 类型 | 说明 |
|---|---|---|
femlite_core |
静态库 | Fortran95 核心库 |
femlite_c |
静态库 | C ABI 包装库 |
femlite |
可执行程序 | 命令行入口 |
test_* |
可执行程序 | 单元、模块和接口测试 |
perf_p1 |
可执行程序 | P1 显式动力性能测试 |
perf_contact_pair |
可执行程序 | contact pair BVH/缓存性能测试 |
常用构建:
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:
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:
cmake -S . -B build-win-gcc-16 -DFEMLITE_ENABLE_OPENMP=ON
OpenMP 当前用于 contact BVH 搜索的可选并行路径。
4. 模块结构
核心目录:
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 壳稳定参数 |
fem_api |
Fortran95 公共 API |
fem_inp_reader |
两遍 INP 读取主流程 |
fem_inp_defs |
INP 模式常量 |
fem_inp_helpers |
INP 行解析和 keyword helper |
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 状态、目标、几何、搜索、摩擦、力、切线、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. 数据流
典型命令行流程:
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
输入读取使用两遍策略:
- 第一遍统计节点、单元、集合、材料、section、载荷、surface 和 contact pair 数量。
- 分配数据库数组。
- 第二遍填充数据库。
- 应用 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。
扩展新 keyword 的建议步骤:
- 在
fem_inp_defs增加 mode 常量。 - 在第一遍
count_keyword中统计需要的数量。 - 在数据库中增加对应数组和分配逻辑。
- 在第二遍 keyword/data-line helper 中解析。
- 在
database_validate_model或相关校验例程中验证。 - 增加
tests/data/*.inp和模块测试。 - 更新接口文档和用户手册。
解析原则:
- keyword 名称在匹配前转大写。
- 参数值可支持空格、大小写和引号时,应加入测试。
- 对无法支持但常见的 inert keyword,可加入 known ignored keyword。
8. 接触模块扩展
接触模块已拆分:
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管理,当前使用 Fortrancpu_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_linear_solver_dispatch.f90:线性求解器统一入口、配置、统计和 method 分发。fem_linear_solver_iterative.f90:CG、BiCGSTAB、GMRES 和 none/Jacobi 预条件。fem_solver_implicit.f90:静力、隐式 Newmark、非线性 Newton。
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。
新增求解路径时应明确:
- 是否需要质量矩阵。
- 是否需要刚度或切线矩阵。
- 是否需要 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 弯曲塑性使用代表性外纤维应变近似,不是完整厚度方向积分;任何多层 section integration 扩展都必须保留 trial/rollback 的状态一致性。
- 壳 benchmark smoke 优先放在
example_smokeCTest 分组,长跑或网格收敛结果不提交全量 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 管理:
fem_output_csv写 CSV。fem_output_vtk写 legacy ASCII VTK。fem_restart写 restart;V4.3 restart v2 额外保存 mortar 积分点摩擦历史槽, 0.5.x 继续保存CONTACT_MULTIPLIER乘子状态段。
新增输出字段时:
- 更新输出模块。
- 更新用户手册中的输出说明。
- 增加 schema 或 smoke 测试。
- 避免把大型输出文件提交到 git。
新增跨时间步状态时:
- 明确该状态是否影响继续计算。
- 若影响继续计算,同步更新
fem_restart写读和 restart 回归。 - 若暂不支持重启,必须在接口文档和当前限制中说明。
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. 测试体系
运行全量测试:
ctest --test-dir build-win-gcc-16 --output-on-failure
常用定向测试:
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生成安全系数 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的通用*BUCKLINGstep 实现。 - Benchmark 编排工具:
tools/benchmarks/roll_forming_kinematics_benchmark.f90链接femlite_core,用于examples/roll_forming读取*ROLLER KINEMATICSbenchmark 输入,驱动生产滚压位姿、运动调度、 接触运动学、正则化牵引和 roll metrics,并输出 history 与 summary。 该工具是 V5.6 benchmark 编排,不是主femlite的通用滚压成形 step。 - Benchmark 编排工具:
tools/benchmarks/roll_forming_springback_benchmark.f90链接femlite_core,用于examples/roll_forming读取*ROLL FORMING SPRINGBACKbenchmark 输入,驱动生产滚压位姿、正则化 牵引、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 COHESIVEbenchmark 输入,将粘附区离散为同心环,驱动 生产 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 CONTAINERbenchmark 输入,加载无*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 调用:
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. 发布检查
发布前建议步骤:
- 确认版本号:
CMakeLists.txtsrc/base/fem_precision.f90
- 运行 Windows GCC build 和 CTest。
- 运行 WSL gfortran build 和 CTest。
- 运行 Windows Intel ifx build 和 CTest。
- 运行
git diff --check。 - 运行
source_size和examples_layout。 - 检查
git status --ignored --short,确认 results 和 build 输出未被暂存。 - 更新
docs/v*_acceptance_report.md和相关接口/测试文档。 - 提交 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 约束求解器。
- 摩擦正则化参数体系。
- 大规模接触收敛控制。
- 更多壳塑性和隐式动力长跑基准。
- 大规模性能、并行和内部稀疏求解器/预条件器强化。