Complete V5 documentation governance

This commit is contained in:
shenw
2026-06-26 13:59:14 +08:00
parent 4800e19b19
commit 393c81397f
3 changed files with 92 additions and 13 deletions
+26 -8
View File
@@ -3,7 +3,8 @@
日期:2026-06-26
本文档记录 FemLite 0.5.x 当前 V5 开发态的阶段验收结果。它不是最终发布
公告;最终发布前仍需完成 release hygiene、干净分支、长跑和多平台复测。
公告;20.1 发布确认和 20.2 多平台复测已完成,最终发布前仍需完成更大规模
longrun 和剩余 PARTIAL 能力的工程化收束。
## 验收范围
@@ -18,16 +19,21 @@
- V5.7 cohesive 单积分点和球-膜粘附/脱粘 benchmark。
- V5.8 内置离散球颗粒、颗粒-facet 映射和动态颗粒柔性容器 benchmark。
- V5.9 benchmark 矩阵和 V5 验收 CTest 标签。
- V5.10 验收报告、release hygiene checkpoint、clean clone 发布确认和多平台复测。
## 测试环境
| 项 | 记录 |
|---|---|
| 工作目录 | `D:\Codex\FemLite` |
| 构建目录 | `build-win-gcc-16` |
| 主构建目录 | `build-win-gcc-16` |
| 多平台构建目录 | `build-wsl-gfortran-v5-20-2`、`build-win-ifx-v5-20-2` |
| 构建类型 | Release |
| 操作环境 | Windows PowerShell |
| 操作环境 | Windows PowerShell、WSL Ubuntu 24.04、Windows Intel oneAPI/VS DevCmd |
| 日期 | 2026-06-26 |
| Windows GCC 工具链 | GNU Fortran 16.1.0 |
| WSL GNU 工具链 | GNU Fortran 13.3.0、GNU C 13.3.0、CMake 3.28.3 |
| Windows Intel/MSVC 工具链 | VS DevCmd 17.14.33、MSVC 19.44.35227.0、IntelLLVM ifx 2026.0.0 |
| 第三方 solver | 不使用;外部/第三方 solver 接口已移除且旧编号作为非法配置拒绝 |
## 执行命令
@@ -38,6 +44,11 @@ cmake --build build-win-gcc-16 --config Release --target dynamic_grain_container
ctest --test-dir build-win-gcc-16 -C Release -R "example_dynamic_grain_container_benchmark|particle_acceptance|source_size" --output-on-failure
ctest --test-dir build-win-gcc-16 -C Release -L v5_acceptance --output-on-failure
ctest --test-dir build-win-gcc-16 -C Release --output-on-failure
ctest --test-dir build-wsl-gfortran-v5-20-2 -C Release --output-on-failure
ctest --test-dir build-wsl-gfortran-v5-20-2 -C Release -L v5_acceptance --output-on-failure
ctest --test-dir build-win-ifx-v5-20-2 -C Release --output-on-failure
ctest --test-dir build-win-ifx-v5-20-2 -C Release -L v5_acceptance --output-on-failure
ctest --test-dir build-win-gcc-16 -C Release -R "contact_omp1|contact_omp4|perf_contact_pair_omp_consistency" --output-on-failure -V
```
## 测试结果
@@ -49,6 +60,11 @@ ctest --test-dir build-win-gcc-16 -C Release --output-on-failure
| `ctest --test-dir build-win-gcc-16 -C Release -R "example_dynamic_grain_container_benchmark|particle_acceptance|source_size" --output-on-failure` | 3/3 passed |
| `ctest --test-dir build-win-gcc-16 -C Release -L v5_acceptance --output-on-failure` | 35/35 passed |
| `ctest --test-dir build-win-gcc-16 -C Release --output-on-failure` | 106/106 passed |
| `ctest --test-dir build-wsl-gfortran-v5-20-2 -C Release --output-on-failure` | 106/106 passed |
| `ctest --test-dir build-wsl-gfortran-v5-20-2 -C Release -L v5_acceptance --output-on-failure` | 35/35 passed |
| `ctest --test-dir build-win-ifx-v5-20-2 -C Release --output-on-failure` | 106/106 passed |
| `ctest --test-dir build-win-ifx-v5-20-2 -C Release -L v5_acceptance --output-on-failure` | 35/35 passed |
| `ctest --test-dir build-win-gcc-16 -C Release -R "contact_omp1|contact_omp4|perf_contact_pair_omp_consistency" --output-on-failure -V` | 3/3 passed |
## 已完成内容
@@ -62,6 +78,8 @@ ctest --test-dir build-win-gcc-16 -C Release --output-on-failure
| cohesive | cohesive law/state/metrics 覆盖 loading、unloading、mixed-mode damage、complete decohesion、非负耗散和 restart;ball adhesion benchmark 输出滞回、拉脱力、能量和脱粘面积。 |
| 颗粒耦合 | `particle_acceptance` 覆盖自由落体、墙碰撞、颗粒堆和颗粒-facet 载荷平衡;dynamic grain container benchmark 验证真实粒子、映射节点力和柔性容器位移。 |
| benchmark 矩阵 | `docs/v5_benchmark_matrix.md` 映射 V5.2-V5.8 已完成能力到 CTest、目录、指标和容差;`v5_acceptance` 标签可运行当前 V5 验收子集。 |
| 发布治理 | `docs/v5_development_plan.md` 为唯一状态入口;`docs/v5_benchmark_matrix.md` 记录可执行矩阵;本报告记录验收结论、限制和多平台复测证据。 |
| 多平台复测 | Windows GCC 16、WSL GNU 13.3 和 Windows IntelLLVM 2026.0/MSVC 19.44 均通过默认 CTest 和 `v5_acceptance`;OpenMP contact/performance smoke 通过。 |
## 关键参考指标
@@ -85,8 +103,7 @@ ctest --test-dir build-win-gcc-16 -C Release --output-on-failure
| 完整三维滚压长跑 | 当前是辊运动学和紧凑多层 J2 截面 springback benchmark | 真实工艺网格、restart 多 step 和长时间稳定性尚未验证 | 用户可验证核心算法路径,但不能直接替代工业 roll forming 工艺仿真 |
| 完整 FE cohesive 接触 step | 当前 cohesive law/state/metrics 和 ring benchmark 已完成,主接触流程切换与切线仍需集成 | 粘附/普通接触切换和 restart 长路径仍有风险 | 用户可使用 benchmark 验证 cohesive 模型,不应把它当作通用 FE cohesive 接触 |
| 颗粒大规模 longrun | 当前 V5.8 限定内置离散球和紧凑柔性容器 benchmark | 大颗粒数性能、邻域搜索和长时间能量稳定性仍需验证 | 用户可验证双向映射闭环,但不能把它当作工业 DEM 装填求解器 |
| 多平台发布验收 | 当前记录为 Windows GCC 16;WSL 和 Intel oneAPI 需发布前复测 | 平台相关编译/数值差异未完成最终确认 | 发布前仍需补多平台记录 |
| 发布 hygiene | 当前工作区包含大量 V5 开发改动和生成构建产物;尚未形成干净发布分支 | 合并/发布时可能夹带非目标文件或过期结果 | 需要最终清理、复测、提交和分支/标签决策 |
| 后续 release tag 刷新 | 当前 `v0.5.0-v5-acceptance-checkpoint` 指向 20.1 clean clone 节点;20.2 多平台复测提交在其后 | 若需要把 20.2 修复纳入正式发布标签,应另行决定是否创建新 tag | 不影响当前 `main` 多平台复测结论,但最终发布公告需明确 tag/commit |
## 暂缓或不纳入当前模块
@@ -100,7 +117,8 @@ ctest --test-dir build-win-gcc-16 -C Release --output-on-failure
当前 V5 开发态已经将 V5.2 和 V5.8 收束到可验收闭环,并为 V5.3-V5.7
建立了真实算法路径、紧凑 benchmark 和可复现指标。`v5_acceptance` 标签提供
当前 V5 验收子集,默认 Release CTest 保持 106/106 passed。
当前 V5 验收子集,默认 Release CTest 保持 106/106 passed,并已完成 WSL GNU
和 Windows Intel/MSVC 多平台复测。
最终 0.5.x 发布仍需完成长跑、多平台复测、release hygiene 和剩余部分能力的工程化
收束;不得把当前紧凑 benchmark 夸大为完整工业场景全覆盖。
最终 0.5.x 发布仍需完成更大规模 longrun、最终标签决策和剩余 PARTIAL 能力的
工程化收束;不得把当前紧凑 benchmark 夸大为完整工业场景全覆盖。
+20
View File
@@ -17,6 +17,15 @@
默认回归当前 Windows GCC 16 Release 记录为 `106/106 passed`。V5 验收子集
当前记录为 `35/35 passed`。
## 多平台复测矩阵
| 平台 | 构建目录 | 工具链 | 默认 CTest | V5 验收子集 | 备注 |
|---|---|---|---|---|---|
| Windows GCC | `build-win-gcc-16` | GNU Fortran 16.1.0 | 106/106 passed | 35/35 passed | 20.1 clean clone 和 20.2 后本地回归均通过 |
| WSL GNU | `build-wsl-gfortran-v5-20-2` | GNU Fortran 13.3.0、GNU C 13.3.0、CMake 3.28.3 | 106/106 passed | 35/35 passed | benchmark 工具已修正跨平台路径分隔符 |
| Windows Intel/MSVC | `build-win-ifx-v5-20-2` | VS DevCmd 17.14.33、MSVC 19.44.35227.0、IntelLLVM ifx 2026.0.0 | 106/106 passed | 35/35 passed | CTest 环境优先加载 ifx compiler runtime;Mohr-Coulomb 边界分类容差已稳定 |
| Windows GCC OpenMP | `build-win-gcc-16` | GNU Fortran 16.1.0,OpenMP enabled | `contact_omp1`、`contact_omp4`、`perf_contact_pair_omp_consistency` 3/3 passed | n/a | 1/4 线程 contact/performance smoke 非计时统计一致 |
## V5 验收矩阵
| V5 项 | 能力 | 目录或模块 | CTest 名称 | 参考指标 | 容差/验收条件 |
@@ -62,3 +71,14 @@
- benchmark 编排工具放在 `tools/benchmarks`,示例输入和 checker 放在对应
`examples/<case>/` 目录,生产功能代码仍保留在 `src`。
- 当前模块不引入第三方 solver 或外部求解器进程;相关验收只覆盖内部 solver。
## 文档治理边界
- 状态标记只在 `docs/v5_development_plan.md` 维护;本矩阵只记录可运行入口、
指标和容差,避免多个文档出现互相冲突的 PASS/PARTIAL 口径。
- 每次新增或修正 benchmark 时,必须同步本文件中的 CTest 名称、示例目录、
checker、参考指标和容差说明。
- 每次完成发布确认、多平台复测或 longrun 后,必须同步本文件的测试层级和
多平台复测矩阵,并同步 `docs/v5_acceptance_report.md` 的验收结论。
- 若某项仅为 smoke、surrogate 或 debug fallback,不得在本矩阵中列为 V5
完成项;只能在边界说明或 DEFERRED/PARTIAL 说明中登记。
+46 -5
View File
@@ -926,8 +926,49 @@ OpenMP contact/performance smoke 记录:
### 20.4 文档与验收治理
1. 每完成一个 PARTIAL 项,先更新 `docs/v5_development_plan.md` 状态表,再同步
`docs/v5_benchmark_matrix.md` 和 `docs/v5_acceptance_report.md`。
2. benchmark 只在 `examples/<case>/` 和 `tools/benchmarks` 增加输入、checker 和
编排工具;生产功能仍进入 `src`。
3. 不重新引入第三方 solver、外部 solver 进程或外部 solver C ABI 常量。
状态:DONE(2026-06-26,治理规则已同步到计划、benchmark 矩阵和验收报告)。
治理目标:
- 防止 V5 状态在多个文档中重复标记、互相冲突。
- 防止 smoke、surrogate、debug fallback 被误写成完成的工业能力。
- 防止 benchmark 工具、示例输入、checker 和生产实现边界混淆。
- 防止第三方 solver、外部 solver 进程或外部 solver C ABI 常量重新进入核心模块。
单一事实源:
| 文档 | 责任 | 更新触发 | 验收要求 |
|---|---|---|---|
| `docs/v5_development_plan.md` | 唯一状态标记入口,维护 PASS/PARTIAL/DEFERRED/NOT STARTED 和下一步建议 | 任一 V5 项状态变化、完成发布确认、多平台复测、longrun 或 tag 决策 | 状态表、完成证据和下一步建议必须一致 |
| `docs/v5_benchmark_matrix.md` | 可执行验收矩阵,维护测试层级、CTest 名称、示例目录、参考指标和容差 | 新增/修改 benchmark、checker、CTest 标签、平台复测或 longrun | 每条 V5 完成项必须可由命令、checker 和指标复现 |
| `docs/v5_acceptance_report.md` | 阶段验收结论,维护测试环境、命令、结果、完成项、限制和用户影响 | 发布确认、多平台复测、清理 deferred/surrogate 或最终发布准备 | 不得保留已完成事项作为未完成风险;不得删除仍存在的 PARTIAL 边界 |
| 核心设计文档 | 记录生产算法、接口和用户可见行为 | `src` 新增生产算法、输入关键字、C ABI、输出字段或状态变量 | 算法文档、接口文档、测试计划、用户手册和开发者手册口径一致 |
更新顺序:
1. 代码或示例变更完成后,先运行对应单元、模块或示例 checker。
2. 若结果改变状态,先更新本文件的阶段状态表和对应 V5 小节。
3. 再同步 `docs/v5_benchmark_matrix.md` 的测试入口、指标和容差。
4. 再同步 `docs/v5_acceptance_report.md` 的测试环境、执行命令、结果和限制。
5. 最后执行 `git diff --check`,并确认没有把生成结果文件或构建目录带入提交。
边界规则:
- benchmark 输入、checker、双击脚本和 benchmark 编排工具只放在
`examples/<case>/` 或 `tools/benchmarks`;生产功能代码仍进入 `src`。
- 方便测试的通用工具可以放在与 `src` 同级的 `tools`,但不得作为生产模块依赖。
- 若一个示例只验证可运行路径,必须标为 smoke;只有带参考指标、checker 和容差的
示例才能进入 V5 benchmark 矩阵。
- 若一个实现仍依赖缩减模型、紧凑模型或 fallback 路径,必须在状态表保留
PARTIAL/DEFERRED 说明,不得为了发布口径改写为 PASS。
- 当前核心模块不引入第三方库,不引入第三方 solver,不保留外部 solver backend、
外部 solver 进程或外部 solver C ABI 编号。
当前同步结果:
| 项 | 结果 |
|---|---|
| `docs/v5_development_plan.md` | 已登记 20.1 发布确认、20.2 多平台复测和 20.4 治理规则;V5.9/V5.10 仍保留 PARTIAL 以反映 longrun 和部分工程化边界 |
| `docs/v5_benchmark_matrix.md` | 已新增多平台复测矩阵和文档治理边界;Windows GCC、WSL GNU、Windows Intel/MSVC 和 OpenMP smoke 结果已登记 |
| `docs/v5_acceptance_report.md` | 已移除“多平台复测/release hygiene 未完成”的旧口径,保留 longrun、最终 tag 决策和剩余 PARTIAL 能力边界 |
| 后续建议 | 下一步优先补更大规模 longrun 和 V5.3-V5.7 的工程化主流程集成;若要把 20.2 修复纳入正式发布标签,需要另行创建或移动发布标签 |