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

24 KiB
Raw Blame History

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 状态:

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 源码交付物

建议新增或补强以下目录:

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。

必须支持:

*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 至少包含:

external_id
internal_index
status
contact_radius
x[3]
v[3]
mass
valid_flags

FEM facet view 至少包含:

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 力模型:

f_i = (k_n d + c_n max(0, -v_n)) n

FEM 节点力:

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 流程:

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:诊断输出

目标:

形成可自动检查的接触诊断。

建议输出:

contact_report.csv
candidate_report.csv
force_balance.csv
ipc_report.csv
run.log
verification_report.json

contact_report.csv 建议字段:

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 增加:

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 输入样例

** 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 才适合继续处理壳、边缘、四边形和接触连续性。