Files
CCLite/docs/05_interface_control_document.md
T
2026-07-05 16:34:52 +08:00

1068 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
<PREFIX>_<ROLE>_<SOLVER>
```
示例:
```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_<SOLVER>
COMMAND_EVENT_<SOLVER>
DONE_EVENT_<SOLVER>
```
示例:
```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`。