14 KiB
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. 任务颗粒度约定
每个待办事项应满足:
- 可以由一个小 patch 独立完成;
- 有明确输入、输出或可观察行为;
- 有最小测试或检查方式;
- 不跨越多个架构层大改;
- 完成后能让项目更接近
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 增加
.inpparser 单元测试。 完成判据:覆盖合法输入、未知关键词、缺失字段、非法 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.jsonschema。 完成判据:包含 case id、status、metrics、failed checks、输入和输出文件。 -
T0166 实现
V010_EMPTY_COUPLINGchecker。 完成判据:检查 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 生产后端。