343 lines
14 KiB
Markdown
343 lines
14 KiB
Markdown
# 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`。
|
||
|
||
状态标记:
|
||
|
||
```text
|
||
[ ] 未开始
|
||
[~] 进行中
|
||
[x] 已完成
|
||
[!] 阻塞
|
||
```
|
||
|
||
# 2. 0.1.0 工程骨架
|
||
|
||
目标:建立可编译工程、程序入口和最小 smoke。
|
||
|
||
- [x] T0101 建立 `src/`、`include/`、`tests/`、`cases/`、`Python/` 基础目录。
|
||
完成判据:目录结构与开发计划一致,空目录有占位说明或后续构建可识别。
|
||
|
||
- [x] T0102 建立 Windows/gfortran 构建入口。
|
||
完成判据:可构建至少一个 `cclite` 空程序目标。
|
||
|
||
- [x] T0103 增加 CCLite 版本模块。
|
||
完成判据:程序能输出 `0.1.0` 版本号和构建平台信息。
|
||
|
||
- [x] T0104 增加主程序 CLI 骨架。
|
||
完成判据:支持 `--help`、`--version`、`check`、`dry-run`、`run` 命令入口。
|
||
|
||
- [x] T0105 增加基础错误码模块。
|
||
完成判据:输入错误、IPC 错误、worker 错误、系统错误有独立范围。
|
||
|
||
- [x] T0106 增加基础日志模块。
|
||
完成判据:能写 `run.log`,包含时间、级别、模块名和消息。
|
||
|
||
- [x] T0107 建立空 mock worker 构建目标。
|
||
完成判据:`mock_sph_worker` 和 `mock_fem_worker` 可启动并输出自身身份。
|
||
|
||
- [x] 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 生产后端。
|