14 KiB
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:
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:
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:
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:
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:
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:
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:
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。三维向量数组按以下方式展开:
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,避免调用方用哨兵值表达缺省字段。
候选接口族:
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_081coupling_load_balance_081coupling_contact_diagnostics_081coupling_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 不置位。