Files
CCLite/todo.md
T
2026-07-06 09:12:22 +08:00

498 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 接入路径,或形成清晰的受控协议缺口。
- [ ] 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` 可写入非空载荷。
- [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` 通过。
- [ ] 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 工程级水下爆炸或船体局部破坏算例。