This commit is contained in:
@@ -0,0 +1,376 @@
|
||||
# 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 性能测试 |
|
||||
|
||||
常用构建:
|
||||
|
||||
```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 接触统计清零和累积
|
||||
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. 测试体系
|
||||
|
||||
运行全量测试:
|
||||
|
||||
```powershell
|
||||
ctest --test-dir build-win-gcc-16 --output-on-failure
|
||||
```
|
||||
|
||||
常用定向测试:
|
||||
|
||||
```powershell
|
||||
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 调用:
|
||||
|
||||
```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.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 约束求解器。
|
||||
- 摩擦正则化参数体系。
|
||||
- 大规模接触收敛控制。
|
||||
- 更多壳塑性和隐式动力长跑基准。
|
||||
- 大规模性能、并行和外部稀疏求解器接口。
|
||||
Reference in New Issue
Block a user