22 KiB
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 的内部算法结构写入核心物理模块。推荐的集成口径是:
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:
sphlite.exe --cclite-worker --solver-id SPH --case sphlite.inp --ipc-name <name>
可选参数:
--command-block <name>
--data-prefix <prefix>
--log <path>
--timeout-ms <value>
--worker-id <id>
未指定 --cclite-worker 时,现有 CLI 行为必须保持不变:
sphlite model.inp --check
sphlite model.inp --run --output result
worker 主循环建议:
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。IPC 句柄、READY/DONE、wait/signal 和错误路径记录在 CCLite Worker IPC Adapter。worker 命令到现有 API 的动作映射记录在 CCLite Worker API Mapping。诊断输出记录在 CCLite Worker Diagnostics,mock 联调覆盖记录在 CCLite Worker Mock Plan。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。后续 worker IPC 和 shared memory 数据块设计应优先对齐该 manifest,再决定是否新增稳定 ABI。
5.1 当前 ABI 保持稳定
现有接口继续作为 0.8.x 稳定契约:
sphlite_coupling_get_region_countsphlite_coupling_get_region_infosphlite_coupling_get_region_modessphlite_coupling_export_particlessphlite_coupling_export_facetssphlite_coupling_apply_particle_forcessphlite_coupling_apply_facet_loadssphlite_coupling_apply_facet_pressuressphlite_coupling_apply_facet_tractionssphlite_coupling_apply_facet_resultantssphlite_coupling_apply_contact_statesphlite_coupling_apply_motion_boundarysphlite_coupling_get_load_balancesphlite_coupling_get_contact_diagnosticssphlite_coupling_get_diagnostics
5.2 建议新增 v2 字段
外部建议中有价值但当前 ABI 尚未稳定暴露的字段,可进入 v2:
body_idcontact_radiussound_speedvalid_flagssource_idpair_idload_modecontact_statemoment[3]interface_pressureinterface_velocity
建议 v2 仍沿用 caller-allocated buffer 风格,数组展开保持当前 C ABI 习惯:
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。
建议后续接口草案:
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 关键词。
推荐继续使用:
*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 侧开关:
*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. 优先级
最高优先级:
- CCLite worker/service adapter。
- command block、data block、named event 的通信闭环。
- 当前 CouplingInterface 字段 manifest。
- 与 CCLite mock 的空耦合和固定粒子联调。
- 输出与诊断:worker log、particle report、force report、VTU/PVD。
次优先级:
- v2 ABI 字段:source id、pair id、valid flags、contact radius、sound speed。
- 更细的 contact state 枚举和 tied/release 诊断。
- boundary/ghost 状态导入。
- Riemann FSI 所需 EOS/material 信息。
- 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 算法核心。 |