Files
SPHLite/docs/cclite_coupling_manifest.md
T
2026-07-05 17:00:13 +08:00

12 KiB
Raw Blame History

CCLite Coupling Manifest

文档状态:0.8.x 集成预研稿

本文记录 SPHLite 与 CCLite worker/service adapter 之间的当前数据契约。它不替代 05 号接口控制文档,也不要求 SPHLite 直接依赖 CCLite 或 FEMLite;它只把当前 0.8.2 可用的 coupling ABI、CLI 诊断、worker mock 契约和后续 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 和 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
contact_radius 由 h、section 或接触参数计算的等效接触半径
sound_speed phase/EOS 对应声速
valid_flags 逐字段有效性位

v2 force/contact/boundary 草案字段:

接口 新增字段
particle force import v2 source_id、pair_id、moment[3]、valid_flags
contact state import v2 source_id、pair_id、contact_state、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 私有类型。

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 只描述外部状态缓存和清零策略:

字段 语义
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 不置位。