From 4a2d30d81dede14995471db75f6fa3c5c53e4353 Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 5 Jul 2026 23:40:12 +0800 Subject: [PATCH] Start CCLite 0.2.0 development baseline --- CMakeLists.txt | 2 +- Python/checkers/audit_real_workers.py | 29 + cases/v0_2_contact/README.md | 21 + docs/07_real_worker_access_audit.md | 35 ++ docs/v2.x_development_plan.md | 874 ++++++++++++++++++++++++++ src/app/cclite_main.f90 | 2 +- src/common/ccl_version.f90 | 6 +- src/controller/ccl_controller.f90 | 2 +- src/mock_workers/ccl_mock_worker.f90 | 2 +- tests/verification/README.md | 10 + todo.md | 591 ++++++++++------- 11 files changed, 1349 insertions(+), 225 deletions(-) create mode 100644 cases/v0_2_contact/README.md create mode 100644 docs/v2.x_development_plan.md diff --git a/CMakeLists.txt b/CMakeLists.txt index 26588ee..5f2f61c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,6 +1,6 @@ cmake_minimum_required(VERSION 3.20) -project(CCLite VERSION 0.1.10 LANGUAGES C Fortran) +project(CCLite VERSION 0.2.0 LANGUAGES C Fortran) set(CMAKE_Fortran_STANDARD 2018) set(CMAKE_Fortran_STANDARD_REQUIRED ON) diff --git a/Python/checkers/audit_real_workers.py b/Python/checkers/audit_real_workers.py index 6153c81..840c566 100644 --- a/Python/checkers/audit_real_workers.py +++ b/Python/checkers/audit_real_workers.py @@ -201,6 +201,34 @@ def build_protocol_alignment(fem_exe: Path) -> dict: } +def build_v020_adapter_gate() -> dict: + return { + "gate_id": "V020_SINGLE_REAL_WORKER_SMOKE", + "status": "CONTROLLED_PROTOCOL_GAP_UNTIL_ADAPTER_TESTS_PASS", + "mock_algorithm_acceptance_independent": True, + "required_paths": [ + "real SPHLite + mock FEMLite, 1 step empty coupling", + "mock SPHLite + real FEMLite, 1 step empty coupling", + "at least one single-real-worker path, 100 step empty coupling", + "real-worker payload header and stride validation", + "real-worker empty or controlled load import validation", + ], + "pass_conditions": [ + "worker process starts through the CCLite worker CLI", + "command seq/ack stays matched for all commands", + "worker exports an empty or controlled interface block that passes CCLite validation", + "worker consumes an empty or controlled load block and acknowledges IMPORT_LOADS", + "worker responds to ADVANCE and STOP without timeout or residual process", + ], + "controlled_gap_conditions": [ + "published command block layout differs from CCLite generic command block", + "published data header layout differs from CCLite generic data block header", + "resource naming cannot be mapped without an adapter", + "record stride or block role cannot be validated by the current CCLite reader", + ], + } + + def main() -> int: parser = argparse.ArgumentParser() parser.add_argument("--sph-exe", required=True) @@ -258,6 +286,7 @@ def main() -> int: "femlite_explicit_ipc_backend": fem_explicit_ipc, "femlite_worker_mock": fem_mock, "protocol_alignment": protocol_alignment, + "v020_adapter_gate": build_v020_adapter_gate(), "conclusion": [ "The current SPHLite package reports CCLite worker and Windows shared memory/named event support.", "The current FEMLite package reports CCLite worker, worker mock, and Windows shared memory/named event support.", diff --git a/cases/v0_2_contact/README.md b/cases/v0_2_contact/README.md new file mode 100644 index 0000000..3f7e2f9 --- /dev/null +++ b/cases/v0_2_contact/README.md @@ -0,0 +1,21 @@ +# V020 Contact Cases + +CCLite 0.2.x 接触算法验收算例目录。 + +本目录用于收纳 0.2.x 基础 SPH 粒子-FEM facet penalty contact 的输入文件、mock worker 配置和预期输出说明。0.2.0 只建立目录骨架,真实算例在后续小版本逐步补齐。 + +命名约定: + +1. 算例编号使用 `V020_*`; +2. 输入文件使用小写版本目录和可读主题,例如 `v020_single_particle_wall.inp`; +3. 输出目录使用 `output/v020_*`; +4. Python checker 报告使用 `verification_report.json`; +5. 真实 worker gate 使用 `V020_SINGLE_REAL_WORKER_SMOKE`。 + +计划算例: + +1. `V020_GEOMETRY_PRIMITIVES`:几何 primitive 验收; +2. `V020_SINGLE_PARTICLE_WALL`:单粒子撞 FEM 平面; +3. `V020_MULTI_PARTICLE_PLANE`:多粒子压 FEM 平面; +4. `V020_FORCE_BALANCE`:合力和力矩平衡; +5. `V020_SINGLE_REAL_WORKER_SMOKE`:单真实 worker gate。 diff --git a/docs/07_real_worker_access_audit.md b/docs/07_real_worker_access_audit.md index 6b7e6ba..7551939 100644 --- a/docs/07_real_worker_access_audit.md +++ b/docs/07_real_worker_access_audit.md @@ -138,3 +138,38 @@ FEMLite 当前发布的真实 IPC worker 使用: 4. 建立 `真实 SPHLite + 真实 FEMLite` 的 1 step 和 100 step 空耦合 gate; 5. 将能力查询、协议版本、record stride、block 容量和错误码纳入自动报告; 6. 在上述 gate 通过前,不把 `supports_real_ipc=yes` 解释为真实外部联调完成。 + +## 7. 0.2.0 Adapter Gate 定义 + +0.2.x 进入基础接触算法开发时,真实 worker 接入作为独立 gate 管理,不阻塞 mock worker 上的 A 层接触算法验收。 + +Gate 编号: + +```text +V020_SINGLE_REAL_WORKER_SMOKE +``` + +0.2.x gate 至少要求推进以下路径: + +1. `真实 SPHLite + mock FEMLite`,1 step 空耦合; +2. `mock SPHLite + 真实 FEMLite`,1 step 空耦合; +3. 至少一条单真实 worker 路径完成 100 step 空耦合; +4. 真实 worker 导出的空或受控 interface block 通过 CCLite header、role、layout、record stride 和 step id 校验; +5. 真实 worker 可接收空或受控 load block,并响应 `IMPORT_LOADS`、`ADVANCE` 和 `STOP`。 + +通过条件: + +1. worker 可由 CCLite 标准 worker CLI 启动; +2. command `seq/ack` 全程匹配; +3. 真实 worker 的 payload 经过与 mock worker 相同的 CCLite 校验; +4. worker 无 timeout、异常退出或残留进程; +5. 验证报告包含 worker 名称、版本、IPC 能力、block 能力和 gate 状态。 + +受控缺口条件: + +1. 外部求解器发布的 command block 与 CCLite generic command block 二进制布局不同; +2. 外部求解器发布的 data header 与 CCLite generic data block header 二进制布局不同; +3. 共享内存和 event 命名无法通过当前参数完全映射; +4. record stride、block role 或错误码不能被当前 CCLite reader 验证。 + +出现上述情况时,0.2.x 应输出 `CONTROLLED_PROTOCOL_GAP` 或等价状态,并继续使用 mock worker 完成基础接触算法验收。该状态不能被写成真实 SPH-FEM 外部进程物理联调完成。 diff --git a/docs/v2.x_development_plan.md b/docs/v2.x_development_plan.md new file mode 100644 index 0000000..11f0aa1 --- /dev/null +++ b/docs/v2.x_development_plan.md @@ -0,0 +1,874 @@ +# CCLite 0.2.x 开发计划 + +## Coupling & Contact Lite for SPHLite and FEMLite + +**文件名**:`v2.x_development_plan.md` +**适用版本**:CCLite 0.2.x +**文档依据**:`01_requirements.md` 到 `06_test_and_verification_plan.md` +**实现基线**:CCLite 0.1.10 主控、通信、mock worker、AoR v1 和真实 worker 能力审计 +**核心目标**:基础 SPH 粒子-FEM facet penalty contact 首次实现 +**第一阶段平台**:Windows / gfortran / 本机共享内存 +**输入格式**:Abaqus 风格 `.inp` +**编码要求**:中文,UTF-8 without BOM + +# 1. 文档目的 + +本文档定义 CCLite 0.2.x 的开发目标、版本节奏、工作包、测试算例、验收清单和风险控制。 + +0.2.x 的核心目标是从 0.1.x 的通信空耦合进入基础物理接触: + +1. 解析 `*CCLITE SURFACE INTERACTION` 和 `*CCLITE CONTACT PAIR`; +2. 建立 SPH particle view 和 FEM facet view; +3. 实现基础几何 primitive、AABB、宽相搜索和窄相最近点; +4. 实现 SPH 粒子到 FEM 三角形 facet 的基础法向 penalty contact; +5. 支持法向阻尼的最小可用路径; +6. 将接触力写回 `CCL_TO_SPH_FORCE` 和 `CCL_TO_FEM_LOAD`; +7. 输出 contact report、force balance 和几何诊断; +8. 通过 `V020_GEOMETRY_PRIMITIVES`、`V020_SINGLE_PARTICLE_WALL` 和 `V020_MULTI_PARTICLE_PLANE`; +9. 至少完成一条单真实 worker 集成 gate,若协议 adapter 尚未完成,则必须形成明确的受控缺口报告。 + +0.2.x 的成功标准不是工程级接触库,而是让 CCLite 第一次具备可验证的 SPH-FEM 基础接触力闭环。 + +# 2. 当前基线 + +0.1.10 已完成: + +1. CCLite 独立主控程序; +2. Windows shared memory 与 named event 薄封装; +3. command block、seq/ack、heartbeat 和 timeout; +4. data block header 与 AoR v1 record; +5. `SPH_TO_CCL_PARTICLE`、`FEM_TO_CCL_FACET`、`CCL_TO_SPH_FORCE`、`CCL_TO_FEM_LOAD` 的基础布局; +6. mock SPH/FEM worker service 模式; +7. 1 step 与 100 step 空耦合; +8. `run.log`、`ipc_report.csv`、`force_balance.csv`; +9. Python checker; +10. SPHLite/FEMLite 外部包能力审计。 + +当前真实 worker 状态: + +```text +EXTERNAL_WORKERS_READY_CCLITE_PROTOCOL_ADAPTER_REQUIRED +``` + +含义是 SPHLite/FEMLite 已报告真实 IPC 能力,但 CCLite 仍需要完成协议/命名 adapter 或统一外部二进制契约,才能声明真实外部进程联调完成。 + +# 3. 版本边界 + +## 3.1 0.2.x 必须完成 + +0.2.x 必须完成以下能力: + +1. `*CCLITE SURFACE INTERACTION` 支持 `NORMAL=PENALTY`; +2. `*CCLITE CONTACT PAIR` 支持 `TYPE=SPH_PARTICLE_TO_FEM_FACE`; +3. CCLite case model 保存 interaction、contact pair 和接触输出配置; +4. SPH particle view 读取 `external_id`、`internal_index`、`status`、`contact_radius`、`x`、`v`; +5. FEM facet view 读取 `facet_id`、`node_count`、`node_ids`、`area`、`thickness`、`normal`、`x`、`v`; +6. 几何基础:Vec3、AABB、point-segment、point-triangle; +7. 四边形 facet 可采用拆三角形的最小实现,复杂四边形一致性补强进入 0.3.x; +8. uniform hash grid 宽相搜索; +9. SPH 粒子到 FEM facet 的候选对生成; +10. 法向间隙 `g`、穿透量 `d` 和局部法向 `n`; +11. 法向 penalty 力和基础法向阻尼; +12. FEM 节点力按 barycentric/shape weight 分配; +13. SPH force record 写回; +14. FEM nodal force load record 写回; +15. 接触数量、最大穿透、总力、总力矩和力平衡误差诊断; +16. Python checker 验证几何、接触方向和力平衡; +17. 0.2.x 验证算例进入回归集合。 + +## 3.2 0.2.x 可做但不作为硬验收 + +以下能力可作为实现便利或实验性能力,但不得作为 0.2.x 完成定义的必要条件: + +1. point-edge helper; +2. 平面四边形拆三角形接触; +3. 单真实 worker + 单 mock worker 的调试性联调; +4. 外部 worker 协议 adapter 原型; +5. 接触快照 CSV; +6. 简单性能计时。 + +## 3.3 0.2.x 不完成 + +0.2.x 不完成以下能力: + +1. Coulomb 摩擦; +2. 接触 persistence 和历史切向变量; +3. 完整 edge fallback 验收; +4. 复杂壳边缘、非平面四边形和壳厚度高级接触; +5. tied coupling 和 release; +6. pressure projection、boundary/ghost particle 和 FSI; +7. 异步子循环和强耦合迭代; +8. 自动 penalty 参数推荐; +9. SoA v2 性能布局; +10. Linux/MPI 生产后端; +11. 工程级水下爆炸或船体局部破坏算例。 + +# 4. 与 0.3.x 和 0.4.x 的分界 + +0.2.x 只做基础接触首次实现。 + +0.3.x 负责: + +1. 壳厚度补强; +2. edge fallback 完整验收; +3. 四边形接触一致性; +4. contact persistence 初步; +5. 接触状态连续性诊断。 + +0.4.x 负责: + +1. Coulomb 摩擦; +2. 接触历史; +3. penalty 参数估计; +4. 接触稳定时间步; +5. 接触能量耗散诊断。 + +0.2.x 可以保留字段和枚举,但不能把这些后续能力写成已完成。 + +# 5. 推荐 patch 版本节奏 + +0.2.x 内部 patch 版本建议如下。实际开发可合并相邻 patch,但不得跳过对应验收目标。 + +| 版本 | 主题 | 主要交付 | +| --- | --- | --- | +| 0.2.0 | 0.2.x 入口和协议前置 | 本计划、0.2 case skeleton、真实 worker protocol adapter 设计和审计 gate | +| 0.2.1 | 接触输入与 case model | `SURFACE INTERACTION`、`CONTACT PAIR`、interaction/pair 校验 | +| 0.2.2 | 接口 view 和 load buffer | SPH particle view、FEM facet view、非空 force/load block 写回 | +| 0.2.3 | 几何 primitive | Vec3、AABB、point-segment、point-triangle、基础退化诊断 | +| 0.2.4 | 宽相搜索 | uniform hash grid、candidate pair、去重和容量保护 | +| 0.2.5 | 窄相接触 | gap、penetration、normal、shape weight、contact pair 输出 | +| 0.2.6 | penalty force | 法向 penalty、基础阻尼、FEM 节点力分配、SPH/FEM 载荷写回 | +| 0.2.7 | 诊断与 checker | contact_report.csv、force_balance.csv 增强、V020 checker | +| 0.2.8 | 验证算例 | 单粒子撞面、多粒子压面、几何/搜索/力平衡回归 | +| 0.2.9 | 单真实 worker gate | 至少完成一侧真实 worker 集成,或形成协议 adapter 受控缺口 | +| 0.2.10 | 发布候选 | 全量 0.1.x/0.2.x 回归、文档一致性、UTF-8 without BOM 检查 | + +# 6. 交付物 + +## 6.1 程序交付物 + +0.2.x 应交付: + +1. `cclite.exe`,支持基础 contact run; +2. mock SPH/FEM worker,可生成可控粒子和 facet; +3. 接触算法模块; +4. 几何和搜索模块; +5. contact diagnostics; +6. Python checker; +7. 0.2.x 验证算例。 + +## 6.2 源码交付物 + +建议新增或补强以下目录: + +```text +src/ + geometry/ + contact/ + search/ + transfer/ + verification_support/ +``` + +若不新增目录,也必须在现有模块边界中保持职责清晰: + +| 职责 | 建议模块 | +| --- | --- | +| Vec3/AABB/最近点 | `src/geometry/` | +| hash grid/candidate | `src/search/` | +| contact pair/penalty force | `src/contact/` | +| SPH force/FEM load 写回 | `src/transfer/` | +| contact report | `src/diagnostics/` | +| checker | `Python/checkers/` | + +0.2.x 不应把接触算法写入 SPHLite 或 FEMLite 内部。 + +## 6.3 文档交付物 + +0.2.x 结束时应更新: + +1. `README.md`; +2. `docs/03_detailed_design.md`,若模块结构或数据结构变化; +3. `docs/04_mathematical_model_and_algorithms.md`,若公式、伪代码或版本映射变化; +4. `docs/05_interface_control_document.md`,若 block 字段、record stride、命名规则或 adapter 变化; +5. `docs/06_test_and_verification_plan.md`,若新增验收算例或 checker; +6. `docs/07_real_worker_access_audit.md`,若真实 worker gate 状态变化; +7. 本开发计划; +8. `docs/0.2.x_release_notes.md`,在发布候选阶段新增。 + +## 6.4 测试交付物 + +0.2.x 测试交付物包括: + +1. 几何单元测试; +2. hash grid 单元测试; +3. contact pair 单元测试; +4. penalty force 单元测试; +5. load buffer 单元测试; +6. `V020_GEOMETRY_PRIMITIVES`; +7. `V020_SINGLE_PARTICLE_WALL`; +8. `V020_MULTI_PARTICLE_PLANE`; +9. `V020_FORCE_BALANCE`; +10. `V020_SINGLE_REAL_WORKER_SMOKE` 或受控缺口报告。 + +# 7. 工作包分解 + +## 7.1 WP00:0.1.10 到 0.2.x 交接 + +目标: + +确认 0.1.x 通信闭环可作为 0.2.x 开发地基,并处理真实 worker 协议前置风险。 + +任务: + +1. 保留 `V010_EMPTY_COUPLING` 为 0.2.x 回归前置; +2. 保留 `real_worker_gap_report.json`; +3. 梳理 SPHLite/FEMLite 当前 IPC 结构、命名规则和能力查询; +4. 决定 0.2.x 是否先采用 mock worker 完成 A 层物理算法验收; +5. 若做真实 worker,先实现 CCLite 侧协议 adapter 或统一外部协议; +6. 记录 adapter 选择到 05 号文档。 + +完成标准: + +1. 0.1.x 全量测试通过; +2. 真实 worker 状态不被误判为物理接触完成; +3. 0.2.x 的 A 层 mock 算例可独立于真实 worker 运行。 + +## 7.2 WP01:接触输入与 case model + +目标: + +解析 0.2.x 接触输入关键词并建立内部 case model。 + +必须支持: + +```text +*CCLITE SURFACE INTERACTION, NAME=PENALTY_1 +NORMAL=PENALTY, KN=..., CN=... + +*CCLITE CONTACT PAIR, NAME=PAIR_1 +INTERFACE=... +INTERACTION=... +TYPE=SPH_PARTICLE_TO_FEM_FACE +``` + +任务: + +1. 扩展 parser 支持 interaction 和 contact pair; +2. 保存 `normal_model`、`kn`、`cn` 和 `friction` 字段; +3. 0.2.x 中若 `FRICTION` 非 0,应报错或 warning 并忽略; +4. 校验 `CONTACT PAIR` 引用的 interface 与 interaction; +5. 校验 `TYPE=SPH_PARTICLE_TO_FEM_FACE`; +6. 输出 check summary; +7. 添加非法输入测试。 + +完成标准: + +1. 合法 contact `.inp` 可通过 `cclite check`; +2. 缺少 `KN`、非法 `NORMAL`、未知 pair 引用能给出行号和错误; +3. 0.2.x 不把摩擦写成已启用能力。 + +## 7.3 WP02:SPH/FEM 接口 view 与 load buffer + +目标: + +把 AoR v1 payload 转成接触算法可用的只读 view,并把接触力写回 load block。 + +SPH particle view 至少包含: + +```text +external_id +internal_index +status +contact_radius +x[3] +v[3] +mass +valid_flags +``` + +FEM facet view 至少包含: + +```text +facet_id +node_count +node_ids[8] +area +thickness +normal[3] +x[8,3] +v[8,3] +valid_flags +``` + +任务: + +1. 建立 SPH particle view; +2. 建立 FEM facet view; +3. 检查有效字段、非有限值、容量和 record stride; +4. 建立 SPH force accumulator; +5. 建立 FEM nodal load accumulator; +6. 写 `CCL_TO_SPH_FORCE`; +7. 写 `CCL_TO_FEM_LOAD`; +8. 对同一粒子或同一节点多条载荷做合并; +9. 输出导入/导出计数。 + +完成标准: + +1. 空 block 仍可合法通过; +2. 固定粒子和固定 facet 可生成非空 view; +3. 非有限输入不进入接触力计算; +4. 写回 block 可由 mock worker 消费; +5. force/load record 的 step id 与 command step 匹配。 + +## 7.4 WP03:几何 primitive + +目标: + +实现 04 号文档第 4 章要求的 0.2.x 几何基础。 + +任务: + +1. Vec3 dot/cross/norm/normalize; +2. AABB 初始化、扩展、重叠测试; +3. SPH particle AABB; +4. FEM facet AABB; +5. point-segment closest point; +6. point-triangle closest point; +7. barycentric/shape weight; +8. point-quad split 为两个 triangle; +9. 退化边、退化三角形和非法 normal 诊断; +10. 单元测试覆盖内部、边、顶点和退化输入。 + +完成标准: + +1. 点到三角形最近点误差在容差内; +2. barycentric 权重和为 1; +3. 退化几何不产生非有限结果; +4. `V020_GEOMETRY_PRIMITIVES` 通过。 + +## 7.5 WP04:宽相搜索 + +目标: + +实现 uniform hash grid,从 SPH particle view 和 FEM facet view 生成 candidate pair。 + +任务: + +1. 定义 grid cell size; +2. facet AABB 插入 grid; +3. particle AABB 查询邻近 cell; +4. candidate pair 去重; +5. candidate 容量保护; +6. 输出 candidate 统计; +7. 添加小规模和边界单元测试。 + +完成标准: + +1. 单 facet、单粒子可生成候选; +2. 不接触的远距离粒子不生成候选; +3. 跨 cell 边界的候选不漏检; +4. 重复 facet 不导致重复 candidate; +5. candidate overflow 有明确错误码。 + +## 7.6 WP05:窄相 contact pair + +目标: + +从 candidate pair 生成真实 contact pair。 + +任务: + +1. 对每个 candidate 计算最近点; +2. 计算局部法向; +3. 计算 gap; +4. 计算有效接触距离; +5. 计算 penetration; +6. 生成 contact pair; +7. 保存 shape weight 和 node_count; +8. 保存 contact state; +9. 记录退化和跳过原因; +10. 输出 `contact_report.csv`。 + +完成标准: + +1. 粒子在面外无接触; +2. 粒子穿透面时生成接触; +3. 接触法向方向与设计一致; +4. `penetration = r_c - g`; +5. shape weight 可用于节点力分配; +6. 退化 facet 不产生接触力。 + +## 7.7 WP06:Penalty force 与节点分配 + +目标: + +实现基础法向 penalty damping 接触力,并写回 SPH/FEM 载荷。 + +0.2.x 力模型: + +```text +f_i = (k_n d + c_n max(0, -v_n)) n +``` + +FEM 节点力: + +```text +F_A = N_A (-f_i) +``` + +任务: + +1. 读取 `KN` 和 `CN`; +2. 计算 FEM 最近点速度; +3. 计算法向相对速度; +4. 计算 penalty 力; +5. 计算阻尼力; +6. 分配 FEM 节点力; +7. 合并 SPH 粒子力; +8. 合并 FEM 节点力; +9. 检查非有限力; +10. 输出力和力矩诊断。 + +完成标准: + +1. 无穿透时接触力为 0; +2. 穿透时接触力方向正确; +3. 闭合速度时阻尼力非负; +4. 分配节点力合力等于 facet 反力; +5. SPH/FEM 总力平衡误差小于容差; +6. 非有限力被拒绝并终止当前 step。 + +## 7.8 WP07:Controller 接触 run 流程 + +目标: + +在 0.1.x step loop 中插入真实接触计算。 + +0.2.x run 流程: + +```text +for each step: + send EXPORT_INTERFACE to SPH/FEM + read SPH particle block + read FEM facet block + build interface views + build broad-phase candidates + run narrow-phase contact + compute penalty loads + write CCL_TO_SPH_FORCE + write CCL_TO_FEM_LOAD + send IMPORT_LOADS + send ADVANCE + write diagnostics +``` + +任务: + +1. 区分 dry-run 和 contact run; +2. contact run 要求 contact pair 已定义; +3. 每步清零 contact/force/load accumulator; +4. 读取 interface block 后执行接触; +5. 写非空 load block; +6. 调用 `IMPORT_LOADS`; +7. 记录 step 级诊断; +8. 异常时停止两个 worker 并释放资源。 + +完成标准: + +1. 空接触 case 仍可运行; +2. 单粒子撞面 case 可产生载荷; +3. 接触算法错误不会造成 worker 残留; +4. `run.log` 可定位输入、接口、几何或力计算错误。 + +## 7.9 WP08:诊断输出 + +目标: + +形成可自动检查的接触诊断。 + +建议输出: + +```text +contact_report.csv +candidate_report.csv +force_balance.csv +ipc_report.csv +run.log +verification_report.json +``` + +`contact_report.csv` 建议字段: + +```text +step_id,pair_id,sph_id,facet_id,contact_type,gap,penetration, +normal_x,normal_y,normal_z,force_x,force_y,force_z,node_count +``` + +`force_balance.csv` 在 0.2.x 增加: + +```text +num_contacts,max_penetration,total_contact_force_norm, +moment_balance_error,nonfinite_contact_count,skipped_degenerate_count +``` + +完成标准: + +1. 每个 contact step 有诊断; +2. 无接触时诊断仍写 0 值; +3. checker 可读取并判定方向、力平衡和最大穿透; +4. CSV 表头变化会触发回归失败。 + +## 7.10 WP09:Python Checker 和算例生成 + +目标: + +使用 `Python/` 支持 0.2.x 自动验收和可控算例生成。 + +任务: + +1. 新增 `check_v020_geometry_primitives.py`; +2. 新增 `check_v020_contact.py`; +3. 新增公共 contact CSV 读取工具; +4. 可选新增 case generator; +5. 对单粒子撞面计算参考力; +6. 对多粒子压面检查总力方向和数量级; +7. 生成 `verification_report.json`; +8. 返回明确退出码。 + +完成标准: + +1. checker 不依赖 CCLite 内部 Fortran 模块; +2. 失败报告包含 step、pair、字段和期望/实际值; +3. Python 只用于测试、算例和报告,不参与核心算法。 + +## 7.11 WP10:真实 worker adapter gate + +目标: + +0.2.x 起逐步接入真实 SPHLite/FEMLite worker,不让 mock 算法验收掩盖真实接口问题。 + +任务: + +1. 明确 CCLite 采用统一通用 block 还是求解器专用 adapter; +2. 为 SPHLite 建立命名/结构 adapter 或要求其支持 CCLite 通用 block; +3. 为 FEMLite 建立命名/结构 adapter 或要求其支持 CCLite 通用 block; +4. 建立单真实 worker 1 step 空耦合; +5. 建立单真实 worker 100 step 空耦合; +6. 建立真实 worker payload 读取 smoke; +7. 将 worker 能力查询写入验证报告; +8. 若无法完成,输出 `CONTROLLED_PROTOCOL_GAP`,不阻塞 A 层算法验证。 + +完成标准: + +1. 至少一条单真实 worker 集成路径通过,或缺口清晰记录; +2. 真实 worker 数据经过与 mock 数据相同的 header 和 payload 校验; +3. 不把 `supports_real_ipc=yes` 写成真实接触物理验收完成。 + +# 8. 0.2.x 输入样例 + +```text +** CCLite 0.2.x single particle wall contact case. +*CCLITE CONTROL, NAME=V020_SINGLE_PARTICLE_WALL, MODE=RUN +VERSION=0.2 + +*CCLITE SOLVER, ID=SPH, KIND=SPHLITE +EXECUTABLE=mock_sph_worker.exe +INPUT=mock_sph_contact.inp + +*CCLITE SOLVER, ID=FEM, KIND=FEMLITE +EXECUTABLE=mock_fem_worker.exe +INPUT=mock_fem_wall.inp + +*CCLITE IPC, TYPE=WINDOWS_SHMEM +NAME_PREFIX=CCLITE_V020 +BUFFER=DOUBLE +TIMEOUT_MS=5000 + +*CCLITE TIME +START=0.0 +END=1.0e-6 +DT=1.0e-6 + +*CCLITE INTERFACE, NAME=WALL_CONTACT +SPH_REGION=SPH_CONTACT_REGION +FEM_SURFACE=FEM_WALL + +*CCLITE SURFACE INTERACTION, NAME=PENALTY_1 +NORMAL=PENALTY, KN=1.0e6, CN=0.0 +FRICTION=0.0 + +*CCLITE CONTACT PAIR, NAME=PAIR_1 +INTERFACE=WALL_CONTACT +INTERACTION=PENALTY_1 +TYPE=SPH_PARTICLE_TO_FEM_FACE + +*CCLITE OUTPUT +DIRECTORY=output/v020_single_particle_wall +CONTACT=YES +IPC=YES +FORCE_BALANCE=YES +``` + +# 9. 验证算例 + +## 9.1 `V020_GEOMETRY_PRIMITIVES` + +目标: + +验证 Vec3、AABB、point-segment、point-triangle 和基础 point-quad split。 + +通过判据: + +1. 最近点位置误差小于容差; +2. 权重和为 1; +3. 退化几何被拒绝; +4. 无非有限值输出。 + +## 9.2 `V020_SINGLE_PARTICLE_WALL` + +目标: + +验证单 SPH 粒子撞 FEM 平面 facet 的接触方向和接触力。 + +通过判据: + +1. 无穿透时接触数为 0; +2. 穿透时接触数为 1; +3. 法向方向正确; +4. 接触力大小等于 `KN * penetration`,若 `CN=0`; +5. FEM 节点力合力等于 SPH 反力; +6. force balance error 小于容差。 + +## 9.3 `V020_MULTI_PARTICLE_PLANE` + +目标: + +验证多个 SPH 粒子同时接触同一 FEM 平面。 + +通过判据: + +1. 接触数量等于预期; +2. 总 SPH 力与总 FEM 力平衡; +3. 最大穿透量与输入几何一致; +4. 无重复 contact pair; +5. candidate 数量可复核。 + +## 9.4 `V020_FORCE_BALANCE` + +目标: + +专门验证力和力矩诊断。 + +通过判据: + +1. `sum_force_sph + sum_force_fem` 小于容差; +2. 力矩误差有界且非有限计数为 0; +3. CSV 中每步都有 force balance 记录。 + +## 9.5 `V020_SINGLE_REAL_WORKER_SMOKE` + +目标: + +验证 CCLite 与至少一个真实 worker 的 0.2.x 接口路径。 + +通过判据: + +1. worker 能启动; +2. worker 能导出非空或可控空 interface block; +3. CCLite 能写回空或可控 load block; +4. worker 能响应 `IMPORT_LOADS`、`ADVANCE` 和 `STOP`; +5. 若协议 adapter 未完成,报告必须明确写出缺口和下一步。 + +# 10. 测试计划 + +## 10.1 单元测试 + +0.2.x 单元测试至少覆盖: + +1. contact keyword parser; +2. interaction/pair 引用校验; +3. Vec3; +4. AABB; +5. point-segment; +6. point-triangle; +7. barycentric weight; +8. hash grid; +9. candidate 去重; +10. contact pair; +11. penalty force; +12. FEM 节点分配; +13. force/load block 写回; +14. 非有限输入保护。 + +## 10.2 接口测试 + +0.2.x 接口测试至少覆盖: + +1. `SPH_TO_CCL_PARTICLE` 非空 payload; +2. `FEM_TO_CCL_FACET` 非空 payload; +3. `CCL_TO_SPH_FORCE` 非空 payload; +4. `CCL_TO_FEM_LOAD` 非空 payload; +5. payload record stride; +6. `valid_flags`; +7. step id 匹配; +8. capacity overflow; +9. block state 转换; +10. worker 消费非空载荷。 + +## 10.3 集成测试 + +0.2.x 集成测试至少覆盖: + +1. CCLite + 双 mock workers 单粒子撞面; +2. CCLite + 双 mock workers 多粒子压面; +3. CCLite + 单真实 SPHLite worker + mock FEM worker,若 adapter 可用; +4. CCLite + mock SPH worker + 单真实 FEMLite worker,若 adapter 可用; +5. 接触输入错误; +6. worker 超时; +7. 非有限粒子; +8. 退化 facet; +9. force balance 回归; +10. 0.1.x 空耦合回归。 + +# 11. 验收清单 + +0.2.x 发布候选必须满足: + +1. 0.1.x 全量回归通过; +2. `cclite --version` 输出 0.2.x; +3. `cclite check` 支持 contact 输入; +4. 几何单元测试通过; +5. 搜索单元测试通过; +6. penalty force 单元测试通过; +7. 非空 force/load block 测试通过; +8. `V020_GEOMETRY_PRIMITIVES` 通过; +9. `V020_SINGLE_PARTICLE_WALL` 通过; +10. `V020_MULTI_PARTICLE_PLANE` 通过; +11. `V020_FORCE_BALANCE` 通过; +12. 至少一条单真实 worker gate 通过,或形成受控协议缺口报告; +13. 接触报告、力平衡报告和验证报告完整; +14. 文档与实现一致; +15. UTF-8 without BOM 检查通过; +16. 不声明摩擦、tied/release、FSI 或工程算例已完成。 + +# 12. 质量门禁 + +每个 0.2.x patch 合入前应满足: + +1. 构建通过; +2. 新增算法有单元测试; +3. 0.1.x 回归不退化; +4. 新增 CSV 表头同步 checker; +5. 新增 `.inp` 样例可由 `cclite check` 解析; +6. 非有限输入有明确错误码; +7. 接触力方向有测试; +8. force balance 有测试; +9. 文档为 UTF-8 without BOM; +10. 不修改已冻结接口字段,除非同步更新 05 号文档。 + +# 13. 风险与对策 + +## 13.1 真实 worker 协议未对齐 + +风险: + +SPHLite/FEMLite 已报告真实 IPC 能力,但二进制结构和命名规则与 CCLite 0.1.x 当前通用 block 不完全一致。 + +对策: + +1. 0.2.x A 层算法验收继续使用 mock worker; +2. 单真实 worker gate 独立推进; +3. adapter 状态写入 `07_real_worker_access_audit.md`; +4. 不把真实 worker 缺口阻塞基础 contact 算法单元测试。 + +## 13.2 接触力方向错误 + +风险: + +法向方向、gap 符号或 SPH/FEM 反力符号错误,会导致单粒子算例看似有力但物理方向错误。 + +对策: + +1. 单粒子撞面必须有手算参考; +2. force balance 必须检查作用-反作用; +3. contact report 输出 normal、gap、penetration 和 force; +4. 测试包含粒子在 facet 两侧的情况。 + +## 13.3 退化几何导致非有限值 + +风险: + +退化 facet、零长度边、非法 normal 会污染接触力。 + +对策: + +1. 几何函数统一返回错误码; +2. 退化候选不产生接触力; +3. 诊断记录 skipped_degenerate_count; +4. checker 检查非有限计数为 0。 + +## 13.4 penalty 参数过大导致数值不稳定 + +风险: + +过大 `KN` 或 `CN` 可产生非有限力或过大速度增量。 + +对策: + +1. 0.2.x 先使用手算小算例; +2. 检查力是否有限; +3. 输出最大接触力和最大穿透; +4. 自动 penalty 参数和稳定时间步放入 0.4.x。 + +## 13.5 范围膨胀 + +风险: + +过早加入摩擦、tie、FSI、工程算例会拖慢基础 contact 验收。 + +对策: + +1. 0.2.x 只做基础法向 penalty contact; +2. 摩擦字段可解析但不启用; +3. tie 和 FSI 只保留接口字段; +4. 工程算例进入 0.9.x。 + +# 14. Backlog + +以下事项不进入 0.2.x 硬验收: + +1. 完整 edge fallback; +2. 四边形双线性投影; +3. 壳厚度高级几何; +4. contact persistence; +5. Coulomb 摩擦; +6. 自动 penalty 参数; +7. 接触稳定时间步; +8. 接触能量诊断; +9. tied/release; +10. pressure projection; +11. boundary/ghost particle; +12. Riemann FSI; +13. SoA v2; +14. Linux/MPI; +15. 工程简化算例。 + +# 15. 完成定义 + +CCLite 0.2.x 完成的定义: + +1. CCLite 保持独立主控程序身份; +2. 0.1.x 通信和空耦合能力不退化; +3. CCLite `.inp` 可定义基础 penalty contact; +4. SPH particle view 和 FEM facet view 可参与接触计算; +5. 几何 primitive、宽相搜索和窄相检测通过单元测试; +6. 单粒子撞面能产生方向正确的接触力; +7. 多粒子压面能产生可复核的总力; +8. SPH/FEM 作用-反作用误差可控; +9. `CCL_TO_SPH_FORCE` 和 `CCL_TO_FEM_LOAD` 可写入非空载荷; +10. contact report 和 force balance 可由 checker 自动验收; +11. 至少一个真实 worker 集成路径完成或形成明确协议缺口; +12. 0.2.x 不宣称摩擦、tied/release、FSI 或工程级应用完成。 + +0.2.x 的成功标准是一条从界面数据、几何搜索、接触力计算、载荷写回到自动验收的最小物理闭环。该闭环稳定后,0.3.x 才适合继续处理壳、边缘、四边形和接触连续性。 diff --git a/src/app/cclite_main.f90 b/src/app/cclite_main.f90 index 9d7a976..a0b9a63 100644 --- a/src/app/cclite_main.f90 +++ b/src/app/cclite_main.f90 @@ -75,7 +75,7 @@ contains end function handle_mode subroutine print_help() - print '(a)', "CCLite 0.1.x" + print '(a)', "CCLite 0.2.x" print '(a)', "Usage:" print '(a)', " cclite --help" print '(a)', " cclite --version" diff --git a/src/common/ccl_version.f90 b/src/common/ccl_version.f90 index 9b53ebf..1fb59b8 100644 --- a/src/common/ccl_version.f90 +++ b/src/common/ccl_version.f90 @@ -2,9 +2,9 @@ module ccl_version implicit none integer, parameter :: CCL_VERSION_MAJOR = 0 - integer, parameter :: CCL_VERSION_MINOR = 1 - integer, parameter :: CCL_VERSION_PATCH = 10 - character(len=*), parameter :: CCL_VERSION_LABEL = "0.1.10" + integer, parameter :: CCL_VERSION_MINOR = 2 + integer, parameter :: CCL_VERSION_PATCH = 0 + character(len=*), parameter :: CCL_VERSION_LABEL = "0.2.0-dev" contains diff --git a/src/controller/ccl_controller.f90 b/src/controller/ccl_controller.f90 index 1517f33..a4ec866 100644 --- a/src/controller/ccl_controller.f90 +++ b/src/controller/ccl_controller.f90 @@ -78,7 +78,7 @@ contains call ccl_diagnostics_open(diag, ccl_case%output%directory, ccl_case%name, input_file, ierr) if (ierr /= CCL_SUCCESS) return - call ccl_log_info("controller", "starting 0.1.6 empty coupling dry-run") + call ccl_log_info("controller", "starting 0.2.0 empty coupling baseline path") call ccl_diagnostics_write_run(diag, "INFO", "controller", "starting empty coupling dry-run") call init_worker(sph_worker, ccl_case, CCL_CASE_SOLVER_SPH, ierr) if (ierr /= CCL_SUCCESS) goto 900 diff --git a/src/mock_workers/ccl_mock_worker.f90 b/src/mock_workers/ccl_mock_worker.f90 index 1173f52..74d7bf7 100644 --- a/src/mock_workers/ccl_mock_worker.f90 +++ b/src/mock_workers/ccl_mock_worker.f90 @@ -92,7 +92,7 @@ contains subroutine print_worker_help(worker_name) character(len=*), intent(in) :: worker_name - print '(a)', trim(worker_name) // " 0.1.x" + print '(a)', trim(worker_name) // " 0.2.x" print '(a)', "Usage:" print '(a)', " " // trim(worker_name) // " --help" print '(a)', " " // trim(worker_name) // " --version" diff --git a/tests/verification/README.md b/tests/verification/README.md index c52e3b4..e8fe5aa 100644 --- a/tests/verification/README.md +++ b/tests/verification/README.md @@ -1,3 +1,13 @@ # tests/verification Verification tests, including `V010_EMPTY_COUPLING`. + +0.2.x 新增验证项统一使用 `V020_*` 前缀。测试名、算例名、输出目录和 checker 报告中的 `case_id` 应保持一致: + +1. `V020_GEOMETRY_PRIMITIVES`; +2. `V020_SINGLE_PARTICLE_WALL`; +3. `V020_MULTI_PARTICLE_PLANE`; +4. `V020_FORCE_BALANCE`; +5. `V020_SINGLE_REAL_WORKER_SMOKE`. + +0.2.0 只冻结命名约定,具体算例和 checker 在后续小版本补齐。 diff --git a/todo.md b/todo.md index 79b42a2..f083c0c 100644 --- a/todo.md +++ b/todo.md @@ -1,11 +1,13 @@ -# CCLite 0.1.x 待办事项 +# CCLite 0.2.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。 +**依据**:`docs/v2.x_development_plan.md` +**适用范围**:CCLite 0.2.x +**实现基线**:CCLite 0.1.10 +**核心目标**:完成基础 SPH 粒子-FEM facet penalty contact 的最小物理闭环。 +**第一阶段平台**:Windows / gfortran / 本机共享内存。 +**不包含**:Coulomb 摩擦、tied/release、FSI、SoA v2、Linux/MPI 生产后端、工程级应用算例。 # 1. 任务颗粒度约定 @@ -13,9 +15,9 @@ 1. 可以由一个小 patch 独立完成; 2. 有明确输入、输出或可观察行为; -3. 有最小测试或检查方式; -4. 不跨越多个架构层大改; -5. 完成后能让项目更接近 `V010_EMPTY_COUPLING`。 +3. 有最小测试、检查命令或诊断文件作为完成判据; +4. 不同时跨越 parser、IPC、算法、诊断和真实 worker 多个大层; +5. 完成后能让项目更接近 0.2.x 接触力闭环。 状态标记: @@ -26,317 +28,470 @@ [!] 阻塞 ``` -# 2. 0.1.0 工程骨架 +执行约定: -目标:建立可编译工程、程序入口和最小 smoke。 +1. 非必须不要跳过待办事项; +2. 每完成一个 0.2.x patch 小版本,应提交一次 git; +3. 若发现现有设计与 01~06 号文档冲突,先更新对应文档或形成缺口记录; +4. 真实 worker gate 不阻塞 mock worker 上的 A 层算法验收,但不得被误写为真实物理联调完成。 -- [x] T0101 建立 `src/`、`include/`、`tests/`、`cases/`、`Python/` 基础目录。 - 完成判据:目录结构与开发计划一致,空目录有占位说明或后续构建可识别。 +# 2. 0.2.0 入口和协议前置 -- [x] T0102 建立 Windows/gfortran 构建入口。 - 完成判据:可构建至少一个 `cclite` 空程序目标。 +目标:从 0.1.10 稳定基线进入 0.2.x,并把真实 worker 协议风险显式放到 gate 中。 -- [x] T0103 增加 CCLite 版本模块。 - 完成判据:程序能输出 `0.1.0` 版本号和构建平台信息。 +- [x] T0200-01 建立 `docs/v2.x_development_plan.md`。 + 完成判据:文档定义 0.2.x 目标、版本节奏、工作包、验证算例和验收清单。 -- [x] T0104 增加主程序 CLI 骨架。 - 完成判据:支持 `--help`、`--version`、`check`、`dry-run`、`run` 命令入口。 +- [x] T0200-02 用 0.2.x 计划替换 `todo.md`。 + 完成判据:待办事项按 0.2.0 到 0.2.10 分组,任务颗粒度均匀。 -- [x] T0105 增加基础错误码模块。 - 完成判据:输入错误、IPC 错误、worker 错误、系统错误有独立范围。 +- [x] T0200-03 将程序开发版本入口切到 `0.2.0-dev`。 + 完成判据:`cclite --version` 或等价版本输出能区分 0.1.x 发布版与 0.2.x 开发版。 -- [x] T0106 增加基础日志模块。 - 完成判据:能写 `run.log`,包含时间、级别、模块名和消息。 +- [x] T0200-04 建立 0.2.x case 目录骨架。 + 完成判据:新增 `cases/v0_2_contact/` 或等价目录,包含 README 和待填充样例说明。 -- [x] T0107 建立空 mock worker 构建目标。 - 完成判据:`mock_sph_worker` 和 `mock_fem_worker` 可启动并输出自身身份。 +- [x] T0200-05 建立 0.2.x 测试命名约定。 + 完成判据:测试名、算例名和输出目录统一使用 `V020_*` 前缀。 -- [x] T0108 增加工程 smoke 测试。 - 完成判据:测试能检查 `cclite --version`、`cclite --help` 和两个 mock worker 启动。 +- [x] T0200-06 复跑 0.1.x 全量回归。 + 完成判据:现有 0.1.x 单元、接口和空耦合集成测试全部通过。 -# 3. 0.1.1 `.inp` 与 Case Model +- [x] T0200-07 梳理 SPHLite/FEMLite 当前 worker 启动参数。 + 完成判据:记录真实 worker 的可执行文件、参数、命名规则和已支持命令。 -目标:支持 CCLite 主控输入和 check 模式。 +- [x] T0200-08 梳理 SPHLite/FEMLite 当前 IPC block 能力。 + 完成判据:确认真实 worker 与 CCLite 通用 block 在 header、role、layout 和 record stride 上的差异。 -- [x] T0111 定义 `CCL_Case` 数据结构。 - 完成判据:可保存 control、solver、ipc、time、interface、output 配置。 +- [x] T0200-09 定义 0.2.x 真实 worker adapter gate。 + 完成判据:明确 gate 输入、输出、通过条件和 `CONTROLLED_PROTOCOL_GAP` 条件。 -- [x] T0112 实现关键词行解析。 - 完成判据:支持 `*CCLITE ...` 关键词、大小写兼容、注释和空行。 +- [x] T0200-10 更新真实 worker 审计记录。 + 完成判据:`docs/07_real_worker_access_audit.md` 反映 0.2.x 入口状态。 -- [x] T0113 实现参数键值解析。 - 完成判据:支持 `KEY=VALUE`、字符串路径、数值和布尔值。 +# 3. 0.2.1 接触输入与 Case Model -- [x] T0114 解析 `*CCLITE CONTROL` 和运行模式。 - 完成判据:能识别 `check`、`dry-run`、`run`,非法模式报错。 +目标:支持 0.2.x 基础接触输入关键词,并把 interaction 与 contact pair 保存到内部模型。 -- [x] T0115 解析 `*CCLITE SOLVER`。 - 完成判据:能保存 SPH/FEM solver id、kind、executable 和 input 文件。 +- [ ] T0201-01 扩展 case model 保存 surface interaction。 + 完成判据:内部结构可保存 `name`、`normal_model`、`kn`、`cn` 和 `friction`。 -- [x] T0116 解析 `*CCLITE IPC`。 - 完成判据:0.1.x 只接受 `TYPE=WINDOWS_SHMEM`,其他类型给出预留或不支持错误。 +- [ ] T0201-02 扩展 case model 保存 contact pair。 + 完成判据:内部结构可保存 `name`、`interface`、`interaction` 和 `type`。 -- [x] T0117 解析 `*CCLITE TIME`、`*CCLITE INTERFACE` 和 `*CCLITE OUTPUT`。 - 完成判据:能保存时间范围、dt、region/surface 映射和输出目录。 +- [ ] T0201-03 解析 `*CCLITE SURFACE INTERACTION` 关键词行。 + 完成判据:可读取 `NAME=...`,缺少名称时给出带行号错误。 -- [x] T0118 实现 case 校验。 - 完成判据:缺失 solver、缺失 IPC、非法时间步、缺失输出目录均能定位到关键词。 +- [ ] T0201-04 解析 surface interaction 数据行。 + 完成判据:可读取 `NORMAL=PENALTY`、`KN=...`、`CN=...` 和 `FRICTION=...`。 -- [x] T0119 实现 `cclite check`。 - 完成判据:合法输入输出检查摘要,非法输入返回非零错误码。 +- [ ] T0201-05 解析 `*CCLITE CONTACT PAIR` 关键词行。 + 完成判据:可读取 `NAME=...`,重复名称能报错。 -- [x] T0120 增加 `.inp` parser 单元测试。 - 完成判据:覆盖合法输入、未知关键词、缺失字段、非法 IPC 和大小写兼容。 +- [ ] T0201-06 解析 contact pair 数据行。 + 完成判据:可读取 `INTERFACE=...`、`INTERACTION=...` 和 `TYPE=SPH_PARTICLE_TO_FEM_FACE`。 -# 4. 0.1.2 IPC 基础 +- [ ] T0201-07 校验 interaction 参数合法性。 + 完成判据:缺少 `KN`、非法 `NORMAL`、负刚度或非有限数值均返回输入错误。 -目标:完成 Windows shared memory 和 named event 最小可用层。 +- [ ] T0201-08 校验 contact pair 引用合法性。 + 完成判据:未知 interface、未知 interaction 和非法 type 均返回输入错误。 -- [x] T0121 定义 C IPC 薄层头文件。 - 完成判据:声明 shared memory、event、error 和 handle 基础接口。 +- [ ] T0201-09 处理 0.2.x 未启用摩擦字段。 + 完成判据:`FRICTION` 非 0 时给出错误或 warning,并且不启用摩擦计算。 -- [x] T0122 实现 shared memory create/open/map。 - 完成判据:可创建命名共享内存并取得 payload 指针。 +- [ ] T0201-10 增加 contact 输入检查摘要。 + 完成判据:`cclite check` 输出 interaction 数量、pair 数量和未启用能力提示。 -- [x] T0123 实现 shared memory unmap/close。 - 完成判据:资源释放后同名测试可重复运行。 +- [ ] T0201-11 增加合法 contact `.inp` 样例。 + 完成判据:样例可通过 `cclite check`,并包含 surface interaction 与 contact pair。 -- [x] T0124 实现 named event create/open。 - 完成判据:可创建 Windows manual-reset named event。 +- [ ] T0201-12 增加 contact parser 单元测试。 + 完成判据:覆盖合法输入、缺少 `KN`、非法 `NORMAL`、未知引用和摩擦未启用路径。 -- [x] T0125 实现 named event wait/signal/reset/close。 - 完成判据:wait 支持 timeout,signal/reset 行为可测试。 +# 4. 0.2.2 接口 View 与 Load Buffer -- [x] T0126 建立 Fortran2018 IPC wrapper。 - 完成判据:Fortran 侧可调用 C IPC 薄层并取得状态码。 +目标:把 AoR v1 payload 转成接触算法只读 view,并支持非空力和载荷写回。 -- [x] T0127 建立 IPC 资源命名规则。 - 完成判据:同一 case 的 command block、data block 和 event 名称可稳定生成。 +- [ ] T0202-01 定义 SPH particle view 类型。 + 完成判据:包含 `external_id`、`internal_index`、`status`、`contact_radius`、`x`、`v`、`mass` 和 `valid_flags`。 -- [x] T0128 增加 IPC 错误映射。 - 完成判据:create/open/map/wait 失败能转换为 CCLite 错误码。 +- [ ] T0202-02 定义 FEM facet view 类型。 + 完成判据:包含 `facet_id`、`node_count`、`node_ids`、`area`、`thickness`、`normal`、`x`、`v` 和 `valid_flags`。 -- [x] T0129 增加 IPC 接口测试。 - 完成判据:覆盖 shared memory 生命周期、event wait/signal/reset、timeout 和重复释放。 +- [ ] T0202-03 实现 SPH AoR record 到 particle view 的转换。 + 完成判据:可从 `SPH_TO_CCL_PARTICLE` 读取固定粒子并生成有效 view。 -# 5. 0.1.3 Command Block 与 Worker 协议 +- [ ] T0202-04 实现 FEM AoR record 到 facet view 的转换。 + 完成判据:可从 `FEM_TO_CCL_FACET` 读取固定 facet 并生成有效 view。 -目标:实现命令共享块、seq/ack 和 worker 状态机基础。 +- [ ] T0202-05 增加 view 输入有限性检查。 + 完成判据:坐标、速度、半径、面积和法向中非有限值会被拒绝或标记无效。 -- [x] T0131 定义 command id 枚举。 - 完成判据:支持 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`。 +- [ ] T0202-06 增加 view 容量和 stride 检查。 + 完成判据:record size、count、capacity 与 payload bytes 不一致时返回明确错误。 -- [x] T0132 定义 worker state 枚举。 - 完成判据:支持 `STARTING`、`READY`、`BUSY`、`DONE`、`ERROR`、`STOPPED`。 +- [ ] T0202-07 定义 SPH force accumulator。 + 完成判据:同一 SPH 粒子的多条接触力可累加到一条写回记录。 -- [x] T0133 定义 command block 逻辑类型。 - 完成判据:字段覆盖 05 号文档要求,`substep_id` 和 `iteration_id` 在 0.1.x 写 0。 +- [ ] T0202-08 定义 FEM nodal load accumulator。 + 完成判据:同一 FEM 节点的多条接触反力可累加到一条写回记录。 -- [x] T0134 实现 command block pack/unpack。 - 完成判据:二进制布局可稳定写入共享内存并读回。 +- [ ] T0202-09 实现 `CCL_TO_SPH_FORCE` 非空写回。 + 完成判据:mock SPH worker 可读取非空 force block,step id 与命令 step 匹配。 -- [x] T0135 实现 magic/version/layout 校验。 - 完成判据:非法 magic、ABI 或 layout id 能在初始化阶段拒绝。 +- [ ] T0202-10 实现 `CCL_TO_FEM_LOAD` 非空写回。 + 完成判据:mock FEM worker 可读取非空 load block,step id 与命令 step 匹配。 -- [x] T0136 实现 command seq/ack 配对。 - 完成判据:每条命令都有递增 seq,worker 回写对应 ack。 +- [ ] T0202-11 输出 interface 导入导出计数。 + 完成判据:`run.log` 或诊断 CSV 包含粒子、facet、force record 和 load record 数量。 -- [x] T0137 实现 heartbeat 更新。 - 完成判据:worker 空闲或执行命令时能更新 `heartbeat_seq`。 +- [ ] T0202-12 增加 view/load buffer 单元测试。 + 完成判据:覆盖空 block、固定 payload、非有限输入、重复累加和 step id 校验。 -- [x] T0138 实现 command timeout 检测。 - 完成判据:worker 不响应时 CCLite 返回超时错误,不永久等待。 +# 5. 0.2.3 几何 Primitive -- [x] T0139 增加 command block 单元测试。 - 完成判据:覆盖字段读写、seq/ack、版本校验、非法状态和 timeout。 +目标:实现 0.2.x 接触检测需要的基础几何函数。 -# 6. 0.1.4 Data Block 与 AoR v1 +- [ ] T0203-01 建立 geometry 模块边界。 + 完成判据:Vec3、AABB 和最近点函数有独立模块或清晰命名空间。 -目标:实现 data block header、block role 和基础 AoR v1 payload。 +- [ ] T0203-02 实现 Vec3 基础运算。 + 完成判据:支持 dot、cross、norm、scale、add、sub 和 normalize。 -- [x] T0141 定义 data block header。 - 完成判据:包含 magic、version、role、layout、record size、count、capacity、state 和 step id。 +- [ ] T0203-03 实现 AABB 初始化与扩展。 + 完成判据:空 AABB、点扩展和半径扩展行为可测试。 -- [x] T0142 定义 block role 枚举。 - 完成判据:支持 `SPH_TO_CCL_PARTICLE`、`FEM_TO_CCL_FACET`、`CCL_DIAGNOSTIC`、`CCL_COMMAND_SPH`、`CCL_COMMAND_FEM`。 +- [ ] T0203-04 实现 AABB 重叠测试。 + 完成判据:相离、相切、包含和部分重叠四类情况结果正确。 -- [x] T0143 定义 buffer state。 - 完成判据:支持 empty、writing、ready、reading、error 状态转换。 +- [ ] T0203-05 实现 SPH particle AABB。 + 完成判据:粒子位置和 `contact_radius` 可生成包围盒。 -- [x] T0144 实现 header pack/unpack。 - 完成判据:共享内存中 header 可由 CCLite 和 worker 双向读写。 +- [ ] T0203-06 实现 FEM facet AABB。 + 完成判据:三角形或四边形节点坐标可生成包围盒,并包含厚度或容差扩展。 -- [x] T0145 实现 header 校验。 - 完成判据:非法 role、record size、count 超限和 payload bytes 超限可被拒绝。 +- [ ] T0203-07 实现 point-segment closest point。 + 完成判据:线段内部、端点外侧和退化线段路径均有确定输出。 -- [x] T0146 定义 SPH particle AoR v1 record。 - 完成判据:字段覆盖 id、index、position、velocity、mass、density、h、radius、pressure、sound speed 和 flags。 +- [ ] T0203-08 实现 point-triangle closest point。 + 完成判据:面内、边区、顶点区和退化三角形路径均有测试。 -- [x] T0147 定义 FEM facet AoR v1 record。 - 完成判据:字段覆盖 facet id、surface id、node ids、coords、velocity、normal、area、thickness、mass per area 和 flags。 +- [ ] T0203-09 实现 barycentric/shape weight。 + 完成判据:三角形权重和为 1,面内权重非负,退化输入返回错误。 -- [x] T0148 定义空载荷 record 预留。 - 完成判据:0.1.x 可创建 `CCL_TO_SPH_FORCE` 和 `CCL_TO_FEM_LOAD` 空 block。 +- [ ] T0203-10 实现 point-quad split 最小路径。 + 完成判据:平面四边形按两个三角形处理,并记录拆分选择。 -- [x] T0149 增加 data block 单元测试。 - 完成判据:覆盖空 payload、固定 record、最大 capacity、bad header 和 bad count。 +- [ ] T0203-11 增加退化几何诊断计数。 + 完成判据:退化边、退化三角形和非法法向不会产生非有限结果。 -# 7. 0.1.5 Controller 空耦合 +- [ ] T0203-12 增加 `V020_GEOMETRY_PRIMITIVES` 单元测试。 + 完成判据:最近点误差、权重和、退化处理和非有限保护全部通过。 -目标:跑通 CCLite + 双 mock worker 的三进程空耦合。 +# 6. 0.2.4 宽相搜索 -- [x] T0151 实现 worker 进程描述结构。 - 完成判据:可保存 executable、input、solver id、ipc 名称、状态和进程句柄。 +目标:实现 uniform hash grid,从 particle/facet view 生成候选接触对。 -- [x] T0152 实现 worker 启动器。 - 完成判据:CCLite 可启动 mock SPH/FEM worker,并记录启动命令。 +- [ ] T0204-01 定义 hash grid 数据结构。 + 完成判据:可保存 cell size、cell key、facet 列表和容量信息。 -- [x] T0153 实现 worker 停止和退出监控。 - 完成判据:正常 STOP 和异常退出都能被 CCLite 识别。 +- [ ] T0204-02 定义 grid cell size 选择规则。 + 完成判据:默认 cell size 与最大接触半径或用户配置有明确关系。 -- [x] T0154 实现 mock worker IPC attach。 - 完成判据:mock worker 可打开 command block、data block 和 named event。 +- [ ] T0204-03 实现 facet AABB 插入 grid。 + 完成判据:跨多个 cell 的 facet 能被插入所有覆盖 cell。 -- [x] T0155 实现 mock worker 命令循环。 - 完成判据:mock worker 可响应 0.1.x 必需命令并回写 ack。 +- [ ] T0204-04 实现 particle AABB 查询 grid。 + 完成判据:粒子可查询相邻 cell 并返回候选 facet id。 -- [x] T0156 实现 mock SPH 固定粒子导出。 - 完成判据:可按配置导出 0 个或少量固定 SPH record。 +- [ ] T0204-05 实现 candidate pair 去重。 + 完成判据:同一粒子和 facet 组合不会重复进入窄相。 -- [x] T0157 实现 mock FEM 固定 facet 导出。 - 完成判据:可按配置导出 0 个或少量固定 FEM facet record。 +- [ ] T0204-06 实现 candidate 容量保护。 + 完成判据:候选数超限时返回明确错误码,并写入诊断。 -- [x] T0158 实现 CCLite dry-run step loop。 - 完成判据:CCLite 可执行 export、读 header、写空载荷、advance、diagnostics。 +- [ ] T0204-07 输出宽相统计。 + 完成判据:每步记录 grid cell 数、facet 插入数、candidate 数和去重数。 -- [x] T0159 实现 1 step 空耦合集成测试。 - 完成判据:双 mock worker 完成 1 step 并正常退出。 +- [ ] T0204-08 增加单 facet 单粒子搜索测试。 + 完成判据:近距离粒子生成候选,远距离粒子不生成候选。 -- [x] T0160 实现 100 step 空耦合集成测试。 - 完成判据:双 mock worker 完成 100 step,无 timeout,无残留进程。 +- [ ] T0204-09 增加跨 cell 边界搜索测试。 + 完成判据:粒子位于 cell 边界时不漏检。 -# 8. 0.1.6 诊断与 Python Checker +- [ ] T0204-10 增加 candidate overflow 测试。 + 完成判据:构造超限候选时程序给出可诊断失败,而不是越界或静默截断。 -目标:形成可自动判定的 `V010_EMPTY_COUPLING` 验证闭环。 +# 7. 0.2.5 窄相 Contact Pair -- [x] T0161 实现 `run.log` 标准输出。 - 完成判据:记录版本、输入、worker 命令、IPC 名称、错误码和资源释放。 +目标:从 candidate pair 生成真实接触对,输出 gap、penetration、normal 和 shape weight。 -- [x] T0162 实现 `ipc_report.csv`。 - 完成判据:每步输出 solver id、command id、seq、ack、worker state、heartbeat、elapsed 和 error。 +- [ ] T0205-01 定义 contact pair record。 + 完成判据:包含 step、pair id、SPH id、facet id、gap、penetration、normal 和 shape weight。 -- [x] T0163 实现 `force_balance.csv`。 - 完成判据:0.1.x 空耦合每步输出 SPH/FEM 总力为 0。 +- [ ] T0205-02 实现 candidate 窄相循环。 + 完成判据:每个宽相候选最多生成一条窄相 contact record。 -- [x] T0164 建立 `Python/checkers/`。 - 完成判据:目录中有 checker 入口和公共 CSV 读取工具。 +- [ ] T0205-03 计算 facet 最近点。 + 完成判据:三角形 facet 使用 point-triangle,四边形 facet 使用 split triangle。 -- [x] T0165 定义 `verification_report.json` schema。 - 完成判据:包含 case id、status、metrics、failed checks、输入和输出文件。 +- [ ] T0205-04 计算局部接触法向。 + 完成判据:法向方向与 04 号文档约定一致,并可在诊断中复核。 -- [x] T0166 实现 `V010_EMPTY_COUPLING` checker。 - 完成判据:检查 seq/ack、step id、timeout、worker state、空载荷和退出状态。 +- [ ] T0205-05 计算法向间隙 `g`。 + 完成判据:粒子中心到 facet 最近点的符号距离可复现。 -- [x] T0167 建立 `cases/v0_1_ipc_empty_coupling/`。 - 完成判据:包含 CCLite `.inp`、mock 输入说明和预期输出说明。 +- [ ] T0205-06 计算有效接触距离。 + 完成判据:SPH `contact_radius` 与 facet 厚度或容差的组合规则明确。 -- [x] T0168 集成 checker 到本地测试命令。 - 完成判据:运行测试后自动生成 `verification_report.json`。 +- [ ] T0205-07 计算穿透量 `penetration`。 + 完成判据:满足 `penetration = contact_distance - g`,非穿透时不生成接触力。 -- [x] T0169 增加诊断回归测试。 - 完成判据:CSV 表头变化或关键字段缺失会导致测试失败。 +- [ ] T0205-08 保存 FEM 节点 shape weight。 + 完成判据:后续节点力分配可直接使用 contact record 中的权重。 -# 9. 0.1.7 真实 Worker 最小接入 +- [ ] T0205-09 记录窄相跳过原因。 + 完成判据:远离、退化、非法法向和非有限输入有独立计数。 -目标:在不破坏 SPHLite/FEMLite 独立运行的前提下,定义或实现最小 worker/service handshake。 +- [ ] T0205-10 输出基础 `contact_report.csv`。 + 完成判据:包含 step、pair、粒子、facet、gap、penetration、normal 和 node_count 字段。 -- [x] T0171 确认 SPHLite worker 接入方式。 - 完成判据:明确是修改 SPHLite 入口、增加包装程序,还是暂以接入缺口记录。 +- [ ] T0205-11 增加窄相 contact 单元测试。 + 完成判据:覆盖无接触、穿透接触、法向方向、shape weight 和退化 facet。 -- [x] T0172 确认 FEMLite worker 接入方式。 - 完成判据:明确是修改 FEMLite 入口、增加包装程序,还是暂以接入缺口记录。 +# 8. 0.2.6 Penalty Force 与节点分配 -- [x] T0173 固化 worker 启动参数。 - 完成判据:SPHLite/FEMLite 采用一致的 `--cclite-worker` 参数约定。 +目标:实现法向 penalty damping 力,并写回 SPH force 与 FEM nodal load。 -- [x] T0174 实现或记录 SPHLite handshake。 - 完成判据:SPHLite worker 能进入 `READY`,或形成明确缺口说明。 +- [ ] T0206-01 从 interaction 中读取 `KN` 和 `CN`。 + 完成判据:每个 contact pair 使用其引用 interaction 的刚度和阻尼。 -- [x] T0175 实现或记录 FEMLite handshake。 - 完成判据:FEMLite worker 能进入 `READY`,或形成明确缺口说明。 +- [ ] T0206-02 计算 FEM 最近点速度。 + 完成判据:使用 contact shape weight 从 FEM 节点速度插值得到最近点速度。 -- [x] T0176 验证 SPHLite 空接口导出。 - 完成判据:真实或包装 worker 可导出空 particle block。 +- [ ] T0206-03 计算法向相对速度。 + 完成判据:`v_n` 的符号与阻尼公式约定一致,并有单元测试。 -- [x] T0177 验证 FEMLite 空接口导出。 - 完成判据:真实或包装 worker 可导出空 facet block。 +- [ ] T0206-04 实现法向 penalty 力。 + 完成判据:`CN=0` 时力大小等于 `KN * penetration`。 -- [x] T0178 验证真实 worker 空载荷接收。 - 完成判据:worker 能接受空 force/load block,不报物理算法错误。 +- [ ] T0206-05 实现基础法向阻尼力。 + 完成判据:闭合速度产生非负阻尼项,分离速度不增加吸引力。 -- [x] T0179 执行单真实 worker 集成 smoke。 - 完成判据:CCLite + 一个真实 worker + 一个 mock worker 可完成最小 dry-run,或输出受控缺口报告。 +- [ ] T0206-06 合成 SPH 粒子接触力。 + 完成判据:同一粒子多接触力累加后写入 force accumulator。 -# 10. 0.1.8 发布候选 +- [ ] T0206-07 分配 FEM 节点反力。 + 完成判据:节点力合力等于 `-SPH_contact_force`,权重来自 shape weight。 -目标:冻结 0.1.x 通信闭环,准备进入 0.2.x 接触算法开发。 +- [ ] T0206-08 增加非有限力保护。 + 完成判据:非有限 penetration、速度或力会终止当前 step 并输出错误。 -- [x] T0181 执行全量 0.1.x 单元测试。 - 完成判据:`.inp`、command block、data block、错误码和 CSV writer 测试通过。 +- [ ] T0206-09 写回 SPH force block。 + 完成判据:`CCL_TO_SPH_FORCE` 中包含非空力记录,并可被 mock worker 消费。 -- [x] T0182 执行全量 0.1.x 接口测试。 - 完成判据:shared memory、named event、timeout、bad header 和 bad layout 测试通过。 +- [ ] T0206-10 写回 FEM load block。 + 完成判据:`CCL_TO_FEM_LOAD` 中包含非空节点力记录,并可被 mock worker 消费。 -- [x] T0183 执行全量 0.1.x 集成测试。 - 完成判据:双 mock workers 1 step 和 100 step 空耦合通过。 +- [ ] T0206-11 输出力和力矩平衡诊断。 + 完成判据:每步记录 SPH 总力、FEM 总力、合力误差和力矩误差。 -- [x] T0184 执行 `V010_EMPTY_COUPLING` 验证算例。 - 完成判据:Python checker 生成通过报告。 +- [ ] T0206-12 增加 penalty force 单元测试。 + 完成判据:覆盖零穿透、单点穿透、阻尼、节点分配和非有限保护。 -- [x] T0185 执行干净环境重建。 - 完成判据:从干净目录构建、运行 smoke 和 V010 均通过。 +# 9. 0.2.7 Controller 接触流程与诊断 -- [x] T0186 检查 UTF-8 without BOM。 - 完成判据:新增文档和 `.inp` 样例均无 BOM。 +目标:把接触算法插入 0.1.x step loop,并形成可自动检查的诊断输出。 -- [x] T0187 检查文档一致性。 - 完成判据:README、03、05、06 和开发计划与实现字段、命令、输出一致。 +- [ ] T0207-01 区分 dry-run 与 contact run。 + 完成判据:无 contact pair 时可保持 dry-run,定义 contact pair 时进入接触路径。 -- [x] T0188 冻结 0.1.x 接口常量。 - 完成判据:command id、worker state、block role、layout id、CSV 表头有记录。 +- [ ] T0207-02 在 step loop 中读取 SPH/FEM interface block。 + 完成判据:每步接触计算前 view 来自当前 step 的 worker 导出数据。 -- [x] T0189 整理 0.1.x release notes。 - 完成判据:列出已完成能力、未完成能力、真实 worker 接入状态和 0.2.x 入口条件。 +- [ ] T0207-03 在 step loop 中调用宽相搜索。 + 完成判据:每步生成 candidate 数并写入诊断。 -# 11. 0.1.x 总体验收清单 +- [ ] T0207-04 在 step loop 中调用窄相接触。 + 完成判据:每步生成 contact 数、最大穿透和跳过计数。 -- [x] A001 `cclite.exe` 可作为独立主控程序启动。 -- [x] A002 `mock_sph_worker` 和 `mock_fem_worker` 可由 CCLite 启动。 -- [x] A003 CCLite 可创建和释放 Windows shared memory。 -- [x] A004 CCLite 可创建和释放 Windows manual-reset named event。 -- [x] A005 Command block seq/ack 在 100 step 中全部匹配。 -- [x] A006 Data block header 校验覆盖正常和异常路径。 -- [x] A007 AoR v1 空 payload 和固定 payload 均可处理。 -- [x] A008 `cclite check` 可检查合法和非法 `.inp`。 -- [x] A009 `cclite dry-run` 可完成双 mock 空耦合。 -- [x] A010 `run.log`、`ipc_report.csv`、`force_balance.csv` 均生成。 -- [x] A011 Python checker 可生成 `verification_report.json`。 -- [x] A012 `V010_EMPTY_COUPLING` 自动检查通过。 -- [x] A013 Linux/MPI 配置只给出预留或不支持提示。 -- [x] A014 0.1.x 不宣称真实 SPH-FEM 接触力已完成。 -- [x] A015 0.2.x 可在该基础上进入基础 penalty contact 开发。 +- [ ] T0207-05 在 step loop 中调用 penalty force。 + 完成判据:接触力写入 accumulator,非接触 step 输出零载荷。 -# 12. 暂不进入 0.1.x 的事项 +- [ ] T0207-06 在写回载荷后发送 `IMPORT_LOADS`。 + 完成判据:SPH/FEM worker 均能确认载荷导入命令。 -以下事项进入 backlog,不作为 0.1.x 待办: +- [ ] T0207-07 在 `ADVANCE` 前后保持 seq/ack 正确。 + 完成判据:0.1.x IPC 报告中的 command seq/ack 不退化。 -- [ ] 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 生产后端。 +- [ ] T0207-08 每步清零接触和载荷 accumulator。 + 完成判据:连续 step 不会继承上一 step 的 contact、force 或 load。 + +- [ ] T0207-09 异常时停止两个 worker 并释放资源。 + 完成判据:接触算法错误、输入错误或 worker 超时后无残留进程和未释放 IPC。 + +- [ ] T0207-10 增强 `contact_report.csv`。 + 完成判据:包含 gap、penetration、normal、force 和 node_count 字段。 + +- [ ] T0207-11 增强 `force_balance.csv`。 + 完成判据:增加接触数、最大穿透、总接触力、力矩误差和非有限计数。 + +- [ ] T0207-12 增强 `run.log` 接触诊断。 + 完成判据:输入、view、搜索、接触、力计算和写回错误均可定位。 + +# 10. 0.2.8 验证算例与 Python Checker + +目标:形成 0.2.x 自动验收闭环,支持几何、接触方向、力平衡和回归检查。 + +- [ ] T0208-01 建立 0.2.x checker 公共 CSV 读取工具。 + 完成判据:checker 可读取 contact、candidate、force balance 和 IPC 报告。 + +- [ ] T0208-02 实现 `check_v020_geometry_primitives.py`。 + 完成判据:可校验几何测试输出、容差、退化输入和非有限计数。 + +- [ ] T0208-03 实现 `check_v020_contact.py`。 + 完成判据:可校验接触数、方向、penetration、力大小和力平衡。 + +- [ ] T0208-04 生成或整理 `V020_GEOMETRY_PRIMITIVES` 算例。 + 完成判据:算例可自动运行并由 checker 判定通过。 + +- [ ] T0208-05 生成或整理 `V020_SINGLE_PARTICLE_WALL` 算例。 + 完成判据:单粒子穿透平面时产生一条方向正确的接触力。 + +- [ ] T0208-06 生成或整理 `V020_MULTI_PARTICLE_PLANE` 算例。 + 完成判据:多粒子接触数量、最大穿透和总力可复核。 + +- [ ] T0208-07 生成或整理 `V020_FORCE_BALANCE` 算例。 + 完成判据:合力误差和力矩误差在容差内,非有限计数为 0。 + +- [ ] T0208-08 输出 `verification_report.json`。 + 完成判据:报告包含 case id、status、metrics、failed checks 和关键输出文件路径。 + +- [ ] T0208-09 将 0.2.x 算例接入本地回归测试。 + 完成判据:一条命令可运行 0.1.x 回归和 0.2.x 基础接触验证。 + +- [ ] T0208-10 增加 CSV 表头回归检查。 + 完成判据:contact、candidate 和 force balance 表头变更会触发测试失败。 + +- [ ] T0208-11 增加失败报告细节。 + 完成判据:checker 失败时输出 step、pair、字段名、期望值和实际值。 + +# 11. 0.2.9 单真实 Worker Gate + +目标:至少推进一条真实 worker 接入路径,或形成清晰的受控协议缺口。 + +- [ ] T0209-01 确认 CCLite adapter 策略。 + 完成判据:明确采用通用 block、求解器专用 adapter,还是二者混合过渡。 + +- [ ] T0209-02 实现或配置 SPHLite worker adapter。 + 完成判据:CCLite 可按统一入口启动 SPHLite worker,或记录阻塞字段。 + +- [ ] T0209-03 实现或配置 FEMLite worker adapter。 + 完成判据:CCLite 可按统一入口启动 FEMLite worker,或记录阻塞字段。 + +- [ ] T0209-04 验证单真实 SPHLite worker 1 step 空耦合。 + 完成判据:真实 SPHLite + mock FEM 可完成 1 step,或输出 `CONTROLLED_PROTOCOL_GAP`。 + +- [ ] T0209-05 验证单真实 FEMLite worker 1 step 空耦合。 + 完成判据:mock SPH + 真实 FEMLite 可完成 1 step,或输出 `CONTROLLED_PROTOCOL_GAP`。 + +- [ ] T0209-06 验证单真实 worker 100 step 空耦合。 + 完成判据:至少一侧真实 worker 在 100 step 内无 seq/ack、timeout 或资源释放错误。 + +- [ ] T0209-07 验证真实 worker payload 读取 smoke。 + 完成判据:真实 worker 导出的空或非空 interface block 通过 CCLite header 和 payload 校验。 + +- [ ] T0209-08 验证真实 worker load import smoke。 + 完成判据:真实 worker 能接收空或可控 load block,并响应 `IMPORT_LOADS`。 + +- [ ] T0209-09 记录 worker 能力查询结果。 + 完成判据:验证报告包含 worker 名称、版本、IPC 能力、block 能力和缺口状态。 + +- [ ] T0209-10 更新真实 worker 审计文档。 + 完成判据:`docs/07_real_worker_access_audit.md` 与实际 gate 结果一致。 + +# 12. 0.2.10 发布候选 + +目标:收束 0.2.x,确认基础接触力闭环、回归、文档和发布说明一致。 + +- [ ] T0210-01 执行 0.1.x 全量回归。 + 完成判据:0.1.x 空耦合、IPC、parser 和诊断测试不退化。 + +- [ ] T0210-02 执行 0.2.x 单元测试。 + 完成判据:contact parser、geometry、search、narrow phase、penalty force 和 load buffer 测试全部通过。 + +- [ ] T0210-03 执行 0.2.x 集成测试。 + 完成判据:双 mock workers 的单粒子撞面、多粒子压面和 force balance 算例通过。 + +- [ ] T0210-04 执行真实 worker gate 测试。 + 完成判据:至少一条单真实 worker 路径通过,或受控协议缺口报告完整。 + +- [ ] T0210-05 执行 UTF-8 without BOM 检查。 + 完成判据:新增文档、`.inp` 样例和 Python 文本文件均无 BOM。 + +- [ ] T0210-06 检查文档与接口一致性。 + 完成判据:03、04、05、06、07 号文档与实现字段、命令、输出和限制一致。 + +- [ ] T0210-07 整理 `docs/0.2.x_release_notes.md`。 + 完成判据:列出完成能力、未完成能力、真实 worker gate 状态和后续 0.3.x 入口条件。 + +- [ ] T0210-08 更新 README 的 0.2.x 状态。 + 完成判据:README 准确描述基础 penalty contact、平台边界和未启用能力。 + +- [ ] T0210-09 将版本输出切到发布候选号。 + 完成判据:`cclite --version` 输出 `0.2.10` 或约定的 0.2.x 发布候选号。 + +- [ ] T0210-10 执行干净环境重建。 + 完成判据:从干净构建目录可完成构建、smoke、0.1.x 回归和 0.2.x 验证。 + +- [ ] T0210-11 检查 0.2.x 不越界声明。 + 完成判据:文档和日志不宣称摩擦、tied/release、FSI、SoA v2、Linux/MPI 或工程级应用已完成。 + +- [ ] T0210-12 完成 0.2.x 发布提交。 + 完成判据:所有 0.2.x 变更已提交,工作区无非预期未跟踪文件。 + +# 13. 0.2.x 总体验收清单 + +- [ ] A0201 CCLite 保持独立主控程序身份。 +- [ ] A0202 0.1.x 通信和空耦合能力不退化。 +- [ ] A0203 `.inp` 可定义基础 `NORMAL=PENALTY` 接触。 +- [ ] A0204 `CONTACT PAIR` 可绑定 interface 与 interaction。 +- [ ] A0205 SPH particle view 可从 AoR v1 payload 构建。 +- [ ] A0206 FEM facet view 可从 AoR v1 payload 构建。 +- [ ] A0207 Vec3、AABB、point-segment 和 point-triangle 通过测试。 +- [ ] A0208 uniform hash grid 可生成去重候选对。 +- [ ] A0209 窄相可生成 gap、penetration、normal 和 shape weight。 +- [ ] A0210 法向 penalty force 方向和大小可由手算算例验证。 +- [ ] A0211 FEM 节点力分配满足作用-反作用平衡。 +- [ ] A0212 `CCL_TO_SPH_FORCE` 可写入非空载荷。 +- [ ] A0213 `CCL_TO_FEM_LOAD` 可写入非空载荷。 +- [ ] A0214 `contact_report.csv` 可被 checker 自动检查。 +- [ ] A0215 `force_balance.csv` 包含接触力和力矩诊断。 +- [ ] A0216 `V020_GEOMETRY_PRIMITIVES` 通过。 +- [ ] A0217 `V020_SINGLE_PARTICLE_WALL` 通过。 +- [ ] A0218 `V020_MULTI_PARTICLE_PLANE` 通过。 +- [ ] A0219 `V020_FORCE_BALANCE` 通过。 +- [ ] A0220 单真实 worker gate 通过或形成受控协议缺口。 +- [ ] A0221 所有新增文档和样例为 UTF-8 without BOM。 +- [ ] A0222 0.2.x 不声明超出版本边界的能力。 + +# 14. 暂不进入 0.2.x 的事项 + +以下事项进入后续版本 backlog,不作为 0.2.x 待办: + +- [ ] B0201 完整 edge fallback。 +- [ ] B0202 四边形双线性投影。 +- [ ] B0203 壳厚度高级几何。 +- [ ] B0204 contact persistence。 +- [ ] B0205 Coulomb 摩擦。 +- [ ] B0206 自动 penalty 参数估计。 +- [ ] B0207 接触稳定时间步。 +- [ ] B0208 接触能量诊断。 +- [ ] B0209 tied coupling 和 release。 +- [ ] B0210 pressure projection。 +- [ ] B0211 boundary/ghost particle。 +- [ ] B0212 Riemann FSI。 +- [ ] B0213 SoA v2 性能布局。 +- [ ] B0214 Linux/MPI 生产后端。 +- [ ] B0215 工程级水下爆炸或船体局部破坏算例。