Files
CCLite/todo.md
T
2026-07-05 16:49:28 +08:00

14 KiB
Raw Blame History

CCLite 0.1.x 待办事项

Coupling & Contact Lite for SPHLite and FEMLite

依据:docs/v1.x_development_plan.md 适用范围:CCLite 0.1.x 目标:完成主控、通信、worker、mock、空耦合、诊断和自动验收闭环。 不包含:真实 SPH-FEM 接触力、单粒子撞面物理验收、摩擦、FSI、Linux/MPI 生产实现、SoA v2。

1. 任务颗粒度约定

每个待办事项应满足:

  1. 可以由一个小 patch 独立完成;
  2. 有明确输入、输出或可观察行为;
  3. 有最小测试或检查方式;
  4. 不跨越多个架构层大改;
  5. 完成后能让项目更接近 V010_EMPTY_COUPLING。

状态标记:

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

2. 0.1.0 工程骨架

目标:建立可编译工程、程序入口和最小 smoke。

  • T0101 建立 src/、include/、tests/、cases/、Python/ 基础目录。 完成判据:目录结构与开发计划一致,空目录有占位说明或后续构建可识别。

  • T0102 建立 Windows/gfortran 构建入口。 完成判据:可构建至少一个 cclite 空程序目标。

  • T0103 增加 CCLite 版本模块。 完成判据:程序能输出 0.1.0 版本号和构建平台信息。

  • T0104 增加主程序 CLI 骨架。 完成判据:支持 --help、--version、check、dry-run、run 命令入口。

  • T0105 增加基础错误码模块。 完成判据:输入错误、IPC 错误、worker 错误、系统错误有独立范围。

  • T0106 增加基础日志模块。 完成判据:能写 run.log,包含时间、级别、模块名和消息。

  • T0107 建立空 mock worker 构建目标。 完成判据:mock_sph_worker 和 mock_fem_worker 可启动并输出自身身份。

  • T0108 增加工程 smoke 测试。 完成判据:测试能检查 cclite --version、cclite --help 和两个 mock worker 启动。

3. 0.1.1 .inp 与 Case Model

目标:支持 CCLite 主控输入和 check 模式。

  • T0111 定义 CCL_Case 数据结构。 完成判据:可保存 control、solver、ipc、time、interface、output 配置。

  • T0112 实现关键词行解析。 完成判据:支持 *CCLITE ... 关键词、大小写兼容、注释和空行。

  • T0113 实现参数键值解析。 完成判据:支持 KEY=VALUE、字符串路径、数值和布尔值。

  • T0114 解析 *CCLITE CONTROL 和运行模式。 完成判据:能识别 check、dry-run、run,非法模式报错。

  • T0115 解析 *CCLITE SOLVER。 完成判据:能保存 SPH/FEM solver id、kind、executable 和 input 文件。

  • T0116 解析 *CCLITE IPC。 完成判据:0.1.x 只接受 TYPE=WINDOWS_SHMEM,其他类型给出预留或不支持错误。

  • T0117 解析 *CCLITE TIME、*CCLITE INTERFACE 和 *CCLITE OUTPUT。 完成判据:能保存时间范围、dt、region/surface 映射和输出目录。

  • T0118 实现 case 校验。 完成判据:缺失 solver、缺失 IPC、非法时间步、缺失输出目录均能定位到关键词。

  • T0119 实现 cclite check。 完成判据:合法输入输出检查摘要,非法输入返回非零错误码。

  • T0120 增加 .inp parser 单元测试。 完成判据:覆盖合法输入、未知关键词、缺失字段、非法 IPC 和大小写兼容。

4. 0.1.2 IPC 基础

目标:完成 Windows shared memory 和 named event 最小可用层。

  • T0121 定义 C IPC 薄层头文件。 完成判据:声明 shared memory、event、error 和 handle 基础接口。

  • T0122 实现 shared memory create/open/map。 完成判据:可创建命名共享内存并取得 payload 指针。

  • T0123 实现 shared memory unmap/close。 完成判据:资源释放后同名测试可重复运行。

  • T0124 实现 named event create/open。 完成判据:可创建 Windows manual-reset named event。

  • T0125 实现 named event wait/signal/reset/close。 完成判据:wait 支持 timeout,signal/reset 行为可测试。

  • T0126 建立 Fortran2018 IPC wrapper。 完成判据:Fortran 侧可调用 C IPC 薄层并取得状态码。

  • T0127 建立 IPC 资源命名规则。 完成判据:同一 case 的 command block、data block 和 event 名称可稳定生成。

  • T0128 增加 IPC 错误映射。 完成判据:create/open/map/wait 失败能转换为 CCLite 错误码。

  • T0129 增加 IPC 接口测试。 完成判据:覆盖 shared memory 生命周期、event wait/signal/reset、timeout 和重复释放。

5. 0.1.3 Command Block 与 Worker 协议

目标:实现命令共享块、seq/ack 和 worker 状态机基础。

  • T0131 定义 command id 枚举。 完成判据:支持 INIT、READ_INPUT、BUILD_MODEL、EXPORT_INTERFACE、ADVANCE、WRITE_OUTPUT、STOP。

  • T0132 定义 worker state 枚举。 完成判据:支持 STARTING、READY、BUSY、DONE、ERROR、STOPPED。

  • T0133 定义 command block 逻辑类型。 完成判据:字段覆盖 05 号文档要求,substep_id 和 iteration_id 在 0.1.x 写 0。

  • T0134 实现 command block pack/unpack。 完成判据:二进制布局可稳定写入共享内存并读回。

  • T0135 实现 magic/version/layout 校验。 完成判据:非法 magic、ABI 或 layout id 能在初始化阶段拒绝。

  • T0136 实现 command seq/ack 配对。 完成判据:每条命令都有递增 seq,worker 回写对应 ack。

  • T0137 实现 heartbeat 更新。 完成判据:worker 空闲或执行命令时能更新 heartbeat_seq。

  • T0138 实现 command timeout 检测。 完成判据:worker 不响应时 CCLite 返回超时错误,不永久等待。

  • T0139 增加 command block 单元测试。 完成判据:覆盖字段读写、seq/ack、版本校验、非法状态和 timeout。

6. 0.1.4 Data Block 与 AoR v1

目标:实现 data block header、block role 和基础 AoR v1 payload。

  • T0141 定义 data block header。 完成判据:包含 magic、version、role、layout、record size、count、capacity、state 和 step id。

  • T0142 定义 block role 枚举。 完成判据:支持 SPH_TO_CCL_PARTICLE、FEM_TO_CCL_FACET、CCL_DIAGNOSTIC、CCL_COMMAND_SPH、CCL_COMMAND_FEM。

  • T0143 定义 buffer state。 完成判据:支持 empty、writing、ready、reading、error 状态转换。

  • T0144 实现 header pack/unpack。 完成判据:共享内存中 header 可由 CCLite 和 worker 双向读写。

  • T0145 实现 header 校验。 完成判据:非法 role、record size、count 超限和 payload bytes 超限可被拒绝。

  • T0146 定义 SPH particle AoR v1 record。 完成判据:字段覆盖 id、index、position、velocity、mass、density、h、radius、pressure、sound speed 和 flags。

  • T0147 定义 FEM facet AoR v1 record。 完成判据:字段覆盖 facet id、surface id、node ids、coords、velocity、normal、area、thickness、mass per area 和 flags。

  • T0148 定义空载荷 record 预留。 完成判据:0.1.x 可创建 CCL_TO_SPH_FORCE 和 CCL_TO_FEM_LOAD 空 block。

  • T0149 增加 data block 单元测试。 完成判据:覆盖空 payload、固定 record、最大 capacity、bad header 和 bad count。

7. 0.1.5 Controller 空耦合

目标:跑通 CCLite + 双 mock worker 的三进程空耦合。

  • T0151 实现 worker 进程描述结构。 完成判据:可保存 executable、input、solver id、ipc 名称、状态和进程句柄。

  • T0152 实现 worker 启动器。 完成判据:CCLite 可启动 mock SPH/FEM worker,并记录启动命令。

  • T0153 实现 worker 停止和退出监控。 完成判据:正常 STOP 和异常退出都能被 CCLite 识别。

  • T0154 实现 mock worker IPC attach。 完成判据:mock worker 可打开 command block、data block 和 named event。

  • T0155 实现 mock worker 命令循环。 完成判据:mock worker 可响应 0.1.x 必需命令并回写 ack。

  • T0156 实现 mock SPH 固定粒子导出。 完成判据:可按配置导出 0 个或少量固定 SPH record。

  • T0157 实现 mock FEM 固定 facet 导出。 完成判据:可按配置导出 0 个或少量固定 FEM facet record。

  • T0158 实现 CCLite dry-run step loop。 完成判据:CCLite 可执行 export、读 header、写空载荷、advance、diagnostics。

  • T0159 实现 1 step 空耦合集成测试。 完成判据:双 mock worker 完成 1 step 并正常退出。

  • T0160 实现 100 step 空耦合集成测试。 完成判据:双 mock worker 完成 100 step,无 timeout,无残留进程。

8. 0.1.6 诊断与 Python Checker

目标:形成可自动判定的 V010_EMPTY_COUPLING 验证闭环。

  • T0161 实现 run.log 标准输出。 完成判据:记录版本、输入、worker 命令、IPC 名称、错误码和资源释放。

  • T0162 实现 ipc_report.csv。 完成判据:每步输出 solver id、command id、seq、ack、worker state、heartbeat、elapsed 和 error。

  • T0163 实现 force_balance.csv。 完成判据:0.1.x 空耦合每步输出 SPH/FEM 总力为 0。

  • T0164 建立 Python/checkers/。 完成判据:目录中有 checker 入口和公共 CSV 读取工具。

  • T0165 定义 verification_report.json schema。 完成判据:包含 case id、status、metrics、failed checks、输入和输出文件。

  • T0166 实现 V010_EMPTY_COUPLING checker。 完成判据:检查 seq/ack、step id、timeout、worker state、空载荷和退出状态。

  • T0167 建立 cases/v0_1_ipc_empty_coupling/。 完成判据:包含 CCLite .inp、mock 输入说明和预期输出说明。

  • T0168 集成 checker 到本地测试命令。 完成判据:运行测试后自动生成 verification_report.json。

  • T0169 增加诊断回归测试。 完成判据:CSV 表头变化或关键字段缺失会导致测试失败。

9. 0.1.7 真实 Worker 最小接入

目标:在不破坏 SPHLite/FEMLite 独立运行的前提下,定义或实现最小 worker/service handshake。

  • T0171 确认 SPHLite worker 接入方式。 完成判据:明确是修改 SPHLite 入口、增加包装程序,还是暂以接入缺口记录。

  • T0172 确认 FEMLite worker 接入方式。 完成判据:明确是修改 FEMLite 入口、增加包装程序,还是暂以接入缺口记录。

  • T0173 固化 worker 启动参数。 完成判据:SPHLite/FEMLite 采用一致的 --cclite-worker 参数约定。

  • T0174 实现或记录 SPHLite handshake。 完成判据:SPHLite worker 能进入 READY,或形成明确缺口说明。

  • T0175 实现或记录 FEMLite handshake。 完成判据:FEMLite worker 能进入 READY,或形成明确缺口说明。

  • T0176 验证 SPHLite 空接口导出。 完成判据:真实或包装 worker 可导出空 particle block。

  • T0177 验证 FEMLite 空接口导出。 完成判据:真实或包装 worker 可导出空 facet block。

  • T0178 验证真实 worker 空载荷接收。 完成判据:worker 能接受空 force/load block,不报物理算法错误。

  • T0179 执行单真实 worker 集成 smoke。 完成判据:CCLite + 一个真实 worker + 一个 mock worker 可完成最小 dry-run,或输出受控缺口报告。

10. 0.1.8 发布候选

目标:冻结 0.1.x 通信闭环,准备进入 0.2.x 接触算法开发。

  • T0181 执行全量 0.1.x 单元测试。 完成判据:.inp、command block、data block、错误码和 CSV writer 测试通过。

  • T0182 执行全量 0.1.x 接口测试。 完成判据:shared memory、named event、timeout、bad header 和 bad layout 测试通过。

  • T0183 执行全量 0.1.x 集成测试。 完成判据:双 mock workers 1 step 和 100 step 空耦合通过。

  • T0184 执行 V010_EMPTY_COUPLING 验证算例。 完成判据:Python checker 生成通过报告。

  • T0185 执行干净环境重建。 完成判据:从干净目录构建、运行 smoke 和 V010 均通过。

  • T0186 检查 UTF-8 without BOM。 完成判据:新增文档和 .inp 样例均无 BOM。

  • T0187 检查文档一致性。 完成判据:README、03、05、06 和开发计划与实现字段、命令、输出一致。

  • T0188 冻结 0.1.x 接口常量。 完成判据:command id、worker state、block role、layout id、CSV 表头有记录。

  • T0189 整理 0.1.x release notes。 完成判据:列出已完成能力、未完成能力、真实 worker 接入状态和 0.2.x 入口条件。

11. 0.1.x 总体验收清单

  • A001 cclite.exe 可作为独立主控程序启动。
  • A002 mock_sph_worker 和 mock_fem_worker 可由 CCLite 启动。
  • A003 CCLite 可创建和释放 Windows shared memory。
  • A004 CCLite 可创建和释放 Windows manual-reset named event。
  • A005 Command block seq/ack 在 100 step 中全部匹配。
  • A006 Data block header 校验覆盖正常和异常路径。
  • A007 AoR v1 空 payload 和固定 payload 均可处理。
  • A008 cclite check 可检查合法和非法 .inp。
  • A009 cclite dry-run 可完成双 mock 空耦合。
  • A010 run.log、ipc_report.csv、force_balance.csv 均生成。
  • A011 Python checker 可生成 verification_report.json。
  • A012 V010_EMPTY_COUPLING 自动检查通过。
  • A013 Linux/MPI 配置只给出预留或不支持提示。
  • A014 0.1.x 不宣称真实 SPH-FEM 接触力已完成。
  • A015 0.2.x 可在该基础上进入基础 penalty contact 开发。

12. 暂不进入 0.1.x 的事项

以下事项进入 backlog,不作为 0.1.x 待办:

  • B001 单粒子撞刚性面物理验收。
  • B002 点到三角形和点到四边形几何验证。
  • B003 基础 penalty contact 力计算。
  • B004 壳厚度、边缘 fallback 和接触 persistence。
  • B005 Coulomb 摩擦和接触能量耗散。
  • B006 tied coupling 和 release。
  • B007 pressure projection 和 boundary/ghost particle。
  • B008 Riemann FSI。
  • B009 SoA v2 性能优化。
  • B010 Linux/MPI 生产后端。