# 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` | 时间步、求解控制、输出控制、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_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/none 预条件、CG、BiCGSTAB 和外部求解器占位。 - `fem_solver_implicit.f90`:静力、隐式 Newmark、非线性 Newton。 V4.6 起,隐式求解器内部不再直调 CG,而是通过 `linear_solver_solve` 分发。新增线性求解器时应先在该分发层注册 method 常量、预条件支持、统计状态和模块测试,再接入 Fortran API / C ABI。 新增求解路径时应明确: - 是否需要质量矩阵。 - 是否需要刚度或切线矩阵。 - 是否需要 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_smoke` CTest 分组,长跑或网格收敛结果不提交全量 CSV/VTK。 ## 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、Scordelis-Lo、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` 子目录,并支持自动检查失败码。 新增基准测试案例应放在 `examples/` 下,并为每个案例建立独立文件夹;旧兼容目录不作为新测试入口。 V4.8 起,`examples_layout` CTest 会检查 `examples/` 一级目录:有文档的目录必须包含至少一个 `.inp`,有 `.inp` 的目录必须包含 `run_case.bat`。 示例目录不应提交: - 每一步全场 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` 和 `examples_layout`。 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 约束求解器。 - 摩擦正则化参数体系。 - 大规模接触收敛控制。 - 更多壳塑性和隐式动力长跑基准。 - 大规模性能、并行和外部稀疏求解器接口。