22 KiB
CCLite 0.2.x 待办事项
Coupling & Contact Lite for SPHLite and FEMLite
依据:docs/v2.x_development_plan.md
适用范围:CCLite 0.2.x
实现基线:CCLite 0.1.10
核心目标:完成基础 SPH 粒子-FEM facet penalty contact 的最小物理闭环。
第一阶段平台:Windows / gfortran / 本机共享内存。
不包含:Coulomb 摩擦、tied/release、FSI、SoA v2、Linux/MPI 生产后端、工程级应用算例。
1. 任务颗粒度约定
每个待办事项应满足:
- 可以由一个小 patch 独立完成;
- 有明确输入、输出或可观察行为;
- 有最小测试、检查命令或诊断文件作为完成判据;
- 不同时跨越 parser、IPC、算法、诊断和真实 worker 多个大层;
- 完成后能让项目更接近 0.2.x 接触力闭环。
状态标记:
[ ] 未开始
[~] 进行中
[x] 已完成
[!] 阻塞
执行约定:
- 非必须不要跳过待办事项;
- 每完成一个 0.2.x patch 小版本,应提交一次 git;
- 若发现现有设计与 01~06 号文档冲突,先更新对应文档或形成缺口记录;
- 真实 worker gate 不阻塞 mock worker 上的 A 层算法验收,但不得被误写为真实物理联调完成。
2. 0.2.0 入口和协议前置
目标:从 0.1.10 稳定基线进入 0.2.x,并把真实 worker 协议风险显式放到 gate 中。
-
T0200-01 建立
docs/v2.x_development_plan.md。 完成判据:文档定义 0.2.x 目标、版本节奏、工作包、验证算例和验收清单。 -
T0200-02 用 0.2.x 计划替换
todo.md。 完成判据:待办事项按 0.2.0 到 0.2.10 分组,任务颗粒度均匀。 -
T0200-03 将程序开发版本入口切到
0.2.0-dev。 完成判据:cclite --version或等价版本输出能区分 0.1.x 发布版与 0.2.x 开发版。 -
T0200-04 建立 0.2.x case 目录骨架。 完成判据:新增
cases/v0_2_contact/或等价目录,包含 README 和待填充样例说明。 -
T0200-05 建立 0.2.x 测试命名约定。 完成判据:测试名、算例名和输出目录统一使用
V020_*前缀。 -
T0200-06 复跑 0.1.x 全量回归。 完成判据:现有 0.1.x 单元、接口和空耦合集成测试全部通过。
-
T0200-07 梳理 SPHLite/FEMLite 当前 worker 启动参数。 完成判据:记录真实 worker 的可执行文件、参数、命名规则和已支持命令。
-
T0200-08 梳理 SPHLite/FEMLite 当前 IPC block 能力。 完成判据:确认真实 worker 与 CCLite 通用 block 在 header、role、layout 和 record stride 上的差异。
-
T0200-09 定义 0.2.x 真实 worker adapter gate。 完成判据:明确 gate 输入、输出、通过条件和
CONTROLLED_PROTOCOL_GAP条件。 -
T0200-10 更新真实 worker 审计记录。 完成判据:
docs/07_real_worker_access_audit.md反映 0.2.x 入口状态。
3. 0.2.1 接触输入与 Case Model
目标:支持 0.2.x 基础接触输入关键词,并把 interaction 与 contact pair 保存到内部模型。
-
T0201-01 扩展 case model 保存 surface interaction。 完成判据:内部结构可保存
name、normal_model、kn、cn和friction。 -
T0201-02 扩展 case model 保存 contact pair。 完成判据:内部结构可保存
name、interface、interaction和type。 -
T0201-03 解析
*CCLITE SURFACE INTERACTION关键词行。 完成判据:可读取NAME=...,缺少名称时给出带行号错误。 -
T0201-04 解析 surface interaction 数据行。 完成判据:可读取
NORMAL=PENALTY、KN=...、CN=...和FRICTION=...。 -
T0201-05 解析
*CCLITE CONTACT PAIR关键词行。 完成判据:可读取NAME=...,重复名称能报错。 -
T0201-06 解析 contact pair 数据行。 完成判据:可读取
INTERFACE=...、INTERACTION=...和TYPE=SPH_PARTICLE_TO_FEM_FACE。 -
T0201-07 校验 interaction 参数合法性。 完成判据:缺少
KN、非法NORMAL、负刚度或非有限数值均返回输入错误。 -
T0201-08 校验 contact pair 引用合法性。 完成判据:未知 interface、未知 interaction 和非法 type 均返回输入错误。
-
T0201-09 处理 0.2.x 未启用摩擦字段。 完成判据:
FRICTION非 0 时给出错误或 warning,并且不启用摩擦计算。 -
T0201-10 增加 contact 输入检查摘要。 完成判据:
cclite check输出 interaction 数量、pair 数量和未启用能力提示。 -
T0201-11 增加合法 contact
.inp样例。 完成判据:样例可通过cclite check,并包含 surface interaction 与 contact pair。 -
T0201-12 增加 contact parser 单元测试。 完成判据:覆盖合法输入、缺少
KN、非法NORMAL、未知引用和摩擦未启用路径。
4. 0.2.2 接口 View 与 Load Buffer
目标:把 AoR v1 payload 转成接触算法只读 view,并支持非空力和载荷写回。
-
T0202-01 定义 SPH particle view 类型。 完成判据:包含
external_id、internal_index、status、contact_radius、x、v、mass和valid_flags。 -
T0202-02 定义 FEM facet view 类型。 完成判据:包含
facet_id、node_count、node_ids、area、thickness、normal、x、v和valid_flags。 -
T0202-03 实现 SPH AoR record 到 particle view 的转换。 完成判据:可从
SPH_TO_CCL_PARTICLE读取固定粒子并生成有效 view。 -
T0202-04 实现 FEM AoR record 到 facet view 的转换。 完成判据:可从
FEM_TO_CCL_FACET读取固定 facet 并生成有效 view。 -
T0202-05 增加 view 输入有限性检查。 完成判据:坐标、速度、半径、面积和法向中非有限值会被拒绝或标记无效。
-
T0202-06 增加 view 容量和 stride 检查。 完成判据:record size、count、capacity 与 payload bytes 不一致时返回明确错误。
-
T0202-07 定义 SPH force accumulator。 完成判据:同一 SPH 粒子的多条接触力可累加到一条写回记录。
-
T0202-08 定义 FEM nodal load accumulator。 完成判据:同一 FEM 节点的多条接触反力可累加到一条写回记录。
-
T0202-09 实现
CCL_TO_SPH_FORCE非空写回。 完成判据:mock SPH worker 可读取非空 force block,step id 与命令 step 匹配。 -
T0202-10 实现
CCL_TO_FEM_LOAD非空写回。 完成判据:mock FEM worker 可读取非空 load block,step id 与命令 step 匹配。 -
T0202-11 输出 interface 导入导出计数。 完成判据:
run.log或诊断 CSV 包含粒子、facet、force record 和 load record 数量。 -
T0202-12 增加 view/load buffer 单元测试。 完成判据:覆盖空 block、固定 payload、非有限输入、重复累加和 step id 校验。
5. 0.2.3 几何 Primitive
目标:实现 0.2.x 接触检测需要的基础几何函数。
-
T0203-01 建立 geometry 模块边界。 完成判据:Vec3、AABB 和最近点函数有独立模块或清晰命名空间。
-
T0203-02 实现 Vec3 基础运算。 完成判据:支持 dot、cross、norm、scale、add、sub 和 normalize。
-
T0203-03 实现 AABB 初始化与扩展。 完成判据:空 AABB、点扩展和半径扩展行为可测试。
-
T0203-04 实现 AABB 重叠测试。 完成判据:相离、相切、包含和部分重叠四类情况结果正确。
-
T0203-05 实现 SPH particle AABB。 完成判据:粒子位置和
contact_radius可生成包围盒。 -
T0203-06 实现 FEM facet AABB。 完成判据:三角形或四边形节点坐标可生成包围盒,并包含厚度或容差扩展。
-
T0203-07 实现 point-segment closest point。 完成判据:线段内部、端点外侧和退化线段路径均有确定输出。
-
T0203-08 实现 point-triangle closest point。 完成判据:面内、边区、顶点区和退化三角形路径均有测试。
-
T0203-09 实现 barycentric/shape weight。 完成判据:三角形权重和为 1,面内权重非负,退化输入返回错误。
-
T0203-10 实现 point-quad split 最小路径。 完成判据:平面四边形按两个三角形处理,并记录拆分选择。
-
T0203-11 增加退化几何诊断计数。 完成判据:退化边、退化三角形和非法法向不会产生非有限结果。
-
T0203-12 增加
V020_GEOMETRY_PRIMITIVES单元测试。 完成判据:最近点误差、权重和、退化处理和非有限保护全部通过。
6. 0.2.4 宽相搜索
目标:实现 uniform hash grid,从 particle/facet view 生成候选接触对。
-
T0204-01 定义 hash grid 数据结构。 完成判据:可保存 cell size、cell key、facet 列表和容量信息。
-
T0204-02 定义 grid cell size 选择规则。 完成判据:默认 cell size 与最大接触半径或用户配置有明确关系。
-
T0204-03 实现 facet AABB 插入 grid。 完成判据:跨多个 cell 的 facet 能被插入所有覆盖 cell。
-
T0204-04 实现 particle AABB 查询 grid。 完成判据:粒子可查询相邻 cell 并返回候选 facet id。
-
T0204-05 实现 candidate pair 去重。 完成判据:同一粒子和 facet 组合不会重复进入窄相。
-
T0204-06 实现 candidate 容量保护。 完成判据:候选数超限时返回明确错误码,并写入诊断。
-
T0204-07 输出宽相统计。 完成判据:每步记录 grid cell 数、facet 插入数、candidate 数和去重数。
-
T0204-08 增加单 facet 单粒子搜索测试。 完成判据:近距离粒子生成候选,远距离粒子不生成候选。
-
T0204-09 增加跨 cell 边界搜索测试。 完成判据:粒子位于 cell 边界时不漏检。
-
T0204-10 增加 candidate overflow 测试。 完成判据:构造超限候选时程序给出可诊断失败,而不是越界或静默截断。
7. 0.2.5 窄相 Contact Pair
目标:从 candidate pair 生成真实接触对,输出 gap、penetration、normal 和 shape weight。
-
T0205-01 定义 contact pair record。 完成判据:包含 step、pair id、SPH id、facet id、gap、penetration、normal 和 shape weight。
-
T0205-02 实现 candidate 窄相循环。 完成判据:每个宽相候选最多生成一条窄相 contact record。
-
T0205-03 计算 facet 最近点。 完成判据:三角形 facet 使用 point-triangle,四边形 facet 使用 split triangle。
-
T0205-04 计算局部接触法向。 完成判据:法向方向与 04 号文档约定一致,并可在诊断中复核。
-
T0205-05 计算法向间隙
g。 完成判据:粒子中心到 facet 最近点的符号距离可复现。 -
T0205-06 计算有效接触距离。 完成判据:SPH
contact_radius与 facet 厚度或容差的组合规则明确。 -
T0205-07 计算穿透量
penetration。 完成判据:满足penetration = contact_distance - g,非穿透时不生成接触力。 -
T0205-08 保存 FEM 节点 shape weight。 完成判据:后续节点力分配可直接使用 contact record 中的权重。
-
T0205-09 记录窄相跳过原因。 完成判据:远离、退化、非法法向和非有限输入有独立计数。
-
T0205-10 输出基础
contact_report.csv。 完成判据:包含 step、pair、粒子、facet、gap、penetration、normal 和 node_count 字段。 -
T0205-11 增加窄相 contact 单元测试。 完成判据:覆盖无接触、穿透接触、法向方向、shape weight 和退化 facet。
8. 0.2.6 Penalty Force 与节点分配
目标:实现法向 penalty damping 力,并写回 SPH force 与 FEM nodal load。
-
T0206-01 从 interaction 中读取
KN和CN。 完成判据:每个 contact pair 使用其引用 interaction 的刚度和阻尼。 -
T0206-02 计算 FEM 最近点速度。 完成判据:使用 contact shape weight 从 FEM 节点速度插值得到最近点速度。
-
T0206-03 计算法向相对速度。 完成判据:
v_n的符号与阻尼公式约定一致,并有单元测试。 -
T0206-04 实现法向 penalty 力。 完成判据:
CN=0时力大小等于KN * penetration。 -
T0206-05 实现基础法向阻尼力。 完成判据:闭合速度产生非负阻尼项,分离速度不增加吸引力。
-
T0206-06 合成 SPH 粒子接触力。 完成判据:同一粒子多接触力累加后写入 force accumulator。
-
T0206-07 分配 FEM 节点反力。 完成判据:节点力合力等于
-SPH_contact_force,权重来自 shape weight。 -
T0206-08 增加非有限力保护。 完成判据:非有限 penetration、速度或力会终止当前 step 并输出错误。
-
T0206-09 写回 SPH force block。 完成判据:
CCL_TO_SPH_FORCE中包含非空力记录,并可被 mock worker 消费。 -
T0206-10 写回 FEM load block。 完成判据:
CCL_TO_FEM_LOAD中包含非空节点力记录,并可被 mock worker 消费。 -
T0206-11 输出力和力矩平衡诊断。 完成判据:每步记录 SPH 总力、FEM 总力、合力误差和力矩误差。
-
T0206-12 增加 penalty force 单元测试。 完成判据:覆盖零穿透、单点穿透、阻尼、节点分配和非有限保护。
9. 0.2.7 Controller 接触流程与诊断
目标:把接触算法插入 0.1.x step loop,并形成可自动检查的诊断输出。
-
T0207-01 区分 dry-run 与 contact run。 完成判据:无 contact pair 时可保持 dry-run,定义 contact pair 时进入接触路径。
-
T0207-02 在 step loop 中读取 SPH/FEM interface block。 完成判据:每步接触计算前 view 来自当前 step 的 worker 导出数据。
-
T0207-03 在 step loop 中调用宽相搜索。 完成判据:每步生成 candidate 数并写入诊断。
-
T0207-04 在 step loop 中调用窄相接触。 完成判据:每步生成 contact 数、最大穿透和跳过计数。
-
T0207-05 在 step loop 中调用 penalty force。 完成判据:接触力写入 accumulator,非接触 step 输出零载荷。
-
T0207-06 在写回载荷后发送
IMPORT_LOADS。 完成判据:SPH/FEM worker 均能确认载荷导入命令。 -
T0207-07 在
ADVANCE前后保持 seq/ack 正确。 完成判据:0.1.x IPC 报告中的 command seq/ack 不退化。 -
T0207-08 每步清零接触和载荷 accumulator。 完成判据:连续 step 不会继承上一 step 的 contact、force 或 load。
-
T0207-09 异常时停止两个 worker 并释放资源。 完成判据:接触算法错误、输入错误或 worker 超时后无残留进程和未释放 IPC。
-
T0207-10 增强
contact_report.csv。 完成判据:包含 gap、penetration、normal、force 和 node_count 字段。 -
T0207-11 增强
force_balance.csv。 完成判据:增加接触数、最大穿透、总接触力、力矩误差和非有限计数。 -
T0207-12 增强
run.log接触诊断。 完成判据:输入、view、搜索、接触、力计算和写回错误均可定位。
10. 0.2.8 验证算例与 Python Checker
目标:形成 0.2.x 自动验收闭环,支持几何、接触方向、力平衡和回归检查。
-
T0208-01 建立 0.2.x checker 公共 CSV 读取工具。 完成判据:checker 可读取 contact、candidate、force balance 和 IPC 报告。
-
T0208-02 实现
check_v020_geometry_primitives.py。 完成判据:可校验几何测试输出、容差、退化输入和非有限计数。 -
T0208-03 实现
check_v020_contact.py。 完成判据:可校验接触数、方向、penetration、力大小和力平衡。 -
T0208-04 生成或整理
V020_GEOMETRY_PRIMITIVES算例。 完成判据:算例可自动运行并由 checker 判定通过。 -
T0208-05 生成或整理
V020_SINGLE_PARTICLE_WALL算例。 完成判据:单粒子穿透平面时产生一条方向正确的接触力。 -
T0208-06 生成或整理
V020_MULTI_PARTICLE_PLANE算例。 完成判据:多粒子接触数量、最大穿透和总力可复核。 -
T0208-07 生成或整理
V020_FORCE_BALANCE算例。 完成判据:合力误差和力矩误差在容差内,非有限计数为 0。 -
T0208-08 输出
verification_report.json。 完成判据:报告包含 case id、status、metrics、failed checks 和关键输出文件路径。 -
T0208-09 将 0.2.x 算例接入本地回归测试。 完成判据:一条命令可运行 0.1.x 回归和 0.2.x 基础接触验证。
-
T0208-10 增加 CSV 表头回归检查。 完成判据:contact、candidate 和 force balance 表头变更会触发测试失败。
-
T0208-11 增加失败报告细节。 完成判据:checker 失败时输出 step、pair、字段名、期望值和实际值。
11. 0.2.9 单真实 Worker Gate
目标:至少推进一条真实 worker 接入路径,或形成清晰的受控协议缺口。
-
T0209-01 确认 CCLite adapter 策略。 完成判据:明确采用通用 block、求解器专用 adapter,还是二者混合过渡。
-
T0209-02 实现或配置 SPHLite worker adapter。 完成判据:CCLite 可按统一入口启动 SPHLite worker,或记录阻塞字段。
-
T0209-03 实现或配置 FEMLite worker adapter。 完成判据:CCLite 可按统一入口启动 FEMLite worker,或记录阻塞字段。
-
T0209-04 验证单真实 SPHLite worker 1 step 空耦合。 完成判据:真实 SPHLite + mock FEM 可完成 1 step,或输出
CONTROLLED_PROTOCOL_GAP。 -
T0209-05 验证单真实 FEMLite worker 1 step 空耦合。 完成判据:mock SPH + 真实 FEMLite 可完成 1 step,或输出
CONTROLLED_PROTOCOL_GAP。 -
T0209-06 验证单真实 worker 100 step 空耦合。 完成判据:至少一侧真实 worker 在 100 step 内无 seq/ack、timeout 或资源释放错误。
-
T0209-07 验证真实 worker payload 读取 smoke。 完成判据:真实 worker 导出的空或非空 interface block 通过 CCLite header 和 payload 校验。
-
T0209-08 验证真实 worker load import smoke。 完成判据:真实 worker 能接收空或可控 load block,并响应
IMPORT_LOADS。 -
T0209-09 记录 worker 能力查询结果。 完成判据:验证报告包含 worker 名称、版本、IPC 能力、block 能力和缺口状态。
-
T0209-10 更新真实 worker 审计文档。 完成判据:
docs/07_real_worker_access_audit.md与实际 gate 结果一致。
12. 0.2.10 发布候选
目标:收束 0.2.x,确认基础接触力闭环、回归、文档和发布说明一致。
-
T0210-01 执行 0.1.x 全量回归。 完成判据:0.1.x 空耦合、IPC、parser 和诊断测试不退化。
-
T0210-02 执行 0.2.x 单元测试。 完成判据:contact parser、geometry、search、narrow phase、penalty force 和 load buffer 测试全部通过。
-
T0210-03 执行 0.2.x 集成测试。 完成判据:双 mock workers 的单粒子撞面、多粒子压面和 force balance 算例通过。
-
T0210-04 执行真实 worker gate 测试。 完成判据:至少一条单真实 worker 路径通过,或受控协议缺口报告完整。
-
T0210-05 执行 UTF-8 without BOM 检查。 完成判据:新增文档、
.inp样例和 Python 文本文件均无 BOM。 -
T0210-06 检查文档与接口一致性。 完成判据:03、04、05、06、07 号文档与实现字段、命令、输出和限制一致。
-
T0210-07 整理
docs/0.2.x_release_notes.md。 完成判据:列出完成能力、未完成能力、真实 worker gate 状态和后续 0.3.x 入口条件。 -
T0210-08 更新 README 的 0.2.x 状态。 完成判据:README 准确描述基础 penalty contact、平台边界和未启用能力。
-
T0210-09 将版本输出切到发布候选号。 完成判据:
cclite --version输出0.2.10或约定的 0.2.x 发布候选号。 -
T0210-10 执行干净环境重建。 完成判据:从干净构建目录可完成构建、smoke、0.1.x 回归和 0.2.x 验证。
-
T0210-11 检查 0.2.x 不越界声明。 完成判据:文档和日志不宣称摩擦、tied/release、FSI、SoA v2、Linux/MPI 或工程级应用已完成。
-
T0210-12 完成 0.2.x 发布提交。 完成判据:所有 0.2.x 变更已提交,工作区无非预期未跟踪文件。
13. 0.2.x 总体验收清单
- A0201 CCLite 保持独立主控程序身份。
- A0202 0.1.x 通信和空耦合能力不退化。
- A0203
.inp可定义基础NORMAL=PENALTY接触。 - A0204
CONTACT PAIR可绑定 interface 与 interaction。 - A0205 SPH particle view 可从 AoR v1 payload 构建。
- A0206 FEM facet view 可从 AoR v1 payload 构建。
- A0207 Vec3、AABB、point-segment 和 point-triangle 通过测试。
- A0208 uniform hash grid 可生成去重候选对。
- A0209 窄相可生成 gap、penetration、normal 和 shape weight。
- A0210 法向 penalty force 方向和大小可由手算算例验证。
- A0211 FEM 节点力分配满足作用-反作用平衡。
- A0212
CCL_TO_SPH_FORCE可写入非空载荷。 - A0213
CCL_TO_FEM_LOAD可写入非空载荷。 - A0214
contact_report.csv可被 checker 自动检查。 - A0215
force_balance.csv包含接触力和力矩诊断。 - A0216
V020_GEOMETRY_PRIMITIVES通过。 - A0217
V020_SINGLE_PARTICLE_WALL通过。 - A0218
V020_MULTI_PARTICLE_PLANE通过。 - A0219
V020_FORCE_BALANCE通过。 - A0220 单真实 worker gate 通过或形成受控协议缺口。
- A0221 所有新增文档和样例为 UTF-8 without BOM。
- A0222 0.2.x 不声明超出版本边界的能力。
14. 暂不进入 0.2.x 的事项
以下事项进入后续版本 backlog,不作为 0.2.x 待办:
- B0201 完整 edge fallback。
- B0202 四边形双线性投影。
- B0203 壳厚度高级几何。
- B0204 contact persistence。
- B0205 Coulomb 摩擦。
- B0206 自动 penalty 参数估计。
- B0207 接触稳定时间步。
- B0208 接触能量诊断。
- B0209 tied coupling 和 release。
- B0210 pressure projection。
- B0211 boundary/ghost particle。
- B0212 Riemann FSI。
- B0213 SoA v2 性能布局。
- B0214 Linux/MPI 生产后端。
- B0215 工程级水下爆炸或船体局部破坏算例。