# SPHLite 配合 CCLite 的改造建议 ## Coupling & Contact Lite for SPHLite and FEMLite **对象**:SPHLite **目的**:使 SPHLite 能作为 CCLite 的独立 worker/service,参与 SPH-FEM 耦合、接触和后续 FSI 联合仿真。 **依据**:CCLite `01` 到 `06` 号文档、`v1.x_development_plan.md`、SPHLite 当前接口文档与能力说明。 **编码要求**:中文,UTF-8 without BOM。 # 1. 总体建议 SPHLite 不需要被改造成 CCLite 的内部库,也不应把 FEMLite 或 CCLite 的内部结构写入 SPHLite 核心物理模块。建议 SPHLite 保持独立主控程序身份,只新增一层面向 CCLite 的 worker/service 模式和 CouplingInterface。 SPHLite 对 CCLite 的核心责任是: 1. 在 worker 模式下接受 CCLite 的命令; 2. 按 coupling region 导出 SPH 粒子状态; 3. 可选导出 SPH 侧 facet、壳粒子或边界近似; 4. 接收 CCLite 写回的粒子力、接触状态、边界状态或后续 FSI 状态; 5. 将外部耦合载荷安全叠加到 SPH 显式求解; 6. 输出可检查的耦合诊断; 7. 保持 SPHLite 原独立运行、Fortran API、C ABI 和 Python 调试入口不被破坏。 建议把本改造定位为: ```text SPHLite 原有求解器 + SPHLite CCLite worker/service adapter + SPH CouplingInterface ``` 其中 adapter 只负责通信、命令和数据映射,不负责 CCLite 接触算法。 # 2. 必须保持的边界 ## 2.1 SPHLite 继续负责 SPHLite 继续负责: 1. SPH 粒子、材料、section、phase、EOS 和时间控制; 2. 水、气、炸药、solid、shell 等 SPH 内部物理; 3. SPH 邻域搜索、密度、压力、内力、人工粘性和稳定时间步; 4. SPH 内部结构/壳粒子的状态更新; 5. 显式动力学推进; 6. SPH 自身输出、restart 和诊断; 7. SPHLite 错误码和 release gate。 ## 2.2 CCLite 负责 CCLite 负责: 1. 启动和调度 SPHLite worker; 2. 创建和销毁 Windows shared memory 与 named event; 3. 读取 SPHLite coupling region; 4. 读取 FEMLite surface/facet; 5. 计算 SPH-FEM 接触、耦合和 FSI 界面载荷; 6. 把结果写回 SPHLite 和 FEMLite; 7. 输出联合诊断。 ## 2.3 SPHLite 不应做 SPHLite 不应: 1. 直接调度 FEMLite; 2. 直接读取 FEMLite 私有数据结构; 3. 在公开 ABI 中出现 FEMLite 内部类型; 4. 直接链接 CCLite Fortran95 算法核心; 5. 在自身内部复制 CCLite 的 SPH-FEM 接触搜索算法; 6. 修改 CCLite 创建的 event reset 责任; 7. 把 0.1.x 的通信闭环宣称为真实接触算法完成。 # 3. 0.1.x 必要改造 0.1.x 的目标是让 SPHLite 能参与 CCLite 空耦合和接口闭环,不要求真实 SPH-FEM 接触力验收。 SPHLite 侧建议完成: 1. 增加 `--cclite-worker` 命令行模式; 2. worker 模式能打开 CCLite 创建的 command block; 3. worker 模式能打开 CCLite 创建的 data block; 4. worker 模式能等待 `COMMAND_EVENT`; 5. worker 模式能触发 `DONE_EVENT`; 6. worker 只 wait/signal,不 reset event; 7. 支持 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`; 8. `substep_id=0`、`iteration_id=0`; 9. 可导出 0 个或少量固定 SPH 粒子; 10. 可接收空粒子力; 11. 可写出 worker 日志和接口诊断。 0.1.x 完成标准: 1. SPHLite 原独立运行入口不受影响; 2. CCLite 能启动 SPHLite worker; 3. SPHLite worker 能进入 `READY`; 4. SPHLite worker 可完成 100 step 空耦合; 5. SPHLite worker 可响应 `STOP`; 6. 异常时能写 `error_code`; 7. 资源由 CCLite 释放后,SPHLite worker 正常退出。 # 4. Worker/Service 模式建议 ## 4.1 启动方式 建议 SPHLite 支持: ```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`,SPHLite 仍按原 CLI 行为运行。 ## 4.2 Worker 主循环 建议 worker 主循环为: ```text initialize worker open command block open data blocks signal READY while true: wait COMMAND_EVENT read command block case INIT: initialize ipc-side state case READ_INPUT: read sphlite.inp case BUILD_MODEL: build SPH model and coupling regions case EXPORT_INTERFACE: write SPH_TO_CCL_PARTICLE case IMPORT_LOADS: read CCL_TO_SPH_FORCE case ADVANCE: advance one explicit step or worker-controlled step case WRITE_OUTPUT: write SPHLite output case STOP: signal DONE and exit write ack_seq update worker_state signal DONE_EVENT ``` 0.1.x 可暂不启用 `IMPORT_LOADS`,但应保留命令枚举。0.2.x 必须支持粒子力导入。 # 5. Coupling Region 导出建议 ## 5.1 导出对象 SPHLite 应按 coupling region 导出粒子状态,而不是导出全部内部数组。 0.2.x 接触至少需要: 1. external particle id; 2. internal index; 3. phase; 4. status; 5. material id; 6. section id; 7. body id; 8. position; 9. velocity; 10. mass; 11. density; 12. volume; 13. smoothing length; 14. contact radius; 15. pressure; 16. sound speed; 17. valid flags。 ## 5.2 接触半径 CCLite 04 号文档允许: 1. SPHLite 直接导出 `radius`; 2. 或 CCLite 根据 `h` 和输入参数估计 `radius = alpha_r h`。 建议 SPHLite 优先显式导出接触半径。该半径只用于跨域接触,不改变 SPHLite 内部核函数和邻域计算。 ## 5.3 Pressure 与 sound speed 为后续 FSI 和 Riemann FSI,建议从 0.2.x 起 SPHLite 粒子导出中保留: 1. pressure; 2. density; 3. sound speed; 4. internal energy,可选; 5. phase; 6. EOS/material id。 0.6.x pressure projection 和 0.7.x Riemann FSI 会使用这些字段。 ## 5.4 SPH facet 或壳粒子 若 SPHLite 已有壳粒子或粒子构成的表面 facet,建议保留 `SPH_TO_CCL_FACET` 的导出能力。 0.1.x 到 0.5.x 可为空 block。 0.6.x 以后用于: 1. SPH 边界近似; 2. SPH shell 与 FEM surface 耦合; 3. boundary/ghost particle 诊断; 4. FSI 接口状态。 # 6. 外部载荷导入建议 ## 6.1 0.2.x 必须支持 0.2.x 起 SPHLite 应支持 `CCL_TO_SPH_FORCE`。 基础 record: ```text particle_id force[3] moment[3] source_id load_mode contact_state valid_flags ``` 其中: 1. `force` 是 CCLite 计算的跨域接触或耦合力; 2. `moment` 第一阶段可为 0,壳粒子后续启用; 3. `source_id` 用于追踪 contact pair 或 FEM facet; 4. `contact_state` 用于诊断和后续 persistence; 5. `load_mode` 区分粒子力、接触状态、运动边界和后续 FSI 状态。 ## 6.2 外部载荷缓存 SPHLite 内部建议增加独立外部耦合载荷缓存: ```text sph_cclite_external_load particle_id_ext internal_index force[3] moment[3] source_id contact_state step_id active ``` 该缓存应在每个 CCLite step 开始前清零,导入后叠加到 SPH 动量方程或显式外力项。 不要让 CCLite 直接写 SPHLite 内部加速度、速度或力数组。 ## 6.3 力和冲量诊断 SPHLite 应输出或允许查询: 1. 本步接收的 CCLite 总力; 2. 本步接收的 CCLite 总力矩; 3. 每个 coupling region 的总力; 4. 被拒绝的 force record 数量; 5. 非有限载荷数量; 6. particle id 未匹配数量。 这些量用于 CCLite 的 `force_balance.csv` 和 06 号验证计划。 # 7. 接触状态导入建议 CCLite 会计算跨域接触状态。SPHLite 不需要重复计算 FEM 接触搜索,但可以接收接触状态,用于诊断、输出或后续物理处理。 建议支持: ```text contact_state = inactive / candidate / active / released / tied penetration normal[3] source_facet_id pair_id ``` 0.2.x 可只导入 `contact_state` 和 `pair_id`。 0.3.x 起可导入 `penetration` 和 `normal` 供输出。 0.5.x tied/release 后可导入 `released` 状态。 # 8. Boundary/Ghost 与 FSI 预留 0.6.x 起 CCLite 需要向 SPHLite 传递 FEM 运动边界、boundary particle 或 ghost particle 状态。 建议 SPHLite 预留: 1. 外部 boundary particle buffer; 2. 外部 ghost state buffer; 3. moving wall velocity; 4. wall normal; 5. boundary pressure; 6. boundary density; 7. interface pressure; 8. interface velocity。 SPHLite 如何把这些状态纳入内部 SPH 邻域求和,不由 CCLite 决定,应由 SPHLite 内部边界模型实现。 建议后续接口: ```c int sphlite_apply_coupling_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); ``` # 9. 输入文件建议 SPHLite 自身输入仍由 SPHLite 解析。为配合 CCLite,建议新增或明确以下关键词能力。 ## 9.1 Coupling region 建议支持类似: ```text *SPHLITE COUPLING REGION, NAME=CCL_SPH_REGION PHASE=SOLID,WATER,SHELL SET=... EXPORT_PARTICLES=YES EXPORT_PRESSURE=YES EXPORT_SOUND_SPEED=YES ACCEPT_EXTERNAL_FORCE=YES ``` CCLite `.inp` 中的 `SPH_REGION` 应引用该名称。 ## 9.2 CCLite 辅助开关 可选支持: ```text *SPHLITE CCLITE WORKER=YES REGION=CCL_SPH_REGION EXPORT_RADIUS=YES EXPORT_PRESSURE=YES EXPORT_SOUND_SPEED=YES ACCEPT_CONTACT_STATE=YES ACCEPT_BOUNDARY_STATE=NO ``` 该关键词只是 SPHLite 侧辅助开关,不替代 CCLite `.inp`。 # 10. API/ABI 建议 SPHLite 当前 05 号接口文档已经建议了 CouplingInterface。为贴合 CCLite 05 号文档,建议补强字段并保持中立命名,不出现 FEMLite 私有结构。 建议 C ABI: ```c int sphlite_get_coupling_particle_count(const char *region, int *count); int sphlite_get_coupling_particles_v2(const char *region, int max_particles, long long *particle_id_ext, int *internal_index, int *phase, int *status, int *material_id, int *section_id, int *body_id, double *x, double *v, double *mass, double *density, double *volume, double *h, double *radius, double *pressure, double *sound_speed, int *valid_flags, int *count); int sphlite_apply_coupling_particle_forces_v2(int num_particles, const long long *particle_id_ext, const double *forces, const double *moments, const long long *source_ids, const int *load_mode, const int *contact_state, const int *valid_flags); ``` 数组展开建议沿用 SPHLite 现有 C ABI 风格: ```text x[dim + 3 * particle] v[dim + 3 * particle] forces[dim + 3 * particle] moments[dim + 3 * particle] ``` 若需要保持旧 ABI,可把新增字段放入 `_v2` 接口,旧接口继续保留。 # 11. 与 CCLite 版本路线的配合 | CCLite 版本 | SPHLite 配合目标 | | --- | --- | | 0.1.x | worker/service、command block、named event、空粒子/固定粒子导出、空载荷接收 | | 0.2.x | coupling region 粒子完整导出、粒子力导入、单粒子撞面和多粒子压面验证 | | 0.3.x | 壳粒子、接触半径、接触状态、pair id 和 persistence 诊断 | | 0.4.x | 阻尼/摩擦所需切向速度、接触功和摩擦耗能诊断 | | 0.5.x | tied/release 所需绑定粒子、damage/release 状态和 tie-to-contact 诊断 | | 0.6.x | pressure projection、boundary/ghost particle 和 FEM 运动边界支持 | | 0.7.x | Riemann FSI 所需 pressure、density、sound speed、EOS/material id | | 0.8.x | 稳定化、长时间运行、异常输入和 AoR/SoA 性能对比 | | 0.9.x | 水下爆炸 FSI、工程简化算例、参数推荐和性能基线 | # 12. 测试建议 ## 12.1 0.1.x 测试 SPHLite 侧建议新增: 1. worker 启动测试; 2. worker `READY` 状态测试; 3. command seq/ack 测试; 4. named event wait/signal 测试; 5. 空粒子导出测试; 6. 固定粒子导出测试; 7. 空载荷导入测试; 8. `STOP` 正常退出测试; 9. 超时和错误码测试。 ## 12.2 0.2.x 测试 建议新增: 1. 单粒子 coupling region 导出; 2. 多粒子 coupling region 导出; 3. pressure 和 sound speed 导出; 4. radius 与 h 字段一致性检查; 5. 粒子力导入; 6. particle id 未匹配错误; 7. 非有限载荷拒绝; 8. 与 CCLite 的 `V020_SINGLE_PARTICLE_WALL` 联合测试。 ## 12.3 FSI 测试 建议保留或新增: 1. 均匀压力场导出; 2. 水相 pressure projection 小算例; 3. boundary/ghost 状态导入 smoke; 4. 一维声阻抗 Riemann 状态导出; 5. 水下爆炸工程简化算例预留。 # 13. 诊断建议 SPHLite worker 应至少输出: 1. worker 启动参数; 2. CCLite command block 名称; 3. data block 名称; 4. 当前 command id; 5. step id; 6. ack seq; 7. worker state; 8. 导出粒子数量; 9. 接收 force 数量; 10. 接收总力; 11. 接收总力矩; 12. coupling region 名称; 13. 非有限粒子状态数量; 14. 错误码和错误消息。 建议输出文件: ```text sphlite_cclite_worker.log sphlite_cclite_particle_report.csv sphlite_cclite_force_report.csv ``` # 14. 优先级建议 最高优先级: 1. worker/service 模式; 2. command block 与 named event; 3. coupling region 粒子导出; 4. 空载荷和粒子力导入; 5. pressure、density、sound speed 字段预留; 6. 诊断输出; 7. 与 CCLite mock/空耦合联调。 次优先级: 1. 接触状态导入; 2. SPH facet 或壳粒子导出; 3. boundary/ghost 状态; 4. tied/release 状态; 5. Riemann FSI EOS 信息; 6. rollback/强耦合预留。 # 15. 当前补充建议:真实 worker 接入闭环 根据 CCLite 0.1.9 对当前本地 SPHLite 的审计结果,SPHLite 已能识别 CCLite worker 启动参数,但真实 Windows shared memory / named event IPC worker 尚未闭合。建议当前不要继续扩散新物理算法需求,先把 SPHLite 与 CCLite 的真实 worker 接入做成可重复验收的最小闭环。 近期建议按以下顺序推进: 1. 完整支持 CCLite 标准 worker 参数: ```text sphlite.exe --cclite-worker --solver-id SPH --case sphlite.inp --ipc-name CCLITE_CASE001 --timeout-ms 30000 ``` 2. 实现真实 IPC worker 主循环,能够打开 CCLite 创建的 command block、data block、command event 和 done event。 3. worker 启动后应进入 `READY`,每条命令执行后回写 `ack_seq`、`worker_state`、`error_code` 和短消息。 4. worker 只负责 wait/signal,不负责 reset CCLite 创建的 event。 5. 优先闭合 `SPH_TO_CCL_PARTICLE`,先支持空粒子、固定粒子,再支持真实 coupling region 粒子导出。 6. 优先闭合 `CCL_TO_SPH_FORCE`,先支持空 force block,再支持粒子力、接触状态和诊断字段导入。 7. 对所有导出粒子检查有限值、有效半径、有效质量、有效状态和有效 id;不合格粒子应计入诊断,不应静默写入。 8. 对所有导入 force record 检查粒子 id、`internal_index`、有限值、`step_id` 和 `valid_flags`;无法匹配的 record 应拒绝并输出计数。 9. 增加 CCLite 能力查询入口,建议命令为: ```text sphlite.exe --cclite-capabilities ``` 建议输出至少包含: ```text solver=SPHLite cclite_worker=yes ipc_backend=windows_shmem_named_event command_block_version=1 data_layout=AOR_V1 supports_real_ipc=yes/no supports_sph_to_ccl_particle=yes/no supports_ccl_to_sph_force=yes/no max_particle_records=... ``` 10. 增加 SPHLite 侧 self-test 或 smoke case,能够在没有 FEMLite 的情况下验证:worker 启动、IPC attach、`READY`、空粒子导出、空 force 导入、`STOP` 正常退出。 11. 与 CCLite 联调时先验收三类路径:`真实 SPHLite + mock FEM` 的 1 step 空耦合、`真实 SPHLite + mock FEM` 的 100 step 空耦合、异常输入/超时可控退出。 12. 在上述闭环完成前,不建议把 SPHLite worker mock 或参数识别视为真实耦合接入完成。 # 16. 总结 SPHLite 配合 CCLite 的关键不是让 SPHLite 直接处理 FEM 接触,而是提供稳定的粒子/region 数据和外部载荷通道。 建议 SPHLite 的改造口径为: ```text 保持独立主控程序 增加 CCLite worker/service 模式 按 coupling region 导出粒子状态 接收 CCLite 粒子力/接触状态/边界状态 提供 pressure、density、sound speed 等 FSI 字段 提供诊断和错误码 不依赖 FEMLite 内部结构 不嵌入 CCLite 算法核心 ``` 这样 SPHLite 能在 0.1.x 参与通信闭环,在 0.2.x 支撑基础 SPH-FEM penalty contact,在后续版本支撑壳粒子、tied/release、boundary/ghost、Riemann FSI 和水下爆炸工程算例。