362 lines
14 KiB
Markdown
362 lines
14 KiB
Markdown
# 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 不置位。
|