Files
CCLite/docs/v2.x_development_plan.md
T
2026-07-05 23:40:12 +08:00

875 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 才适合继续处理壳、边缘、四边形和接触连续性。