# CCLite 接口控制文档 ## Coupling & Contact Lite for SPHLite and FEMLite **文档版本**:V0.1 草案 **软件名称**:CCLite **文档定位**:CCLite 与 SPHLite/FEMLite 的外部接口契约 **实现基线**:独立主控程序 + CCLite worker/service 模式 + Windows shared memory + named event **数据布局基线**:AoR v1,0.8.x 预留 SoA v2 **编码要求**:中文,UTF-8 without BOM --- # 1. 文档定位与接口边界 ## 1.1 编写目的 本文档定义 CCLite 与 SPHLite/FEMLite 之间的外部接口契约,包括: 1. worker/service 启动方式; 2. CCLite `.inp` 输入关键词接口; 3. 控制 IPC; 4. 共享内存 block; 5. command shared block; 6. AoR payload 布局; 7. 命令、状态、错误码和超时; 8. 接口版本兼容策略; 9. 0.1.x 到 0.10.x 的接口演进路线。 ## 1.2 接口边界 本文档只冻结外部接口,不规定 SPHLite/FEMLite 内部 Fortran API、内部模块、内部数组或内部求解流程。 CCLite 与求解器之间只通过以下通道交互: ```text control IPC: named event + command shared block data IPC: Windows shared memory data blocks process interface: worker/service command line case interface: cclite.inp keywords ``` ## 1.3 第一阶段平台约束 0.1.x 到 0.2.x 的接口实现范围: ```text OS: Windows Compiler: gfortran Communication: local shared memory Control sync: named event Data layout: AoR v1 ``` Linux shared memory、MPI、socket、pipe 和 SoA v2 只作为后续预留。 --- # 2. 总体接口架构 ## 2.1 三进程关系 ```text CCLite.exe Controller / Contact / Transfer / Output / \ command/event command/event / \ SPHLite.exe FEMLite.exe --cclite-worker --cclite-worker shared memory: SPH_TO_CCL_PARTICLE SPH_TO_CCL_FACET FEM_TO_CCL_FACET CCL_TO_SPH_FORCE CCL_TO_FEM_LOAD CCL_DIAGNOSTIC CCL_COMMAND_SPH CCL_COMMAND_FEM ``` ## 2.2 接口所有权 | 对象 | 创建者 | 写入者 | 读取者 | | --- | --- | --- | --- | | command block | CCLite | CCLite / Solver | CCLite / Solver | | named event | CCLite | CCLite / Solver | CCLite / Solver | | SPH_TO_CCL_PARTICLE | CCLite | SPHLite | CCLite | | SPH_TO_CCL_FACET | CCLite | SPHLite | CCLite | | FEM_TO_CCL_FACET | CCLite | FEMLite | CCLite | | CCL_TO_SPH_FORCE | CCLite | CCLite | SPHLite | | CCL_TO_FEM_LOAD | CCLite | CCLite | FEMLite | | CCL_DIAGNOSTIC | CCLite | CCLite / Solver | CCLite | CCLite 负责创建和销毁所有共享内存和 named event。求解器 worker 只打开、映射和使用这些对象。 ## 2.3 命名原则 共享对象名称由 `prefix + role + solver` 组成: ```text __ ``` 示例: ```text CCLITE_CASE001_COMMAND_SPH CCLITE_CASE001_COMMAND_FEM CCLITE_CASE001_SPH_TO_CCL_PARTICLE CCLITE_CASE001_FEM_TO_CCL_FACET CCLITE_CASE001_CCL_TO_SPH_FORCE CCLITE_CASE001_CCL_TO_FEM_LOAD ``` `PREFIX` 由 `*CCLITE IPC` 的 `PREFIX=` 参数指定。名称只能包含字母、数字和下划线。 --- # 3. Worker/Service 模式接口 ## 3.1 启动方式 SPHLite 和 FEMLite 必须增加 CCLite worker/service 模式。 推荐命令行: ```powershell sphlite.exe --cclite-worker sphlite.inp --ipc-prefix CCLITE_CASE001 --solver-name SPH femlite.exe --cclite-worker femlite.inp --ipc-prefix CCLITE_CASE001 --solver-name FEM ``` 最小参数: | 参数 | 必填 | 含义 | | --- | --- | --- | | `--cclite-worker` | 是 | 进入 CCLite worker/service 模式 | | input file | 是 | 求解器自己的 `.inp` 文件 | | `--ipc-prefix` | 是 | CCLite 创建的共享对象前缀 | | `--solver-name` | 是 | `SPH` 或 `FEM` | | `--workdir` | 否 | worker 工作目录 | | `--timeout-ms` | 否 | worker 默认等待超时 | ## 3.2 worker 行为 worker 模式下,求解器不得自行完整运行到结束,而是等待 CCLite 命令。 worker 主循环: ```text attach command block attach data blocks signal READY loop: wait command event read command block execute command write status/error signal done event if command == STOP: exit ``` ## 3.3 worker 必须支持的操作 | 操作 | SPHLite | FEMLite | | --- | --- | --- | | attach IPC | 必须 | 必须 | | read input | 必须 | 必须 | | build model | 必须 | 必须 | | export interface | 必须 | 必须 | | import loads | 必须 | 必须 | | advance explicit | 必须 | 必须 | | write output | 必须 | 必须 | | stop | 必须 | 必须 | 隐式推进、restart 和高级输出不属于 0.1.x 必须项,可在后续版本追加。 --- # 4. CCLite `.inp` 关键词接口 ## 4.1 关键词范围 0.1.x 必须支持: ```text *CCLITE CONTROL *CCLITE SOLVER *CCLITE IPC *CCLITE TIME *CCLITE INTERFACE *CCLITE OUTPUT ``` 0.2.x 必须支持: ```text *CCLITE SURFACE INTERACTION *CCLITE CONTACT PAIR ``` 后续版本追加 tied coupling、FSI、restart 和高级稳定性关键词。 ## 4.2 `*CCLITE CONTROL` 示例: ```text *CCLITE CONTROL, NAME=CASE001 MODE=EXPLICIT_EXPLICIT_SYNC ``` 参数: | 参数 | 必填 | 默认 | 含义 | | --- | --- | --- | --- | | `NAME` | 是 | 无 | 算例名称 | 数据行: | 字段 | 必填 | 默认 | 允许值 | | --- | --- | --- | --- | | `MODE` | 是 | 无 | `EXPLICIT_EXPLICIT_SYNC` | 后续允许值: ```text EXPLICIT_EXPLICIT_ASYNC EXPLICIT_SPH_IMPLICIT_FEM_WEAK EXPLICIT_SPH_IMPLICIT_FEM_STRONG ``` ## 4.3 `*CCLITE SOLVER` 示例: ```text *CCLITE SOLVER, NAME=SPH, TYPE=SPHLITE EXECUTABLE=SPHLite/cpu_release/bin/sphlite.exe INPUT=sphlite.inp WORKDIR=work/sph WORKER=YES ``` 参数: | 参数 | 必填 | 允许值 | | --- | --- | --- | | `NAME` | 是 | `SPH`、`FEM` | | `TYPE` | 是 | `SPHLITE`、`FEMLITE` | 数据行字段: | 字段 | 必填 | 默认 | | --- | --- | --- | | `EXECUTABLE` | 是 | 无 | | `INPUT` | 是 | 无 | | `WORKDIR` | 否 | 当前目录下自动生成 | | `WORKER` | 否 | `YES` | | `TIMEOUT_MS` | 否 | 30000 | ## 4.4 `*CCLITE IPC` 示例: ```text *CCLITE IPC, TYPE=WINDOWS_SHMEM PREFIX=CCLITE_CASE001 CONTROL=NAMED_EVENT COMMAND_BLOCK=YES BUFFERING=DOUBLE PAYLOAD_LAYOUT=AOR_V1 TIMEOUT_MS=30000 ``` 字段: | 字段 | 必填 | 默认 | 允许值 | | --- | --- | --- | --- | | `PREFIX` | 是 | 无 | 字母、数字、下划线 | | `CONTROL` | 是 | `NAMED_EVENT` | `NAMED_EVENT` | | `COMMAND_BLOCK` | 否 | `YES` | `YES` | | `BUFFERING` | 否 | `DOUBLE` | `SINGLE`、`DOUBLE`、`TRIPLE` | | `PAYLOAD_LAYOUT` | 否 | `AOR_V1` | `AOR_V1` | | `TIMEOUT_MS` | 否 | 30000 | 正整数 | 0.1.x 只允许 `TYPE=WINDOWS_SHMEM`。 ## 4.5 `*CCLITE TIME` 示例: ```text *CCLITE TIME START=0.0, END=1.0E-3, DT=1.0E-7 OUTPUT_FREQUENCY=10 ``` 字段: | 字段 | 必填 | 默认 | | --- | --- | --- | | `START` | 是 | 无 | | `END` | 是 | 无 | | `DT` | 是 | 无 | | `OUTPUT_FREQUENCY` | 否 | 1 | ## 4.6 `*CCLITE INTERFACE` 示例: ```text *CCLITE INTERFACE, NAME=HULL_IMPACT SPH_REGION=WATER_CONTACT FEM_SURFACE=HULL_OUTER ``` 字段: | 字段 | 必填 | 含义 | | --- | --- | --- | | `SPH_REGION` | 是 | SPHLite coupling region 名称 | | `FEM_SURFACE` | 是 | FEMLite surface/facet 集合名称 | ## 4.7 `*CCLITE SURFACE INTERACTION` 示例: ```text *CCLITE SURFACE INTERACTION, NAME=PENALTY_1 NORMAL=PENALTY, KN=1.0E9, CN=1.0E4 FRICTION=0.0 ``` 字段: | 字段 | 必填 | 默认 | 含义 | | --- | --- | --- | --- | | `NORMAL` | 是 | 无 | 法向模型 | | `KN` | 是 | 无 | penalty 刚度 | | `CN` | 否 | 0 | 法向阻尼 | | `FRICTION` | 否 | 0 | 摩擦系数,0.4.x 起启用 | 0.2.x 必须支持 `NORMAL=PENALTY`。 ## 4.8 `*CCLITE CONTACT PAIR` 示例: ```text *CCLITE CONTACT PAIR, NAME=PAIR_1 INTERFACE=HULL_IMPACT INTERACTION=PENALTY_1 TYPE=SPH_PARTICLE_TO_FEM_FACE ``` 字段: | 字段 | 必填 | 允许值 | | --- | --- | --- | | `INTERFACE` | 是 | 已定义 interface | | `INTERACTION` | 是 | 已定义 surface interaction | | `TYPE` | 是 | `SPH_PARTICLE_TO_FEM_FACE`、`SPH_PARTICLE_TO_FEM_SHELL` | 后续版本追加 SPH shell、facet proxy、tie 和 FSI 类型。 ## 4.9 `*CCLITE OUTPUT` 示例: ```text *CCLITE OUTPUT DIRECTORY=work/cclite FREQUENCY=10 CONTACT=YES IPC=YES FORCE_BALANCE=YES SNAPSHOT=NO ``` 字段: | 字段 | 默认 | | --- | --- | | `DIRECTORY` | `work/cclite` | | `FREQUENCY` | 1 | | `CONTACT` | `YES` | | `IPC` | `YES` | | `FORCE_BALANCE` | `YES` | | `SNAPSHOT` | `NO` | --- # 5. 控制 IPC 接口 ## 5.1 控制 IPC 组成 每个 solver worker 有一组控制对象: ```text COMMAND_BLOCK_ COMMAND_EVENT_ DONE_EVENT_ ``` 示例: ```text CCLITE_CASE001_COMMAND_BLOCK_SPH CCLITE_CASE001_COMMAND_EVENT_SPH CCLITE_CASE001_DONE_EVENT_SPH ``` ## 5.2 command block 职责 command block 用于传递小命令和状态,不用于传递大数组。 内容包括: 1. magic/version; 2. command id; 3. step id; 4. buffer id; 5. dt/time; 6. target block role; 7. command state; 8. error code; 9. message。 ## 5.3 事件流程 ```text CCLite: write command block reset COMMAND_EVENT reset DONE_EVENT signal COMMAND_EVENT wait DONE_EVENT read command block status Solver: wait COMMAND_EVENT read command block set state BUSY execute command set state DONE or FAILED signal DONE_EVENT ``` 0.1.x 约定使用 Windows manual-reset named event。CCLite 负责 reset `COMMAND_EVENT` 和 `DONE_EVENT`;worker 只执行 wait 和 signal,不负责 reset。这样可以减少求解器 worker 端状态复杂度。 ## 5.4 超时 每个命令都有 `timeout_ms`。若超时: 1. CCLite 将 solver 状态置为 `TIMEOUT`; 2. 写入 `ipc_report.csv`; 3. 0.1.x 默认终止当前 run; 4. 0.8.x 后可引入恢复策略。 --- # 6. Command Shared Block 布局 ## 6.1 基本类型 | 名称 | 类型 | 说明 | | --- | --- | --- | | `int32` | 32 位有符号整数 | 枚举、数量、状态 | | `int64` | 64 位有符号整数 | 字节数、全局 id | | `real64` | IEEE 754 double | 浮点数据 | | `char[N]` | 固定长度 ASCII/UTF-8 字节 | 短消息,不允许变长指针 | 所有共享内存字段不得包含进程私有指针。 ## 6.2 字节序与对齐 0.1.x 只支持 Windows/x86_64 little-endian。 共享结构不依赖编译器默认派生类型布局,正式实现应使用显式 offset 常量或 `bind(C)` 镜像结构。 ## 6.3 command block 字段顺序 AoR v1 command block 头部字段顺序: | 序号 | 字段 | 类型 | 含义 | | --- | --- | --- | --- | | 1 | `magic` | int32 | 固定 magic | | 2 | `version_major` | int32 | 接口主版本 | | 3 | `version_minor` | int32 | 接口次版本 | | 4 | `layout_id` | int32 | command block layout | | 5 | `solver_id` | int32 | SPH/FEM | | 6 | `worker_state` | int32 | worker 生命周期状态 | | 7 | `command_id` | int32 | 命令枚举 | | 8 | `command_state` | int32 | 当前命令状态 | | 9 | `command_seq` | int32 | CCLite 发出的命令序号 | | 10 | `ack_seq` | int32 | worker 确认的命令序号 | | 11 | `step_id` | int32 | 宏步编号 | | 12 | `substep_id` | int32 | 子步编号,无子步时为 0 | | 13 | `iteration_id` | int32 | 强耦合迭代号,无迭代时为 0 | | 14 | `buffer_id` | int32 | buffer 编号 | | 15 | `target_block_role` | int32 | 相关 data block | | 16 | `command_flags` | int32 | 命令标志位 | | 17 | `error_code` | int32 | 错误码 | | 18 | `warning_count` | int32 | warning 数量 | | 19 | `heartbeat_seq` | int32 | worker 心跳序号 | | 20 | `timeout_ms` | int32 | 超时 | | 21 | `message_length` | int32 | message 有效长度 | | 22 | `reserved_i4` | int32[8] | 预留 | | 23 | `time` | real64 | 当前时间 | | 24 | `dt` | real64 | 当前步长 | | 25 | `macro_dt` | real64 | 宏步步长,无子循环时等于 `dt` | | 26 | `int_param` | int32[16] | 命令整数参数槽 | | 27 | `real_param` | real64[16] | 命令浮点参数槽 | | 28 | `message` | char[256] | 短消息 | `command_seq` 必须单调递增,用于检测重复命令和 stale command。 `ack_seq` 必须等于 worker 已处理完成的 `command_seq`。CCLite 等待 `DONE_EVENT` 后必须检查 `ack_seq == command_seq`。 `substep_id` 为显式异步子循环预留,`iteration_id` 为显隐强耦合和 Aitken 松弛预留。0.1.x/0.2.x 中二者均写 0。 `int_param` 和 `real_param` 是稳定扩展槽,用于 `ADVANCE`、`WRITE_OUTPUT`、`READ_RESTART`、`EXPORT_INTERFACE` 等命令传递少量参数,避免频繁修改 command block 主结构。 ## 6.4 command flags `command_flags` 使用 bit mask: | bit | 名称 | 含义 | | --- | --- | --- | | 0 | `FLAG_FINAL_STEP` | 当前为最后一步 | | 1 | `FLAG_WRITE_OUTPUT` | 本步要求输出 | | 2 | `FLAG_STRICT_CHECK` | 严格校验 block/header | | 3 | `FLAG_ALLOW_EMPTY_BLOCK` | 允许导出空 block | | 4 | `FLAG_RESTART_POINT` | 本步为 restart 点 | | 5 | `FLAG_SUBCYCLING` | 当前命令属于子循环 | | 6 | `FLAG_COUPLING_ITERATION` | 当前命令属于强耦合迭代 | 未定义 bit 必须写 0。 --- # 7. 共享内存 Data Block 通用 Header ## 7.1 Data block header 字段 所有 data block 都以统一 header 开始。 | 序号 | 字段 | 类型 | 含义 | | --- | --- | --- | --- | | 1 | `magic` | int32 | block magic | | 2 | `version_major` | int32 | block 主版本 | | 3 | `version_minor` | int32 | block 次版本 | | 4 | `layout_id` | int32 | `AOR_V1`、后续 `SOA_V2` | | 5 | `block_role` | int32 | block role | | 6 | `producer_id` | int32 | 写入者 | | 7 | `consumer_id` | int32 | 读取者 | | 8 | `step_id` | int32 | 耦合步 | | 9 | `buffer_id` | int32 | buffer 编号 | | 10 | `state` | int32 | buffer 状态 | | 11 | `item_count` | int32 | 记录数量 | | 12 | `item_stride` | int32 | 单条记录字节数 | | 13 | `payload_bytes` | int64 | payload 总字节数 | | 14 | `header_bytes` | int32 | header 字节数 | | 15 | `max_item_count` | int32 | 最大记录数 | | 16 | `error_code` | int32 | 错误码 | | 17 | `reserved_i4` | int32[16] | 预留 | ## 7.2 buffer 状态 | 状态 | 含义 | | --- | --- | | `EMPTY` | 可写 | | `WRITING` | producer 正在写 | | `READY` | producer 写完,可读 | | `READING` | consumer 正在读 | | `CONSUMED` | consumer 已读完 | | `ERROR` | 数据无效 | 状态转换: ```text EMPTY -> WRITING -> READY -> READING -> CONSUMED \-> ERROR ``` ## 7.3 header 校验 读取 data block 前必须检查: 1. magic 正确; 2. major 版本兼容; 3. layout id 支持; 4. block role 与预期一致; 5. payload bytes 不超过映射大小; 6. item count 不超过 max item count; 7. state 为 `READY`; 8. step id 与 command block 匹配。 --- # 8. Block Role 与版本 ## 8.1 block role 枚举 | role | 名称 | 首次版本 | 说明 | | --- | --- | --- | --- | | 101 | `SPH_TO_CCL_PARTICLE` | 0.1.x | SPH 粒子界面状态 | | 102 | `SPH_TO_CCL_FACET` | 0.6.x | SPH facet proxy | | 201 | `FEM_TO_CCL_FACET` | 0.1.x | FEM 边界 facet | | 301 | `CCL_TO_SPH_FORCE` | 0.2.x | CCLite 写给 SPH 的力/接触状态 | | 302 | `CCL_TO_FEM_LOAD` | 0.2.x | CCLite 写给 FEM 的节点力/facet 载荷 | | 401 | `CCL_DIAGNOSTIC` | 0.1.x | 诊断摘要 | | 901 | `CCL_COMMAND_SPH` | 0.1.x | SPH command block | | 902 | `CCL_COMMAND_FEM` | 0.1.x | FEM command block | ## 8.2 layout id | layout id | 名称 | 说明 | | --- | --- | --- | | 1 | `AOR_V1` | Array of Records,第一阶段默认 | | 2 | `SOA_V2` | Structure of Arrays,0.8.x 性能优化预留 | 0.1.x 到 0.7.x 以 `AOR_V1` 为主。 --- # 9. AoR v1 Payload 布局 ## 9.1 通用要求 AoR v1 表示 payload 是连续 record 数组: ```text payload = record[0], record[1], ..., record[item_count-1] ``` 每个 record: 1. 字段顺序固定; 2. 不含指针; 3. 不含变长字符串; 4. 浮点为 real64; 5. 枚举和局部数量为 int32; 6. 全局 id 可用 int64。 ## 9.2 SPH_TO_CCL_PARTICLE record | 序号 | 字段 | 类型 | 说明 | | --- | --- | --- | --- | | 1 | `external_id` | int64 | SPHLite 外部粒子 id | | 2 | `internal_index` | int32 | SPHLite 导出 index | | 3 | `phase` | int32 | 相/粒子类型 | | 4 | `status` | int32 | active/failed/inactive | | 5 | `material_id` | int32 | 材料 id | | 6 | `section_id` | int32 | section id | | 7 | `valid_flags` | int32 | 有效字段 bit mask | | 8 | `reserved_i4` | int32[2] | 预留 | | 9 | `mass` | real64 | 质量 | | 10 | `volume` | real64 | 体积 | | 11 | `density` | real64 | 密度 | | 12 | `pressure` | real64 | 压力 | | 13 | `internal_energy` | real64 | 内能 | | 14 | `temperature` | real64 | 温度 | | 15 | `h` | real64 | 光滑长度 | | 16 | `smoothing_length` | real64 | 平滑长度别名,默认等于 `h` | | 17 | `contact_radius` | real64 | 接触半径 | | 18 | `sound_speed` | real64 | 声速,FSI/Riemann 使用 | | 19 | `x` | real64[3] | 坐标 | | 20 | `v` | real64[3] | 速度 | | 21 | `a` | real64[3] | 加速度 | 0.2.x 接触算法至少需要: ```text external_id, internal_index, status, contact_radius, x, v ``` `valid_flags` 定义: | bit | 字段 | | --- | --- | | 0 | `mass` | | 1 | `volume` | | 2 | `density` | | 3 | `pressure` | | 4 | `internal_energy` | | 5 | `temperature` | | 6 | `h/smoothing_length` | | 7 | `contact_radius` | | 8 | `sound_speed` | 无效的 real64 字段建议填 0,并通过 `valid_flags` 判断,不使用 NaN 作为接口语义。 ## 9.3 SPH_TO_CCL_FACET record 0.6.x 起启用。0.1.x 到 0.5.x 可不创建或创建空 block。 | 字段 | 类型 | 说明 | | --- | --- | --- | | `facet_id` | int64 | SPH facet proxy id | | `particle_count` | int32 | 局部粒子数 | | `particle_ids` | int64[8] | 粒子 id,最多 8 | | `section_id` | int32 | section | | `material_id` | int32 | material | | `area` | real64 | 面积 | | `normal` | real64[3] | 法向 | | `x` | real64[8,3] | facet 粒子坐标 | | `v` | real64[8,3] | facet 粒子速度 | ## 9.4 FEM_TO_CCL_FACET record | 序号 | 字段 | 类型 | 说明 | | --- | --- | --- | --- | | 1 | `facet_id` | int64 | FEM facet id | | 2 | `elem_id` | int64 | FEM element id | | 3 | `face_id` | int32 | element face id | | 4 | `node_count` | int32 | facet 节点数 | | 5 | `element_type` | int32 | 元素类型枚举 | | 6 | `surface_type` | int32 | solid/shell | | 7 | `surface_id` | int64 | surface 名称 hash 或导出 id | | 8 | `valid_flags` | int32 | 有效字段 bit mask | | 9 | `reserved_i4` | int32[3] | 预留 | | 10 | `node_ids` | int64[8] | 节点 id,最多 8 | | 11 | `area` | real64 | 面积 | | 12 | `thickness` | real64 | 壳厚度,实体为 0 | | 13 | `shell_thickness` | real64 | 壳厚度别名,默认等于 `thickness` | | 14 | `mass_per_area` | real64 | 面密度或等效质量/面积 | | 15 | `normal` | real64[3] | facet 法向 | | 16 | `x` | real64[8,3] | 节点坐标 | | 17 | `v` | real64[8,3] | 节点速度 | 0.2.x 接触算法至少需要: ```text facet_id, node_count, node_ids, surface_type, area, thickness, normal, x, v ``` `surface_id` 可以是 FEMLite 导出的 surface id,也可以是 CCLite 对 surface 名称计算的稳定 hash。若当前 FEMLite 只能按全边界导出,可填 0。 `valid_flags` 定义: | bit | 字段 | | --- | --- | | 0 | `area` | | 1 | `thickness/shell_thickness` | | 2 | `mass_per_area` | | 3 | `normal` | | 4 | `x` | | 5 | `v` | ## 9.5 CCL_TO_SPH_FORCE record | 序号 | 字段 | 类型 | 说明 | | --- | --- | --- | --- | | 1 | `external_id` | int64 | SPH 粒子 id | | 2 | `internal_index` | int32 | SPH 导出 index | | 3 | `load_mode` | int32 | particle force / motion / contact state | | 4 | `contact_state` | int32 | 接触状态 | | 5 | `coupling_step` | int32 | CCLite 耦合步 | | 6 | `valid_flags` | int32 | 有效字段 bit mask | | 7 | `source_pair_id` | int64 | CCLite contact pair id | | 8 | `source_facet_id` | int64 | 关联 FEM facet id | | 9 | `force` | real64[3] | 作用于 SPH 的力 | | 10 | `moment` | real64[3] | 作用于 SPH 的力矩,第一阶段可为 0 | | 11 | `normal` | real64[3] | 接触法向 | | 12 | `gap` | real64 | 法向间隙 | | 13 | `penetration` | real64 | 穿透量 | | 14 | `pressure` | real64 | 接触压力或 FSI 压力 | | 15 | `target_motion` | real64[3] | 运动边界目标,0.6.x 起使用 | 同一 SPH 粒子可出现多条 record,SPHLite 负责累加或 CCLite 可在写入前合并。0.2.x 建议 CCLite 写入前按粒子合并。 ## 9.6 CCL_TO_FEM_LOAD record | 序号 | 字段 | 类型 | 说明 | | --- | --- | --- | --- | | 1 | `facet_id` | int64 | FEM facet id | | 2 | `source_pair_id` | int64 | CCLite contact pair id | | 3 | `source_particle_id` | int64 | 关联 SPH 粒子 id | | 4 | `node_count` | int32 | 节点数 | | 5 | `load_type` | int32 | nodal force / pressure / traction | | 6 | `distribution_mode` | int32 | 节点分配模式 | | 7 | `contact_state` | int32 | 接触状态 | | 8 | `valid_flags` | int32 | 有效字段 bit mask | | 9 | `node_ids` | int64[8] | 节点 id | | 10 | `node_forces` | real64[8,3] | 节点力 | | 11 | `pressure` | real64 | facet 压力 | | 12 | `traction` | real64[3] | facet 牵引 | | 13 | `resultant` | real64[3] | facet 合力 | | 14 | `normal` | real64[3] | 接触法向 | 0.2.x 必须支持 `load_type=NODAL_FORCE`。 ## 9.7 CCL_DIAGNOSTIC record 诊断 record 可使用 key-value 风格的固定记录: | 字段 | 类型 | 说明 | | --- | --- | --- | | `step_id` | int32 | 步号 | | `source_id` | int32 | CCLite/SPH/FEM | | `metric_id` | int32 | 指标枚举 | | `count_value` | int64 | 计数值 | | `real_value` | real64 | 浮点值 | | `message` | char[128] | 可选短消息 | 详细 CSV 输出由 CCLite 自身负责,不依赖该 block。 --- # 10. 命令与状态枚举 ## 10.1 solver id | id | 名称 | | --- | --- | | 1 | `SOLVER_SPH` | | 2 | `SOLVER_FEM` | | 3 | `SOLVER_CCL` | ## 10.2 command id | id | 命令 | 首次版本 | 含义 | | --- | --- | --- | --- | | 1 | `INIT` | 0.1.x | worker 初始化 IPC | | 2 | `READ_INPUT` | 0.1.x | 读取求解器输入 | | 3 | `BUILD_MODEL` | 0.1.x | 构建模型 | | 4 | `EXPORT_INTERFACE` | 0.1.x | 导出界面状态 | | 5 | `IMPORT_LOADS` | 0.2.x | 导入 CCLite 载荷 | | 6 | `ADVANCE` | 0.1.x | 推进一步 | | 7 | `WRITE_OUTPUT` | 0.1.x | 写输出 | | 8 | `WRITE_RESTART` | 0.8.x | 写 restart | | 9 | `READ_RESTART` | 0.8.x | 读 restart | | 99 | `STOP` | 0.1.x | 停止 worker | ## 10.3 command state | id | 状态 | | --- | --- | | 0 | `IDLE` | | 1 | `READY` | | 2 | `BUSY` | | 3 | `DONE` | | 4 | `FAILED` | | 5 | `TIMEOUT` | | 6 | `STOPPED` | ## 10.4 worker state | id | 状态 | | --- | --- | | 0 | `WORKER_CREATED` | | 1 | `WORKER_ATTACHED` | | 2 | `WORKER_INPUT_READ` | | 3 | `WORKER_MODEL_BUILT` | | 4 | `WORKER_READY` | | 5 | `WORKER_BUSY` | | 6 | `WORKER_FAILED` | | 7 | `WORKER_STOPPED` | `worker_state` 描述 worker 生命周期,`command_state` 描述当前命令执行状态。二者不得混用。 ## 10.5 contact state | id | 状态 | | --- | --- | | 0 | `CONTACT_NONE` | | 1 | `CONTACT_ACTIVE` | | 2 | `CONTACT_EDGE` | | 3 | `CONTACT_RELEASED` | | 4 | `CONTACT_SKIPPED_DEGENERATE` | ## 10.6 load type | id | 类型 | | --- | --- | | 1 | `NODAL_FORCE` | | 2 | `FACET_PRESSURE` | | 3 | `FACET_TRACTION` | | 4 | `FACET_RESULTANT` | ## 10.7 SPH load mode | id | 类型 | | --- | --- | | 1 | `PARTICLE_FORCE` | | 2 | `PARTICLE_MOMENT` | | 3 | `CONTACT_STATE` | | 4 | `MOTION_BOUNDARY` | | 5 | `FACET_LOAD` | 0.2.x 必须支持 `PARTICLE_FORCE` 和 `CONTACT_STATE`。`MOTION_BOUNDARY` 和 `FACET_LOAD` 为 0.6.x 后续 FSI 能力预留。 ## 10.8 distribution mode | id | 类型 | | --- | --- | | 1 | `DISTRIBUTION_SHAPE_FUNCTION` | | 2 | `DISTRIBUTION_UNIFORM` | | 3 | `DISTRIBUTION_AREA` | | 4 | `DISTRIBUTION_MASS` | 0.2.x 默认使用 `DISTRIBUTION_SHAPE_FUNCTION`。若无法获得可靠形函数权重,可降级为 `DISTRIBUTION_UNIFORM` 并输出 warning。 --- # 11. 错误码与异常处理 ## 11.1 错误码范围 | 范围 | 类型 | | --- | --- | | 0 | `CCL_OK` | | 1000-1999 | 输入错误 | | 2000-2999 | IPC 错误 | | 3000-3999 | worker/进程错误 | | 4000-4999 | 数据 block 错误 | | 5000-5999 | 接触/几何错误 | | 6000-6999 | 非有限值/数值保护 | ## 11.2 必须定义的错误 ```text CCL_OK = 0 CCL_ERROR_INPUT_MISSING_KEYWORD = 1001 CCL_ERROR_INPUT_BAD_PARAM = 1002 CCL_ERROR_IPC_CREATE_FAILED = 2001 CCL_ERROR_IPC_OPEN_FAILED = 2002 CCL_ERROR_IPC_TIMEOUT = 2003 CCL_ERROR_IPC_EVENT_FAILED = 2004 CCL_ERROR_WORKER_START_FAILED = 3001 CCL_ERROR_WORKER_FAILED = 3002 CCL_ERROR_WORKER_BAD_STATE = 3003 CCL_ERROR_BLOCK_BAD_MAGIC = 4001 CCL_ERROR_BLOCK_BAD_VERSION = 4002 CCL_ERROR_BLOCK_BAD_STATE = 4003 CCL_ERROR_BLOCK_SIZE_OVERFLOW = 4004 CCL_ERROR_BLOCK_STALE_STEP = 4005 CCL_ERROR_GEOMETRY_DEGENERATE = 5001 CCL_ERROR_CONTACT_OVERFLOW = 5002 CCL_ERROR_NONFINITE_INPUT = 6001 CCL_ERROR_NONFINITE_LOAD = 6002 ``` ## 11.3 异常策略 0.1.x 到 0.2.x: 1. IPC 失败:终止 run; 2. worker 失败:终止 run; 3. block 版本不兼容:终止 run; 4. 单个退化几何:跳过该 candidate 并诊断; 5. 非有限输入:跳过对应 record;超过阈值终止 step; 6. 非有限载荷:禁止写入 load block 并终止 step。 0.8.x 后可增加错误恢复和 restart 续算。 --- # 12. 接口版本兼容策略 ## 12.1 版本字段 所有 command block 和 data block 必须包含: ```text version_major version_minor layout_id ``` ## 12.2 兼容规则 | 变更 | major | minor | 说明 | | --- | --- | --- | --- | | 修改已有字段含义 | 增加 | 重置 | 不兼容 | | 修改已有字段顺序 | 增加 | 重置 | 不兼容 | | 删除字段 | 增加 | 重置 | 不兼容 | | 追加字段到 record 尾部 | 不变 | 增加 | 条件兼容 | | 追加新 block role | 不变 | 增加 | 兼容 | | 追加新 command id | 不变 | 增加 | 兼容 | | 新增 SoA layout | 不变或增加 | 增加 | 取决于是否保留 AoR | ## 12.3 0.x 阶段策略 0.x 阶段允许快速迭代,但每次接口变化必须同步更新本文档。 0.10.x 前应冻结: 1. worker 命令行; 2. command block v1; 3. AoR v1 基本 block; 4. 错误码范围; 5. 0.2.x 接触最小 payload; 6. 0.7.x 主要算法 block。 --- # 13. 版本接口演进路线 | 版本线 | 接口目标 | | --- | --- | | 0.1.x | worker 模式、command block、named event、基础 data block、空耦合 | | 0.2.x | SPH 粒子、FEM facet、SPH force、FEM load、基础接触字段 | | 0.3.x | 壳厚度、edge contact、contact persistence 字段 | | 0.4.x | 摩擦、自动 penalty、接触历史字段 | | 0.5.x | tie bond、release、tie-to-contact 字段 | | 0.6.x | pressure projection、boundary/ghost、SPH facet proxy | | 0.7.x | Riemann FSI、异步子循环、强耦合残差字段 | | 0.8.x | restart、SoA v2、性能统计、错误恢复字段 | | 0.9.x | 工程算例、参数推荐、验收矩阵接口稳定化 | | 0.10.x | 接口冻结、文档冻结、回归体系和工程发布候选 | --- # 14. 与 03、04、06 号文档的关系 ## 14.1 与 03 号详细设计 03 号文档描述 CCLite 内部模块和实现结构。本文档只描述外部接口契约。 ## 14.2 与 04 号数学模型 04 号文档定义几何、接触、耦合、FSI 和时间耦合的数学模型。本文档将这些数学对象落实为可交换数据字段。 ## 14.3 与 06 号测试计划 06 号文档应按本文档逐项建立接口测试,包括: 1. worker 启动测试; 2. command block 测试; 3. named event 同步测试; 4. data block header 校验; 5. AoR payload pack/unpack; 6. SPH/FEM 最小接触数据交换; 7. 错误码和超时测试。 --- # 15. 第一阶段冻结项 0.1.x/0.2.x 必须冻结: 1. worker/service 模式存在; 2. 控制 IPC 为 named event + command shared block; 3. 大数据使用 Windows shared memory; 4. payload 采用 AoR v1; 5. block header 包含 magic/version/layout/role/step/state/count/bytes/error; 6. 最小命令集为 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`IMPORT_LOADS`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`; 7. `SPH_TO_CCL_PARTICLE`、`FEM_TO_CCL_FACET`、`CCL_TO_SPH_FORCE`、`CCL_TO_FEM_LOAD` 四类核心 block 可用; 8. `.inp` 至少支持 `CONTROL`、`SOLVER`、`IPC`、`TIME`、`INTERFACE`、`SURFACE INTERACTION`、`CONTACT PAIR`、`OUTPUT`。