Files
CCLite/docs/05_interface_control_document.md
T
2026-07-05 17:21:51 +08:00

28 KiB
Raw Blame History

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 与求解器之间只通过以下通道交互:

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 --solver-id SPH --case sphlite.inp --ipc-name CCLITE_CASE001 --timeout-ms 5000
femlite.exe --cclite-worker --solver-id FEM --case femlite.inp --ipc-name CCLITE_CASE001 --timeout-ms 5000

最小参数:

参数 必填 含义
--cclite-worker 是 进入 CCLite worker/service 模式
--solver-id 是 SPH 或 FEM
--case 是 求解器自己的 .inp 文件
--ipc-name 是 CCLite 创建的共享对象前缀
--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 用于传递小命令和状态,不用于传递大数组。

内容包括:

  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 事件流程

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 数据无效

状态转换:

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 数组:

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 接触算法至少需要:

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:

  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 必须包含:

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。