Files
CCLite/sphlite_suggests.md
T
2026-07-05 16:34:52 +08:00

15 KiB
Raw Blame History

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 调试入口不被破坏。

建议把本改造定位为:

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 支持:

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,SPHLite 仍按原 CLI 行为运行。

4.2 Worker 主循环

建议 worker 主循环为:

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:

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 内部建议增加独立外部耦合载荷缓存:

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 接触搜索,但可以接收接触状态,用于诊断、输出或后续物理处理。

建议支持:

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 内部边界模型实现。

建议后续接口:

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

建议支持类似:

*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 辅助开关

可选支持:

*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:

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 风格:

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. 错误码和错误消息。

建议输出文件:

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. 总结

SPHLite 配合 CCLite 的关键不是让 SPHLite 直接处理 FEM 接触,而是提供稳定的粒子/region 数据和外部载荷通道。

建议 SPHLite 的改造口径为:

保持独立主控程序
增加 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 和水下爆炸工程算例。