Files
FemLite/docs/12_cclite_integration_suggestions.md
T
shenw 0440ed5a64
FemLite CI / build-test (push) Has been cancelled
Release FemLite 0.6.4
2026-07-05 17:23:34 +08:00

304 lines
12 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 当前能力修订
## 1. 改造口径
FemLite 不建议改造成 CCLite 的内部库,也不建议把 CCLite 的 SPH-FEM 接触搜索、FSI 或调度算法复制进 FemLite。更合适的边界是:
- FemLite 保持独立求解器、独立 CLI、Fortran API 和 C ABI。
- 新增一层面向 CCLite 的 worker/service adapter。
- adapter 只负责命令、通信、数据映射、诊断和错误码。
- FEM 侧只提供稳定 surface/facet 状态和外部载荷入口。
- CCLite 负责联合调度、shared memory、named event、SPH-FEM 接触/耦合算法和联合诊断。
## 2. FemLite 当前已有基础
当前 FemLite 已具备一部分耦合基础,不应重复开发:
- 已有边界 facet 查询能力:`fem_get_boundary_facet_count`、`fem_get_boundary_facets` 及 C ABI 对应接口。
- 已有 facet 压力、traction、facet nodal load 入口和总力查询入口。
- 已有元素 introspection API,可查询元素类型、节点、坐标、积分点、形函数、Jacobian 和 B 矩阵。
- 已有接触、particle-facet、particle-FEM 相关模块和 smoke 测试,可作为后续联合验证基础。
- 默认场变量输出已是 `result_XXXXXXXX.vtu` + `results.pvd`,适合 CCLite 联合结果检查。
这些能力目前仍偏内部或历史命名,例如 `sph` 前缀较多。后续建议先增加中立 coupling wrapper,而不是直接删改旧接口。
## 3. 必须保持的边界
FemLite 继续负责:
- FEM 输入、网格、材料、section、边界条件解析。
- 实体/壳单元内力、质量、刚度和本构更新。
- 显式动力学、静力、非线性静力、隐式 Newmark。
- FEM 内部接触、cohesive、mortar/AL 等已有能力。
- restart、CSV、VTU/PVD、诊断和自身 release gate。
CCLite 负责:
- 启动、监控和停止 FemLite worker。
- 创建和销毁 Windows shared memory 与 named event。
- 解析 CCLite 联合输入。
- 读取 FemLite boundary facet 和 SPHLite 粒子状态。
- 计算 SPH-FEM 接触、FSI 或其他联合界面载荷。
- 写回 FemLite 与 SPHLite 的外部载荷。
- 输出联合诊断和力平衡报告。
FemLite 不应:
- 直接调度 SPHLite。
- 读取 SPHLite 私有数据结构。
- 链接 CCLite Fortran95 算法核心。
- 在内部复制 CCLite 的 SPH-FEM 接触搜索算法。
- reset 由 CCLite 创建并拥有的 event。
- 把 CCLite 预留能力描述成 FemLite 已完成物理算法。
## 4. 推荐分阶段路线
### 4.1 阶段 A:中立 coupling API 固化
目标是把已有 facet/load 能力整理为 CCLite 可稳定依赖的公共接口,不引入 worker IPC。
建议内容:
- 新增或文档化中立命名 C ABI,例如 `femlite_get_coupling_surface_count`、`femlite_get_coupling_surface_facets`、`femlite_apply_coupling_nodal_forces`。
- 旧 `sph` 命名接口保留为兼容 wrapper。
- 明确数组展开方式、容量不足返回、无效 id 返回和非有限载荷拒绝。
- 增加 coupling load 总力、总力矩、拒绝记录数、节点未匹配数查询。
- 增加 C API smoke,覆盖 facet 导出、空载荷、节点力和错误边界。
建议先作为 0.6.x 小版本完成。
当前实现状态:
- 已新增中立 surface count/facets wrapper,阶段 A 暂导出全部边界 facet。
- 已新增中立 nodal force wrapper,复用现有外部耦合力向量。
- 已新增 coupling load 诊断,可查询总力、总力矩、接受记录数、非有限载荷拒绝数、未知节点拒绝数和容量/metadata 拒绝数。
- 已补充 C API smoke,覆盖 surface count、三角形/四边形 facet 导出、当前坐标/速度导出、空载荷、节点力、非有限载荷、未知节点和容量错误。
- surface 名称过滤、壳厚度、mass per area 和更完整 surface 字段仍留在后续阶段。
### 4.2 阶段 B:worker 协议 smoke
目标是让 FemLite 具备 worker 主循环和命令状态机,但通信层先使用 mock transport 或文件/内存模拟,避免一开始就把 Windows IPC 和求解流程耦合在一起。
建议命令:
```text
INIT
READ_INPUT
BUILD_MODEL
EXPORT_INTERFACE
IMPORT_LOADS
ADVANCE
WRITE_OUTPUT
STOP
```
完成标准:
- `femlite.exe --cclite-worker --case femlite.inp --ipc-name <name>` 可进入 worker 模式。
- 未指定 `--cclite-worker` 时原 CLI 行为完全不变。
- worker 可进入 `READY`、响应 `STOP`、写错误码和日志。
- mock 传输可完成 100 step 空耦合。
当前实现状态:
- 已新增 `fem_cclite_worker` mock worker,内部命令覆盖 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`IMPORT_LOADS`、`ADVANCE`、`WRITE_OUTPUT` 和 `STOP`。
- 已新增 worker command block,包含 `seq`、`ack_seq`、`command_id`、`step_id`、`substep_id`、`iteration_id`、`worker_state` 和 `error_code`。
- 已新增 `--cclite-worker` CLI 入口,支持 `--case`、`--ipc-name`、`--log`、`--output-dir` 和 `--mock-steps`。
- 已新增 CSV 风格 worker 日志,记录启动参数、命令状态和错误码。
- 已补充 `cclite_worker_mock` 回归测试,覆盖 READY、seq/ack、100 step 空耦合、VTU/PVD 输出、STOP 和输入错误路径。
- 当前仍是 mock 协议闭环,不是真实 Windows shared memory/named event IPC。
### 4.3 阶段 C:Windows IPC adapter
目标是接入 CCLite 创建的 command block、data block、named event。
建议边界:
- FemLite 只 open CCLite 创建的对象。
- FemLite 只 wait/signal,不 reset event。
- command block 必须包含 `seq`、`ack_seq`、`command_id`、`step_id`、`substep_id`、`iteration_id`、`error_code`。
- 0.1.x 可固定 `substep_id=0`、`iteration_id=0`。
- IPC 错误必须写 worker 日志和稳定错误码。
该阶段建议只验收空 facet 或少量固定 facet 导出,不验收真实 SPH-FEM 接触力。
当前实现状态:
- 已新增 `femlite_cclite_ipc.h` 和 C adapter,定义稳定 command block 布局、命令枚举、状态枚举和 IPC 错误码。
- 已新增 shared memory open/close wrapper,Windows 下只打开 CCLite 已创建对象,非 Windows 返回 unsupported。
- 已新增 named event open/wait/signal/close wrapper,wait/signal 不 reset event。
- 已新增 `femlite_cclite_wait_command` 和 `femlite_cclite_write_done`,支持等待 `COMMAND_EVENT` 后读取 command block,并写回 ack/state/error 后 signal `DONE_EVENT`。
- 已新增 `femlite_cclite_transport` facade,提供 mock 与 Windows IPC 两个 backend 的统一 receive/complete 入口。
- 已补充 `cclite_ipc_adapter` smoke,覆盖命名、布局、open、timeout、wait/signal 和 event 不 reset。
- 已补充 `cclite_ipc_worker_loop` smoke,使用本地测试 helper 模拟 CCLite,并通过 transport facade 完成 INIT 到 STOP 和 100 step 空耦合。
- 当前尚未把 `femlite.exe --cclite-worker` 主循环切换为真实跨进程 Windows IPC 运行模式;现阶段先固化 adapter 和 transport 小闭环。
### 4.4 阶段 D:真实 surface/facet 导出
目标是让 CCLite 能读取稳定 FEM 边界状态。
最小字段:
- `facet_id`
- `surface_id`
- `elem_id`
- `face_id`
- `node_count`
- `node_ids`
- 当前节点坐标
- 当前节点速度
- facet normal
- facet area
- material id
- section id
- valid flags
壳单元扩展字段:
- shell thickness
- mass per area
实体面 `shell_thickness=0`。退化 facet 应设置 invalid flag,不应静默导出为有效接触面。
当前实现状态:
- 已新增 coupling surface 扩展导出接口,保留旧 ABI,同时输出 `surface_id`、`material_id`、`section_id`、`valid_flags`、`shell_thickness` 和 `mass_per_area`。
- 未指定 surface 时继续导出全部边界 facet,`surface_id=0` 并写 warning。
- 已支持按已有 `*SURFACE, NAME=..., TYPE=ELEMENT` 名称过滤导出。
- 已补充单三角形、单四边形、退化三角形、退化四边形、实体面厚度为 0、壳厚度、面密度和 normal 单位化 smoke。
- 当前 surface_id 使用内部 surface 序号;若 CCLite 需要稳定跨文件 ID,后续可增加显式映射表。
### 4.5 阶段 E:外部载荷导入与诊断
目标是支持 CCLite 写回的节点力,并安全叠加到 FemLite 求解流程。
建议先只做:
- `NODAL_FORCE`
- `node_id`
- `force[3]`
- `source_id`
- `load_mode`
- `valid_flags`
FemLite 内部应有独立外部耦合载荷缓存。每个 CCLite step 开始前清零,导入后再叠加到当前求解步外力或 RHS。不要让 CCLite 直接写 FemLite 全局力数组。
诊断至少包括:
- 本步接收总力。
- 本步接收总力矩。
- 每个 surface 的总载荷。
- 被拒绝的 load record 数量。
- 非有限载荷数量。
- 节点 id 未匹配数量。
当前实现状态:
- 已新增独立 coupling external load 缓存,并通过 `fem_clear_coupling_loads` 统一清理本步载荷和诊断。
- coupling 节点力已叠加到显式动力外力路径、静力线性 RHS 和隐式/非线性外力装配路径。
- 已校验 `source_id`、`load_mode`、`valid_flags`、非有限载荷和未知节点,拒绝记录会进入诊断计数。
- 已提供本步总力、总力矩、按 `source_id` 汇总的诊断查询。
- 已输出 `femlite_cclite_load_report.csv` 与 `femlite_cclite_surface_report.csv`,worker mock 在写 VTU/PVD 时同步写出两份报告。
- 已补充显式单步响应、静力 RHS 响应、force balance CSV 和 worker 输出一致性回归测试。
- 当前仍是基础节点力闭环,不包含真实 SPH-FEM penalty contact、FSI 或 CCLite 强耦合 rollback。
## 5. 输入与 surface 语义建议
FemLite 自身输入仍由 FemLite 解析。建议优先复用或加强已有 `*SURFACE`/接触 surface 解析能力,而不是新增另一套不兼容语法。
建议目标:
```text
*SURFACE, NAME=CCL_SURF_PLATE, TYPE=ELEMENT
...
```
可选增加辅助关键词:
```text
*FEMLITE CCLITE
WORKER=YES
EXPORT_SURFACE=CCL_SURF_PLATE
EXPORT_VELOCITY=YES
EXPORT_THICKNESS=YES
ACCEPT_EXTERNAL_LOAD=YES
```
该关键词只作为 FemLite 侧辅助配置,不替代 CCLite 联合输入。
## 6. 测试建议
阶段 A 测试:
- C ABI coupling surface count。
- 三角形 facet 导出。
- 四边形 facet 导出。
- 当前坐标和速度导出。
- 空载荷导入。
- 节点力导入。
- 容量不足错误。
- 非有限载荷拒绝。
- 节点 id 未匹配错误。
阶段 B/C 测试:
- worker 启动。
- `READY` 状态。
- command seq/ack。
- wait/signal,不 reset event。
- 100 step 空耦合。
- `STOP` 正常退出。
- 超时和错误码。
阶段 D/E 联合测试:
- 单三角形 facet。
- 单四边形 facet。
- 壳厚度导出。
- 单粒子撞面。
- 多粒子压面。
- force balance CSV 对账。
- VTU/PVD 场输出和 worker 诊断文件一致性检查。
可复用算例:
- `contact_rigid_plane_indentation`
- `shell_rigid_plane_contact`
- `shell_solid_contact`
- `clamped_square_plate_pressure_pulse`
- `rigid_sphere_impact_plate`
## 7. 建议版本切分
| 建议版本 | FemLite 目标 |
|---|---|
| 0.6.x | 中立 coupling API wrapper、文档、C ABI smoke、外部载荷诊断框架 |
| 0.7.0 | worker/service mock transport、命令状态机、空耦合闭环 |
| 0.7.1 | Windows shared memory + named event adapter、CCLite 空耦合联调 |
| 0.7.2 | surface/facet 完整导出、节点力导入、force/moment 诊断 |
| 0.7.x 后续 | shell thickness、mass per area、surface id 稳定化、pressure/facet load |
| 0.8.x | tie/release、rollback/强耦合预留、长时间稳定性 |
| 0.9.x | FSI 工程简化算例、性能基线和异常处理补强 |
## 8. 不建议立即做的事项
- 不建议把 CCLite 接触算法移入 FemLite。
- 不建议 FemLite 直接链接 CCLite 核心库。
- 不建议一开始就做真实 SPH-FEM penalty contact 验收。
- 不建议 worker IPC、真实载荷导入、surface 名称稳定化和强耦合 rollback 一次性开发。
- 不建议删除旧 `sph` 命名接口,应先提供中立 wrapper 并保留兼容期。
## 9. 推荐下一步
最稳的小闭环是先做阶段 A:
1. 盘点现有 boundary facet 与 sph load API。
2. 增加中立 coupling wrapper。
3. 增加 coupling load 诊断。
4. 补 C ABI smoke。
5. 更新接口文档。
完成后再进入 worker/service,而不是直接上 Windows IPC。