# FEMLite 配合 CCLite 的改造建议 ## Coupling & Contact Lite for SPHLite and FEMLite **对象**:FEMLite **目的**:使 FEMLite 能作为 CCLite 的独立 worker/service,参与 SPH-FEM 耦合、接触和后续 FSI 联合仿真。 **依据**:CCLite `01` 到 `06` 号文档、`v1.x_development_plan.md`、FEMLite 当前接口文档与能力说明。 **编码要求**:中文,UTF-8 without BOM。 # 1. 总体建议 FEMLite 不需要被改造成 CCLite 的内部库,也不应把 CCLite 接触算法写入 FEMLite 内部。建议 FEMLite 保持独立主控程序身份,只新增一层面向 CCLite 的 worker/service 模式。 FEMLite 对 CCLite 的核心责任是: 1. 在 worker 模式下接受 CCLite 的命令; 2. 按 CCLite 要求导出 FEM 边界 surface/facet 状态; 3. 接收 CCLite 写回的节点力、facet 载荷或后续压力载荷; 4. 将外部载荷安全叠加到 FEM 显式或隐式求解流程; 5. 输出可检查的接口诊断; 6. 保持原 FEMLite 独立运行、Fortran API 和 C ABI 不被破坏。 建议把本改造定位为: ```text FEMLite 原有求解器 + FEMLite CCLite worker/service adapter + FEM surface/load public interface ``` 其中 adapter 只负责通信、命令和数据映射,不负责 CCLite 算法。 # 2. 必须保持的边界 ## 2.1 FEMLite 继续负责 FEMLite 继续负责: 1. FEM 节点、单元、材料、section、边界条件解析; 2. 实体/壳单元内力、质量、刚度和本构更新; 3. 显式动力学、静力、非线性、隐式 Newmark 等自身求解流程; 4. FEM 内部接触、cohesive、mortar/AL 等已有能力; 5. restart、CSV/VTK 输出和自身 release gate; 6. FEM 内部错误码和诊断。 ## 2.2 CCLite 负责 CCLite 负责: 1. 启动和调度 FEMLite worker; 2. 创建和销毁 Windows shared memory 与 named event; 3. 解析 CCLite `.inp`; 4. 读取 FEMLite 导出的 boundary facet; 5. 读取 SPHLite 导出的粒子状态; 6. 计算 SPH-FEM 接触、耦合和 FSI 界面载荷; 7. 把结果写回 FEMLite 和 SPHLite; 8. 输出联合诊断。 ## 2.3 FEMLite 不应做 FEMLite 不应: 1. 直接调度 SPHLite; 2. 直接读取 SPHLite 私有数据结构; 3. 直接链接 CCLite Fortran95 算法核心; 4. 在自身内部复制 CCLite 的 SPH-FEM 接触搜索算法; 5. 修改 CCLite 创建的 event reset 责任; 6. 把 CCLite 0.1.x 预留能力宣称为已完成物理算法。 # 3. 0.1.x 必要改造 0.1.x 的目标是让 FEMLite 能参与 CCLite 空耦合和接口闭环,不要求真实 SPH-FEM 接触力验收。 FEMLite 侧建议完成: 1. 增加 `--cclite-worker` 命令行模式; 2. worker 模式能打开 CCLite 创建的 command block; 3. worker 模式能打开 CCLite 创建的 data block; 4. worker 模式能等待 `COMMAND_EVENT`; 5. worker 模式能触发 `DONE_EVENT`; 6. worker 只 wait/signal,不 reset event; 7. 支持 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`; 8. `substep_id=0`、`iteration_id=0`; 9. 可导出 0 个或少量固定 FEM facet; 10. 可接收空载荷; 11. 可写出 worker 日志和接口诊断。 0.1.x 完成标准: 1. FEMLite 原独立运行入口不受影响; 2. CCLite 能启动 FEMLite worker; 3. FEMLite worker 能进入 `READY`; 4. FEMLite worker 可完成 100 step 空耦合; 5. FEMLite worker 可响应 `STOP`; 6. 异常时能写 `error_code`; 7. 资源由 CCLite 释放后,FEMLite worker 正常退出。 # 4. Worker/Service 模式建议 ## 4.1 启动方式 建议 FEMLite 支持: ```text femlite.exe --cclite-worker --solver-id FEM --case femlite.inp --ipc-name ``` 可选参数: ```text --command-block --data-prefix --log --timeout-ms --worker-id ``` 若未指定 `--cclite-worker`,FEMLite 仍按原 CLI 行为运行。 ## 4.2 Worker 主循环 建议 worker 主循环为: ```text initialize worker open command block open data blocks signal READY while true: wait COMMAND_EVENT read command block case INIT: initialize ipc-side state case READ_INPUT: read femlite.inp case BUILD_MODEL: build FEM model and surface database case EXPORT_INTERFACE: write FEM_TO_CCL_FACET case IMPORT_LOADS: read CCL_TO_FEM_LOAD case ADVANCE: advance one CCLite macro step or worker-controlled step case WRITE_OUTPUT: write FEMLite output case STOP: signal DONE and exit write ack_seq update worker_state signal DONE_EVENT ``` 0.1.x 可暂不启用 `IMPORT_LOADS`,但应保留命令枚举。0.2.x 必须支持载荷导入。 # 5. FEM Surface/Facet 导出建议 ## 5.1 导出对象 FEMLite 应面向 CCLite 导出 boundary surface/facet,而不是导出完整单元内部状态。 0.2.x 接触至少需要: 1. facet id; 2. surface id; 3. element id; 4. node count; 5. node ids; 6. 当前节点坐标; 7. 当前节点速度; 8. facet normal; 9. facet area; 10. shell thickness; 11. mass per area; 12. material id; 13. section id; 14. body id; 15. valid flags。 ## 5.2 实体面 实体单元边界面建议导出: ```text face_id elem_id surface_id node_count = 3 or 4 node_ids[] x_node[3,node] v_node[3,node] normal[3] area material_id body_id valid_flags ``` 实体面 `shell_thickness` 可写 0。 ## 5.3 壳面 壳单元面建议导出: ```text face_id elem_id surface_id node_count = 3 or 4 node_ids[] x_node[3,node] v_node[3,node] normal[3] area shell_thickness mass_per_area section_id material_id body_id valid_flags ``` 壳厚度必须来自 FEMLite section 或壳单元属性,不能由 CCLite 猜测。CCLite 只把 `shell_thickness` 用于接触距离、载荷分配和诊断。 ## 5.4 法向约定 FEMLite 应导出稳定、可复现的 facet normal。 建议: 1. normal 使用当前构型; 2. normal 长度为 1; 3. 退化 facet 设置 invalid flag; 4. 四边形 facet 的 normal 与 FEMLite 自身壳/面定义一致; 5. CCLite 可在单个接触对内部翻转局部法向,但不得修改 FEMLite 原始法向。 ## 5.5 Surface id FEMLite 输入文件应允许用户定义可被 CCLite 引用的 surface 名称。 建议: ```text *SURFACE, NAME=CCL_SURF_1 ... ``` FEMLite worker 导出时应提供稳定 `surface_id`。若短期内只能导出全边界,可填 0,但必须输出 warning,便于 0.2.x 后定位接触范围。 # 6. 载荷导入建议 ## 6.1 0.2.x 必须支持 0.2.x 起 FEMLite 应支持 `CCL_TO_FEM_LOAD`。 基本载荷类型: 1. `NODAL_FORCE`; 2. 后续预留 `FACET_PRESSURE`; 3. 后续预留 `MOMENT`; 4. 后续预留 `KINEMATIC_BOUNDARY`。 基础接触建议先只做节点力: ```text node_id force[3] source_id load_mode distribution_mode valid_flags ``` ## 6.2 外部载荷缓存 FEMLite 内部建议增加独立外部耦合载荷缓存: ```text fem_cclite_external_load node_id force[3] moment[3] source_id step_id active ``` 该缓存应在每个 CCLite step 开始前清零,导入后叠加到当前求解步的外力项或 RHS。 不要让 CCLite 直接写 FEMLite 内部全局力数组。 ## 6.3 力和力矩守恒 FEMLite 应输出或允许查询: 1. 本步接收的 CCLite 总力; 2. 本步接收的 CCLite 总力矩; 3. 每个 surface 的总载荷; 4. 被拒绝的 load record 数量; 5. 非有限载荷数量; 6. 节点 id 未匹配数量。 这些量用于 CCLite 的 `force_balance.csv` 和 06 号验证计划。 # 7. 输入文件建议 FEMLite 自身输入仍由 FEMLite 解析。为配合 CCLite,建议新增或明确以下关键词能力。 ## 7.1 Surface 定义 建议支持: ```text *SURFACE, NAME=CCL_SURF_PLATE, TYPE=ELEMENT ... ``` 对于壳: ```text *SHELL SECTION, ELSET=PLATE, THICKNESS=... ``` FEMLite worker 应能根据 `FEM_SURFACE` 名称导出对应 facet。 ## 7.2 CCLite 输出开关 可选支持: ```text *FEMLITE CCLITE WORKER=YES EXPORT_SURFACE=CCL_SURF_PLATE EXPORT_VELOCITY=YES EXPORT_THICKNESS=YES ACCEPT_EXTERNAL_LOAD=YES ``` 该关键词只是 FEMLite 侧辅助开关,不替代 CCLite `.inp`。 # 8. API/ABI 建议 FEMLite 已有 Fortran API 和 C ABI。建议在不破坏现有接口的前提下增加中立命名接口,不要出现 SPHLite 私有结构。 建议 C ABI: ```c int femlite_get_coupling_surface_count(const char *surface_name, int *num_facets, int *max_nodes_per_facet); int femlite_get_coupling_surface_facets(const char *surface_name, int max_facets, int max_nodes_per_facet, long long *facet_id, long long *elem_id, int *surface_id, int *node_count, long long *node_ids, double *x, double *v, double *normal, double *area, double *shell_thickness, double *mass_per_area, int *material_id, int *section_id, int *body_id, int *valid_flags, int *num_facets); int femlite_apply_coupling_nodal_forces(int num_loads, const long long *node_ids, const double *forces, const long long *source_ids, const int *load_mode, const int *valid_flags); ``` 数组展开建议沿用 FEMLite 现有 C ABI 风格: ```text x[dim + 3 * (local_node + max_nodes_per_facet * facet)] v[dim + 3 * (local_node + max_nodes_per_facet * facet)] normal[dim + 3 * facet] forces[dim + 3 * load] ``` # 9. 与 CCLite 版本路线的配合 | CCLite 版本 | FEMLite 配合目标 | | --- | --- | | 0.1.x | worker/service、command block、named event、空 facet/固定 facet 导出、空载荷接收 | | 0.2.x | surface/facet 完整导出、节点力导入、单粒子撞面和多粒子压面验证 | | 0.3.x | 壳厚度、边缘、四边形 facet、surface id 稳定化 | | 0.4.x | 阻尼/摩擦接触所需切向速度、接触诊断和载荷能量统计 | | 0.5.x | tied/release 所需绑定 surface、release 状态和 tie-to-contact 诊断 | | 0.6.x | pressure projection、FEM 运动边界、boundary/ghost 数据支持 | | 0.7.x | 弱耦合/强耦合需要的 step rollback 或预测状态接口预留 | | 0.8.x | SoA v2 性能测试、长时间稳定性和异常处理补强 | | 0.9.x | 工程简化算例、水下爆炸 FSI、参数推荐和性能基线 | # 10. 测试建议 ## 10.1 0.1.x 测试 FEMLite 侧建议新增: 1. worker 启动测试; 2. worker `READY` 状态测试; 3. command seq/ack 测试; 4. named event wait/signal 测试; 5. 空 facet 导出测试; 6. 固定 facet 导出测试; 7. 空载荷导入测试; 8. `STOP` 正常退出测试; 9. 超时和错误码测试。 ## 10.2 0.2.x 测试 建议新增: 1. 单三角形 facet 导出; 2. 单四边形 facet 导出; 3. 壳 facet 厚度导出; 4. 节点速度导出; 5. 节点力导入; 6. 节点 id 未匹配错误; 7. 非有限载荷拒绝; 8. 与 CCLite 的 `V020_SINGLE_PARTICLE_WALL` 联合测试。 ## 10.3 工程测试 建议保留以下 FEMLite 原有或新增算例作为后续联合验证基础: 1. 刚性平面/壳板接触小算例; 2. clamped square plate pressure pulse; 3. rigid sphere impact plate; 4. shell rigid plane contact; 5. shell/solid surface 导出 smoke。 # 11. 诊断建议 FEMLite worker 应至少输出: 1. worker 启动参数; 2. CCLite command block 名称; 3. data block 名称; 4. 当前 command id; 5. step id; 6. ack seq; 7. worker state; 8. 导出 facet 数量; 9. 接收 load 数量; 10. 接收总力; 11. 接收总力矩; 12. 错误码和错误消息。 建议输出文件: ```text femlite_cclite_worker.log femlite_cclite_surface_report.csv femlite_cclite_load_report.csv ``` # 12. 优先级建议 最高优先级: 1. worker/service 模式; 2. command block 与 named event; 3. surface/facet 导出; 4. 空载荷和节点力导入; 5. 诊断输出; 6. 与 CCLite mock/空耦合联调。 次优先级: 1. shell thickness 和 mass_per_area 精确导出; 2. surface id 稳定化; 3. pressure/facet load; 4. tie/release 支持; 5. rollback/强耦合预留。 # 13. 当前补充建议:真实 worker 接入闭环 根据 CCLite 0.1.9 对当前本地 FEMLite 的审计结果,FEMLite 已提供自运行的 CCLite worker mock,但尚未完整接受 CCLite 标准 IPC worker 参数,也尚未作为真实 Windows shared memory / named event worker 运行。建议当前保留已有 mock 能力,同时把重点收敛到真实 IPC worker adapter。 近期建议按以下顺序推进: 1. 完整支持 CCLite 标准 worker 参数: ```text femlite.exe --cclite-worker --solver-id FEM --case femlite.inp --ipc-name CCLITE_CASE001 --timeout-ms 30000 ``` 2. 保留现有 worker mock 参数和测试,但在日志、能力输出和文档中明确区分 `worker mock` 与 `real IPC worker`。 3. 实现真实 IPC worker 主循环,能够打开 CCLite 创建的 command block、data block、command event 和 done event。 4. worker 启动后应进入 `READY`,每条命令执行后回写 `ack_seq`、`worker_state`、`error_code` 和短消息。 5. worker 只负责 wait/signal,不负责 reset CCLite 创建的 event。 6. 优先闭合 `FEM_TO_CCL_FACET`,先支持空 facet、固定 facet,再支持由真实 surface 生成的 facet。 7. 优先闭合 `CCL_TO_FEM_LOAD`,先支持空 load block,再支持节点力、facet pressure 预留字段和诊断字段导入。 8. 对所有导出 facet 检查节点数、节点 id、面积、法向、厚度、坐标和速度有限值;退化 facet 应设置 invalid flag 并进入诊断。 9. 对所有导入 load record 检查节点 id、facet id、有限值、`step_id` 和 `valid_flags`;无法匹配的 record 应拒绝并输出计数。 10. 增加 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=... ``` 11. 增加 FEMLite 侧 self-test 或 smoke case,能够在没有 SPHLite 的情况下验证:worker 启动、IPC attach、`READY`、空 facet 导出、空 load 导入、`STOP` 正常退出。 12. 与 CCLite 联调时先验收三类路径:`mock SPH + 真实 FEMLite` 的 1 step 空耦合、`mock SPH + 真实 FEMLite` 的 100 step 空耦合、异常输入/超时可控退出。 13. 在上述闭环完成前,不建议把 FEMLite worker mock 通过视为真实耦合接入完成。 # 14. 总结 FEMLite 配合 CCLite 的关键不是重写 FEMLite 接触算法,而是提供稳定的外部边界数据和外部载荷通道。 建议 FEMLite 的改造口径为: ```text 保持独立主控程序 增加 CCLite worker/service 模式 导出 surface/facet 状态 接收 CCLite 节点力/面载荷 提供诊断和错误码 不依赖 SPHLite 内部结构 不嵌入 CCLite 算法核心 ``` 这样 FEMLite 能在 0.1.x 参与通信闭环,在 0.2.x 支撑基础 SPH-FEM penalty contact,在后续版本支撑壳厚度、tied/release、FSI 和工程算例。