# 12 CCLite 集成建议 文档状态:建议稿 本文从 `..\CCLite\sphlite_suggests.md` 提取建议,并按 SPHLite 当前 0.8.2 能力进行修订。原文件中许多 0.1.x/0.2.x 的“起步改造”在 SPHLite 侧已经由 0.8.0/0.8.1 的 `CouplingInterface` 和 0.8.2 worker mock 契约覆盖,因此本文不再原样沿用版本号,而是按“现状、缺口、建议路线和验收”重新组织。 ## 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.2,SPHLite 已具备以下与 CCLite 集成相关的基础: - Fortran 95 核心求解器,C ABI、C++ 薄包装、Python `ctypes` 和 CLI 均可用。 - `*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.2 worker release gate 已覆盖 worker CLI、协议、IPC mock、命令映射、v2 契约、诊断格式和 CCLite mock command/data block。 当前仍未交付的内容: - CCLite worker/service IPC 模式。 - Windows 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 阶段只把入口、mockable adapter 和纯逻辑协议骨架稳定下来,真实 IPC 在后续阶段实现。 ## 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` 参数解析骨架;真实 IPC 未实现时返回受控 `UNSUPPORTED`。 - 已实现 command block/data block 名称抽象、READY/DONE、wait/signal 和 error code 的 mock adapter;真实 shared memory/named event 仍未实现。 - 已支持 `INIT/READ_INPUT/BUILD_MODEL/EXPORT_INTERFACE/IMPORT_LOADS/ADVANCE/WRITE_OUTPUT/STOP` 的状态/动作映射。 - 已完成 100 step 空耦合、空/固定粒子导出、空/粒子力/facet load 导入和异常命令的 CCLite mock 联调测试。 - 已通过普通 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 接触算法核心。 - 生产级摩擦/绑定/释放约束。 - 外部耦合模块的调度器。