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

12 KiB
Raw Blame History

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 和求解流程耦合在一起。

建议命令:

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 解析能力,而不是新增另一套不兼容语法。

建议目标:

*SURFACE, NAME=CCL_SURF_PLATE, TYPE=ELEMENT
...

可选增加辅助关键词:

*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。