Files
CCLite/femlite_suggests.md
2026-07-05 20:41:40 +08:00

560 lines
16 KiB
Markdown
Raw Permalink 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.
# 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 <name>
```
可选参数:
```text
--command-block <name>
--data-prefix <prefix>
--log <path>
--timeout-ms <value>
--worker-id <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 和工程算例。