1068 lines
28 KiB
Markdown
1068 lines
28 KiB
Markdown
# 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`。
|