Files
FemLite/docs/12_cclite_integration_suggestions.md
T
shenw a2126f360c
FemLite CI / build-test (push) Has been cancelled
Release 0.6.5 real IPC worker
2026-07-05 21:09:37 +08:00

338 lines
16 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.
# 12 CCLite 联合改造建议
文档状态:根据 `..\CCLite\femlite_suggests.md` 新建议提取,并按 FemLite 0.6.5 当前能力修订。
## 1. 结论摘要
CCLite 对 FemLite 的新建议已经从“建立基础 coupling API”推进到“真实 IPC worker 接入闭环”。FemLite 0.6.5 已经完成中立 coupling API、worker mock、Windows IPC adapter、surface/facet 扩展导出、节点力导入、诊断 CSV、真实 IPC worker、能力查询和对应回归测试,因此后续不应重复做这些基础项。
0.6.5 已经保留现有 mock worker,同时新增真实 IPC worker 运行模式,让 `femlite.exe --cclite-worker --worker-backend ipc` 能按 CCLite 标准参数打开 command block、data block 和 named event,完成无 SPHLite 依赖的 attach、READY、空 facet/load、STOP 自测闭环。
真实 SPH-FEM penalty contact、FSI、tie/release 或强耦合 rollback 仍属于 CCLite 算法或后续联调层能力,不应作为 0.6.5 已完成能力声明。
## 2. 必须保持的边界
FemLite 继续负责:
- FEM 输入、网格、材料、section、边界条件解析。
- 实体/壳单元内力、质量、刚度和本构更新。
- 显式动力、线性静力、非线性静力、隐式 Newmark 等自身求解流程。
- FemLite 内部接触、cohesive、mortar/AL 等已有能力。
- restart、CSV、VTU/PVD、诊断、Fortran API、C ABI 和自身 release gate。
- 稳定导出 FEM surface/facet 状态,并接收外部节点力等基础载荷。
CCLite 继续负责:
- 启动、监控和停止 FemLite worker。
- 创建、reset 和销毁 Windows shared memory 与 named event。
- 解析 CCLite 联合输入。
- 读取 FemLite facet 状态和 SPHLite 粒子状态。
- 计算 SPH-FEM 接触、FSI 或其他联合界面载荷。
- 写回 FemLite 与 SPHLite 外部载荷。
- 输出联合诊断、force balance 和跨求解器一致性报告。
FemLite 不应做:
- 直接调度 SPHLite。
- 读取 SPHLite 私有数据结构。
- 链接 CCLite Fortran95 算法核心。
- 复制 CCLite 的 SPH-FEM 接触搜索、耦合或 FSI 算法。
- reset CCLite 创建并拥有的 event。
- 把 CCLite 预留能力描述成 FemLite 已完成物理算法。
## 3. FemLite 0.6.4 已完成项
0.6.4 已经覆盖 CCLite 建议中的基础闭环:
- 中立 coupling surface/facet wrapper 和 C ABI。
- 旧 `boundary` 与 `sph` 命名接口继续兼容。
- surface/facet 扩展导出字段:`surface_id`、`material_id`、`section_id`、`valid_flags`、`shell_thickness`、`mass_per_area`。
- 按 `*SURFACE, NAME=..., TYPE=ELEMENT` 名称过滤导出。
- 退化 facet invalid flag、normal 单位化、实体面厚度为 0、壳厚度和面密度测试。
- coupling 节点力导入,包含 `source_id`、`load_mode`、`valid_flags`。
- 独立 external load cache,`fem_clear_coupling_loads` 统一清理本步载荷和诊断。
- 节点力已叠加到显式动力外力、线性静力 RHS 和隐式/非线性外力装配路径。
- 本步总力、总力矩、接受记录、非有限载荷、未知节点和容量/metadata 拒绝计数。
- 按 `source_id` 汇总诊断。
- `femlite_cclite_load_report.csv` 和 `femlite_cclite_surface_report.csv`。
- worker mock 命令状态机,覆盖 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`IMPORT_LOADS`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`。
- worker mock 100 step 空耦合、seq/ack、STOP、错误路径、VTU/PVD 与诊断 CSV 一致性测试。
- Windows shared memory / named event C adapter,提供 open/wait/signal/close,不 reset event。
- transport facade 的 mock 与 Windows IPC backend 小闭环测试。
这些能力是后续真实 IPC worker 的基础,不需要重写。
## 4. 新建议提取与修订
### 4.1 标准 worker 参数
CCLite 新建议要求支持:
```text
femlite.exe --cclite-worker --solver-id FEM --case femlite.inp --ipc-name CCLITE_CASE001 --timeout-ms 30000
```
并预留:
```text
--command-block <name>
--data-prefix <prefix>
--log <path>
--timeout-ms <value>
--worker-id <id>
```
FemLite 修订建议:
- 保留当前 `--cclite-worker --case --ipc-name --log --output-dir --mock-steps`,避免破坏 0.6.4 回归。
- 新增 `--solver-id`、`--timeout-ms`、`--command-block`、`--data-prefix`、`--worker-id`。
- 增加模式区分:`--mock-steps` 存在或显式 `--worker-backend mock` 时运行 mock worker;指定真实 IPC backend 时打开 CCLite 对象。
- `--solver-id` 初期只接受 `FEM` 或 `FEMLite`,不把求解器类型泛化成插件系统。
优先级:高,适合下一版。
### 4.2 真实 IPC worker 主循环
CCLite 新建议要求 worker 启动后打开 CCLite 创建的 command block、data block、command event、done event,进入 READY,随后 wait command、执行命令、写回 ack/state/error 并 signal done。
FemLite 修订建议:
- 复用 0.6.4 的 `femlite_cclite_transport` facade,不另起一套 IPC 代码。
- 将现有 mock worker 的命令处理逻辑抽成 backend 无关的命令执行器。
- 第一阶段只闭合真实 IPC 下的 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`IMPORT_LOADS` 空载荷、`ADVANCE` 空耦合、`WRITE_OUTPUT`、`STOP`。
- FemLite 只 wait/signal,不 reset event。
- 非 Windows 继续返回 unsupported,并保留 mock worker 可运行。
优先级:最高,适合下一版作为主目标。
### 4.3 data block 与数据布局
CCLite 新建议明确要求打开 data block,并优先闭合 `FEM_TO_CCL_FACET` 与 `CCL_TO_FEM_LOAD`。
FemLite 修订建议:
- 新增明确版本化布局,例如 `AOR_V1`。
- `FEM_TO_CCL_FACET` 先支持 header + facet records,字段来自现有扩展导出。
- `CCL_TO_FEM_LOAD` 先支持 header + nodal force records,字段映射到现有 coupling 节点力导入。
- data block 由 CCLite 创建和定容,FemLite 只 open、检查版本和容量、读写合法范围。
- 如果容量不足,FemLite 返回稳定错误码并写 worker 日志,不截断静默成功。
优先级:高,适合与真实 IPC worker 同版完成最小闭环。
### 4.4 surface/facet 字段
CCLite 建议字段包括:
```text
facet_id, surface_id, elem_id, face_id, node_count, node_ids,
x_node, v_node, normal, area, shell_thickness, mass_per_area,
material_id, section_id, body_id, valid_flags
```
FemLite 当前已完成除 `body_id` 外的主要字段。
FemLite 修订建议:
- `body_id` 不应临时伪造为材料号、section 号或 element set 号。
- 下一步可先定义 `body_id=0` 的占位规则并文档化,或增加显式 body/part 映射表后再输出真实稳定 ID。
- 继续保持实体面 `shell_thickness=0`、`mass_per_area=0`。
- 继续让退化 facet 进入导出但标记 `valid_flags=0`,便于诊断。
- 如果 CCLite 需要跨文件稳定 surface id,应新增显式 surface id 映射表,而不是依赖内部 surface 序号。
优先级:中高。`body_id` 和稳定 surface id 可在真实 IPC data block 之后做。
### 4.5 外部载荷导入
CCLite 建议基础载荷为:
```text
node_id
force[3]
source_id
load_mode
distribution_mode
valid_flags
```
并预留:
```text
FACET_PRESSURE
MOMENT
KINEMATIC_BOUNDARY
```
FemLite 当前已支持节点力、source/load_mode/valid_flags、总力/总力矩和诊断 CSV。
FemLite 修订建议:
- 下一步在 data block 中增加 `step_id`、`record_id`、`distribution_mode` 字段,但 Fortran 求解侧暂不必使用 `distribution_mode`。
- `MOMENT` 不应直接假装已支持。若要支持,应先明确转动自由度、壳/实体节点 DOF 映射和静力/动力 RHS 规则。
- `FACET_PRESSURE` 可复用历史 facet pressure 能力,但需要中立 coupling API 和 data block 记录格式后再开放。
- `KINEMATIC_BOUNDARY` 风险较高,涉及约束生命周期和求解器一致性,应延期。
优先级:节点力 data block 高;facet pressure 中;moment/kinematic boundary 暂缓。
### 4.6 诊断和 force balance
CCLite 建议 worker 至少输出启动参数、command block 名称、data block 名称、command id、step id、ack seq、worker state、facet 数、load 数、总力、总力矩、错误码和错误消息。
FemLite 当前已有 worker log、load report、surface report,但还缺真实 IPC 对象名称、data block 名称和短错误消息字段。
FemLite 修订建议:
- 扩展 worker log header:记录 backend、solver_id、worker_id、ipc_name、command_block、data_prefix、timeout_ms。
- 扩展每条命令日志:记录 command_id、step_id、substep_id、iteration_id、state、error_code、短错误消息。
- 在 `WRITE_OUTPUT` 或每步结束时同步输出 facet/load 诊断。
- 保持报告文件名:
- `femlite_cclite_worker.log`
- `femlite_cclite_surface_report.csv`
- `femlite_cclite_load_report.csv`
- 不把 CCLite 的联合 `force_balance.csv` 直接写进 FemLite;FemLite 提供原始统计,由 CCLite 生成跨求解器 force balance。
优先级:高,适合真实 IPC worker 同版完成。
### 4.7 能力查询入口
CCLite 新建议增加:
```text
femlite.exe --cclite-capabilities
```
建议输出:
```text
solver=FEMLite
cclite_worker=yes
worker_mock=yes/no
ipc_backend=windows_shmem_named_event
command_block_version=1
data_layout=AOR_V1
supports_real_ipc=yes/no
supports_fem_to_ccl_facet=yes/no
supports_ccl_to_fem_load=yes/no
max_facet_records=...
max_load_records=...
```
FemLite 修订建议:
- 建议新增该 CLI,输出稳定 key=value 文本,方便 CCLite 解析。
- 同步提供 C ABI 能力查询不是必须,可后置。
- `supports_real_ipc` 在真实 worker 主循环完成前必须输出 `no`,避免误判。
- `max_facet_records`、`max_load_records` 初期可输出编译期常量或 `0` 表示由 CCLite data block 容量决定。
优先级:高,成本低,适合下一版。
### 4.8 输入关键字
CCLite 建议 FemLite 可选支持:
```text
*FEMLITE CCLITE
WORKER=YES
EXPORT_SURFACE=CCL_SURF_PLATE
EXPORT_VELOCITY=YES
EXPORT_THICKNESS=YES
ACCEPT_EXTERNAL_LOAD=YES
```
FemLite 修订建议:
- 不建议把它作为下一版主线。真实 worker 的命令行和 IPC data block 优先级更高。
- 若要做,应只作为 FemLite 侧辅助配置,不替代 CCLite 联合输入。
- `EXPORT_SURFACE` 可映射到已有 surface 名称过滤。
- 不应在 input keyword 中声明真实 SPH-FEM 接触算法已经启用。
优先级:中低,建议在真实 IPC worker 闭环后再做。
### 4.9 自测和联调路径
CCLite 新建议要求在没有 SPHLite 的情况下验证 worker 启动、IPC attach、READY、空 facet、空 load、STOP。
FemLite 修订建议:
- 新增真实 IPC self-test,使用本地测试 helper 创建 shared memory/event,启动或调用 FemLite worker,验证 INIT 到 STOP。
- 测试分三层:
- adapter 单元测试:open/wait/signal/no reset/timeout。
- in-process transport 测试:command block 与 100 step 空耦合。
- process-level worker 测试:`femlite.exe --cclite-worker --worker-backend ipc` 真实进程 attach。
- 与 CCLite 联调先验收三类路径:
- mock SPH + 真实 FemLite,1 step 空耦合。
- mock SPH + 真实 FemLite,100 step 空耦合。
- 异常输入和 timeout 可控退出。
优先级:最高,真实 IPC worker 必须配套。
## 5. 逐条响应 CCLite 建议
| CCLite 建议 | FemLite 0.6.5 状态 | 修订响应 |
|---|---|---|
| 保持 FemLite 独立 worker/service,不嵌入 CCLite 算法 | 已遵守 | 继续保持,adapter 只做通信和数据映射 |
| 支持 `--cclite-worker` | 已支持 mock worker 和真实 IPC backend | 继续保持两种 backend |
| 打开 command block | 已通过真实 IPC worker 接入 | 继续保持小闭环回归 |
| 打开 data block | 已定义 `AOR_V1` 并接入 facet/load block | 后续扩展更多记录类型 |
| wait `COMMAND_EVENT` / signal `DONE_EVENT` | 已在真实 worker 中使用 | 继续保持不 reset event 约束 |
| 不 reset event | 已遵守 | 继续作为接口约束和测试项 |
| 支持 INIT 到 STOP 命令 | mock 与真实 IPC worker 已支持 | 继续复用同一命令执行器 |
| `substep_id=0`、`iteration_id=0` | 已有字段 | 真实 IPC worker 初期继续固定为 0 |
| 导出空或固定 facet | 已通过 data block 支持空/fixed facet 边界 | 后续接入更完整 surface/body 映射 |
| 接收空载荷 | 已支持 | 继续保持空载荷自测 |
| 接收节点力 | API 与求解路径已支持,`CCL_TO_FEM_LOAD` 已接入 | 后续扩展更多载荷类型 |
| 输出 worker 日志和接口诊断 | 已补充 backend、IPC 名称、data block 名称和短错误消息 | 后续补强跨求解器对账字段 |
| 导出 shell thickness/mass per area | 已支持并加入 data block | 继续保留 |
| 导出 body_id | 未支持 | 暂用 `0` 占位或后续显式 body 映射,不伪造 |
| 稳定 surface id | 当前为内部序号 | 后续增加显式映射表 |
| 支持 facet pressure | 历史内部能力存在,中立 CCLite block 未接 | 后续单独做,不与真实 IPC worker 混在同一最小闭环 |
| 支持 moment | 未支持 | 暂缓,需要 DOF/RHS 语义设计 |
| 支持 kinematic boundary | 未支持 | 暂缓,风险较高 |
| `--cclite-capabilities` | 已支持 | 保持 key=value 输出稳定 |
| 无 SPHLite 自测 | 已补 process-level 真实 IPC 自测 | 后续可增加 CCLite mock 联调 |
| 不把 mock 当真实耦合完成 | 文档已说明 | 继续明确区分 mock worker 与 real IPC worker |
## 6. 0.6.5 完成范围
0.6.5 已按“真实 IPC worker 接入闭环”落地以下范围:
1. CLI 参数补齐:`--solver-id`、`--timeout-ms`、`--command-block`、`--data-prefix`、`--worker-id`、`--worker-backend`。
2. `--cclite-capabilities` key=value 输出。
3. worker 命令执行器与 transport backend 解耦。
4. 真实 Windows IPC worker 主循环接入 command block/event。
5. 定义 `FEM_TO_CCL_FACET` data block `AOR_V1` header 和最小 facet records。
6. 定义 `CCL_TO_FEM_LOAD` data block `AOR_V1` header 和空/nodal force records。
7. worker log 增加 backend、IPC 名称、data block 名称和短错误消息。
8. process-level self-test 覆盖 attach、READY、空 facet、空 load、STOP、timeout 和异常输入。
9. 文档更新,明确 mock worker、IPC adapter、real IPC worker 三者边界。
该版本不建议包含:
- 真实 SPH-FEM penalty contact 物理验收。
- FSI 工程算例。
- tied/release。
- rollback 或预测状态接口。
- facet pressure 的完整物理验收。
- kinematic boundary。
- 删除旧 `sph` 命名接口。
## 7. 建议版本路线
| 建议版本 | FemLite 目标 |
|---|---|
| 0.6.4 | 已完成:中立 coupling API、worker mock、IPC adapter、surface/facet 扩展导出、节点力导入与诊断 |
| 0.6.5 | 已完成:真实 IPC worker 接入闭环、标准 worker 参数、data block AOR_V1、能力查询、自测 |
| 0.6.6 | 推荐:稳定 surface/body id 映射、process-level CCLite mock 联调和诊断字段补强 |
| 0.6.7 | 可选:facet pressure 中立导入、更多 force balance 对账 |
| 0.7.x | tied/release、rollback 预留、弱/强耦合策略、长时间稳定性 |
| 0.8.x | FSI 和工程化联合算例 |
## 8. 最终建议
CCLite 新建议中,0.6.5 已完成的“真实 IPC worker 接入闭环”直接承接 0.6.4 的 adapter、mock worker、surface/load API 和诊断能力,能让 CCLite 明确区分:
- `worker mock`:FemLite 内部顺序执行命令的测试模式。
- `IPC adapter`:C 层 shared memory/event 操作封装。
- `real IPC worker`:真正由 CCLite command/event 驱动的 worker 运行模式。
真实 IPC worker、data block 和 process-level self-test 已在 0.6.5 形成最小闭环;但它仍只是通信和数据边界验收,不等同于真实 SPH-FEM 接触物理验收。