# 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 不置位。