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