This commit is contained in:
1 parent
97bc0f1cca
commit
255c7caf4f
53 files changed
+5662
-432
No files matched your search
+37
-15
@@ -1,4 +1,4 @@
|
||||
# FemLite 0.3.3 开发者手册
|
||||
# FemLite 0.4.3 开发者手册
|
||||
|
||||
日期:2026-06-24
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
本文档面向 FemLite 开发者,说明代码结构、构建测试、模块职责、接口扩展、编码约束和发布检查流程。
|
||||
|
||||
FemLite 核心代码采用 Fortran 95 非面向对象风格,使用集中式 `fem_database` 保存模型、状态和求解数据。当前版本为 0.3.3。
|
||||
FemLite 核心代码采用 Fortran 95 非面向对象风格,使用集中式 `fem_database` 保存模型、状态和求解数据。当前版本为 0.4.3。
|
||||
|
||||
## 2. 开发原则
|
||||
|
||||
@@ -28,7 +28,8 @@ CMake 主要目标:
|
||||
| `femlite_c` | 静态库 | C ABI 包装库 |
|
||||
| `femlite` | 可执行程序 | 命令行入口 |
|
||||
| `test_*` | 可执行程序 | 单元、模块和接口测试 |
|
||||
| `perf_p1` | 可执行程序 | P1 性能测试 |
|
||||
| `perf_p1` | 可执行程序 | P1 显式动力性能测试 |
|
||||
| `perf_contact_pair` | 可执行程序 | contact pair BVH/缓存性能测试 |
|
||||
|
||||
常用构建:
|
||||
|
||||
@@ -167,11 +168,13 @@ INP 相关文件:
|
||||
|
||||
```text
|
||||
fem_contact.f90 公开入口、刚性平面 penalty 接触
|
||||
fem_contact_state.f90 接触统计清零和累积
|
||||
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_friction.f90 Coulomb 粘滑历史
|
||||
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 字段辅助
|
||||
@@ -184,6 +187,13 @@ fem_contact_output.f90 contact CSV 字段辅助
|
||||
- 法向/切向力分配放在 `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 行为应覆盖:
|
||||
|
||||
@@ -191,6 +201,11 @@ fem_contact_output.f90 contact CSV 字段辅助
|
||||
- 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 输出。
|
||||
- 输入解析。
|
||||
|
||||
@@ -224,7 +239,7 @@ fem_contact_output.f90 contact CSV 字段辅助
|
||||
|
||||
- `fem_output_csv` 写 CSV。
|
||||
- `fem_output_vtk` 写 legacy ASCII VTK。
|
||||
- `fem_restart` 写 restart。
|
||||
- `fem_restart` 写 restart;V4.3 restart v2 额外保存 mortar 积分点摩擦历史槽。
|
||||
|
||||
新增输出字段时:
|
||||
|
||||
@@ -233,6 +248,12 @@ fem_contact_output.f90 contact CSV 字段辅助
|
||||
3. 增加 schema 或 smoke 测试。
|
||||
4. 避免把大型输出文件提交到 git。
|
||||
|
||||
新增跨时间步状态时:
|
||||
|
||||
1. 明确该状态是否影响继续计算。
|
||||
2. 若影响继续计算,同步更新 `fem_restart` 写读和 restart 回归。
|
||||
3. 若暂不支持重启,必须在接口文档和当前限制中说明。
|
||||
|
||||
## 11. Fortran API
|
||||
|
||||
公共 Fortran API 在 `src/base/fem_api.f90` 中。常用类别:
|
||||
@@ -242,7 +263,7 @@ fem_contact_output.f90 contact CSV 字段辅助
|
||||
- 显式:`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。
|
||||
- 查询:模型规模、当前时间、节点运动学、反力、单元状态、接触 summary、contact diagnostics、contact friction summary 和 contact history stats。
|
||||
- 输出:`fem_write_output`、`fem_write_restart`、`fem_read_restart`。
|
||||
|
||||
新增 API 时:
|
||||
@@ -260,7 +281,7 @@ C ABI:
|
||||
- 实现:`src/interface/fem_c_api.c`。
|
||||
- Fortran-C bridge:`src/interface/fem_fortran_bridge.f90`。
|
||||
|
||||
C ABI 当前暴露初始化、读取、构建、显式推进、SPH 力、facet 查询、节点运动学、contact summary 和 restart 子集。
|
||||
C ABI 当前暴露初始化、读取、构建、显式推进、SPH 力、facet 查询、节点运动学、contact summary、contact diagnostics、contact friction summary、contact history stats 和 restart 子集。
|
||||
|
||||
Python 调试接口:
|
||||
|
||||
@@ -279,7 +300,7 @@ 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
|
||||
ctest --test-dir build-win-gcc-16 -R "^(contact|contact_omp1|contact_omp4|restart|c_api|implicit_inp|source_size)$" --output-on-failure
|
||||
```
|
||||
|
||||
测试分层:
|
||||
@@ -289,9 +310,9 @@ ctest --test-dir build-win-gcc-16 -R "^(contact|implicit_inp|source_size)$" --ou
|
||||
- 接口测试:C ABI、Python debug。
|
||||
- CLI 测试:静力、隐式 Newmark 等命令行入口。
|
||||
- 示例 smoke:shell patch、pressure pulse、rigid sphere impact。
|
||||
- 性能测试:`perf_p1`。
|
||||
- 性能测试:`perf_p1`、`perf_contact_pair`、`perf_contact_pair_omp_consistency`。
|
||||
|
||||
0.3.3 当前 CTest 包含 33 项。
|
||||
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. 源码规模门禁
|
||||
|
||||
@@ -309,7 +330,7 @@ python tests\scripts\check_source_size.py . --warn-file-lines 1500 --max-file-li
|
||||
- 超过 2000 行必须登记 hard-threshold exception。
|
||||
- stale exception 会导致测试失败。
|
||||
|
||||
0.3.3 当前无 active hard-threshold exception;软警告不阻断发布。
|
||||
0.4.3 当前无 active hard-threshold exception;软警告不阻断发布。
|
||||
|
||||
## 15. 编码规范
|
||||
|
||||
@@ -335,6 +356,7 @@ python tests\scripts\check_source_size.py . --warn-file-lines 1500 --max-file-li
|
||||
- 网格/输入生成脚本。
|
||||
- `.inp` 输入文件。
|
||||
- 可选结果检查脚本。
|
||||
- Windows 双击自动运行脚本可命名为 `run_case.bat`;脚本应把结果写入示例目录下的 `results` 子目录,并支持自动检查失败码。
|
||||
|
||||
示例目录不应提交:
|
||||
|
||||
@@ -361,15 +383,15 @@ python tests\scripts\check_source_size.py . --warn-file-lines 1500 --max-file-li
|
||||
8. 更新 `docs/v*_acceptance_report.md` 和相关接口/测试文档。
|
||||
9. 提交 git,必要时打 tag 并推送。
|
||||
|
||||
0.3.3 发布基线记录见 `docs/v3_acceptance_report.md`。
|
||||
0.3.3 发布基线记录见 `docs/v3_acceptance_report.md`。0.4.x 阶段开发和阶段记录见 `docs/v4_development_plan.md`。
|
||||
|
||||
## 18. 后续开发重点
|
||||
|
||||
建议后续版本重点推进:
|
||||
|
||||
- 完整 Abaqus surface 语义。
|
||||
- node-based surface 和 analytic rigid surface。
|
||||
- 工程级 mortar 约束求解器。
|
||||
- 更完整的 analytical rigid surface 和 node-surface contact pair 路径。
|
||||
- 完整工程级 mortar/augmented Lagrangian 约束求解器。
|
||||
- 摩擦正则化参数体系。
|
||||
- 大规模接触收敛控制。
|
||||
- 更多壳塑性和隐式动力长跑基准。
|
||||
|
||||