Files
FemLite/docs/08_developer_manual.md
T
shenw 255c7caf4f
FemLite CI / build-test (push) Has been cancelled
Advance V4 contact search and parallelism
2026-06-25 08:59:14 +08:00

399 lines
16 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.4.3 开发者手册
日期:2026-06-24
## 1. 目的
本文档面向 FemLite 开发者,说明代码结构、构建测试、模块职责、接口扩展、编码约束和发布检查流程。
FemLite 核心代码采用 Fortran 95 非面向对象风格,使用集中式 `fem_database` 保存模型、状态和求解数据。当前版本为 0.4.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 显式动力性能测试 |
| `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` | 时间步、求解控制、输出控制 |
| `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. 数据流
典型命令行流程:
```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。
扩展新 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_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_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 遍历切线路径。
新增 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_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;V4.3 restart v2 额外保存 mortar 积分点摩擦历史槽。
新增输出字段时:
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、pressure pulse、rigid sphere impact。
- 性能测试:`perf_p1`、`perf_contact_pair`、`perf_contact_pair_omp_consistency`。
0.4.3 基线 CTest 包含 34 项;V4.4 开发态加入 `contact_omp1`、`contact_omp4`、`perf_contact_pair_smoke`、`perf_contact_pair_medium` 和 `perf_contact_pair_omp_consistency` 后,在 Python 可用时包含 39 项。
## 14. 源码规模门禁
`source_size` CTest 调用:
```powershell
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.4.3 当前无 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` 子目录,并支持自动检查失败码。
示例目录不应提交:
- 每一步全场 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`。0.4.x 阶段开发和阶段记录见 `docs/v4_development_plan.md`。
## 18. 后续开发重点
建议后续版本重点推进:
- 完整 Abaqus surface 语义。
- 更完整的 analytical rigid surface 和 node-surface contact pair 路径。
- 完整工程级 mortar/augmented Lagrangian 约束求解器。
- 摩擦正则化参数体系。
- 大规模接触收敛控制。
- 更多壳塑性和隐式动力长跑基准。
- 大规模性能、并行和外部稀疏求解器接口。