Files
SPHLite/docs/12_cclite_integration_suggestions.md
T
2026-07-05 17:00:13 +08:00

364 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <name>
```
可选参数:
```text
--command-block <name>
--data-prefix <prefix>
--log <path>
--timeout-ms <value>
--worker-id <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 接触算法核心。
- 生产级摩擦/绑定/释放约束。
- 外部耦合模块的调度器。