840 lines
23 KiB
Markdown
840 lines
23 KiB
Markdown
# 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 的算法实现才能可靠落地。
|