Files
CCLite/docs/v1.x_development_plan.md
2026-07-05 16:34:52 +08:00

840 lines
23 KiB
Markdown
Raw Permalink 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.1.x 开发计划
## Coupling & Contact Lite for SPHLite and FEMLite
**文件名**:`v1.x_development_plan.md`
**适用版本**:CCLite 0.1.x
**文档依据**:`01_requirements.md` 到 `06_test_and_verification_plan.md`
**实现基线**:Fortran95 算法核心 + Fortran2018 IPC 包装 + C/C++ Windows IPC 薄层
**第一阶段平台**:Windows / gfortran / 本机共享内存
**输入格式**:Abaqus 风格 `.inp`
**编码要求**:中文,UTF-8 without BOM
# 1. 文档目的
本文档定义 CCLite 0.1.x 的开发目标、工作分解、版本节奏、交付物、测试验收和风险控制。
0.1.x 的核心目标不是完成真实 SPH-FEM 接触算法,而是建立可靠的工程骨架:
1. CCLite 独立主控程序;
2. SPHLite 和 FEMLite 的 CCLite worker/service 运行模式;
3. Windows/gfortran/本机共享内存通信闭环;
4. named event + command shared block 控制同步;
5. AoR v1 data block 基础布局;
6. `.inp` 主控输入;
7. mock worker 空耦合测试;
8. CSV 诊断和 Python checker;
9. 可复现的 0.1.x 验收流程。
0.1.x 完成后,应能证明 CCLite 的三进程主控、IPC、worker 调度、数据块版本化和测试体系已经可用,为 0.2.x 的基础 penalty contact 接触算法开发提供稳定地基。
# 2. 版本边界
## 2.1 0.1.x 必须完成
0.1.x 必须完成以下能力:
1. `cclite.exe` 可作为独立主控程序启动;
2. 支持 `check`、`dry-run` 和最小 `run` 模式;
3. 支持 CCLite `.inp` 关键词子集;
4. 可创建和销毁 Windows shared memory;
5. 可创建和销毁 Windows manual-reset named event;
6. 可读写 command shared block;
7. 可读写 data block header;
8. 支持 AoR v1 基础 payload 布局;
9. 支持 `mock_sph_worker` 和 `mock_fem_worker`;
10. 支持 SPHLite/FEMLite worker/service 最小命令序列;
11. 可执行空耦合多步同步推进;
12. 输出 `run.log`、`ipc_report.csv`、`force_balance.csv` 和验证报告;
13. 通过 `V010_EMPTY_COUPLING` 验证算例;
14. Linux/MPI 只保留配置、枚举和错误提示。
## 2.2 0.1.x 不完成
0.1.x 不完成以下能力:
1. 真实 SPH-FEM 接触力计算;
2. 单粒子撞刚性面物理验收;
3. 多粒子接触;
4. 壳厚度、边缘 fallback、四边形高级接触验收;
5. 摩擦、tied/release、FSI、Riemann FSI;
6. 异步子循环;
7. SoA v2 data block;
8. Linux/MPI 生产实现;
9. 工程算例验收;
10. 性能优化硬指标。
0.1.x 可以保留接触、FSI、SoA v2、Linux/MPI 的接口枚举和预留字段,但不得把这些预留项写成已经可用的交付能力。
## 2.3 0.1.x 与 0.2.x 的分界
0.1.x 结束标准是通信和空耦合闭环通过。
0.2.x 开始标准是 0.1.x 的 IPC、worker、payload、诊断和 mock 测试均稳定,随后才进入基础 penalty contact:
1. `V020_GEOMETRY_PRIMITIVES`;
2. `V020_SINGLE_PARTICLE_WALL`;
3. `V020_MULTI_PARTICLE_PLANE`。
# 3. 总体开发策略
0.1.x 采用“先 mock,后真实;先接口,后物理;先 check/dry-run,后 run”的策略。
开发顺序为:
1. 建立可编译工程骨架;
2. 建立 CCLite 主控入口和 `.inp` case model;
3. 建立 Windows IPC 薄层;
4. 建立 Fortran2018 IPC wrapper;
5. 建立 command block 和 data block header;
6. 建立 mock worker;
7. 建立 controller 状态机;
8. 跑通空耦合;
9. 增加 CSV 诊断;
10. 增加 Python checker;
11. 接入 SPHLite/FEMLite worker/service 最小模式;
12. 固化 0.1.x 验收测试。
每一步都应有可运行的小闭环,不等待所有模块完成后再集成。
# 4. 推荐 patch 版本节奏
0.1.x 内部 patch 版本可按以下节奏推进。实际开发时允许合并相邻 patch,但不得跳过验收目标。
| 版本 | 主题 | 主要交付 |
| --- | --- | --- |
| 0.1.0 | 工程骨架 | 目录结构、构建脚本、`cclite.exe` 空入口、版本输出 |
| 0.1.1 | `.inp` 与 case model | CCLite 关键词解析、check 模式、输入错误码 |
| 0.1.2 | IPC 基础 | Windows shared memory、named event、Fortran wrapper |
| 0.1.3 | command block 与 worker 协议 | command block、seq/ack、worker state、mock worker 启动 |
| 0.1.4 | data block 与 AoR v1 | data block header、block role、基础 payload、空载荷写回 |
| 0.1.5 | Controller 空耦合 | 三进程调度、100 step dry-run、正常退出和资源释放 |
| 0.1.6 | 诊断与 Python checker | CSV 输出、`V010_EMPTY_COUPLING` 自动检查 |
| 0.1.7 | 真实 worker 最小接入 | SPHLite/FEMLite worker/service handshake,真实 worker 可空耦合 |
| 0.1.8 | 0.1.x 发布候选 | 全量 0.1.x 回归、文档一致性、干净环境重建 |
若 SPHLite/FEMLite 当前包短期内不便修改,0.1.7 可先定义为 worker/service 接口样例和接入指南;但 0.1.x 发布候选前至少应有可执行的 mock worker 完整闭环。
# 5. 交付物
## 5.1 程序交付物
0.1.x 应交付以下可执行程序或构建目标:
1. `cclite.exe`;
2. `mock_sph_worker.exe`;
3. `mock_fem_worker.exe`;
4. SPHLite worker/service 最小入口,若 SPHLite 源码可修改;
5. FEMLite worker/service 最小入口,若 FEMLite 源码可修改。
## 5.2 源码交付物
0.1.x 源码至少包含:
1. App 层;
2. `.inp` parser;
3. case/config 数据结构;
4. controller 状态机;
5. process launcher;
6. Windows IPC C/C++ 薄层;
7. Fortran2018 IPC wrapper;
8. command block pack/unpack;
9. data block header pack/unpack;
10. AoR v1 payload 基础类型;
11. diagnostics writer;
12. mock worker;
13. Python checker。
## 5.3 文档交付物
0.1.x 结束时应更新:
1. `README.md`;
2. `docs/01_requirements.md`,如有需求变更;
3. `docs/02_architectural_design_specification.md`,如有架构变更;
4. `docs/03_detailed_design.md`,如有实现变更;
5. `docs/05_interface_control_document.md`,如有接口字段变更;
6. `docs/06_test_and_verification_plan.md`,如有测试变更;
7. 本开发计划。
04 号数学模型文档在 0.1.x 不应大改,因为 0.1.x 不实现真实接触算法;若发现后续算法边界影响接口,应记录到待讨论项。
## 5.4 测试交付物
0.1.x 测试交付物包括:
1. `.inp` parser 单元测试;
2. command block 单元测试;
3. data block header 单元测试;
4. named event 接口测试;
5. shared memory 接口测试;
6. worker 启动和退出测试;
7. mock workers 空耦合集成测试;
8. `V010_EMPTY_COUPLING` 验证算例;
9. Python checker;
10. 测试报告样例。
# 6. 推荐目录结构
0.1.x 可按以下目录组织。若现有仓库已有结构,应优先兼容现有结构。
```text
src/
app/
case/
controller/
ipc/
process/
interface_data/
diagnostics/
mock_workers/
include/
cclite_ipc.h
tests/
unit/
interface/
integration/
verification/
data/
baselines/
cases/
v0_1_ipc_empty_coupling/
Python/
checkers/
references/
casegen/
runners/
```
目录职责:
| 目录 | 0.1.x 职责 |
| --- | --- |
| `src/app/` | 主程序入口、命令行、版本输出 |
| `src/case/` | `.inp` 解析、case model、参数校验 |
| `src/controller/` | 主控状态机、step 调度、worker 命令 |
| `src/ipc/` | Windows IPC 薄层和 Fortran wrapper |
| `src/process/` | worker 启动、监控、停止 |
| `src/interface_data/` | block header、AoR v1 record、buffer view |
| `src/diagnostics/` | log 和 CSV 输出 |
| `src/mock_workers/` | mock SPH/FEM worker |
| `Python/checkers/` | CSV 与验证报告检查 |
| `cases/v0_1_ipc_empty_coupling/` | 0.1.x 验收算例 |
# 7. 工作包分解
## 7.1 WP01:工程骨架与构建
目标:
1. 建立 Windows/gfortran 可编译工程;
2. 形成 CCLite 主程序入口;
3. 形成 mock worker 构建目标;
4. 输出版本号、构建信息和平台信息。
任务:
1. 确定构建方式;
2. 建立源码目录;
3. 建立公共精度和错误码模块;
4. 建立 `cclite --version`;
5. 建立 `cclite --help`;
6. 建立最小日志输出;
7. 建立 CI 或本地测试脚本预留。
完成标准:
1. 干净仓库可构建;
2. `cclite --version` 输出版本;
3. mock worker 可构建或至少有独立入口;
4. 构建产物不依赖开发者个人绝对路径。
## 7.2 WP02:`.inp` 解析与 case model
目标:
支持 0.1.x 所需 CCLite `.inp` 关键词子集。
0.1.x 必须识别:
1. `*CCLITE CONTROL`;
2. `*CCLITE SOLVER`;
3. `*CCLITE IPC`;
4. `*CCLITE TIME`;
5. `*CCLITE INTERFACE`;
6. `*CCLITE OUTPUT`。
可识别但不启用真实物理计算:
1. `*CCLITE SURFACE INTERACTION`;
2. `*CCLITE CONTACT PAIR`。
任务:
1. 实现关键词行解析;
2. 实现参数键值解析;
3. 实现大小写兼容;
4. 实现注释和空行处理;
5. 实现路径参数解析;
6. 实现必需字段校验;
7. 实现 `IPC TYPE=WINDOWS_SHMEM` 限制;
8. 实现 Linux/MPI 配置项的明确拒绝或预留提示;
9. 实现 check 模式输出。
完成标准:
1. 合法 `.inp` 生成 case model;
2. 非法 `.inp` 给出行号、关键词和错误码;
3. `CONTACT=YES` 等真实接触能力在 0.1.x 中不误报为已支持;
4. check 模式不创建真实 IPC 资源。
## 7.3 WP03:Windows IPC 薄层
目标:
完成 Windows shared memory 和 named event 的最小可用封装。
任务:
1. 封装 shared memory create/open/map/unmap/close;
2. 封装 named event create/open/wait/signal/reset/close;
3. 支持 manual-reset named event;
4. 统一错误码;
5. 隐藏 Windows API 细节;
6. 提供 Fortran2018 `iso_c_binding` wrapper;
7. 提供资源释放函数;
8. 提供 timeout 支持。
完成标准:
1. Fortran 侧可创建和映射共享内存;
2. Fortran 侧可等待和触发 named event;
3. CCLite 负责 reset `COMMAND_EVENT` 和 `DONE_EVENT`;
4. worker 只 wait/signal,不 reset;
5. 资源释放后可重复运行测试。
## 7.4 WP04:Command Shared Block
目标:
实现 05 号接口文档定义的 command shared block。
0.1.x 需要支持字段:
1. `magic`;
2. `abi_version`;
3. `layout_id`;
4. `solver_id`;
5. `command_id`;
6. `command_seq`;
7. `ack_seq`;
8. `step_id`;
9. `substep_id`,0.1.x 写 0;
10. `iteration_id`,0.1.x 写 0;
11. `command_flags`;
12. `heartbeat_seq`;
13. `worker_state`;
14. `int_param[16]`;
15. `real_param[16]`;
16. `macro_dt`;
17. `error_code`。
任务:
1. 定义 command block 逻辑类型;
2. 定义二进制布局;
3. 实现 pack/unpack 或 `bind(C)` 镜像类型;
4. 实现 magic 和 version 检查;
5. 实现 seq/ack 配对;
6. 实现 worker state 转换;
7. 实现 timeout 错误处理;
8. 实现 command block 单元测试。
完成标准:
1. 字节数、字段顺序和对齐符合 05 号文档;
2. seq/ack 不错配;
3. worker state 非法转换被拒绝;
4. 不兼容 layout 在初始化阶段停止。
## 7.5 WP05:Data Block Header 与 AoR v1
目标:
实现基础 data block header 和 AoR v1 record 布局。
0.1.x 必须支持 block role:
1. `SPH_TO_CCL_PARTICLE`;
2. `FEM_TO_CCL_FACET`;
3. `CCL_DIAGNOSTIC`;
4. `CCL_COMMAND_SPH`;
5. `CCL_COMMAND_FEM`。
0.1.x 可创建但保持空内容:
1. `CCL_TO_SPH_FORCE`;
2. `CCL_TO_FEM_LOAD`;
3. `SPH_TO_CCL_FACET`。
任务:
1. 定义 data block header;
2. 定义 block role 枚举;
3. 定义 buffer state;
4. 定义 record size 和 capacity 检查;
5. 定义 AoR v1 粒子 record;
6. 定义 AoR v1 facet record;
7. 定义空载荷 record;
8. 实现 header 校验;
9. 实现空 payload 处理;
10. 实现最大 capacity 边界测试。
完成标准:
1. CCLite 可拒绝非法 header;
2. record count 不超过 capacity;
3. record size 与 layout id 匹配;
4. 空 payload 合法;
5. 0.1.x 空耦合不读取未初始化字段。
## 7.6 WP06:Mock Worker
目标:
提供稳定可控的 mock SPH worker 和 mock FEM worker,用于 0.1.x 的主要集成测试。
任务:
1. mock worker 支持 worker/service 启动参数;
2. 支持打开 CCLite 创建的 shared memory;
3. 支持打开 named event;
4. 支持命令:`INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`;
5. 支持 heartbeat;
6. 支持 ack;
7. 支持写入 0 个 record;
8. 支持写入少量固定 record;
9. 支持故障注入预留;
10. 支持正常退出和异常退出测试。
完成标准:
1. mock worker 可被 CCLite 启动;
2. mock worker 可进入 `READY`;
3. mock worker 可完成 100 step 空耦合;
4. mock worker 可响应 `STOP`;
5. worker 崩溃或超时时 CCLite 可给出错误码。
## 7.7 WP07:SPHLite/FEMLite Worker 最小接入
目标:
在不破坏 SPHLite/FEMLite 独立主控程序身份的前提下,增加 CCLite worker/service 模式的最小入口。
任务:
1. 定义 worker 启动参数;
2. 保持 SPHLite/FEMLite 原独立运行入口;
3. 增加 CCLite worker/service 分支;
4. worker 模式只通过 05 号外部接口和 CCLite 通信;
5. 0.1.x 支持最小命令序列;
6. 0.1.x 可导出空接口数据或少量固定接口数据;
7. 0.1.x 可接收空载荷;
8. 不要求真实求解推进结果参与物理验收。
完成标准:
1. SPHLite/FEMLite 仍可独立运行;
2. worker 模式可启动并进入 `READY`;
3. worker 模式可响应 `STOP`;
4. worker 模式不直接依赖 CCLite 内部 Fortran API;
5. 若真实 worker 暂不能完成,mock worker 必须完整通过验收,并记录真实 worker 接入缺口。
## 7.8 WP08:Controller 状态机
目标:
实现 CCLite 三进程主控流程。
0.1.x controller 状态包括:
1. parse input;
2. create IPC;
3. launch workers;
4. wait workers ready;
5. send init/read/build/export;
6. step loop;
7. read interface data;
8. write empty loads;
9. collect diagnostics;
10. send stop;
11. release resources。
任务:
1. 实现 `check` 流程;
2. 实现 `dry-run` 流程;
3. 实现最小 `run` 流程;
4. 实现 command dispatch;
5. 实现 timeout;
6. 实现 worker exit 监控;
7. 实现异常清理;
8. 实现 step id 单调递增;
9. 0.1.x 中 `substep_id=0`;
10. 0.1.x 中 `iteration_id=0`。
完成标准:
1. 两个 mock worker 可同步推进;
2. 每步 seq/ack 匹配;
3. 每步 step id 正确;
4. timeout 不造成永久等待;
5. 所有 IPC 资源最终释放。
## 7.9 WP09:诊断输出
目标:
提供 0.1.x 验收所需的日志和 CSV。
0.1.x 输出:
1. `run.log`;
2. `ipc_report.csv`;
3. `force_balance.csv`;
4. `verification_report.json`,由 Python checker 生成。
`ipc_report.csv` 建议字段:
1. `step_id`;
2. `solver_id`;
3. `command_id`;
4. `command_seq`;
5. `ack_seq`;
6. `worker_state`;
7. `heartbeat_seq`;
8. `elapsed_ms`;
9. `error_code`。
`force_balance.csv` 在 0.1.x 中可输出:
1. `step_id`;
2. `sum_force_sph_x`;
3. `sum_force_sph_y`;
4. `sum_force_sph_z`;
5. `sum_force_fem_x`;
6. `sum_force_fem_y`;
7. `sum_force_fem_z`;
8. `force_balance_error`。
0.1.x 空耦合中所有力应为 0。
完成标准:
1. CSV 表头稳定;
2. 每步都有记录;
3. 异常路径写错误码;
4. Python checker 可读取并判定通过或失败。
## 7.10 WP10:Python Checker
目标:
使用 `.\Python\` 支持 0.1.x 自动验收。
任务:
1. 建立 `Python/checkers/`;
2. 建立 CSV 读取工具;
3. 建立 `V010_EMPTY_COUPLING` checker;
4. 检查 seq/ack;
5. 检查 worker state;
6. 检查 timeout;
7. 检查空载荷;
8. 生成 `verification_report.json`;
9. 返回明确退出码。
完成标准:
1. checker 可在本机直接运行;
2. 失败报告指出字段和步号;
3. 报告包含 case id、status、metrics 和 failed checks;
4. Python 不参与 CCLite 核心算法实现。
# 8. `.inp` 最小样例
0.1.x 验收算例建议使用以下风格输入。具体字段名以后以 05 号接口文档和代码实现为准。
```text
*CCLITE CONTROL, NAME=V010_EMPTY_COUPLING, MODE=DRY_RUN
VERSION=0.1
*CCLITE SOLVER, ID=SPH, KIND=SPHLITE
EXECUTABLE=mock_sph_worker.exe
INPUT=mock_sph.inp
*CCLITE SOLVER, ID=FEM, KIND=FEMLITE
EXECUTABLE=mock_fem_worker.exe
INPUT=mock_fem.inp
*CCLITE IPC, TYPE=WINDOWS_SHMEM
NAME_PREFIX=CCLITE_V010
BUFFER=DOUBLE
TIMEOUT_MS=5000
*CCLITE TIME
START=0.0
END=1.0e-4
DT=1.0e-6
*CCLITE INTERFACE, NAME=IFACE_1
SPH_REGION=MOCK_SPH_REGION
FEM_SURFACE=MOCK_FEM_SURFACE
*CCLITE OUTPUT
DIRECTORY=output/v010_empty_coupling
CSV=YES
LOG=YES
```
0.1.x 中该算例不要求产生真实接触力;若输入显式请求真实 contact,程序应给出明确错误或仅允许空耦合模式,不能静默伪装成真实接触已完成。
# 9. 0.1.x 命令流程
0.1.x 主流程:
```text
CCLite parse .inp
CCLite check case
CCLite create command blocks
CCLite create data blocks
CCLite create named events
CCLite launch SPH worker
CCLite launch FEM worker
CCLite wait READY
for each step:
CCLite send EXPORT_INTERFACE
SPH/FEM write interface data
CCLite read headers and payload
CCLite write zero loads
CCLite send ADVANCE
SPH/FEM advance or mock advance
CCLite write diagnostics
CCLite send WRITE_OUTPUT
CCLite send STOP
CCLite release IPC
CCLite exit
```
0.1.x 支持的 worker 命令:
| command | 0.1.x 行为 |
| --- | --- |
| `INIT` | worker 打开 IPC 并初始化 |
| `READ_INPUT` | worker 读取输入或 mock 配置 |
| `BUILD_MODEL` | worker 构建模型或 mock 数据 |
| `EXPORT_INTERFACE` | worker 写出接口数据,可为空 |
| `ADVANCE` | worker 推进一步或 mock step |
| `WRITE_OUTPUT` | worker 写自身输出,可为空 |
| `STOP` | worker 正常退出 |
# 10. 测试计划
## 10.1 单元测试
0.1.x 单元测试:
1. `.inp` 正常解析;
2. `.inp` 缺失必需字段;
3. `.inp` 非法 IPC 类型;
4. keyword 大小写;
5. command block pack/unpack;
6. data block header pack/unpack;
7. block role 枚举;
8. buffer state 转换;
9. 错误码映射;
10. CSV writer。
## 10.2 接口测试
0.1.x 接口测试:
1. shared memory create/open/map/close;
2. named event create/open/wait/signal/reset/close;
3. command seq/ack;
4. heartbeat;
5. timeout;
6. worker state;
7. data block header 校验;
8. record count 超限;
9. bad magic;
10. bad layout id。
## 10.3 集成测试
0.1.x 集成测试:
1. CCLite + mock SPH worker;
2. CCLite + mock FEM worker;
3. CCLite + 双 mock workers;
4. 双 mock workers 空耦合 1 step;
5. 双 mock workers 空耦合 100 steps;
6. worker 启动失败;
7. worker 中途超时;
8. CCLite 正常 STOP;
9. CCLite 异常清理。
## 10.4 验证算例
0.1.x 唯一硬验证算例:
```text
V010_EMPTY_COUPLING
```
通过指标:
1. 连续运行不少于 100 个空耦合 step;
2. `command_seq` 与 `ack_seq` 全部配对;
3. `step_id` 连续递增;
4. `num_active_contacts = 0`;
5. `sum_force_sph = 0`;
6. `sum_force_fem = 0`;
7. 无 IPC 超时;
8. 无未解释错误码;
9. worker 正常退出;
10. 资源释放完整。
# 11. 验收清单
0.1.x 发布候选必须满足:
1. 构建通过;
2. `cclite --version` 可用;
3. `cclite --help` 可用;
4. check 模式通过合法 `.inp`;
5. check 模式拒绝非法 `.inp`;
6. dry-run 模式可创建并释放 IPC;
7. mock workers 可由 CCLite 启动;
8. command block 字段检查通过;
9. named event 同步检查通过;
10. data block header 检查通过;
11. `V010_EMPTY_COUPLING` 通过;
12. Python checker 生成通过报告;
13. 日志和 CSV 输出完整;
14. Linux/MPI 配置给出预留或不支持提示;
15. 0.1.x 文档与实现一致;
16. 不要求真实接触力验收。
# 12. 质量门禁
每个 0.1.x patch 合入前应满足:
1. 代码可编译;
2. 新增模块有最小测试;
3. 不破坏已有 mock 测试;
4. 不引入非 UTF-8 文档;
5. 不改变已冻结接口字段,除非同步更新 05 号文档;
6. 不把 Windows API 暴露到算法层;
7. 不让 SPHLite/FEMLite 直接链接 CCLite 算法核心;
8. 不把 Python checker 写成核心算法依赖。
0.1.x 发布前应执行:
1. quick 测试;
2. standard 测试中的 mock 集成部分;
3. `V010_EMPTY_COUPLING`;
4. 文档一致性检查;
5. UTF-8 without BOM 检查。
# 13. 风险与对策
## 13.1 Windows IPC 细节复杂
风险:
Windows shared memory、named event、句柄生命周期和错误码容易泄漏到 Fortran 算法层。
对策:
1. IPC 细节只放在 C/C++ 薄层和 Fortran2018 wrapper;
2. Fortran95 核心只看到逻辑数据结构;
3. 所有 IPC 资源创建和释放都集中管理;
4. 增加重复运行测试。
## 13.2 C/Fortran 二进制布局不一致
风险:
command block 和 data block header 如果直接跨语言映射,可能出现对齐和字节数差异。
对策:
1. 优先使用明确 pack/unpack;
2. 若使用 `bind(C)`,必须写字段偏移测试;
3. 所有 block 有 `magic`、`abi_version` 和 `layout_id`;
4. Python checker 不直接假设未文档化字段。
## 13.3 真实 worker 接入拖慢 0.1.x
风险:
SPHLite/FEMLite 原有主程序改造可能影响 0.1.x 通信闭环进度。
对策:
1. 先用 mock worker 完成硬验收;
2. 真实 worker 接入按最小 handshake 推进;
3. 保持 SPHLite/FEMLite 独立主控入口;
4. 若真实 worker 未完全接入,应记录缺口,不影响 mock 闭环验收。
## 13.4 0.1.x 范围膨胀
风险:
过早加入接触力、摩擦、FSI 或性能优化,会破坏 0.1.x 建立通信地基的目标。
对策:
1. 0.1.x 不做真实物理接触验收;
2. 接触算法入口可预留但默认关闭;
3. 单粒子撞面放入 0.2.x;
4. 工程算例放入 0.9.x;
5. 所有超范围需求进入 backlog。
# 14. Backlog
以下事项不进入 0.1.x 硬验收,但应记录为后续版本准备:
1. `V020_SINGLE_PARTICLE_WALL` 输入模板;
2. 几何最近点单元测试框架;
3. 基础 hash grid 数据结构;
4. penalty 接触力模块空接口;
5. SPH/FEM 真实界面数据导出细节;
6. SoA v2 layout 设计草案;
7. Linux shared memory 后端草案;
8. MPI 后端草案;
9. worker 故障注入扩展;
10. 长时间运行性能指标。
# 15. 完成定义
CCLite 0.1.x 完成的定义:
1. 文档、源码、测试和样例均以 Fortran/IPC/.inp 方案为基线;
2. CCLite、mock SPH worker、mock FEM worker 可形成三进程闭环;
3. Windows shared memory 和 named event 可稳定创建、使用和释放;
4. command block 和 data block header 与 05 号文档一致;
5. `V010_EMPTY_COUPLING` 通过自动检查;
6. 日志和 CSV 可定位输入、IPC、worker 和资源释放问题;
7. 0.1.x 不宣称真实 SPH-FEM 接触力已经完成;
8. 0.2.x 可以在此基础上开始基础 penalty contact 开发。
0.1.x 的成功标准是一条干净、可重复、可诊断的通信和主控链路。只要这条链路稳定,后续 0.2.x 到 0.7.x 的算法实现才能可靠落地。