Files
CCLite/todo.md
T
2026-07-05 23:58:34 +08:00

22 KiB
Raw Blame History

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. 任务颗粒度约定

每个待办事项应满足:

  1. 可以由一个小 patch 独立完成;
  2. 有明确输入、输出或可观察行为;
  3. 有最小测试、检查命令或诊断文件作为完成判据;
  4. 不同时跨越 parser、IPC、算法、诊断和真实 worker 多个大层;
  5. 完成后能让项目更接近 0.2.x 接触力闭环。

状态标记:

[ ] 未开始
[~] 进行中
[x] 已完成
[!] 阻塞

执行约定:

  1. 非必须不要跳过待办事项;
  2. 每完成一个 0.2.x patch 小版本,应提交一次 git;
  3. 若发现现有设计与 01~06 号文档冲突,先更新对应文档或形成缺口记录;
  4. 真实 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 工程级水下爆炸或船体局部破坏算例。