# 12 CCLite 集成建议 文档状态:建议稿 本文从 `..\CCLite\sphlite_suggests.md` 提取建议,并按 SPHLite 当前 0.8.3 能力进行修订。原文件中许多 0.1.x/0.2.x 的“起步改造”在 SPHLite 侧已经由 0.8.0/0.8.1 的 `CouplingInterface`、0.8.2 worker mock 契约和 0.8.3 worker IPC self-test 覆盖,因此本文不再原样沿用版本号,而是按“现状、缺口、建议路线和验收”重新组织。CCLite 0.1.9 审计新增的“真实 worker 接入闭环”建议已在第 13 节逐条响应。 ## 1. 总体结论 SPHLite 不应被改造成 CCLite 的内部库,也不应把 FEMLite 或 CCLite 的内部算法结构写入核心物理模块。推荐的集成口径是: ```text SPHLite 独立求解器 + SPHLite 侧中立 CouplingInterface + 可选 CCLite worker/service adapter ``` 其中: - `CouplingInterface` 负责导出 SPH 侧区域状态、接收外部载荷/接触状态/运动边界并提供诊断。 - CCLite 负责启动 worker、管理 shared memory/named event、计算 SPH-FEM 接触/FSI 载荷并写回。 - SPHLite 不直接调度 FEMLite,不读取 FEMLite 私有数据结构,不链接 CCLite 算法核心。 - worker/service adapter 只负责通信、命令分发和数据映射,不承担接触搜索、接触约束或 FSI 算法。 ## 2. 当前 SPHLite 基线 截至 0.8.3,SPHLite 已具备以下与 CCLite 集成相关的基础: - Fortran 95 算法核心求解器,C ABI、C++ 薄包装、Python `ctypes` 和 CLI 均可用;worker、CLI、IPC 等外围集成层及其测试/工具性 Fortran 代码可放宽到 Fortran 2018。 - `*SPHLITE COUPLING REGION` 输入已支持 `TYPE=CONTACT/CONTINUUM`。 - coupling region 已支持 `EXPORT=PARTICLE/FACET/BOTH`。 - 外部导入已支持 `IMPORT=FORCE/FACET_LOAD/MOTION`。 - facet load 已支持 `LOAD_MODE=PRESSURE/TRACTION` 以及 resultant 类导入。 - facet load 分配已支持 `DISTRIBUTION=UNIFORM/AREA/MASS`。 - contact state 已支持法向、gap、penetration、contact pressure 的导入诊断。 - motion boundary 已支持速度/位置目标的 direct 模式。 - C ABI 已提供 region info、region modes、粒子导出、facet proxy 导出、粒子力、facet load、facet pressure/traction/resultant、contact state、motion boundary、load balance 和 coupling diagnostics。 - 输出侧已具备 CSV、summary CSV、VTU、PVD 和 restart。 - 0.8.0/0.8.1 coupling release gate 已覆盖 mock coupling、输出、restart、Fortran/C/C++/Python/CLI 接口和 source size。 - 0.8.3 worker release gate 已覆盖 worker CLI、能力查询、协议、IPC mock、Windows shared memory/named event self-test、命令映射、AOR v1 粒子/力数据块、诊断文件和 CCLite mock command/data block。 当前仍未交付的内容: - 真实外部 CCLite worker/service 进程联调。 - 由 CCLite 生产调度的 shared memory/named event 跨进程闭环。 - 与真实 CCLite 进程的联合运行。 - 真实 SPH-FEM 接触搜索、接触约束、摩擦、tied/release 和生产级 FSI。 - 连续体一部分 FEM、一部分 SPH 的生产级强耦合。 - 工程级船舶水下接触爆炸舱段破坏 benchmark。 ## 3. 模块边界 ### 3.1 SPHLite 继续负责 - SPH 粒子、phase、status、material、section、EOS 和时间推进。 - Water、Gas、Explosive、Solid、Shell 的内部物理。 - 显式 Velocity-Verlet 推进和稳定时间步估计。 - SPH 侧 coupling region 的定义、导出、载荷缓存、载荷施加和诊断。 - CSV/VTU/PVD、restart、错误码和 release gate。 ### 3.2 CCLite 负责 - 启动和调度 SPHLite worker。 - 创建、重置和销毁 Windows shared memory 与 named event。 - 读取 SPHLite region 数据和 FEMLite surface/facet 数据。 - 计算 SPH-FEM 接触、耦合、载荷投影、FSI 界面量和强/弱耦合控制。 - 将结果写回 SPHLite 和 FEMLite。 - 输出联合诊断和跨求解器守恒检查。 ### 3.3 SPHLite 不应做 - 直接依赖 FEMLite 模块或 FEMLite 内部结构。 - 在公开 ABI 中出现 FEMLite 私有类型。 - 直接链接 CCLite 的 Fortran95 算法核心。 - 在 SPHLite 核心物理模块中复制 CCLite 的 SPH-FEM 接触搜索算法。 - reset 或销毁由 CCLite 持有的 named event/shared memory。 - 把 worker 通信闭环宣称为真实接触或 FSI 算法完成。 ## 4. Worker/Service 建议 worker/service 是当前相对原建议最大的缺口。建议新增为独立 adapter,优先放在 `src/app` 或独立 `src/cclite_worker` 目录,避免侵入 Water/Gas/Solid/Shell 等物理模块。 建议 CLI: ```text sphlite.exe --cclite-worker --solver-id SPH --case sphlite.inp --ipc-name ``` 可选参数: ```text --command-block --data-prefix --log --timeout-ms --worker-id ``` 未指定 `--cclite-worker` 时,现有 CLI 行为必须保持不变: ```text sphlite model.inp --check sphlite model.inp --run --output result ``` worker 主循环建议: ```text initialize worker adapter open command block and data blocks signal READY while true: wait COMMAND_EVENT read command sequence and command kind INIT: reset worker-side state READ_INPUT: call sphlite_read_inp BUILD_MODEL: call sphlite_build_model EXPORT_INTERFACE: export region particles/facets through current CouplingInterface IMPORT_LOADS: import forces/facet loads/contact/motion data ADVANCE: call sphlite_advance_explicit or a worker-controlled substep loop WRITE_OUTPUT: call sphlite_write_output STOP: signal DONE and exit write ack sequence, worker state and error code signal DONE_EVENT ``` worker 只 wait/signal,不 reset event。event 生命周期和 shared memory 生命周期由 CCLite 持有。 当前 worker 入口参数、状态枚举、命令枚举、ack 序号和错误码记录在 [CCLite Worker Protocol](cclite_worker_protocol.md)。IPC 句柄、READY/DONE、wait/signal 和错误路径记录在 [CCLite Worker IPC Adapter](cclite_worker_ipc_adapter.md)。worker 命令到现有 API 的动作映射记录在 [CCLite Worker API Mapping](cclite_worker_api_mapping.md)。诊断输出记录在 [CCLite Worker Diagnostics](cclite_worker_diagnostics.md),mock 联调覆盖记录在 [CCLite Worker Mock Plan](cclite_worker_mock_plan.md)。0.8.x 阶段已形成 CLI、能力查询、mock adapter、Windows shared memory/named event attach/loop self-test、worker 主循环骨架和数据块诊断输出;真实外部 CCLite 进程联调与生产级接触/FSI 仍在后续阶段验收。 ## 5. Coupling 数据契约建议 SPHLite 已经具备 region 导出与载荷导入的基础,因此不建议重写当前 ABI。建议采用“保留现有 ABI + 增量 v2 字段”的方式。 当前字段清单、数组展开顺序、external id/export index 边界和 v2 预留字段记录在 [CCLite Coupling Manifest](cclite_coupling_manifest.md)。后续 worker IPC 和 shared memory 数据块设计应优先对齐该 manifest,再决定是否新增稳定 ABI。 ### 5.1 当前 ABI 保持稳定 现有接口继续作为 0.8.x 稳定契约: - `sphlite_coupling_get_region_count` - `sphlite_coupling_get_region_info` - `sphlite_coupling_get_region_modes` - `sphlite_coupling_export_particles` - `sphlite_coupling_export_facets` - `sphlite_coupling_apply_particle_forces` - `sphlite_coupling_apply_facet_loads` - `sphlite_coupling_apply_facet_pressures` - `sphlite_coupling_apply_facet_tractions` - `sphlite_coupling_apply_facet_resultants` - `sphlite_coupling_apply_contact_state` - `sphlite_coupling_apply_motion_boundary` - `sphlite_coupling_get_load_balance` - `sphlite_coupling_get_contact_diagnostics` - `sphlite_coupling_get_diagnostics` ### 5.2 建议新增 v2 字段 外部建议中有价值但当前 ABI 尚未稳定暴露的字段,可进入 v2: - `body_id` - `contact_radius` - `sound_speed` - `valid_flags` - `source_id` - `pair_id` - `load_mode` - `contact_state` - `moment[3]` - `interface_pressure` - `interface_velocity` 建议 v2 仍沿用 caller-allocated buffer 风格,数组展开保持当前 C ABI 习惯: ```text x[dim + 3 * particle] v[dim + 3 * particle] forces[dim + 3 * particle] moments[dim + 3 * particle] ``` 粒子 id 建议长期保留 external id 和 internal/export index 两套路径: - worker/shared memory 可使用 external id 便于跨模块追踪。 - 当前 C ABI 可继续使用 region index + export index,避免破坏已有测试。 ## 6. 外部载荷和接触状态 SPHLite 当前已支持粒子力、facet load、pressure/traction/resultant、contact state 和 motion boundary。后续补强重点不应是“能否导入”,而应是“导入记录可追踪、可拒绝、可诊断、可复现”。 建议新增或扩展: - force/facet/contact record 的 `source_id` 和 `pair_id`。 - force record 的非有限值拒绝原因分类。 - particle id 未匹配计数。 - contact state 枚举:`inactive/candidate/active/released/tied`。 - tied/release 对 Solid/Shell damage/release 状态的只读诊断映射。 - 每个 coupling region 的输入总力、总力矩、分配后总力、分配后总力矩和误差。 - 每步清零与 repeated/stale epoch 的清晰策略。 现有 0.8.1 的 `coupling_stale_epoch_081`、`coupling_load_balance_081`、`coupling_contact_diagnostics_081` 应作为这些扩展的回归基础。 ## 7. Boundary/Ghost 与 FSI 预留 Boundary/Ghost 和 Riemann FSI 不建议抢在 worker IPC 之前实现为生产能力。建议先冻结数据契约,再接入物理边界模型。 建议预留的数据: - boundary/ghost state id。 - position、velocity、normal。 - pressure、density、sound speed。 - interface pressure、interface velocity。 - state mode 和 valid flags。 建议后续接口草案: ```c int sphlite_coupling_apply_boundary_states(int num_states, const long long *state_id, const double *x, const double *v, const double *normal, const double *pressure, const double *density, const double *sound_speed, const int *state_mode, const int *valid_flags); ``` 该接口只导入外部边界状态,不规定 SPHLite 内部如何参与 SPH 邻域求和;内部处理应由 Water/Gas/Solid/Shell 或专门边界模型决定。 ## 8. 输入文件建议 当前 `*SPHLITE COUPLING REGION` 已经比原建议更完整,应继续沿用现有语法,不建议另起一套 `SPH_REGION` 关键词。 推荐继续使用: ```text *SPHLITE COUPLING REGION, NAME=..., SET=..., TYPE=CONTACT, EXPORT=PARTICLE|FACET|BOTH, IMPORT=FORCE|FACET_LOAD|MOTION, LOAD_MODE=PARTICLE_FORCE|FACET_FORCE|PRESSURE|TRACTION, DISTRIBUTION=UNIFORM|AREA|MASS, CONTACT_STATE=OFF|IMPORT, ENABLED=YES ``` `*SPHLITE CCLITE` 可作为后续 worker 辅助开关,但不应替代 CCLite 自身配置文件。若增加该关键词,建议只表达 SPHLite 侧开关: ```text *SPHLITE CCLITE, WORKER=YES, REGION=..., EXPORT_RADIUS=YES, EXPORT_SOUND_SPEED=YES, ACCEPT_CONTACT_STATE=YES ``` ## 9. 建议路线 ### 9.1 近期:0.8.x 稳定化 - 保持 0.8.0/0.8.1 coupling ABI 不破坏。 - 更新文档中 `Output` 对 VTU/PVD 的描述。 - 保持 `examples/infinite_underwater_explosion` 的 VTU/PVD 和双击运行脚本可用。 - 使用 `tools/publish_to_cclite.*` 发布到 `..\CCLite\SPHLite`,并确保发布版 examples 指向 `cpu_release/cpu_debug`。 - 增加 CCLite 集成前的 schema 文档或 manifest,列出 region、particle、facet、load、diagnostics 字段。 ### 9.2 下一阶段:CCLite worker 通信闭环 - 已增加 `--cclite-worker` 参数解析骨架;非 Windows 或资源缺失时返回受控 `UNSUPPORTED`/`IPC`。 - 已实现 command block/data block 名称抽象、READY/DONE、wait/signal、error code 的 mock adapter 和 Windows shared memory/named event attach 骨架。 - 已支持 `INIT/READ_INPUT/BUILD_MODEL/EXPORT_INTERFACE/IMPORT_LOADS/ADVANCE/WRITE_OUTPUT/STOP` 的状态/动作映射,并接入粒子导出、粒子力导入、contact state 导入和 worker diagnostics 输出。 - 已完成 100 step 空耦合、空/固定粒子导出、空/粒子力/contact state 导入和异常命令的 CCLite mock 联调测试,并完成 SPHLite 侧 Windows IPC self-test。 - 已通过普通 CLI 回归,C ABI、C++ wrapper 和 Python wrapper 仍保持原有路径。 ### 9.3 后续:数据契约 v2 - 已形成不破坏当前 ABI 的 v2 数据字段草案。 - 已预留 source id、pair id、body id、contact radius、sound speed、moment 和 valid flags。 - 已增加 boundary/ghost 状态缓存和清零 smoke 测试;该能力仍标记为预留,不是生产级 FSI。 - pressure projection 和 Riemann FSI 物理接入仍为后续工作。 ### 9.4 长期:水下爆炸 FSI 工程链路 - CCLite 侧完成真实 SPH-FEM 接触/FSI 载荷,SPHLite 侧只接收中立载荷和边界状态。 - SPHLite 提供 Water/Gas/Explosive/Solid/Shell 的可视化输出、restart 和诊断。 - 建立无限水域爆炸、单壁面反射、简化板壳响应、舱段局部破坏等逐级 benchmark。 ## 10. 测试建议 ### 10.1 Worker gate - worker 启动和参数解析。 - READY/DONE 状态切换。 - command seq/ack 一致性。 - named event wait/signal。 - 超时、STOP 和异常退出。 - 空 coupling、固定粒子导出、空载荷导入。 - 普通 CLI 回归。 ### 10.2 Coupling 数据 gate - 单粒子 region 导出。 - 多粒子 region 导出。 - facet proxy 导出。 - pressure、density、h、temperature、internal energy 导出。 - sound speed/contact radius v2 导出。 - 粒子力导入、facet pressure/traction/resultant 导入。 - contact state、gap、penetration、normal 导入。 - stale/repeated epoch 和非有限载荷拒绝。 ### 10.3 FSI/工程预留 gate - 均匀压力场导出。 - 水相 pressure projection 小算例。 - boundary/ghost 状态导入 smoke。 - 一维声阻抗 Riemann 状态导出。 - 水下爆炸工程简化算例预留。 ## 11. 验收口径 后续与 CCLite 的任一版本联调,都应满足: - SPHLite 独立运行能力不退化。 - 公开 C ABI、C++ wrapper、Python wrapper 不破坏已有调用。 - 不新增 FEMLite 直接依赖。 - worker adapter 不侵入核心物理模块。 - shared memory/event 生命周期仍由 CCLite 持有。 - 输出 CSV/VTU/PVD、restart 和 coupling diagnostics 可用于复核。 - release gate 至少覆盖完整 CTest、coupling 专项 gate、source size 和 `git diff --check`。 ## 12. 优先级 最高优先级: 1. CCLite worker/service adapter。 2. command block、data block、named event 的通信闭环。 3. 当前 CouplingInterface 字段 manifest。 4. 与 CCLite mock 的空耦合和固定粒子联调。 5. 输出与诊断:worker log、particle report、force report、VTU/PVD。 次优先级: 1. v2 ABI 字段:source id、pair id、valid flags、contact radius、sound speed。 2. 更细的 contact state 枚举和 tied/release 诊断。 3. boundary/ghost 状态导入。 4. Riemann FSI 所需 EOS/material 信息。 5. rollback 或强耦合迭代预留。 暂不建议在 SPHLite 内部实现: - FEMLite surface 读取。 - FEM-SPH 接触搜索。 - CCLite 接触算法核心。 - 生产级摩擦/绑定/释放约束。 - 外部耦合模块的调度器。 ## 13. 新增建议逐条响应 `..\CCLite\sphlite_suggests.md` 第 15 节新增建议的核心判断是:SPHLite 0.8.2 已具备 worker 参数识别和 mock 契约,但真实 Windows shared memory/named event IPC worker 尚未闭合。0.8.3 已补齐 SPHLite 侧 Windows IPC self-test;真实外部 CCLite 进程联调仍需由 CCLite gate 验收。SPHLite 的修订响应如下。 | 新建议 | SPHLite 修订响应 | 状态与落点 | | --- | --- | --- | | 完整支持 CCLite 标准 worker 参数 | 保留 `--cclite-worker --solver-id SPH --case sphlite.inp --ipc-name ... --timeout-ms ...` 作为正式入口,普通 CLI 行为不得变化;参数缺失、冲突和未知参数应返回受控错误。 | 0.8.3 已完成参数骨架、mock 测试和 SPHLite 侧 Windows IPC self-test;真实外部 CCLite 进程联调继续加严校验。 | | 实现真实 IPC worker 主循环 | 新增 Windows IPC adapter,打开 CCLite 创建的 command block、data block、command event 和 done event;非 Windows 平台返回明确 unsupported。 | 已完成 SPHLite 侧 attach/loop self-test;真实外部 CCLite 进程联调仍待验收。 | | READY 与命令 ack 回写 | worker 启动后写入 `READY`;每条命令后回写 `ack_seq`、`worker_state`、`error_code` 和短消息。 | 已写入共享内存命令块,并由 Windows IPC self-test 覆盖。 | | 只 wait/signal,不 reset event | SPHLite 只等待 command event、触发 done event;event reset、创建和销毁由 CCLite 持有。 | 作为不可破坏边界写入 worker gate。 | | 优先闭合 `SPH_TO_CCL_PARTICLE` | 共享内存数据块先支持空粒子和固定粒子,再映射真实 coupling region 粒子导出;字段以 `cclite_coupling_manifest.md` 为准。 | 已实现 particle AOR v1 数据块导出、校验和 particle report;facet 数据块待补。 | | 优先闭合 `CCL_TO_SPH_FORCE` | 共享内存导入先支持空 force block,再支持粒子力、接触状态和诊断字段;不得让 CCLite 直接写内部加速度/速度数组。 | 已实现 particle force/contact state ingest、stale/repeated/nonfinite 拒绝计数和 force report;facet load/motion 待补。 | | 导出粒子严格检查 | 导出前检查有限值、有效半径、有效质量、有效状态、有效 external id 和有效 internal/export index;不合格粒子计数并跳过。 | 已进入 worker block 校验和 particle report。 | | 导入 force record 严格检查 | 导入时检查 particle id、internal/export index、有限值、step_id、valid_flags 和重复/过期 epoch;无法匹配或非法记录拒绝并计数。 | 已进入 worker block 校验、force report 和 worker log total force/moment。 | | 增加能力查询入口 | 新增 `sphlite.exe --cclite-capabilities`,输出 solver、worker 支持、IPC backend、command block version、data layout、real IPC 支持状态和记录容量。 | 已实现;Windows 构建报告 `supports_real_ipc=yes`,非 Windows 构建报告 `supports_real_ipc=no`。 | | 增加 SPHLite 侧 self-test/smoke case | 在没有 FEMLite 的情况下验证 worker 启动、IPC attach、READY、空粒子导出、空 force 导入和 STOP 退出。 | 已增加 mock smoke 与 Windows IPC self-test。 | | 与 CCLite 先验收三类联调路径 | 先验收真实 SPHLite + mock FEM 的 1 step 空耦合、100 step 空耦合、异常输入/超时可控退出。 | SPHLite 提供 worker、能力查询和诊断;跨进程调度由 CCLite gate 负责。 | | mock 不等同真实耦合完成 | release note、测试名和能力查询必须区分 `mock worker`、`real IPC worker`、`real contact/FSI`。 | 0.8.2 可称为 SPHLite 侧 real IPC self-test 已覆盖,但不宣称真实外部 CCLite 联调或真实耦合完成。 | ## 14. 原始建议覆盖清单 为避免遗漏,原始建议 1 到 16 章按以下口径完整响应: | 原始章节 | 响应 | | --- | --- | | 1 总体建议 | 采纳。SPHLite 保持独立求解器身份,只新增中立 CouplingInterface 和 worker/service adapter。 | | 2 必须保持的边界 | 采纳。SPHLite、CCLite 和 FEMLite 的职责边界写入第 3 节,禁止 FEMLite 私有结构进入公开 ABI。 | | 3 0.1.x 必要改造 | 已按 SPHLite 0.8.3 现状重映射。参数识别、mock 闭环和 SPHLite 侧 Windows IPC self-test 已完成,真实外部 CCLite 进程联调列为下一阶段最高优先级。 | | 4 Worker/Service 模式 | 部分完成。0.8.3 已有 CLI、协议、mock adapter、Windows IPC adapter self-test 和命令映射;真实外部 CCLite 进程联调待实现。 | | 5 Coupling Region 导出 | 大部分完成。当前 ABI 已支持 region 粒子和 facet proxy 导出;`body_id`、`contact_radius`、`sound_speed`、`valid_flags` 进入 v2 契约。 | | 6 外部载荷导入 | 大部分完成。粒子力、facet load、pressure/traction/resultant 已支持;source id、pair id、moment、valid flags 和真实 IPC 拒绝计数待补强。 | | 7 接触状态导入 | 部分完成。normal、gap、penetration、contact pressure 已有诊断;inactive/candidate/active/released/tied 枚举和 tied/release 映射作为后续增强。 | | 8 Boundary/Ghost 与 FSI 预留 | 采纳为预留能力。先冻结数据契约和 smoke gate,不在真实 IPC 前宣称生产级 FSI。 | | 9 输入文件建议 | 修订采纳。继续沿用现有 `*SPHLITE COUPLING REGION`,不新增重复 `SPH_REGION` 关键词;`*SPHLITE CCLITE` 仅作为未来辅助开关。 | | 10 API/ABI 建议 | 修订采纳。保留现有 ABI,新增字段只进入 `_v2` 或 worker shared memory 契约,数组展开沿用 caller-allocated buffer 风格。 | | 11 与 CCLite 版本路线配合 | 修订采纳。SPHLite 不照搬 CCLite 版本号,而按当前 0.8.x 基线、下一阶段真实 IPC 和长期 FSI 路线映射。 | | 12 测试建议 | 采纳并扩展。worker、coupling 数据、FSI/工程预留 gate 已列入第 10 节,真实 IPC self-test 作为新增 gate。 | | 13 诊断建议 | 采纳。worker log、particle report、force report、错误码、短消息、总力和总力矩已作为 worker diagnostics 输出。 | | 14 优先级建议 | 采纳并重排。真实 IPC 闭环、能力查询、粒子/force 校验和 CCLite mock 联调列为最高优先级。 | | 15 真实 worker 接入闭环 | 新增逐条响应见第 13 节。该建议是下一阶段 SPHLite 与 CCLite 集成的主线。 | | 16 总结 | 采纳。SPHLite 提供稳定 region 数据、外部载荷通道、FSI 字段和诊断,不嵌入 FEMLite 或 CCLite 算法核心。 |