Start CCLite 0.2.0 development baseline
This commit is contained in:
@@ -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 才适合继续处理壳、边缘、四边形和接触连续性。
|
||||
Reference in New Issue
Block a user