28 KiB
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 之间的外部接口契约,包括:
- worker/service 启动方式;
- CCLite
.inp输入关键词接口; - 控制 IPC;
- 共享内存 block;
- command shared block;
- AoR payload 布局;
- 命令、状态、错误码和超时;
- 接口版本兼容策略;
- 0.1.x 到 0.10.x 的接口演进路线。
1.2 接口边界
本文档只冻结外部接口,不规定 SPHLite/FEMLite 内部 Fortran API、内部模块、内部数组或内部求解流程。
CCLite 与求解器之间只通过以下通道交互:
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 的接口实现范围:
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 三进程关系
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 组成:
<PREFIX>_<ROLE>_<SOLVER>
示例:
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 模式。
推荐命令行:
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 主循环:
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 必须支持:
*CCLITE CONTROL
*CCLITE SOLVER
*CCLITE IPC
*CCLITE TIME
*CCLITE INTERFACE
*CCLITE OUTPUT
0.2.x 必须支持:
*CCLITE SURFACE INTERACTION
*CCLITE CONTACT PAIR
后续版本追加 tied coupling、FSI、restart 和高级稳定性关键词。
4.2 *CCLITE CONTROL
示例:
*CCLITE CONTROL, NAME=CASE001
MODE=EXPLICIT_EXPLICIT_SYNC
参数:
| 参数 | 必填 | 默认 | 含义 |
|---|---|---|---|
NAME |
是 | 无 | 算例名称 |
数据行:
| 字段 | 必填 | 默认 | 允许值 |
|---|---|---|---|
MODE |
是 | 无 | EXPLICIT_EXPLICIT_SYNC |
后续允许值:
EXPLICIT_EXPLICIT_ASYNC
EXPLICIT_SPH_IMPLICIT_FEM_WEAK
EXPLICIT_SPH_IMPLICIT_FEM_STRONG
4.3 *CCLITE SOLVER
示例:
*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
示例:
*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
示例:
*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
示例:
*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
示例:
*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
示例:
*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
示例:
*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 有一组控制对象:
COMMAND_BLOCK_<SOLVER>
COMMAND_EVENT_<SOLVER>
DONE_EVENT_<SOLVER>
示例:
CCLITE_CASE001_COMMAND_BLOCK_SPH
CCLITE_CASE001_COMMAND_EVENT_SPH
CCLITE_CASE001_DONE_EVENT_SPH
5.2 command block 职责
command block 用于传递小命令和状态,不用于传递大数组。
内容包括:
- magic/version;
- command id;
- step id;
- buffer id;
- dt/time;
- target block role;
- command state;
- error code;
- message。
5.3 事件流程
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。若超时:
- CCLite 将 solver 状态置为
TIMEOUT; - 写入
ipc_report.csv; - 0.1.x 默认终止当前 run;
- 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 |
数据无效 |
状态转换:
EMPTY -> WRITING -> READY -> READING -> CONSUMED
\-> ERROR
7.3 header 校验
读取 data block 前必须检查:
- magic 正确;
- major 版本兼容;
- layout id 支持;
- block role 与预期一致;
- payload bytes 不超过映射大小;
- item count 不超过 max item count;
- state 为
READY; - 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 数组:
payload = record[0], record[1], ..., record[item_count-1]
每个 record:
- 字段顺序固定;
- 不含指针;
- 不含变长字符串;
- 浮点为 real64;
- 枚举和局部数量为 int32;
- 全局 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 接触算法至少需要:
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 接触算法至少需要:
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 必须定义的错误
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:
- IPC 失败:终止 run;
- worker 失败:终止 run;
- block 版本不兼容:终止 run;
- 单个退化几何:跳过该 candidate 并诊断;
- 非有限输入:跳过对应 record;超过阈值终止 step;
- 非有限载荷:禁止写入 load block 并终止 step。
0.8.x 后可增加错误恢复和 restart 续算。
12. 接口版本兼容策略
12.1 版本字段
所有 command block 和 data block 必须包含:
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 前应冻结:
- worker 命令行;
- command block v1;
- AoR v1 基本 block;
- 错误码范围;
- 0.2.x 接触最小 payload;
- 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 号文档应按本文档逐项建立接口测试,包括:
- worker 启动测试;
- command block 测试;
- named event 同步测试;
- data block header 校验;
- AoR payload pack/unpack;
- SPH/FEM 最小接触数据交换;
- 错误码和超时测试。
15. 第一阶段冻结项
0.1.x/0.2.x 必须冻结:
- worker/service 模式存在;
- 控制 IPC 为 named event + command shared block;
- 大数据使用 Windows shared memory;
- payload 采用 AoR v1;
- block header 包含 magic/version/layout/role/step/state/count/bytes/error;
- 最小命令集为
INIT、READ_INPUT、BUILD_MODEL、EXPORT_INTERFACE、IMPORT_LOADS、ADVANCE、WRITE_OUTPUT、STOP; SPH_TO_CCL_PARTICLE、FEM_TO_CCL_FACET、CCL_TO_SPH_FORCE、CCL_TO_FEM_LOAD四类核心 block 可用;.inp至少支持CONTROL、SOLVER、IPC、TIME、INTERFACE、SURFACE INTERACTION、CONTACT PAIR、OUTPUT。