Files
CCLite/sphlite_suggests.md
T
2026-07-05 20:41:40 +08:00

592 lines
18 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.
# 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 <name>
```
可选参数:
```text
--command-block <name>
--data-prefix <prefix>
--log <path>
--timeout-ms <value>
--worker-id <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 和水下爆炸工程算例。