Files
CCLite/SPHLite/docs/12_cclite_integration_suggestions.md
2026-07-05 22:48:27 +08:00

22 KiB
Raw Permalink Blame History

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_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 习惯:

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. 优先级

最高优先级:

  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 算法核心。