Start CCLite 0.2.0 development baseline

This commit is contained in:
Codex
2026-07-05 23:40:12 +08:00
parent b7d00fe6a7
commit 4a2d30d81d
11 changed files with 1349 additions and 225 deletions
+874
View File
@@ -0,0 +1,874 @@
# CCLite 0.2.x 开发计划
## Coupling & Contact Lite for SPHLite and FEMLite
**文件名**:`v2.x_development_plan.md`
**适用版本**:CCLite 0.2.x
**文档依据**:`01_requirements.md` 到 `06_test_and_verification_plan.md`
**实现基线**:CCLite 0.1.10 主控、通信、mock worker、AoR v1 和真实 worker 能力审计
**核心目标**:基础 SPH 粒子-FEM facet penalty contact 首次实现
**第一阶段平台**:Windows / gfortran / 本机共享内存
**输入格式**:Abaqus 风格 `.inp`
**编码要求**:中文,UTF-8 without BOM
# 1. 文档目的
本文档定义 CCLite 0.2.x 的开发目标、版本节奏、工作包、测试算例、验收清单和风险控制。
0.2.x 的核心目标是从 0.1.x 的通信空耦合进入基础物理接触:
1. 解析 `*CCLITE SURFACE INTERACTION` 和 `*CCLITE CONTACT PAIR`;
2. 建立 SPH particle view 和 FEM facet view;
3. 实现基础几何 primitive、AABB、宽相搜索和窄相最近点;
4. 实现 SPH 粒子到 FEM 三角形 facet 的基础法向 penalty contact;
5. 支持法向阻尼的最小可用路径;
6. 将接触力写回 `CCL_TO_SPH_FORCE` 和 `CCL_TO_FEM_LOAD`;
7. 输出 contact report、force balance 和几何诊断;
8. 通过 `V020_GEOMETRY_PRIMITIVES`、`V020_SINGLE_PARTICLE_WALL` 和 `V020_MULTI_PARTICLE_PLANE`;
9. 至少完成一条单真实 worker 集成 gate,若协议 adapter 尚未完成,则必须形成明确的受控缺口报告。
0.2.x 的成功标准不是工程级接触库,而是让 CCLite 第一次具备可验证的 SPH-FEM 基础接触力闭环。
# 2. 当前基线
0.1.10 已完成:
1. CCLite 独立主控程序;
2. Windows shared memory 与 named event 薄封装;
3. command block、seq/ack、heartbeat 和 timeout;
4. data block header 与 AoR v1 record;
5. `SPH_TO_CCL_PARTICLE`、`FEM_TO_CCL_FACET`、`CCL_TO_SPH_FORCE`、`CCL_TO_FEM_LOAD` 的基础布局;
6. mock SPH/FEM worker service 模式;
7. 1 step 与 100 step 空耦合;
8. `run.log`、`ipc_report.csv`、`force_balance.csv`;
9. Python checker;
10. SPHLite/FEMLite 外部包能力审计。
当前真实 worker 状态:
```text
EXTERNAL_WORKERS_READY_CCLITE_PROTOCOL_ADAPTER_REQUIRED
```
含义是 SPHLite/FEMLite 已报告真实 IPC 能力,但 CCLite 仍需要完成协议/命名 adapter 或统一外部二进制契约,才能声明真实外部进程联调完成。
# 3. 版本边界
## 3.1 0.2.x 必须完成
0.2.x 必须完成以下能力:
1. `*CCLITE SURFACE INTERACTION` 支持 `NORMAL=PENALTY`;
2. `*CCLITE CONTACT PAIR` 支持 `TYPE=SPH_PARTICLE_TO_FEM_FACE`;
3. CCLite case model 保存 interaction、contact pair 和接触输出配置;
4. SPH particle view 读取 `external_id`、`internal_index`、`status`、`contact_radius`、`x`、`v`;
5. FEM facet view 读取 `facet_id`、`node_count`、`node_ids`、`area`、`thickness`、`normal`、`x`、`v`;
6. 几何基础:Vec3、AABB、point-segment、point-triangle;
7. 四边形 facet 可采用拆三角形的最小实现,复杂四边形一致性补强进入 0.3.x;
8. uniform hash grid 宽相搜索;
9. SPH 粒子到 FEM facet 的候选对生成;
10. 法向间隙 `g`、穿透量 `d` 和局部法向 `n`;
11. 法向 penalty 力和基础法向阻尼;
12. FEM 节点力按 barycentric/shape weight 分配;
13. SPH force record 写回;
14. FEM nodal force load record 写回;
15. 接触数量、最大穿透、总力、总力矩和力平衡误差诊断;
16. Python checker 验证几何、接触方向和力平衡;
17. 0.2.x 验证算例进入回归集合。
## 3.2 0.2.x 可做但不作为硬验收
以下能力可作为实现便利或实验性能力,但不得作为 0.2.x 完成定义的必要条件:
1. point-edge helper;
2. 平面四边形拆三角形接触;
3. 单真实 worker + 单 mock worker 的调试性联调;
4. 外部 worker 协议 adapter 原型;
5. 接触快照 CSV;
6. 简单性能计时。
## 3.3 0.2.x 不完成
0.2.x 不完成以下能力:
1. Coulomb 摩擦;
2. 接触 persistence 和历史切向变量;
3. 完整 edge fallback 验收;
4. 复杂壳边缘、非平面四边形和壳厚度高级接触;
5. tied coupling 和 release;
6. pressure projection、boundary/ghost particle 和 FSI;
7. 异步子循环和强耦合迭代;
8. 自动 penalty 参数推荐;
9. SoA v2 性能布局;
10. Linux/MPI 生产后端;
11. 工程级水下爆炸或船体局部破坏算例。
# 4. 与 0.3.x 和 0.4.x 的分界
0.2.x 只做基础接触首次实现。
0.3.x 负责:
1. 壳厚度补强;
2. edge fallback 完整验收;
3. 四边形接触一致性;
4. contact persistence 初步;
5. 接触状态连续性诊断。
0.4.x 负责:
1. Coulomb 摩擦;
2. 接触历史;
3. penalty 参数估计;
4. 接触稳定时间步;
5. 接触能量耗散诊断。
0.2.x 可以保留字段和枚举,但不能把这些后续能力写成已完成。
# 5. 推荐 patch 版本节奏
0.2.x 内部 patch 版本建议如下。实际开发可合并相邻 patch,但不得跳过对应验收目标。
| 版本 | 主题 | 主要交付 |
| --- | --- | --- |
| 0.2.0 | 0.2.x 入口和协议前置 | 本计划、0.2 case skeleton、真实 worker protocol adapter 设计和审计 gate |
| 0.2.1 | 接触输入与 case model | `SURFACE INTERACTION`、`CONTACT PAIR`、interaction/pair 校验 |
| 0.2.2 | 接口 view 和 load buffer | SPH particle view、FEM facet view、非空 force/load block 写回 |
| 0.2.3 | 几何 primitive | Vec3、AABB、point-segment、point-triangle、基础退化诊断 |
| 0.2.4 | 宽相搜索 | uniform hash grid、candidate pair、去重和容量保护 |
| 0.2.5 | 窄相接触 | gap、penetration、normal、shape weight、contact pair 输出 |
| 0.2.6 | penalty force | 法向 penalty、基础阻尼、FEM 节点力分配、SPH/FEM 载荷写回 |
| 0.2.7 | 诊断与 checker | contact_report.csv、force_balance.csv 增强、V020 checker |
| 0.2.8 | 验证算例 | 单粒子撞面、多粒子压面、几何/搜索/力平衡回归 |
| 0.2.9 | 单真实 worker gate | 至少完成一侧真实 worker 集成,或形成协议 adapter 受控缺口 |
| 0.2.10 | 发布候选 | 全量 0.1.x/0.2.x 回归、文档一致性、UTF-8 without BOM 检查 |
# 6. 交付物
## 6.1 程序交付物
0.2.x 应交付:
1. `cclite.exe`,支持基础 contact run;
2. mock SPH/FEM worker,可生成可控粒子和 facet;
3. 接触算法模块;
4. 几何和搜索模块;
5. contact diagnostics;
6. Python checker;
7. 0.2.x 验证算例。
## 6.2 源码交付物
建议新增或补强以下目录:
```text
src/
geometry/
contact/
search/
transfer/
verification_support/
```
若不新增目录,也必须在现有模块边界中保持职责清晰:
| 职责 | 建议模块 |
| --- | --- |
| Vec3/AABB/最近点 | `src/geometry/` |
| hash grid/candidate | `src/search/` |
| contact pair/penalty force | `src/contact/` |
| SPH force/FEM load 写回 | `src/transfer/` |
| contact report | `src/diagnostics/` |
| checker | `Python/checkers/` |
0.2.x 不应把接触算法写入 SPHLite 或 FEMLite 内部。
## 6.3 文档交付物
0.2.x 结束时应更新:
1. `README.md`;
2. `docs/03_detailed_design.md`,若模块结构或数据结构变化;
3. `docs/04_mathematical_model_and_algorithms.md`,若公式、伪代码或版本映射变化;
4. `docs/05_interface_control_document.md`,若 block 字段、record stride、命名规则或 adapter 变化;
5. `docs/06_test_and_verification_plan.md`,若新增验收算例或 checker;
6. `docs/07_real_worker_access_audit.md`,若真实 worker gate 状态变化;
7. 本开发计划;
8. `docs/0.2.x_release_notes.md`,在发布候选阶段新增。
## 6.4 测试交付物
0.2.x 测试交付物包括:
1. 几何单元测试;
2. hash grid 单元测试;
3. contact pair 单元测试;
4. penalty force 单元测试;
5. load buffer 单元测试;
6. `V020_GEOMETRY_PRIMITIVES`;
7. `V020_SINGLE_PARTICLE_WALL`;
8. `V020_MULTI_PARTICLE_PLANE`;
9. `V020_FORCE_BALANCE`;
10. `V020_SINGLE_REAL_WORKER_SMOKE` 或受控缺口报告。
# 7. 工作包分解
## 7.1 WP00:0.1.10 到 0.2.x 交接
目标:
确认 0.1.x 通信闭环可作为 0.2.x 开发地基,并处理真实 worker 协议前置风险。
任务:
1. 保留 `V010_EMPTY_COUPLING` 为 0.2.x 回归前置;
2. 保留 `real_worker_gap_report.json`;
3. 梳理 SPHLite/FEMLite 当前 IPC 结构、命名规则和能力查询;
4. 决定 0.2.x 是否先采用 mock worker 完成 A 层物理算法验收;
5. 若做真实 worker,先实现 CCLite 侧协议 adapter 或统一外部协议;
6. 记录 adapter 选择到 05 号文档。
完成标准:
1. 0.1.x 全量测试通过;
2. 真实 worker 状态不被误判为物理接触完成;
3. 0.2.x 的 A 层 mock 算例可独立于真实 worker 运行。
## 7.2 WP01:接触输入与 case model
目标:
解析 0.2.x 接触输入关键词并建立内部 case model。
必须支持:
```text
*CCLITE SURFACE INTERACTION, NAME=PENALTY_1
NORMAL=PENALTY, KN=..., CN=...
*CCLITE CONTACT PAIR, NAME=PAIR_1
INTERFACE=...
INTERACTION=...
TYPE=SPH_PARTICLE_TO_FEM_FACE
```
任务:
1. 扩展 parser 支持 interaction 和 contact pair;
2. 保存 `normal_model`、`kn`、`cn` 和 `friction` 字段;
3. 0.2.x 中若 `FRICTION` 非 0,应报错或 warning 并忽略;
4. 校验 `CONTACT PAIR` 引用的 interface 与 interaction;
5. 校验 `TYPE=SPH_PARTICLE_TO_FEM_FACE`;
6. 输出 check summary;
7. 添加非法输入测试。
完成标准:
1. 合法 contact `.inp` 可通过 `cclite check`;
2. 缺少 `KN`、非法 `NORMAL`、未知 pair 引用能给出行号和错误;
3. 0.2.x 不把摩擦写成已启用能力。
## 7.3 WP02:SPH/FEM 接口 view 与 load buffer
目标:
把 AoR v1 payload 转成接触算法可用的只读 view,并把接触力写回 load block。
SPH particle view 至少包含:
```text
external_id
internal_index
status
contact_radius
x[3]
v[3]
mass
valid_flags
```
FEM facet view 至少包含:
```text
facet_id
node_count
node_ids[8]
area
thickness
normal[3]
x[8,3]
v[8,3]
valid_flags
```
任务:
1. 建立 SPH particle view;
2. 建立 FEM facet view;
3. 检查有效字段、非有限值、容量和 record stride;
4. 建立 SPH force accumulator;
5. 建立 FEM nodal load accumulator;
6. 写 `CCL_TO_SPH_FORCE`;
7. 写 `CCL_TO_FEM_LOAD`;
8. 对同一粒子或同一节点多条载荷做合并;
9. 输出导入/导出计数。
完成标准:
1. 空 block 仍可合法通过;
2. 固定粒子和固定 facet 可生成非空 view;
3. 非有限输入不进入接触力计算;
4. 写回 block 可由 mock worker 消费;
5. force/load record 的 step id 与 command step 匹配。
## 7.4 WP03:几何 primitive
目标:
实现 04 号文档第 4 章要求的 0.2.x 几何基础。
任务:
1. Vec3 dot/cross/norm/normalize;
2. AABB 初始化、扩展、重叠测试;
3. SPH particle AABB;
4. FEM facet AABB;
5. point-segment closest point;
6. point-triangle closest point;
7. barycentric/shape weight;
8. point-quad split 为两个 triangle;
9. 退化边、退化三角形和非法 normal 诊断;
10. 单元测试覆盖内部、边、顶点和退化输入。
完成标准:
1. 点到三角形最近点误差在容差内;
2. barycentric 权重和为 1;
3. 退化几何不产生非有限结果;
4. `V020_GEOMETRY_PRIMITIVES` 通过。
## 7.5 WP04:宽相搜索
目标:
实现 uniform hash grid,从 SPH particle view 和 FEM facet view 生成 candidate pair。
任务:
1. 定义 grid cell size;
2. facet AABB 插入 grid;
3. particle AABB 查询邻近 cell;
4. candidate pair 去重;
5. candidate 容量保护;
6. 输出 candidate 统计;
7. 添加小规模和边界单元测试。
完成标准:
1. 单 facet、单粒子可生成候选;
2. 不接触的远距离粒子不生成候选;
3. 跨 cell 边界的候选不漏检;
4. 重复 facet 不导致重复 candidate;
5. candidate overflow 有明确错误码。
## 7.6 WP05:窄相 contact pair
目标:
从 candidate pair 生成真实 contact pair。
任务:
1. 对每个 candidate 计算最近点;
2. 计算局部法向;
3. 计算 gap;
4. 计算有效接触距离;
5. 计算 penetration;
6. 生成 contact pair;
7. 保存 shape weight 和 node_count;
8. 保存 contact state;
9. 记录退化和跳过原因;
10. 输出 `contact_report.csv`。
完成标准:
1. 粒子在面外无接触;
2. 粒子穿透面时生成接触;
3. 接触法向方向与设计一致;
4. `penetration = r_c - g`;
5. shape weight 可用于节点力分配;
6. 退化 facet 不产生接触力。
## 7.7 WP06:Penalty force 与节点分配
目标:
实现基础法向 penalty damping 接触力,并写回 SPH/FEM 载荷。
0.2.x 力模型:
```text
f_i = (k_n d + c_n max(0, -v_n)) n
```
FEM 节点力:
```text
F_A = N_A (-f_i)
```
任务:
1. 读取 `KN` 和 `CN`;
2. 计算 FEM 最近点速度;
3. 计算法向相对速度;
4. 计算 penalty 力;
5. 计算阻尼力;
6. 分配 FEM 节点力;
7. 合并 SPH 粒子力;
8. 合并 FEM 节点力;
9. 检查非有限力;
10. 输出力和力矩诊断。
完成标准:
1. 无穿透时接触力为 0;
2. 穿透时接触力方向正确;
3. 闭合速度时阻尼力非负;
4. 分配节点力合力等于 facet 反力;
5. SPH/FEM 总力平衡误差小于容差;
6. 非有限力被拒绝并终止当前 step。
## 7.8 WP07:Controller 接触 run 流程
目标:
在 0.1.x step loop 中插入真实接触计算。
0.2.x run 流程:
```text
for each step:
send EXPORT_INTERFACE to SPH/FEM
read SPH particle block
read FEM facet block
build interface views
build broad-phase candidates
run narrow-phase contact
compute penalty loads
write CCL_TO_SPH_FORCE
write CCL_TO_FEM_LOAD
send IMPORT_LOADS
send ADVANCE
write diagnostics
```
任务:
1. 区分 dry-run 和 contact run;
2. contact run 要求 contact pair 已定义;
3. 每步清零 contact/force/load accumulator;
4. 读取 interface block 后执行接触;
5. 写非空 load block;
6. 调用 `IMPORT_LOADS`;
7. 记录 step 级诊断;
8. 异常时停止两个 worker 并释放资源。
完成标准:
1. 空接触 case 仍可运行;
2. 单粒子撞面 case 可产生载荷;
3. 接触算法错误不会造成 worker 残留;
4. `run.log` 可定位输入、接口、几何或力计算错误。
## 7.9 WP08:诊断输出
目标:
形成可自动检查的接触诊断。
建议输出:
```text
contact_report.csv
candidate_report.csv
force_balance.csv
ipc_report.csv
run.log
verification_report.json
```
`contact_report.csv` 建议字段:
```text
step_id,pair_id,sph_id,facet_id,contact_type,gap,penetration,
normal_x,normal_y,normal_z,force_x,force_y,force_z,node_count
```
`force_balance.csv` 在 0.2.x 增加:
```text
num_contacts,max_penetration,total_contact_force_norm,
moment_balance_error,nonfinite_contact_count,skipped_degenerate_count
```
完成标准:
1. 每个 contact step 有诊断;
2. 无接触时诊断仍写 0 值;
3. checker 可读取并判定方向、力平衡和最大穿透;
4. CSV 表头变化会触发回归失败。
## 7.10 WP09:Python Checker 和算例生成
目标:
使用 `Python/` 支持 0.2.x 自动验收和可控算例生成。
任务:
1. 新增 `check_v020_geometry_primitives.py`;
2. 新增 `check_v020_contact.py`;
3. 新增公共 contact CSV 读取工具;
4. 可选新增 case generator;
5. 对单粒子撞面计算参考力;
6. 对多粒子压面检查总力方向和数量级;
7. 生成 `verification_report.json`;
8. 返回明确退出码。
完成标准:
1. checker 不依赖 CCLite 内部 Fortran 模块;
2. 失败报告包含 step、pair、字段和期望/实际值;
3. Python 只用于测试、算例和报告,不参与核心算法。
## 7.11 WP10:真实 worker adapter gate
目标:
0.2.x 起逐步接入真实 SPHLite/FEMLite worker,不让 mock 算法验收掩盖真实接口问题。
任务:
1. 明确 CCLite 采用统一通用 block 还是求解器专用 adapter;
2. 为 SPHLite 建立命名/结构 adapter 或要求其支持 CCLite 通用 block;
3. 为 FEMLite 建立命名/结构 adapter 或要求其支持 CCLite 通用 block;
4. 建立单真实 worker 1 step 空耦合;
5. 建立单真实 worker 100 step 空耦合;
6. 建立真实 worker payload 读取 smoke;
7. 将 worker 能力查询写入验证报告;
8. 若无法完成,输出 `CONTROLLED_PROTOCOL_GAP`,不阻塞 A 层算法验证。
完成标准:
1. 至少一条单真实 worker 集成路径通过,或缺口清晰记录;
2. 真实 worker 数据经过与 mock 数据相同的 header 和 payload 校验;
3. 不把 `supports_real_ipc=yes` 写成真实接触物理验收完成。
# 8. 0.2.x 输入样例
```text
** CCLite 0.2.x single particle wall contact case.
*CCLITE CONTROL, NAME=V020_SINGLE_PARTICLE_WALL, MODE=RUN
VERSION=0.2
*CCLITE SOLVER, ID=SPH, KIND=SPHLITE
EXECUTABLE=mock_sph_worker.exe
INPUT=mock_sph_contact.inp
*CCLITE SOLVER, ID=FEM, KIND=FEMLITE
EXECUTABLE=mock_fem_worker.exe
INPUT=mock_fem_wall.inp
*CCLITE IPC, TYPE=WINDOWS_SHMEM
NAME_PREFIX=CCLITE_V020
BUFFER=DOUBLE
TIMEOUT_MS=5000
*CCLITE TIME
START=0.0
END=1.0e-6
DT=1.0e-6
*CCLITE INTERFACE, NAME=WALL_CONTACT
SPH_REGION=SPH_CONTACT_REGION
FEM_SURFACE=FEM_WALL
*CCLITE SURFACE INTERACTION, NAME=PENALTY_1
NORMAL=PENALTY, KN=1.0e6, CN=0.0
FRICTION=0.0
*CCLITE CONTACT PAIR, NAME=PAIR_1
INTERFACE=WALL_CONTACT
INTERACTION=PENALTY_1
TYPE=SPH_PARTICLE_TO_FEM_FACE
*CCLITE OUTPUT
DIRECTORY=output/v020_single_particle_wall
CONTACT=YES
IPC=YES
FORCE_BALANCE=YES
```
# 9. 验证算例
## 9.1 `V020_GEOMETRY_PRIMITIVES`
目标:
验证 Vec3、AABB、point-segment、point-triangle 和基础 point-quad split。
通过判据:
1. 最近点位置误差小于容差;
2. 权重和为 1;
3. 退化几何被拒绝;
4. 无非有限值输出。
## 9.2 `V020_SINGLE_PARTICLE_WALL`
目标:
验证单 SPH 粒子撞 FEM 平面 facet 的接触方向和接触力。
通过判据:
1. 无穿透时接触数为 0;
2. 穿透时接触数为 1;
3. 法向方向正确;
4. 接触力大小等于 `KN * penetration`,若 `CN=0`;
5. FEM 节点力合力等于 SPH 反力;
6. force balance error 小于容差。
## 9.3 `V020_MULTI_PARTICLE_PLANE`
目标:
验证多个 SPH 粒子同时接触同一 FEM 平面。
通过判据:
1. 接触数量等于预期;
2. 总 SPH 力与总 FEM 力平衡;
3. 最大穿透量与输入几何一致;
4. 无重复 contact pair;
5. candidate 数量可复核。
## 9.4 `V020_FORCE_BALANCE`
目标:
专门验证力和力矩诊断。
通过判据:
1. `sum_force_sph + sum_force_fem` 小于容差;
2. 力矩误差有界且非有限计数为 0;
3. CSV 中每步都有 force balance 记录。
## 9.5 `V020_SINGLE_REAL_WORKER_SMOKE`
目标:
验证 CCLite 与至少一个真实 worker 的 0.2.x 接口路径。
通过判据:
1. worker 能启动;
2. worker 能导出非空或可控空 interface block;
3. CCLite 能写回空或可控 load block;
4. worker 能响应 `IMPORT_LOADS`、`ADVANCE` 和 `STOP`;
5. 若协议 adapter 未完成,报告必须明确写出缺口和下一步。
# 10. 测试计划
## 10.1 单元测试
0.2.x 单元测试至少覆盖:
1. contact keyword parser;
2. interaction/pair 引用校验;
3. Vec3;
4. AABB;
5. point-segment;
6. point-triangle;
7. barycentric weight;
8. hash grid;
9. candidate 去重;
10. contact pair;
11. penalty force;
12. FEM 节点分配;
13. force/load block 写回;
14. 非有限输入保护。
## 10.2 接口测试
0.2.x 接口测试至少覆盖:
1. `SPH_TO_CCL_PARTICLE` 非空 payload;
2. `FEM_TO_CCL_FACET` 非空 payload;
3. `CCL_TO_SPH_FORCE` 非空 payload;
4. `CCL_TO_FEM_LOAD` 非空 payload;
5. payload record stride;
6. `valid_flags`;
7. step id 匹配;
8. capacity overflow;
9. block state 转换;
10. worker 消费非空载荷。
## 10.3 集成测试
0.2.x 集成测试至少覆盖:
1. CCLite + 双 mock workers 单粒子撞面;
2. CCLite + 双 mock workers 多粒子压面;
3. CCLite + 单真实 SPHLite worker + mock FEM worker,若 adapter 可用;
4. CCLite + mock SPH worker + 单真实 FEMLite worker,若 adapter 可用;
5. 接触输入错误;
6. worker 超时;
7. 非有限粒子;
8. 退化 facet;
9. force balance 回归;
10. 0.1.x 空耦合回归。
# 11. 验收清单
0.2.x 发布候选必须满足:
1. 0.1.x 全量回归通过;
2. `cclite --version` 输出 0.2.x;
3. `cclite check` 支持 contact 输入;
4. 几何单元测试通过;
5. 搜索单元测试通过;
6. penalty force 单元测试通过;
7. 非空 force/load block 测试通过;
8. `V020_GEOMETRY_PRIMITIVES` 通过;
9. `V020_SINGLE_PARTICLE_WALL` 通过;
10. `V020_MULTI_PARTICLE_PLANE` 通过;
11. `V020_FORCE_BALANCE` 通过;
12. 至少一条单真实 worker gate 通过,或形成受控协议缺口报告;
13. 接触报告、力平衡报告和验证报告完整;
14. 文档与实现一致;
15. UTF-8 without BOM 检查通过;
16. 不声明摩擦、tied/release、FSI 或工程算例已完成。
# 12. 质量门禁
每个 0.2.x patch 合入前应满足:
1. 构建通过;
2. 新增算法有单元测试;
3. 0.1.x 回归不退化;
4. 新增 CSV 表头同步 checker;
5. 新增 `.inp` 样例可由 `cclite check` 解析;
6. 非有限输入有明确错误码;
7. 接触力方向有测试;
8. force balance 有测试;
9. 文档为 UTF-8 without BOM;
10. 不修改已冻结接口字段,除非同步更新 05 号文档。
# 13. 风险与对策
## 13.1 真实 worker 协议未对齐
风险:
SPHLite/FEMLite 已报告真实 IPC 能力,但二进制结构和命名规则与 CCLite 0.1.x 当前通用 block 不完全一致。
对策:
1. 0.2.x A 层算法验收继续使用 mock worker;
2. 单真实 worker gate 独立推进;
3. adapter 状态写入 `07_real_worker_access_audit.md`;
4. 不把真实 worker 缺口阻塞基础 contact 算法单元测试。
## 13.2 接触力方向错误
风险:
法向方向、gap 符号或 SPH/FEM 反力符号错误,会导致单粒子算例看似有力但物理方向错误。
对策:
1. 单粒子撞面必须有手算参考;
2. force balance 必须检查作用-反作用;
3. contact report 输出 normal、gap、penetration 和 force;
4. 测试包含粒子在 facet 两侧的情况。
## 13.3 退化几何导致非有限值
风险:
退化 facet、零长度边、非法 normal 会污染接触力。
对策:
1. 几何函数统一返回错误码;
2. 退化候选不产生接触力;
3. 诊断记录 skipped_degenerate_count;
4. checker 检查非有限计数为 0。
## 13.4 penalty 参数过大导致数值不稳定
风险:
过大 `KN` 或 `CN` 可产生非有限力或过大速度增量。
对策:
1. 0.2.x 先使用手算小算例;
2. 检查力是否有限;
3. 输出最大接触力和最大穿透;
4. 自动 penalty 参数和稳定时间步放入 0.4.x。
## 13.5 范围膨胀
风险:
过早加入摩擦、tie、FSI、工程算例会拖慢基础 contact 验收。
对策:
1. 0.2.x 只做基础法向 penalty contact;
2. 摩擦字段可解析但不启用;
3. tie 和 FSI 只保留接口字段;
4. 工程算例进入 0.9.x。
# 14. Backlog
以下事项不进入 0.2.x 硬验收:
1. 完整 edge fallback;
2. 四边形双线性投影;
3. 壳厚度高级几何;
4. contact persistence;
5. Coulomb 摩擦;
6. 自动 penalty 参数;
7. 接触稳定时间步;
8. 接触能量诊断;
9. tied/release;
10. pressure projection;
11. boundary/ghost particle;
12. Riemann FSI;
13. SoA v2;
14. Linux/MPI;
15. 工程简化算例。
# 15. 完成定义
CCLite 0.2.x 完成的定义:
1. CCLite 保持独立主控程序身份;
2. 0.1.x 通信和空耦合能力不退化;
3. CCLite `.inp` 可定义基础 penalty contact;
4. SPH particle view 和 FEM facet view 可参与接触计算;
5. 几何 primitive、宽相搜索和窄相检测通过单元测试;
6. 单粒子撞面能产生方向正确的接触力;
7. 多粒子压面能产生可复核的总力;
8. SPH/FEM 作用-反作用误差可控;
9. `CCL_TO_SPH_FORCE` 和 `CCL_TO_FEM_LOAD` 可写入非空载荷;
10. contact report 和 force balance 可由 checker 自动验收;
11. 至少一个真实 worker 集成路径完成或形成明确协议缺口;
12. 0.2.x 不宣称摩擦、tied/release、FSI 或工程级应用完成。
0.2.x 的成功标准是一条从界面数据、几何搜索、接触力计算、载荷写回到自动验收的最小物理闭环。该闭环稳定后,0.3.x 才适合继续处理壳、边缘、四边形和接触连续性。