Files
FemLite/docs/08_developer_manual.md
T
shenw cde2b82c91
FemLite CI / build-test (push) Has been cancelled
Add user and developer manuals
2026-06-24 17:33:55 +08:00

12 KiB
Raw Blame History

FemLite 0.3.3 开发者手册

日期:2026-06-24

1. 目的

本文档面向 FemLite 开发者,说明代码结构、构建测试、模块职责、接口扩展、编码约束和发布检查流程。

FemLite 核心代码采用 Fortran 95 非面向对象风格,使用集中式 fem_database 保存模型、状态和求解数据。当前版本为 0.3.3。

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 性能测试

常用构建:

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 时间步、求解控制、输出控制
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_element_stiffness 实体/壳单元静力刚度
fem_element_internal 单元内力
fem_solver_implicit 静力、隐式 Newmark、非线性 Newton 主流程
fem_contact 接触公开入口和刚性平面接触
fem_contact_* contact pair 状态、目标、几何、搜索、摩擦、力、切线和输出
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

输入读取使用两遍策略:

  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。

扩展新 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. 接触模块扩展

接触模块已拆分:

fem_contact.f90          公开入口、刚性平面 penalty 接触
fem_contact_state.f90    接触统计清零和累积
fem_contact_target.f90   目标匹配、shared-node、pair 参数
fem_contact_geometry.f90 facet 几何、投影裁剪、mortar 权重
fem_contact_search.f90   空间网格、BVH、候选 master facet
fem_contact_friction.f90 Coulomb 粘滑历史
fem_contact_force.f90    contact pair 力路径
fem_contact_tangent.f90  contact pair CSR 切线装配
fem_contact_output.f90   contact CSV 字段辅助

扩展接触时优先保持这个边界:

  • 搜索逻辑放在 fem_contact_search。
  • 几何积分放在 fem_contact_geometry。
  • 法向/切向力分配放在 fem_contact_force。
  • 切线矩阵装配放在 fem_contact_tangent。
  • 统计和输出字段放在 fem_contact_state 和 fem_contact_output。

新增 contact pair 行为应覆盖:

  • 串行路径。
  • uniform grid 路径。
  • BVH 路径。
  • force 和 tangent 路径。
  • contact CSV 输出。
  • 输入解析。

9. 求解器扩展

求解器核心文件:

  • fem_assembly_csr.f90:DOF 获取、CSR 图案和装配。
  • fem_linear_solver_cg.f90:Jacobi 预条件 CG。
  • fem_solver_implicit.f90:静力、隐式 Newmark、非线性 Newton。

新增求解路径时应明确:

  • 是否需要质量矩阵。
  • 是否需要刚度或切线矩阵。
  • 是否需要 Rayleigh 阻尼。
  • 是否需要 trial/rollback。
  • 是否写 convergence、reaction、VTK/CSV。
  • 是否与 contact、Robin、MPC 切线耦合。

非线性路径必须保护:

  • 材料状态 trial/restore。
  • 元素删除状态。
  • Newmark 运动学量。
  • 线搜索失败和步长缩减后的 rollback。

10. 输出扩展

输出文件由 src/output 管理:

  • fem_output_csv 写 CSV。
  • fem_output_vtk 写 legacy ASCII VTK。
  • fem_restart 写 restart。

新增输出字段时:

  1. 更新输出模块。
  2. 更新用户手册中的输出说明。
  3. 增加 schema 或 smoke 测试。
  4. 避免把大型输出文件提交到 git。

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。
  • 输出: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 和 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|implicit_inp|source_size)$" --output-on-failure

测试分层:

  • 单元测试:材料、CSR、线性求解器、单元质量/内力/刚度。
  • 模块测试:数据库、facet、接触、输出、restart、INP。
  • 接口测试:C ABI、Python debug。
  • CLI 测试:静力、隐式 Newmark 等命令行入口。
  • 示例 smoke:shell patch、pressure pulse、rigid sphere impact。
  • 性能测试:perf_p1。

0.3.3 当前 CTest 包含 33 项。

14. 源码规模门禁

source_size CTest 调用:

python tests\scripts\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.3.3 当前无 active hard-threshold exception;软警告不阻断发布。

15. 编码规范

  • 默认 ASCII,除非文件已有明确中文文档语境。
  • Fortran 缩进保持当前风格。
  • 变量命名沿用模块现有风格。
  • 注释只解释非显然算法或约定。
  • 不使用面向对象 Fortran 特性。
  • 不把 shell 命令、临时路径或本机绝对路径写入核心源码。
  • 不提交 build、results、CSV/VTK 全量结果、restart 和临时文件。

函数和文件拆分建议:

  • 新功能先放在职责明确的既有模块。
  • 当模块开始跨越多个职责时,按状态、目标、几何、搜索、力、切线、输出等轴线拆分。
  • 拆分后优先通过 CMake 依赖顺序、单元测试和 source_size 检查验证。

16. 示例维护

示例目录应包含:

  • README.md。
  • 网格/输入生成脚本。
  • .inp 输入文件。
  • 可选结果检查脚本。

示例目录不应提交:

  • 每一步全场 CSV。
  • 每一步 VTK。
  • contact CSV 全量结果。
  • 临时 gmsh/cache 文件。

若需要保留结果,应保留小型 summary 或抽样结果,并在 README 中说明生成命令和误差指标。

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。
  7. 检查 git status --ignored --short,确认 results 和 build 输出未被暂存。
  8. 更新 docs/v*_acceptance_report.md 和相关接口/测试文档。
  9. 提交 git,必要时打 tag 并推送。

0.3.3 发布基线记录见 docs/v3_acceptance_report.md。

18. 后续开发重点

建议后续版本重点推进:

  • 完整 Abaqus surface 语义。
  • node-based surface 和 analytic rigid surface。
  • 工程级 mortar 约束求解器。
  • 摩擦正则化参数体系。
  • 大规模接触收敛控制。
  • 更多壳塑性和隐式动力长跑基准。
  • 大规模性能、并行和外部稀疏求解器接口。