Files
SPHLite/docs/cclite_coupling_manifest.md
2026-07-05 21:41:34 +08:00

362 lines
14 KiB
Markdown
Raw Permalink 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.
# CCLite Coupling Manifest
文档状态:0.8.x 集成预研稿
本文记录 SPHLite 与 CCLite worker/service adapter 之间的当前数据契约。它不替代 05 号接口控制文档,也不要求 SPHLite 直接依赖 CCLite 或 FEMLite;它只把当前 0.8.3 可用的 coupling ABI、CLI 诊断、worker IPC self-test 契约和后续 v2 预留字段整理成可检查清单。
## 1. 范围复核
SPHLite 当前保持独立求解器定位。CCLite 负责 worker 启动、shared memory、named event、跨求解器接触/FSI 载荷计算和联合诊断;SPHLite 侧只提供中立 CouplingInterface、可选 worker adapter、输入输出和诊断。
当前已经具备的能力:
- `*SPHLITE COUPLING REGION` 支持 `TYPE=CONTACT/CONTINUUM`。
- region 支持 `EXPORT=PARTICLE/FACET/BOTH`。
- region 支持 `IMPORT=FORCE/FACET_LOAD/MOTION`。
- facet load 支持 `PRESSURE`、`TRACTION` 和 resultant 类导入。
- facet load 分配支持 `UNIFORM`、`AREA` 和 `MASS`。
- contact state 支持法向、gap、penetration 和 contact pressure 导入诊断。
- motion boundary 支持 velocity/position target 的 direct 模式。
- 输出侧已具备 CSV、summary CSV、VTU、PVD 和 restart。
- release gate 已覆盖 0.8.0/0.8.1 coupling 输入、导入、导出、restart、Fortran/C/C++/Python/CLI、0.8.2 worker mock、0.8.3 worker IPC self-test 和 source size。
当前仍不承诺的能力:
- CCLite worker IPC 的生产级实现。
- Windows shared memory 与 named event 生命周期管理。
- 真实 SPH-FEM 接触搜索、接触约束、摩擦、tied/release 和生产级 FSI。
- 连续体一部分 FEM、一部分 SPH 的生产级强耦合。
worker 通信闭环只代表 SPHLite 可以按外部命令读入、建模、导出、导入载荷、推进和写出;它不等同于真实接触或 FSI 算法完成。
## 2. Region Info
当前 C ABI:
```c
sphlite_coupling_get_region_count
sphlite_coupling_get_region_info
```
`region_info` 字段:
| 字段 | 含义 |
|---|---|
| `region_index` | 1-based region 序号,由调用方传入 |
| `name` | coupling region 名称 |
| `region_type` | `CONTACT` 或 `CONTINUUM` |
| `export_mode` | `PARTICLE`、`FACET` 或 `BOTH` |
| `import_mode` | `FORCE`、`FACET_LOAD` 或 `MOTION` |
| `enabled` | 是否启用 |
| `particle_count` | region 内可导出粒子数量 |
| `facet_count` | region 内可导出 facet 数量 |
## 3. Region Modes
当前 C ABI:
```c
sphlite_coupling_get_region_modes
```
`region_modes` 字段:
| 字段 | 含义 |
|---|---|
| `load_mode` | `PARTICLE_FORCE`、`FACET_FORCE`、`PRESSURE` 或 `TRACTION` |
| `distribution_mode` | `UNIFORM`、`AREA` 或 `MASS` |
| `contact_state_mode` | `OFF` 或 `IMPORT` |
## 4. Particle Export
当前 C ABI:
```c
sphlite_coupling_export_particles
```
粒子字段:
| 字段 | 含义 |
|---|---|
| `ext_ids` | 输入文件粒子外部 id |
| `internal_indices` | SPHLite 内部粒子序号 |
| `phases` | Water、Gas、Explosive、Solid、Shell 等 phase |
| `statuses` | active、inactive、failed 等状态 |
| `materials` | material id |
| `sections` | section id |
| `scalar_values[0]` | mass |
| `scalar_values[1]` | volume |
| `scalar_values[2]` | density |
| `scalar_values[3]` | pressure |
| `scalar_values[4]` | internal energy |
| `scalar_values[5]` | temperature |
| `scalar_values[6]` | smoothing length `h` |
| `vector_values[0]` | position `x[3]` |
| `vector_values[1]` | velocity `v[3]` |
| `vector_values[2]` | acceleration `a[3]` |
## 5. Facet Export
当前 C ABI:
```c
sphlite_coupling_export_facets
```
facet 字段:
| 字段 | 含义 |
|---|---|
| `facet_ids` | region 内 facet id |
| `particle_ids` | facet 关联粒子 id |
| `materials` | facet material id |
| `sections` | facet section id |
| `vector_values[0]` | facet center `x[3]` |
| `vector_values[1]` | facet velocity `v[3]` |
| `vector_values[2]` | facet normal `n[3]` |
| `area_values` | facet area |
## 6. Load Import
当前 C ABI:
```c
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
```
导入字段:
| 接口 | 字段 |
|---|---|
| particle force | `region_index`、`force_count`、`export_indices`、`forces[3]` |
| generic facet load | `region_index`、`load_count`、`facet_ids`、`loads[3]` |
| facet pressure | `region_index`、`load_count`、`facet_ids`、`pressures`、`distribution_mode`、`coupling_step` |
| facet traction | `region_index`、`load_count`、`facet_ids`、`tractions[3]`、`distribution_mode`、`coupling_step` |
| facet resultant | `region_index`、`load_count`、`facet_ids`、`resultants[3]`、`distribution_mode`、`coupling_step` |
`distribution_mode` 由外部调用明确传入,便于 CCLite 在同一 region 内复核 SPHLite 侧分配策略。
## 7. Contact And Motion Import
当前 C ABI:
```c
sphlite_coupling_apply_contact_state
sphlite_coupling_apply_motion_boundary
```
contact state 字段:
| 字段 | 含义 |
|---|---|
| `region_index` | region 序号 |
| `contact_count` | contact record 数量 |
| `facet_ids` | contact 所在 facet |
| `normals[3]` | 外部接触法向 |
| `gaps` | gap |
| `penetrations` | penetration |
| `contact_pressures` | contact pressure |
| `coupling_step` | 外部耦合步序号 |
motion boundary 字段:
| 字段 | 含义 |
|---|---|
| `region_index` | region 序号 |
| `export_index` | region 粒子导出序号 |
| `target_kind` | velocity 或 position |
| `mode` | direct 或 penalty;当前 direct 是可用主路径 |
| `target[3]` | 目标速度或目标位置 |
## 8. Diagnostics
当前 C ABI:
```c
sphlite_coupling_get_load_balance
sphlite_coupling_get_contact_diagnostics
sphlite_coupling_get_diagnostics
```
load balance 字段:
| 字段 | 含义 |
|---|---|
| `input_force[3]` | 外部输入总力 |
| `distributed_force[3]` | SPHLite 分配后总力 |
| `force_error` | 总力误差 |
| `input_moment[3]` | 外部输入总力矩 |
| `distributed_moment[3]` | SPHLite 分配后总力矩 |
| `moment_error` | 总力矩误差 |
contact diagnostics 字段:
| 字段 | 含义 |
|---|---|
| `counts[0..6]` | active、skipped、stale、invalid、nonfinite 等 contact 计数,容量为 `SPHLITE_COUPLING_CONTACT_DIAGNOSTIC_COUNT_COUNT` |
| `values[0]` | contact 诊断值,当前容量为 `SPHLITE_COUPLING_CONTACT_DIAGNOSTIC_VALUE_COUNT` |
CLI 已公开的 extended diagnostics 字段:
| 字段 | 来源 |
|---|---|
| `coupling_force_x/y/z` | `values[0..2]` |
| `coupling_impulse_x/y/z` | `values[6..8]` |
| `coupling_work` | `values[15]` |
| `coupling_energy_exchange` | `values[17]` |
| `coupling_force_balance_error` | `values[22]` |
| `coupling_moment_balance_error` | `values[23]` |
| `coupling_max_pressure` | `values[24]` |
| `coupling_max_traction` | `values[25]` |
| `coupling_max_penetration` | `values[26]` |
| `coupling_stale_loads` | `counts[0]` |
| `coupling_nonfinite_imports` | `counts[2]` |
| `coupling_repeated_imports` | `counts[5]` |
| `coupling_invalid_weights` | `counts[7]` |
| `coupling_active_contacts` | `counts[8]` |
| `coupling_skipped_contacts` | `counts[9]` |
| `coupling_nonfinite_contact_imports` | `counts[10]` |
## 9. Array Layout
C ABI 采用 caller-allocated buffer。三维向量数组按以下方式展开:
```text
array[dim + 3 * item]
```
其中 `dim=0,1,2`,`item` 为 0-based 导出/导入记录序号。Fortran 内部可保持自身列主序存储,C 边界必须显式转换为上述布局。
## 10. External Id And Export Index
`external id` 与 `export index` 不承担同一职责:
- `external id` 用于跨模块追踪、日志和结果复核,长期适合 shared memory 数据块。
- `export index` 用于当前 region 内紧凑数组访问,适合已有 C ABI 的粒子力导入。
- CCLite worker v1 可优先沿用 `region_index + export_index`,v2 再补充更完整的 `external id`、`source_id` 和 `pair_id` 路径。
## 11. V2 Reserved Fields
以下字段尚未作为稳定 ABI 暴露,暂列入 v2 预留:
| 字段 | 建议语义 |
|---|---|
| `body_id` | 刚体/部件/舱段级归属,用于 CCLite 分组追踪 |
| `contact_radius` | 接触搜索等效半径,可由 `h`、section 或专门接触参数计算 |
| `sound_speed` | phase/EOS 对应声速,用于 FSI 和 CFL 复核 |
| `source_id` | 外部载荷、contact 或 boundary record 来源 |
| `pair_id` | SPH-FEM 接触/耦合配对 id |
| `valid_flags` | 逐字段有效性位,避免用哨兵值表达缺省 |
| `boundary_id` | 外部 boundary state id |
| `ghost_id` | 外部 ghost state id |
| `boundary_position[3]` | boundary/ghost 位置 |
| `boundary_velocity[3]` | boundary/ghost 速度 |
| `boundary_normal[3]` | boundary/ghost 法向 |
| `boundary_pressure` | boundary/ghost 压力 |
| `boundary_density` | boundary/ghost 密度 |
| `boundary_sound_speed` | boundary/ghost 声速 |
| `interface_pressure` | FSI 界面压力 |
| `interface_velocity[3]` | FSI 界面速度 |
这些字段进入接口前,需要先明确 owner、清零策略、restart 策略、CLI/Python 暴露策略和 release gate。
## 12. V2 Interface Draft
v2 草案采用“现有 ABI 继续稳定 + 新增 v2 扩展接口”的共存策略。旧接口不改变参数顺序和数组布局;v2 接口增加 `valid_flags`,避免调用方用哨兵值表达缺省字段。
候选接口族:
```c
sphlite_coupling_export_particles_v2
sphlite_coupling_apply_particle_forces_v2
sphlite_coupling_apply_contact_state_v2
sphlite_coupling_apply_boundary_states_v2
```
v2 particle export 草案字段:
| 字段 | 语义 |
|---|---|
| `source_id` | 数据来源,CCLite 或其他外部模块负责分配 |
| `pair_id` | SPH-FEM 或 SPH-boundary 配对 id |
| `body_id` | 船体部件、舱段或刚体分组 id;当前默认 `-1` 表示未分配 |
| `contact_radius` | 由 `h`、section 或接触参数计算的等效接触半径;worker AOR v1 临时采用 `2h`,不改变内部核函数半径 |
| `sound_speed` | phase/EOS 对应声速;当前 worker AOR v1 没有稳定 EOS 查询时使用正占位值并通过 `valid_flags` 标识 |
| `valid_flags` | 逐字段有效性位;当前定义覆盖 position、velocity、normal、pressure、density、sound speed、moment、interface pressure 和 interface velocity |
v2 force/contact/boundary 草案字段:
| 接口 | 新增字段 |
|---|---|
| particle force import v2 | `source_id`、`pair_id`、`export_index`、`internal_index`、`moment[3]`、`valid_flags` |
| contact state import v2 | `source_id`、`pair_id`、`contact_state`、`contact_normal[3]`、`contact_gap`、`contact_penetration`、`contact_pressure`、`valid_flags` |
| boundary state import v2 | `boundary_state_id`、`ghost_state_id`、`position[3]`、`velocity[3]`、`normal[3]`、`pressure`、`density`、`sound_speed`、`interface_pressure`、`interface_velocity[3]`、`state_mode`、`valid_flags` |
C++ wrapper 应保留薄包装风格,把 v2 字段暴露为 POD/`std::vector` 容器;Python wrapper 应继续使用 `ctypes` caller-allocated buffer 风格,并提供 debug dict 视图。二者均不应引入 CCLite 私有类型。
补充约定:
- `source_id` 由 CCLite 或其他外部耦合模块分配,用于追踪 contact pair、facet 或边界来源;SPHLite 只保存和回显,不解释其内部结构。
- `pair_id` 与 contact state 同步使用,用于标记同一接触对的 persistence;没有 contact state 时可为 0。
- `moment[3]` 是 Solid/Shell 和后续壳粒子接触的预留字段;当前粒子力导入只使用 `force[3]`,但 force report 会保留 moment。
worker force block header 当前记录:
| 字段 | 含义 |
|---|---|
| `stale_count` | 被拒绝的过期 step force record 数量 |
| `repeated_count` | 被拒绝的重复 force record 数量 |
| `contact_count` | 可映射到 contact state 导入的记录数量 |
| `total_force[3]` | 有效 force record 的导入总力 |
| `total_moment[3]` | 有效 force record 的导入总力矩 |
- `interface_pressure` 和 `interface_velocity[3]` 是 pressure projection/Riemann FSI 预留字段;当前不驱动生产级 FSI。
- `sphlite_coupling_apply_boundary_states` 的草案接口只导入外部 boundary/ghost 状态,不规定 Water/Gas/Solid/Shell 如何参与邻域求和。
- boundary/ghost 缓存容量应由后续 v2 ABI 或 worker data block 显式给出;每个 coupling step 开始前清零,避免 stale boundary state。
## 13. Diagnostics Draft
外部载荷和接触诊断扩展的目标是让每条导入记录“可追踪、可拒绝、可复现”。当前预留枚举见 `sph_worker_contract`,建议长期暴露以下类别:
| 类别 | 字段 |
|---|---|
| id 匹配 | unmatched particle count |
| 拒绝原因 | nonfinite force、nonfinite contact、invalid weight、stale epoch、repeated import |
| per-region 总量 | input force、input moment、distributed force、distributed moment |
| per-region 误差 | force error、moment error |
| contact state | inactive、candidate、active、released、tied |
`released` 和 `tied` 在当前阶段仅作为只读诊断映射,不驱动 Solid/Shell damage 或 release 算法。
已有回归基础:
- `coupling_stale_epoch_081`
- `coupling_load_balance_081`
- `coupling_contact_diagnostics_081`
- `coupling_smoke_081`
## 14. Boundary And Ghost Draft
boundary/ghost 当前是预留能力,而非生产级 FSI。`sphlite_worker_boundary_state_t` 只描述外部状态缓存和清零策略;`sphlite_worker_boundary_state_clear` 是当前 smoke gate,用于保证状态可以完整清零。
| 字段 | 语义 |
|---|---|
| `boundary_state_id` | 外部 boundary state id |
| `ghost_state_id` | 外部 ghost state id |
| `position[3]` | boundary/ghost 位置 |
| `velocity[3]` | boundary/ghost 速度 |
| `normal[3]` | boundary/ghost 法向 |
| `pressure` | boundary/ghost 压力 |
| `density` | boundary/ghost 密度 |
| `sound_speed` | boundary/ghost 声速 |
| `interface_pressure` | FSI 界面压力 |
| `interface_velocity[3]` | FSI 界面速度 |
| `state_mode` | boundary state 模式 |
| `valid_flags` | 有效字段位 |
清零策略:每次导入新 boundary state 前应先清空缓存,未设置的字段保持零值且对应 valid flag 不置位。