commit 4ee25db7d912b2c8df4864c0001c99d2b6ca749c Author: Codex Date: Sat Jul 4 21:52:49 2026 +0800 Add CCLite documentation baseline diff --git a/README.md b/README.md new file mode 100644 index 0000000..bb70c4d --- /dev/null +++ b/README.md @@ -0,0 +1,50 @@ +# CCLite + +CCLite(Coupling & Contact Lite)是面向 SPHLite 与 FEMLite 的 SPH-FEM 耦合、接触联合仿真软件。 + +本软件基于 Fortran 开发,算法核心采用 Fortran95 风格实现;数据交换、进程通信和共享内存映射可采用 Fortran2018 与必要的 C/C++ 薄封装。默认编译器为 gfortran。 + +## 软件定位 + +CCLite、SPHLite、FEMLite 均保持独立主控程序形态。CCLite 作为联合仿真的主控程序,负责: + +1. 启动和调度 SPHLite、FEMLite; +2. 建立本机共享内存和控制 IPC; +3. 读取 CCLite 自身 Abaqus 风格 `.inp` 控制文件; +4. 交换 SPH/FEM 界面状态; +5. 执行 SPH-FEM 接触搜索、接触判定和界面力传递; +6. 输出接触、耦合、通信、时间步和力平衡诊断。 + +CCLite 不替代 SPHLite 或 FEMLite,不负责 SPH/FEM 内部求解、材料本构、网格生成或粒子生成。 + +## 第一阶段目标 + +第一版优先支持: + +1. Windows / gfortran / 本机共享内存; +2. CCLite Controller + SPHLite/FEMLite 独立进程; +3. 大数据共享内存交换,小命令控制 IPC; +4. 三文件 `.inp` 输入体系; +5. 显式-显式同步 SPH-FEM 接触; +6. SPH 粒子到 FEM 面/壳面的 penalty damping 接触; +7. 接触报告、通信报告、时间步报告和力平衡报告。 + +Linux 共享内存、MPI、显隐耦合、强耦合、tied coupling 和 FSI 高级能力作为后续版本预留。 + +## 文档 + +当前文档位于 `docs/`: + +1. `01_requirements.md`:软件需求规格说明书; +2. `02_architectural_design_specification.md`:概要设计说明书; +3. `03_detailed_design.md`:详细设计说明书。 + +辅助讨论文档: + +1. `data_femlite_sphlite.md`:SPHLite/FEMLite 独立程序之间的数据交换与通信建议; +2. `suggests.md`:CCLite 定位、边界和版本路线建议。 + +## 编码要求 + +本仓库文档均使用中文,文件编码为 UTF-8 without BOM。 + diff --git a/data_femlite_sphlite.md b/data_femlite_sphlite.md new file mode 100644 index 0000000..ad9ac2b --- /dev/null +++ b/data_femlite_sphlite.md @@ -0,0 +1,278 @@ +如果升级到 **Fortran 2018**,方案会干净很多:可以把老的 Fortran95 计算核心保留,但用 Fortran 2018 的 `iso_c_binding`、`iso_fortran_env`、`event_type`/coarray 等现代能力做一层更稳的接口。不过要注意:**Fortran 2018 本身仍然没有标准的“操作系统共享内存 API”**,所以共享内存创建、映射、命名信号量这类事,仍建议由 C/C++ 或系统库封装。 + +我会推荐这个架构: + +```text + Controller + 进程启动 / 同步调度 / 状态机 / 异常恢复 + | + control IPC: pipe/socket/semaphore/event + / \ + / \ + Solver A Solver B + Fortran 2018 Fortran 2018 + 计算 + IPC接口层 计算 + IPC接口层 + + shared memory A_to_B + shared memory B_to_A +``` + +核心原则不变: + +```text +大数据:共享内存 +小命令:控制通道 +同步权:Controller +A/B:只按命令读写,不直接调度对方 +``` + +**推荐模块划分** + +```text +controller + - 创建共享内存 + - 创建同步对象 + - 启动 A/B + - 发送 step/read/write/stop 命令 + - 等待 A/B done + - 处理超时、崩溃、重启 + +ipc_c_layer + - shm_create / shm_open / shm_map + - event_wait / event_signal + - mutex_lock / mutex_unlock + - pipe_send / pipe_recv + +fortran_ipc_module + - Fortran 2018 包装层 + - 使用 iso_c_binding 调 C 接口 + - 把 C 指针转换成 Fortran 数组指针 + +solver_a / solver_b + - 原计算逻辑 + - 调用 fortran_ipc_module 读写共享内存 +``` + +**共享内存布局** + +建议固定二进制布局,避免复杂对象: + +```text +SharedBlock + Header + magic + version + role + step_id + nx, ny, nz + elem_kind + data_bytes + state + error_code + Payload + real(real64) data(nx, ny, nz) +``` + +Fortran 2018 侧可以通过 `c_f_pointer` 把共享内存 payload 映射成数组: + +```fortran +use iso_c_binding +use iso_fortran_env, only: real64 + +type(c_ptr) :: raw_ptr +real(real64), pointer :: field(:,:,:) + +raw_ptr = ipc_get_payload_ptr(handle) +call c_f_pointer(raw_ptr, field, [nx, ny, nz]) +``` + +这样 Solver 看到的就是普通 Fortran 数组: + +```fortran +call compute(field) +``` + +**双向数据区** + +为了减少锁竞争,建议不要共用一块 buffer,而是两个单向通道: + +```text +A_to_B_shm: + A 只写 + B 只读 + +B_to_A_shm: + B 只写 + A 只读 +``` + +如果是实时流数据,再加双缓冲或三缓冲: + +```text +A_to_B: + buffer[0] + buffer[1] + buffer[2] +``` + +Header 里放: + +```text +write_index +read_index +latest_step +buffer_state[3] +``` + +**同步流程示例** + +```text +Controller: + create shared memory + start A + start B + +loop step = 1..N: + signal A: compute_and_write_A_to_B(step) + wait A_done + + signal B: read_A_to_B_and_compute(step) + wait B_done + + signal B: write_B_to_A(step) + wait B_done + + signal A: read_B_to_A_and_update(step) + wait A_done + +shutdown: + signal A/B stop + release resources +``` + +如果 A/B 可以并行计算,则改成: + +```text +Controller: + signal A and B start_step + wait both done + signal both exchange_ready + wait both consumed +``` + +**Fortran 2018 带来的好处** + +相比 Fortran95,主要提升在接口层: + +| 能力 | Fortran95 | Fortran2018 | +|---|---|---| +| 调 C 接口 | 依赖编译器扩展 | 标准 `iso_c_binding` | +| 整数/浮点 kind | 不完全统一 | `iso_fortran_env` 更清楚 | +| C 指针转数组 | 麻烦且不标准 | `c_f_pointer` 标准支持 | +| 字符串/枚举/句柄 | 易混乱 | 可用 `c_ptr`, `c_int`, `c_size_t` | +| 并行同步 | 依赖外部库 | 可考虑 coarray/event,但跨进程仍有限 | + +**是否使用 coarray?** + +可以考虑,但我不建议作为第一方案。 + +Fortran 2018 的 coarray/event 适合 Fortran 程序之间的并行模型,但你的场景是: + +- 两个独立主控程序 +- 由第三个主控程序统一调度 +- 大数据同机交换 +- 需要工程上可控的进程生命周期 + +这种情况下,coarray 运行时可能反而把进程模型绑定到特定编译器和运行时,例如 Intel、GNU/OpenCoarrays、Cray 等。可移植性、调试和与外部 Controller 集成会更麻烦。 + +所以优先级我会排成: + +```text +首选:Fortran 2018 + C IPC 封装 + 共享内存 + Controller +备选:MPI + Fortran 2018,如果你们本来就是 HPC/MPI 体系 +谨慎:Fortran coarray,用于同一 Fortran 运行时生态内的并行程序 +``` + +**最小接口设计** + +C 层暴露给 Fortran 的接口可以保持很少: + +```c +void* ipc_attach(const char* name, int role); +void* ipc_payload_ptr(void* handle, int buffer_id); +int ipc_wait_command(void* handle, int* command, int* step_id); +int ipc_signal_done(void* handle, int step_id, int status); +int ipc_detach(void* handle); +``` + +Fortran 2018 包一层: + +```fortran +module ipc_mod + use iso_c_binding + implicit none + + type :: ipc_handle + type(c_ptr) :: p = c_null_ptr + end type + +contains + + subroutine attach(handle, name, role) + end subroutine + + subroutine map_real64_3d(handle, buffer_id, nx, ny, nz, field) + type(ipc_handle), intent(in) :: handle + integer, intent(in) :: buffer_id, nx, ny, nz + real(c_double), pointer, intent(out) :: field(:,:,:) + end subroutine + + subroutine wait_command(handle, command, step_id) + end subroutine + + subroutine signal_done(handle, step_id, status) + end subroutine + +end module +``` + +Solver 主循环大概是: + +```fortran +do + call wait_command(ipc, cmd, step_id) + + select case (cmd) + case (CMD_COMPUTE_WRITE) + call compute(local_state, out_field) + call signal_done(ipc, step_id, STATUS_OK) + + case (CMD_READ_UPDATE) + call update_from_peer(in_field) + call signal_done(ipc, step_id, STATUS_OK) + + case (CMD_STOP) + exit + end select +end do +``` + +**最终推荐** + +升级到 Fortran 2018 后,最合适的方案是: + +```text +Controller: + 独立主控程序,管理 A/B 生命周期和同步状态机 + +Solver A / Solver B: + Fortran 2018 独立程序 + 保留各自计算主循环 + 通过统一 ipc_mod 接收命令、读写共享内存、上报状态 + +IPC 底层: + C/C++ 封装 OS 共享内存 + semaphore/event/named pipe + Fortran 2018 用 iso_c_binding 标准调用 +``` + +这比 Fortran95 的版本更可维护、可移植、可测试。关键是把系统相关的复杂度压进很薄的 C/C++ IPC 层,让 Fortran 代码只面对“数组 + 命令 + 状态”。 \ No newline at end of file diff --git a/docs/01_requirements.md b/docs/01_requirements.md new file mode 100644 index 0000000..02765bb --- /dev/null +++ b/docs/01_requirements.md @@ -0,0 +1,554 @@ +# CCLite 软件需求规格说明书 + +## Coupling & Contact Lite for SPHLite and FEMLite + +**文档版本**:V1.1 +**软件名称**:CCLite +**软件全称**:Coupling & Contact Lite +**设计基线**:独立主控程序、Fortran95 算法核心、Fortran2018/C IPC 通信层、Abaqus 风格 `.inp` 输入 +**关联软件**:SPHLite、FEMLite +**第一阶段平台**:Windows / gfortran / 本机共享内存 + +--- + +# 1. 引言 + +## 1.1 编写目的 + +本文档定义 CCLite 的软件需求边界、运行形态、输入输出、通信方式、耦合与接触能力、版本目标和验收要求。 + +CCLite 面向已有的 SPHLite 与 FEMLite,是二者之间的 SPH-FEM 跨域耦合与接触主控程序。CCLite、SPHLite、FEMLite 均保持独立可执行程序形态;CCLite 负责启动、同步调度、数据交换、接触/耦合算法和诊断输出。 + +## 1.2 软件背景 + +SPHLite 已具备 SPH 水、气、炸药、实体粒子和壳粒子等计算能力,并提供 coupling region 的粒子/facet 导出、外部载荷导入、接触状态导入和诊断接口。 + +FEMLite 已具备有限元实体/壳单元、显式动力学、静力、非线性静力、隐式 Newmark、接触、restart、Fortran API 和 C ABI,并提供边界 facet 查询与 SPH 外载荷施加接口。 + +工程场景中常见的水下爆炸、流固耦合、局部破坏、碎片冲击、SPH 局部区域与 FEM 远场结构耦合,需要在两个独立求解器之间建立受控的数据交换和界面算法。CCLite 的任务就是建立这一层。 + +## 1.3 软件定位 + +CCLite 定位为: + +> 面向 SPHLite 与 FEMLite 的独立 SPH-FEM 耦合与接触主控程序。 + +CCLite 负责: + +1. 读取 CCLite 自身 `.inp` 控制文件; +2. 启动或连接 SPHLite 与 FEMLite 独立进程; +3. 建立控制 IPC 与共享内存数据区; +4. 同步调度两个求解器; +5. 从 SPHLite/FEMLite 获取界面状态; +6. 执行 SPH-FEM 接触搜索、接触判定和接触力计算; +7. 执行界面力、压力、牵引、运动边界和接触状态传递; +8. 输出接触、耦合、通信、时间步、能量和动量诊断。 + +CCLite 不负责: + +1. SPH 内部粒子相互作用; +2. SPH 内部壳粒子接触; +3. SPH 材料本构、EOS、邻域求和; +4. FEM 单元刚度、质量、内力、本构更新; +5. FEM 内部实体/壳接触; +6. SPHLite/FEMLite 网格、粒子和几何前处理; +7. 第一阶段不负责 Linux/MPI 生产实现,只预留接口。 + +## 1.4 技术基线 + +CCLite 第一版采用以下技术基线: + +| 项目 | 需求 | +| --- | --- | +| 软件形态 | CCLite、SPHLite、FEMLite 均为独立主控程序 | +| 核心语言 | 接触、几何、搜索、传递算法核心使用 Fortran95 风格实现 | +| 通信语言 | 数据映射和进程通信层可使用 Fortran2018 | +| 系统 IPC | Windows 共享内存、事件、信号量、管道等系统调用可由 C/C++ 薄层封装 | +| 编译器 | 默认 gfortran | +| 输入格式 | Abaqus 风格 `.inp`,不使用 YAML 作为第一版主控输入 | +| 第一版平台 | Windows 本机三进程共享内存 | +| 预留平台 | Linux 共享内存、MPI、socket 分布式通信 | + +--- + +# 2. 总体需求 + +## 2.1 总体目标 + +CCLite 应构建一个轻量、可测试、可扩展的 SPH-FEM 耦合运行系统,使 SPHLite 和 FEMLite 能够在互不嵌入、互不直接依赖内部数据结构的前提下完成联合仿真。 + +第一阶段目标为: + +1. CCLite 可读取 Abaqus 风格 `cclite.inp`; +2. CCLite 可启动 SPHLite 与 FEMLite 独立进程; +3. CCLite 可创建并管理本机共享内存与控制 IPC; +4. SPHLite 与 FEMLite 可按 CCLite 命令完成初始化、导出、导入、推进和停止; +5. CCLite 可完成显式同步 SPH-FEM 接触; +6. CCLite 可输出可追踪的接触与通信诊断。 + +## 2.2 运行模式 + +CCLite 应支持以下运行模式: + +| 模式 | 命令示例 | 说明 | +| --- | --- | --- | +| check | `cclite check cclite.inp` | 检查 CCLite 输入、SPHLite/FEMLite 路径、关键词和通信配置 | +| dry-run | `cclite dry-run cclite.inp` | 建立通信区、读取模型元信息、构造界面但不推进时间 | +| run | `cclite run cclite.inp` | 正式执行耦合仿真 | +| post | `cclite post cclite.inp` | 汇总接触/耦合/通信历史输出 | + +第一版不要求 `replay-coupling`,但输出格式应为后续重放保留 step、region、pair、force 和状态字段。 + +## 2.3 三程序关系 + +三程序关系如下: + +```text + CCLite + Controller / IPC / Contact + / \ + control IPC control IPC + / \ + SPHLite FEMLite + independent exe independent exe + + shared memory: + SPH_to_CCLite + FEM_to_CCLite + CCLite_to_SPH + CCLite_to_FEM +``` + +基本原则: + +1. CCLite 拥有同步调度权; +2. SPHLite 和 FEMLite 不直接调度对方; +3. 大数据通过共享内存交换; +4. 小命令和状态通过控制 IPC 交换; +5. CCLite 不直接访问求解器私有内存; +6. SPHLite/FEMLite 通过通信接口层把公开数据写入共享内存。 + +--- + +# 3. 输入需求 + +## 3.1 三文件输入体系 + +CCLite 第一版采用三份 `.inp`: + +| 文件 | 责任 | +| --- | --- | +| `cclite.inp` | CCLite 主控、通信、时间、界面、接触、输出 | +| `sphlite.inp` | SPHLite 粒子、材料、section、时间和 coupling region | +| `femlite.inp` | FEMLite 节点、单元、材料、边界、surface 和输出 | + +CCLite 只解析 `cclite.inp` 和必要的模型元信息;SPHLite/FEMLite 自身输入仍由各自程序解析。 + +## 3.2 关键词风格 + +CCLite 输入采用 Abaqus 风格关键词。关键词以 `*CCLITE` 前缀区分 CCLite 专有控制项。 + +第一版必须支持: + +```text +*CCLITE CONTROL +*CCLITE SOLVER +*CCLITE IPC +*CCLITE TIME +*CCLITE INTERFACE +*CCLITE CONTACT PAIR +*CCLITE SURFACE INTERACTION +*CCLITE OUTPUT +*END STEP +``` + +关键词示例: + +```text +*CCLITE CONTROL, NAME=CASE_001 +MODE=EXPLICIT_EXPLICIT_SYNC + +*CCLITE SOLVER, NAME=SPH, TYPE=SPHLITE +EXECUTABLE=SPHLite/cpu_release/bin/sphlite.exe +INPUT=sphlite.inp +WORKDIR=work/sph + +*CCLITE SOLVER, NAME=FEM, TYPE=FEMLITE +EXECUTABLE=FEMLite/cpu_release/bin/femlite.exe +INPUT=femlite.inp +WORKDIR=work/fem + +*CCLITE IPC, TYPE=WINDOWS_SHMEM +PREFIX=CCLITE_CASE_001 +CONTROL=EVENT +BUFFERING=DOUBLE + +*CCLITE TIME +START=0.0, END=1.0E-3, DT=1.0E-7 + +*CCLITE INTERFACE, NAME=HULL_IMPACT +SPH_REGION=WATER_CONTACT +FEM_SURFACE=HULL_OUTER + +*CCLITE SURFACE INTERACTION, NAME=PENALTY_1 +NORMAL=Penalty, KN=1.0E9, CN=1.0E4, FRICTION=0.0 + +*CCLITE CONTACT PAIR, NAME=PAIR_1 +INTERFACE=HULL_IMPACT, INTERACTION=PENALTY_1 +TYPE=SPH_PARTICLE_TO_FEM_FACE + +*CCLITE OUTPUT +FREQUENCY=10 +CONTACT=YES, COUPLING=YES, IPC=YES +``` + +## 3.3 SPHLite 输入要求 + +SPHLite 输入文件应提供可供 CCLite 识别的 coupling region。第一版要求 SPHLite 能导出: + +1. region 名称; +2. region 类型; +3. 粒子 external id 和 internal index; +4. phase、status、material、section; +5. 质量、体积、密度、压力、内能、温度、光滑长度; +6. 坐标、速度、加速度; +7. 可选 facet proxy,包括 facet id、粒子连接、法向和面积。 + +SPHLite 应能接收: + +1. 粒子力; +2. facet 载荷; +3. facet 压力; +4. facet 牵引; +5. 接触状态; +6. 运动边界。 + +## 3.4 FEMLite 输入要求 + +FEMLite 输入文件应提供可供 CCLite 识别的 surface 或边界 facet。第一版要求 FEMLite 能导出: + +1. 边界 facet 数量; +2. facet id、element id、face id; +3. facet 节点数与节点连接; +4. facet 节点当前坐标和速度; +5. facet 法向和面积; +6. 节点运动学状态。 + +FEMLite 应能接收: + +1. 节点力; +2. facet 压力; +3. facet 牵引; +4. facet 节点载荷。 + +--- + +# 4. 通信需求 + +## 4.1 第一版通信范围 + +第一版通信只要求支持: + +```text +Windows + gfortran + 本机共享内存 +``` + +Linux 共享内存、MPI、socket 分布式通信只作为预留设计,不进入第一版验收。 + +## 4.2 通信架构 + +CCLite 应采用“大数据共享内存、小命令控制 IPC”的通信架构。 + +```text +大数据: + SPH_to_CCLite + FEM_to_CCLite + CCLite_to_SPH + CCLite_to_FEM + +小命令: + INIT + BUILD + EXPORT + IMPORT + ADVANCE + WRITE_OUTPUT + STOP +``` + +## 4.3 共享内存数据块 + +共享内存数据块应采用固定二进制布局: + +```text +Header + magic + version + block_role + step_id + buffer_id + state + item_count + item_stride + payload_bytes + error_code + +Payload + plain numeric arrays +``` + +payload 不得包含 Fortran pointer、C++ object、可变长字符串或进程私有地址。 + +## 4.4 控制状态 + +每个求解器进程应支持以下状态: + +```text +CREATED +INITIALIZING +READY +EXPORTING +WAITING_IMPORT +ADVANCING +DONE +FAILED +STOPPED +``` + +CCLite 应检测超时、异常退出、错误码和共享内存版本不匹配。 + +--- + +# 5. 功能需求 + +## 5.1 CCLite Controller + +CCLite Controller 应提供: + +1. 解析 `cclite.inp`; +2. 创建工作目录; +3. 创建共享内存和同步对象; +4. 启动 SPHLite/FEMLite; +5. 发送控制命令; +6. 等待求解器完成; +7. 管理 step_id 和 buffer_id; +8. 处理超时、错误和停止; +9. 汇总输出诊断。 + +## 5.2 接口数据管理 + +CCLite 应从共享内存中构造以下界面视图: + +1. SPH particle view; +2. SPH facet proxy view; +3. FEM boundary facet view; +4. FEM node kinematics view; +5. CCLite contact force buffer; +6. CCLite facet load buffer。 + +## 5.3 接触搜索与检测 + +第一版必须支持: + +1. SPH 粒子到 FEM 三角形/四边形面的候选搜索; +2. point-face 最近点; +3. point-edge fallback; +4. FEM 壳厚度接触距离; +5. 接触法向、gap、penetration 计算; +6. 接触对持久编号和诊断输出。 + +第一版不要求: + +1. 通用 mortar; +2. Nitsche; +3. 任意壳自接触; +4. 多体复杂接触; +5. GPU 或大规模并行搜索。 + +## 5.4 接触力模型 + +第一版必须支持 penalty damping 接触: + +```text +fn = kn * penetration + cn * normal_relative_velocity +``` + +可选支持 Coulomb 摩擦,但不作为第一版硬性验收项。 + +接触力必须满足: + +1. SPH 侧与 FEM 侧作用-反作用平衡; +2. FEM face 载荷按形函数或面积权重分配至节点; +3. 输出总力误差和总力矩误差; +4. 非有限值、异常大穿透、异常大接触力必须进入诊断。 + +## 5.5 时间同步 + +第一版支持显式-显式同步: + +```text +for step = 1..n: + SPHLite export interface state + FEMLite export interface state + CCLite search and compute contact + CCLite write loads to shared memory + SPHLite import loads + FEMLite import loads + SPHLite advance explicit dt + FEMLite advance explicit dt + CCLite write diagnostics +``` + +后续版本预留: + +1. 显式-显式异步子循环; +2. SPH 显式 + FEM 隐式弱耦合; +3. SPH 显式 + FEM 隐式强耦合; +4. rollback 与 Aitken 松弛。 + +## 5.6 输出需求 + +CCLite 应输出: + +| 文件 | 内容 | +| --- | --- | +| `cclite.log` | 主控流程、错误、警告 | +| `ipc_report.csv` | 命令、状态、耗时、共享内存统计 | +| `contact_report.csv` | 接触对数、最大穿透、最大接触力 | +| `force_balance.csv` | SPH/FEM 总力、总力矩和平衡误差 | +| `timestep_report.csv` | dt、step、求解器状态 | +| `interface_snapshot_*.csv` | 可选调试用界面快照 | + +--- + +# 6. 非功能需求 + +## 6.1 可维护性 + +1. Fortran95 算法核心不得依赖 Windows API; +2. Windows IPC 细节必须限制在薄 C/C++ 层和 Fortran2018 wrapper; +3. 共享内存布局必须版本化; +4. 输入关键词必须可扩展且向后兼容。 + +## 6.2 稳定性 + +CCLite 必须检查: + +1. 共享内存 magic/version; +2. payload 大小; +3. step_id 顺序; +4. buffer 状态; +5. 求解器错误码; +6. 非有限数; +7. 接触力异常; +8. 通信超时。 + +## 6.3 性能 + +第一版目标: + +1. 接触搜索复杂度接近 O(N) 或 O(N log M); +2. 大数组不通过文本文件交换; +3. 每步数据交换避免重复分配; +4. 双缓冲应可配置; +5. 输出频率可控。 + +--- + +# 7. 版本规划 + +## 7.1 CCLite 0.1:主控与通信闭环 + +目标: + +1. `cclite.inp` 解析; +2. Windows/gfortran 本机共享内存; +3. 控制 IPC; +4. 启动 SPHLite/FEMLite; +5. 空耦合同步推进; +6. 通信诊断输出。 + +验收: + +1. CCLite 能启动两个独立求解器; +2. 三进程状态机可稳定运行; +3. 空耦合运行结果与各自独立运行一致; +4. 通信错误能被明确报告。 + +## 7.2 CCLite 0.2:显式同步 SPH-FEM 接触 + +目标: + +1. SPH particle view; +2. FEM boundary facet view; +3. point-face/point-edge 检测; +4. penalty damping 接触; +5. SPH/FEM 力传递; +6. force balance 诊断。 + +验收: + +1. 单粒子撞 FEM 面可产生正确方向接触力; +2. 壳厚度接触距离正确; +3. 作用-反作用误差可控; +4. 接触报告可复核。 + +## 7.3 CCLite 0.3:异步子循环 + +目标: + +1. SPH 子循环; +2. FEM 宏步平均力; +3. 冲量累计; +4. 子循环诊断。 + +## 7.4 CCLite 0.4:tied coupling 与 release + +目标: + +1. SPH-FEM penalty tie; +2. InterfaceBond; +3. damage release; +4. release 后转接触。 + +## 7.5 CCLite 0.5:FSI 基础能力 + +目标: + +1. SPH 压力投影到 FEM; +2. FEM 边界运动传递给 SPH; +3. boundary/ghost particle 支持; +4. 水下爆炸 FSI 小型验证。 + +## 7.6 CCLite 0.6+:高级耦合 + +预留: + +1. SPH 显式 + FEM 隐式弱耦合; +2. 强耦合 rollback; +3. Aitken 松弛; +4. Riemann FSI; +5. Linux/MPI 通信后端; +6. 大规模并行和性能优化。 + +--- + +# 8. 第一阶段验收清单 + +CCLite 第一阶段完成时应满足: + +1. 文档、输入关键词、代码目录和测试命名均以 Fortran/IPC/.inp 方案为基线; +2. 不再以 YAML 作为第一版主控输入; +3. 不再以 C++ class/`std::vector` 作为内部设计基线; +4. CCLite、SPHLite、FEMLite 均可作为独立可执行程序存在; +5. Windows/gfortran/本机共享内存通信闭环可运行; +6. 显式同步接触最小算例可运行; +7. 接触力、穿透量、通信状态、时间步和错误可诊断; +8. Linux/MPI 只作为接口预留,不作为第一版交付承诺。 + +--- + +# 9. 总结 + +CCLite 应作为 SPHLite 与 FEMLite 之间的独立 SPH-FEM 耦合与接触主控程序。第一版重点不是追求完整工业级接触库,而是建立可靠的三进程通信、`.inp` 控制、显式同步、界面数据交换、基础 penalty 接触和诊断闭环。 + diff --git a/docs/02_architectural_design_specification.md b/docs/02_architectural_design_specification.md new file mode 100644 index 0000000..c798160 --- /dev/null +++ b/docs/02_architectural_design_specification.md @@ -0,0 +1,643 @@ +# CCLite 概要设计说明书 + +## Coupling & Contact Lite for SPHLite and FEMLite + +**文档版本**:V1.1 +**软件名称**:CCLite +**设计基线**:三独立进程、CCLite Controller、本机共享内存、Fortran95/Fortran2018 混合实现、Abaqus 风格 `.inp` +**第一阶段平台**:Windows / gfortran / 本机共享内存 + +--- + +# 1. 引言 + +## 1.1 编写目的 + +本文档在《CCLite 软件需求规格说明书》的基础上,给出 CCLite 的总体架构、模块划分、运行流程、通信结构、输入输出体系、版本路径和关键风险。 + +## 1.2 设计目标 + +CCLite 的概要设计目标是: + +1. 保持 CCLite、SPHLite、FEMLite 均为独立主控程序; +2. CCLite 作为 Controller 统一管理进程生命周期和同步状态机; +3. SPHLite/FEMLite 不直接链接彼此,也不直接调度彼此; +4. 大数据通过共享内存交换; +5. 小命令和状态通过控制 IPC 交换; +6. 接触、搜索、力传递等核心算法采用 Fortran95 风格实现; +7. 共享内存映射、C 指针转换和进程通信接口采用 Fortran2018 与 C/C++ 薄封装; +8. 输入采用 Abaqus 风格 `.inp`,第一版不使用 YAML。 + +## 1.3 设计原则 + +1. **独立进程优先**:SPHLite 与 FEMLite 仍可独立运行,CCLite 只在联合仿真时启动和调度它们。 +2. **通信边界清晰**:跨进程只交换公开数据块,不暴露求解器内部私有数组。 +3. **算法与系统解耦**:接触/搜索/传递算法不直接调用 Windows API。 +4. **固定二进制布局**:共享内存使用版本化 header 和纯数值 payload。 +5. **Abaqus 风格输入**:CCLite 专有控制项使用 `*CCLITE ...` 关键词。 +6. **第一版收敛**:先完成 Windows/gfortran/本机共享内存和显式同步接触,Linux/MPI 只预留。 + +--- + +# 2. 总体架构 + +## 2.1 三进程架构 + +CCLite、SPHLite、FEMLite 的运行关系如下: + +```text + CCLite.exe + Controller / IPC / Contact / Output + / \ + control IPC control IPC + / \ + SPHLite.exe FEMLite.exe + Fortran solver Fortran solver + IPC interface IPC interface + + shared memory blocks managed by CCLite +``` + +CCLite 是联合仿真的主控程序,但不是 SPH 或 FEM 求解器。SPHLite 与 FEMLite 仍负责各自物理域内部求解。 + +## 2.2 数据交换方向 + +第一版建议使用四类单向共享内存块: + +```text +SPH_TO_CCL + SPHLite 写,CCLite 读 + +FEM_TO_CCL + FEMLite 写,CCLite 读 + +CCL_TO_SPH + CCLite 写,SPHLite 读 + +CCL_TO_FEM + CCLite 写,FEMLite 读 +``` + +每类数据块可配置单缓冲、双缓冲或三缓冲。第一版默认双缓冲。 + +## 2.3 控制 IPC + +控制 IPC 负责小命令和状态同步: + +```text +CCLite -> Solver: + INIT + READ_INPUT + BUILD_MODEL + EXPORT_INTERFACE + IMPORT_LOADS + ADVANCE + WRITE_OUTPUT + STOP + +Solver -> CCLite: + READY + DONE + WARNING + FAILED + STOPPED +``` + +Windows 第一版可采用命名事件、信号量、管道或 socket。具体 OS 调用封装在薄 C/C++ 层,Fortran2018 通过 `iso_c_binding` 调用。 + +## 2.4 层次结构 + +CCLite 采用以下分层: + +```text +CCLite +├── App Layer +│ └── 命令行入口、运行模式、日志初始化 +├── Case/Input Layer +│ └── cclite.inp 解析、关键词校验、路径解析 +├── Controller Layer +│ └── 进程启动、命令调度、状态机、错误恢复 +├── IPC Layer +│ └── 共享内存、事件/信号量/管道、buffer 状态 +├── Solver Process Layer +│ └── SPHLite/FEMLite 进程描述和命令封装 +├── Interface Data Layer +│ └── SPH/FEM 公开数据视图 +├── Geometry & Search Layer +│ └── AABB、hash grid、point-face、point-edge +├── Contact Layer +│ └── penalty/damping 接触、壳厚度处理 +├── Transfer Layer +│ └── SPH 粒子力、FEM 节点力、facet 压力/牵引 +├── Diagnostics Layer +│ └── 接触、通信、能量、动量、时间步诊断 +└── Output Layer + └── CSV、日志、调试快照 +``` + +--- + +# 3. 软件运行形态 + +## 3.1 独立入口程序 + +第一版主要运行形态: + +```powershell +cclite check cclite.inp +cclite dry-run cclite.inp +cclite run cclite.inp +cclite post cclite.inp +``` + +SPHLite 与 FEMLite 由 CCLite 按输入路径启动: + +```text +*CCLITE SOLVER, NAME=SPH, TYPE=SPHLITE +EXECUTABLE=SPHLite/cpu_release/bin/sphlite.exe +INPUT=sphlite.inp + +*CCLITE SOLVER, NAME=FEM, TYPE=FEMLITE +EXECUTABLE=FEMLite/cpu_release/bin/femlite.exe +INPUT=femlite.inp +``` + +## 3.2 库模式预留 + +后续可将 CCLite 的接触搜索和力传递算法编译为库,供其他主控程序调用。但第一版需求、架构和验收均以独立主控程序为准。 + +--- + +# 4. 输入输出架构 + +## 4.1 输入文件 + +CCLite 联合仿真采用三份 `.inp`: + +```text +cclite.inp CCLite 主控、通信、界面和接触 +sphlite.inp SPHLite 物理模型和 coupling region +femlite.inp FEMLite 物理模型和 surface/facet +``` + +CCLite 不替代 SPHLite/FEMLite 输入解析,不修改二者输入语义,只通过自身关键词指定模型文件路径、接口映射和耦合算法参数。 + +## 4.2 CCLite 关键词分组 + +第一版关键词分组: + +| 关键词 | 作用 | +| --- | --- | +| `*CCLITE CONTROL` | 算例名、运行模式、全局选项 | +| `*CCLITE SOLVER` | 求解器类型、可执行文件、输入文件、工作目录 | +| `*CCLITE IPC` | 共享内存、控制 IPC、buffer、超时 | +| `*CCLITE TIME` | 起止时间、dt、输出间隔 | +| `*CCLITE INTERFACE` | SPH region 与 FEM surface 映射 | +| `*CCLITE SURFACE INTERACTION` | penalty、damping、摩擦等参数 | +| `*CCLITE CONTACT PAIR` | 接触对定义 | +| `*CCLITE OUTPUT` | 日志、CSV、调试快照 | + +## 4.3 输出文件 + +默认输出目录: + +```text +work/cclite/ +├── cclite.log +├── ipc_report.csv +├── contact_report.csv +├── force_balance.csv +├── timestep_report.csv +└── interface_snapshot_*.csv +``` + +输出文件应使用简单文本 CSV,方便人工检查和自动验收。 + +--- + +# 5. 模块概要设计 + +## 5.1 App Layer + +职责: + +1. 解析命令行; +2. 建立全局运行上下文; +3. 初始化日志; +4. 调用 check、dry-run、run、post 流程。 + +主要过程: + +```fortran +ccl_app_main +ccl_run_command +ccl_check_command +ccl_dry_run_command +ccl_post_command +``` + +## 5.2 Case/Input Layer + +职责: + +1. 读取 `cclite.inp`; +2. 识别 `*CCLITE` 关键词; +3. 校验必填参数; +4. 解析路径和枚举; +5. 构造内部配置结构。 + +第一版解析器可采用 Fortran 文本扫描实现,不要求完整 Abaqus 语法兼容,但必须支持: + +1. 关键词行; +2. 逗号分隔参数; +3. `KEY=VALUE`; +4. 数据行; +5. 注释行。 + +## 5.3 Controller Layer + +职责: + +1. 创建 IPC 资源; +2. 启动求解器进程; +3. 发送命令; +4. 等待状态; +5. 管理 step 循环; +6. 处理错误和超时。 + +核心状态: + +```text +UNINITIALIZED +IPC_READY +SOLVERS_STARTED +SOLVERS_READY +RUNNING +FINALIZING +FAILED +DONE +``` + +## 5.4 IPC Layer + +职责: + +1. 管理共享内存 block; +2. 管理 event/semaphore/pipe; +3. 提供 Fortran2018 可调用接口; +4. 提供 header 校验; +5. 提供 buffer acquire/release。 + +IPC Layer 包含三部分: + +```text +ipc_c_layer + Windows OS API 薄封装 + +ipc_f2018_mod + iso_c_binding wrapper + +ccl_ipc_manager + CCLite 侧资源管理 +``` + +## 5.5 Solver Process Layer + +职责: + +1. 描述 SPHLite/FEMLite 进程; +2. 保存可执行路径、输入路径和工作目录; +3. 发送命令; +4. 读取状态; +5. 处理退出码。 + +CCLite 不应直接操作 SPHLite/FEMLite 私有数据结构。 + +## 5.6 Interface Data Layer + +职责: + +1. 从共享内存读取 SPH region 数据; +2. 从共享内存读取 FEM facet 数据; +3. 构造只读 interface view; +4. 构造 CCLite 输出 force/load buffer; +5. 管理 step_id 和数据有效性。 + +主要数据视图: + +```text +SPHParticleView +SPHFacetProxyView +FEMFacetView +FEMNodeView +SPHForceBuffer +FEMLoadBuffer +``` + +## 5.7 Geometry & Search Layer + +职责: + +1. 构造 FEM facet AABB; +2. 构造 SPH 粒子 contact AABB; +3. 建立 hash grid 或轻量 BVH; +4. 生成候选接触对; +5. 执行 point-face/point-edge 几何计算。 + +第一版推荐 hash grid,BVH 作为后续扩展。 + +## 5.8 Contact Layer + +职责: + +1. 判断 SPH particle 与 FEM face 是否接触; +2. 处理壳厚度; +3. 处理边缘 fallback; +4. 计算 penetration、normal、relative velocity; +5. 计算 penalty damping 接触力。 + +第一版接触类型: + +```text +SPH_PARTICLE_TO_FEM_FACE +SPH_PARTICLE_TO_FEM_SHELL +``` + +## 5.9 Transfer Layer + +职责: + +1. 将 SPH 侧接触力写入 `CCL_TO_SPH`; +2. 将 FEM 侧反力分配到 facet 节点; +3. 写入 `CCL_TO_FEM`; +4. 计算总力和总力矩平衡误差。 + +## 5.10 Diagnostics & Output Layer + +职责: + +1. 输出通信状态; +2. 输出接触对统计; +3. 输出最大穿透、最大接触力; +4. 输出总力/总力矩误差; +5. 输出异常状态和错误码。 + +--- + +# 6. 共享内存概要设计 + +## 6.1 Block Header + +共享内存 block header 应包含: + +```text +magic +version_major +version_minor +block_role +producer_id +consumer_id +step_id +buffer_id +state +item_count +item_stride +payload_bytes +error_code +reserved +``` + +所有字段使用固定宽度整数或 real64,不写入进程本地指针。 + +## 6.2 Block Role + +第一版 block role: + +```text +BLOCK_SPH_PARTICLES +BLOCK_SPH_FACETS +BLOCK_FEM_FACETS +BLOCK_CCL_SPH_FORCES +BLOCK_CCL_FEM_LOADS +BLOCK_DIAGNOSTICS +``` + +## 6.3 Buffer State + +```text +EMPTY +WRITING +READY +READING +CONSUMED +ERROR +``` + +写入者只从 `EMPTY/CONSUMED` 进入 `WRITING`,写完后置为 `READY`。读取者只读取 `READY`,读完后置为 `CONSUMED`。 + +--- + +# 7. 运行流程 + +## 7.1 check 流程 + +```text +1. 读取 cclite.inp +2. 检查关键词和参数 +3. 检查 SPHLite/FEMLite executable/input 路径 +4. 检查 IPC 类型是否为第一版支持项 +5. 检查 interface/contact pair 引用关系 +6. 输出 check 报告 +``` + +## 7.2 dry-run 流程 + +```text +1. 执行 check +2. 创建 IPC 资源 +3. 启动 SPHLite/FEMLite +4. 发送 READ_INPUT / BUILD_MODEL +5. 请求导出界面元信息 +6. 构造初始 interface view +7. 可选执行初始接触搜索 +8. 停止求解器并释放 IPC +``` + +## 7.3 run 流程 + +```text +1. 执行 check +2. 创建 IPC 资源 +3. 启动 SPHLite/FEMLite +4. 初始化并建模 +5. 进入时间步循环 +6. 请求两侧导出界面状态 +7. CCLite 计算接触和界面力 +8. CCLite 写入两侧 load buffer +9. 请求两侧导入载荷 +10. 请求两侧推进 dt +11. 输出诊断 +12. 完成后停止求解器并释放 IPC +``` + +## 7.4 显式同步流程 + +```text +for step = 1, nstep + call controller_export_sph(step) + call controller_export_fem(step) + + call interface_read_views(step) + call search_build_candidates() + call contact_detect() + call contact_compute_forces() + call transfer_write_loads(step) + + call controller_import_sph_loads(step) + call controller_import_fem_loads(step) + + call controller_advance_sph(dt, step) + call controller_advance_fem(dt, step) + + call diagnostics_write(step) +end do +``` + +--- + +# 8. 编译与目录概要 + +## 8.1 推荐目录 + +```text +CCLite/ +├── Makefile +├── CMakeLists.txt 可选,不作为 C++ 架构前提 +├── include/ +│ └── cclite/ +│ └── cclite_ipc.h +├── src/ +│ ├── app/ +│ ├── case/ +│ ├── controller/ +│ ├── ipc/ +│ ├── interface/ +│ ├── geometry/ +│ ├── search/ +│ ├── contact/ +│ ├── transfer/ +│ ├── diagnostics/ +│ └── output/ +├── tests/ +├── examples/ +└── docs/ +``` + +## 8.2 语言边界 + +| 层 | 推荐语言 | +| --- | --- | +| 接触算法 | Fortran95 | +| 几何/搜索 | Fortran95 | +| 输入解析 | Fortran95 | +| Controller 状态机 | Fortran95/Fortran2018 | +| IPC Fortran wrapper | Fortran2018 | +| Windows IPC 底层 | C 或 C++ | +| 调试脚本 | Python 可选 | + +## 8.3 编译要求 + +默认采用 gfortran。第一版应提供可直接使用的 Windows 构建方式,例如: + +```powershell +mingw32-make +``` + +或: + +```powershell +cmake -S . -B build -G "MinGW Makefiles" +cmake --build build +``` + +CMake 可以作为构建工具存在,但不能把软件设计写成 C++ 类库方案。 + +--- + +# 9. 测试概要 + +## 9.1 单元测试 + +1. `.inp` 关键词解析; +2. IPC header pack/unpack; +3. buffer state 转换; +4. point-triangle 最近点; +5. point-quad 最近点; +6. point-edge 最近点; +7. penalty contact force; +8. force balance。 + +## 9.2 集成测试 + +1. CCLite 启动空 mock solver; +2. CCLite 启动 SPHLite/FEMLite dry-run; +3. 空耦合同步推进; +4. 单 SPH 粒子撞 FEM 平面; +5. SPH 粒子撞 FEM 壳面; +6. 通信超时与错误路径; +7. 非有限载荷保护。 + +## 9.3 第一版验收算例 + +第一版至少应包含: + +1. 空耦合双求解器同步; +2. SPH 粒子到刚性 FEM 面的接触; +3. SPH 粒子到 FEM 壳面的厚度接触; +4. 接触力平衡诊断; +5. 通信异常诊断。 + +--- + +# 10. 关键风险与对策 + +## 10.1 风险:通信层过度复杂 + +对策: + +1. 第一版只支持 Windows/gfortran/本机共享内存; +2. Linux/MPI 只预留; +3. 共享内存 payload 只用纯数值数组; +4. OS 细节封装在很薄的 C/C++ 层。 + +## 10.2 风险:CCLite 侵入求解器内部 + +对策: + +1. 只通过公开 coupling/export/import 数据交换; +2. 不使用 SPHLite/FEMLite 私有模块数据; +3. 不在 CCLite 文档中要求修改求解器内部算法。 + +## 10.3 风险:接触力不稳定 + +对策: + +1. 第一版采用 penalty damping; +2. 输出最大穿透和最大接触力; +3. 加入力限制和非有限检查; +4. 后续再引入高级稳定化。 + +## 10.4 风险:`.inp` 语法膨胀 + +对策: + +1. 第一版只实现 CCLite 专有关键词子集; +2. 保持 Abaqus 风格但不承诺完整兼容; +3. 所有关键词参数版本化。 + +--- + +# 11. 总结 + +CCLite 概要设计采用三独立进程架构:CCLite 作为 Controller,SPHLite 与 FEMLite 作为独立求解器。第一版通过 Windows/gfortran/本机共享内存实现数据交换,通过控制 IPC 实现同步调度,通过 Fortran95 核心算法完成显式同步 SPH-FEM penalty 接触,并通过 `.inp` 关键词和 CSV 诊断形成可测试的工程闭环。 + diff --git a/docs/03_detailed_design.md b/docs/03_detailed_design.md new file mode 100644 index 0000000..8dfa13b --- /dev/null +++ b/docs/03_detailed_design.md @@ -0,0 +1,1106 @@ +# CCLite 详细设计说明书 + +## Coupling & Contact Lite for SPHLite and FEMLite + +**文档版本**:V1.1 +**软件名称**:CCLite +**实现基线**:Fortran95 算法核心 + Fortran2018 IPC 包装 + C/C++ Windows IPC 薄层 +**输入基线**:Abaqus 风格 `.inp` +**第一阶段平台**:Windows / gfortran / 本机共享内存 + +--- + +# 1. 文档说明 + +## 1.1 编写目的 + +本文档细化 CCLite 的目录结构、模块职责、核心数据结构、共享内存布局、控制状态机、输入关键词、显式同步流程、接触算法、诊断输出、错误码和版本实现路径。 + +## 1.2 设计范围 + +本文档覆盖: + +1. Fortran 源码目录结构; +2. CCLite 主控上下文; +3. `.inp` 解析器; +4. Controller 状态机; +5. Windows 本机共享内存和控制 IPC; +6. Fortran2018 `iso_c_binding` 包装; +7. SPH/FEM interface view; +8. 几何、搜索和接触检测; +9. penalty damping 接触力; +10. SPH/FEM 力传递; +11. 诊断输出; +12. 第一阶段测试和验收。 + +## 1.3 设计边界 + +CCLite 负责 SPHLite 与 FEMLite 之间的数据交换、接触/耦合算法和同步调度;不负责 SPH/FEM 内部求解。 + +第一版只实现 Windows/gfortran/本机共享内存。Linux 共享内存、MPI 和分布式 socket 后端只保留枚举、配置项和错误提示。 + +--- + +# 2. 推荐目录结构 + +## 2.1 源码目录 + +```text +CCLite/ +├── Makefile +├── CMakeLists.txt 可选构建入口 +├── include/ +│ └── cclite/ +│ └── cclite_ipc.h C IPC 薄层头文件 +├── src/ +│ ├── app/ +│ │ └── cclite_main.f90 +│ ├── base/ +│ │ ├── ccl_precision.f90 +│ │ ├── ccl_error.f90 +│ │ ├── ccl_constants.f90 +│ │ └── ccl_string.f90 +│ ├── case/ +│ │ ├── ccl_case_types.f90 +│ │ ├── ccl_inp_reader.f90 +│ │ ├── ccl_keyword_parser.f90 +│ │ └── ccl_case_validate.f90 +│ ├── controller/ +│ │ ├── ccl_context.f90 +│ │ ├── ccl_controller.f90 +│ │ ├── ccl_solver_process.f90 +│ │ └── ccl_state_machine.f90 +│ ├── ipc/ +│ │ ├── ccl_ipc_types.f90 +│ │ ├── ccl_ipc_f2018.f90 +│ │ ├── ccl_shared_block.f90 +│ │ ├── ccl_buffer_state.f90 +│ │ └── ccl_win_ipc.c +│ ├── interface/ +│ │ ├── ccl_interface_types.f90 +│ │ ├── ccl_sph_view.f90 +│ │ ├── ccl_fem_view.f90 +│ │ └── ccl_interface_manager.f90 +│ ├── geometry/ +│ │ ├── ccl_vec3.f90 +│ │ ├── ccl_aabb.f90 +│ │ ├── ccl_closest_point.f90 +│ │ └── ccl_shell_geometry.f90 +│ ├── search/ +│ │ ├── ccl_hash_grid.f90 +│ │ └── ccl_candidate_builder.f90 +│ ├── contact/ +│ │ ├── ccl_contact_types.f90 +│ │ ├── ccl_contact_detector.f90 +│ │ ├── ccl_penalty_contact.f90 +│ │ └── ccl_contact_manager.f90 +│ ├── transfer/ +│ │ ├── ccl_force_buffer.f90 +│ │ ├── ccl_force_transfer.f90 +│ │ └── ccl_force_balance.f90 +│ ├── diagnostics/ +│ │ ├── ccl_diag_types.f90 +│ │ ├── ccl_contact_report.f90 +│ │ ├── ccl_ipc_report.f90 +│ │ └── ccl_timestep_report.f90 +│ └── output/ +│ ├── ccl_log.f90 +│ ├── ccl_csv_writer.f90 +│ └── ccl_snapshot_writer.f90 +├── tests/ +│ ├── unit/ +│ ├── integration/ +│ └── regression/ +├── examples/ +└── docs/ +``` + +## 2.2 命名约定 + +```text +ccl_ Fortran procedure/module 前缀 +ccl_*_mod Fortran module 后缀 +CCL_ 公共枚举和常量前缀 +CCLITE_ 共享内存 magic、环境变量和命令行前缀 +``` + +示例: + +```fortran +module ccl_contact_manager_mod +subroutine ccl_contact_manager_compute(ctx, ierr) +integer, parameter :: CCL_CMD_EXPORT_INTERFACE = 20 +``` + +--- + +# 3. 核心数据类型 + +## 3.1 精度模块 + +```fortran +module ccl_precision_mod + implicit none + integer, parameter :: ccl_i4 = selected_int_kind(9) + integer, parameter :: ccl_i8 = selected_int_kind(18) + integer, parameter :: ccl_r8 = selected_real_kind(15, 300) +end module +``` + +算法核心使用上述 kind,避免在 Fortran95 核心中依赖平台类型。 + +## 3.2 CCL_Case + +```fortran +type CCL_SolverConfig + character(len=32) :: name + character(len=32) :: solver_type + character(len=260) :: executable + character(len=260) :: input_file + character(len=260) :: work_dir +end type + +type CCL_IpcConfig + character(len=32) :: ipc_type + character(len=64) :: prefix + character(len=32) :: control + character(len=32) :: buffering + integer :: timeout_ms +end type + +type CCL_TimeConfig + real(ccl_r8) :: start_time + real(ccl_r8) :: end_time + real(ccl_r8) :: dt + integer :: output_frequency +end type + +type CCL_InterfaceConfig + character(len=64) :: name + character(len=64) :: sph_region + character(len=64) :: fem_surface +end type + +type CCL_ContactConfig + character(len=64) :: name + character(len=64) :: interface_name + character(len=64) :: interaction_name + character(len=64) :: contact_type +end type +``` + +## 3.3 CCL_Context + +`CCL_Context` 是 CCLite 顶层运行上下文。 + +```fortran +type CCL_Context + type(CCL_Case) :: case_data + type(CCL_RunState) :: run_state + type(CCL_IpcManager) :: ipc + type(CCL_InterfaceManager) :: interfaces + type(CCL_SearchState) :: search + type(CCL_ContactState) :: contact + type(CCL_TransferState) :: transfer + type(CCL_Diagnostics) :: diagnostics +end type +``` + +上下文保存 CCLite 自身状态,不保存 SPHLite/FEMLite 私有求解状态。 + +## 3.4 Run State + +```fortran +type CCL_RunState + integer :: mode + integer :: controller_state + integer :: current_step + real(ccl_r8) :: current_time + integer :: last_error_code + character(len=256) :: last_error_message +end type +``` + +--- + +# 4. `.inp` 解析详细设计 + +## 4.1 解析范围 + +第一版解析器支持 CCLite 关键词子集: + +```text +*CCLITE CONTROL +*CCLITE SOLVER +*CCLITE IPC +*CCLITE TIME +*CCLITE INTERFACE +*CCLITE SURFACE INTERACTION +*CCLITE CONTACT PAIR +*CCLITE OUTPUT +*END STEP +``` + +不承诺完整 Abaqus 语法兼容。 + +## 4.2 关键词行 + +关键词行格式: + +```text +*KEYWORD, PARAM1=VALUE1, PARAM2=VALUE2 +``` + +解析步骤: + +1. 去除首尾空白; +2. 跳过空行和 `**` 注释; +3. 若首字符为 `*`,识别新关键词; +4. 逗号分割参数; +5. 将参数名转换为大写; +6. 保存到当前 keyword record; +7. 后续非关键词行作为数据行归属当前关键词。 + +## 4.3 参数校验 + +必须检查: + +1. 是否存在一个 `*CCLITE CONTROL`; +2. 是否存在 SPH 和 FEM 两个 `*CCLITE SOLVER`; +3. 是否存在 `*CCLITE IPC`; +4. 是否存在 `*CCLITE TIME`; +5. `CONTACT PAIR` 引用的 interface 和 interaction 是否存在; +6. 第一版 `IPC TYPE` 是否为 `WINDOWS_SHMEM`; +7. 路径字段是否非空。 + +## 4.4 错误策略 + +解析错误必须包含: + +```text +file +line_number +keyword +parameter +message +``` + +示例: + +```text +CCL_ERROR_INPUT_MISSING_PARAM: +line 18, *CCLITE SOLVER missing INPUT +``` + +--- + +# 5. IPC 详细设计 + +## 5.1 C IPC 薄层 + +C/C++ 薄层只负责 OS 资源,不包含接触算法。 + +建议导出接口: + +```c +void* ccl_ipc_create_block(const char* name, long long bytes); +void* ccl_ipc_open_block(const char* name, long long bytes); +void* ccl_ipc_map_block(void* handle); +int ccl_ipc_unmap_block(void* ptr); +int ccl_ipc_close_block(void* handle); + +void* ccl_ipc_create_event(const char* name); +void* ccl_ipc_open_event(const char* name); +int ccl_ipc_wait_event(void* handle, int timeout_ms); +int ccl_ipc_signal_event(void* handle); +int ccl_ipc_reset_event(void* handle); +``` + +Windows 实现可使用 file mapping object 和 named event。Linux 实现只预留。 + +## 5.2 Fortran2018 Wrapper + +Fortran2018 wrapper 使用 `iso_c_binding`: + +```fortran +module ccl_ipc_f2018_mod + use iso_c_binding + implicit none + + type CCL_IpcHandle + type(c_ptr) :: raw = c_null_ptr + type(c_ptr) :: mapped = c_null_ptr + integer(c_size_t) :: bytes = 0 + end type + +contains + + subroutine ccl_ipc_map_real64_1d(handle, offset_bytes, n, values) + type(CCL_IpcHandle), intent(in) :: handle + integer(c_size_t), intent(in) :: offset_bytes + integer, intent(in) :: n + real(c_double), pointer, intent(out) :: values(:) + end subroutine + +end module +``` + +Fortran95 算法核心不得直接依赖 `c_ptr`。 + +## 5.3 Shared Block Header + +Header 使用固定字段: + +```fortran +type CCL_SharedHeader + integer(ccl_i4) :: magic + integer(ccl_i4) :: version_major + integer(ccl_i4) :: version_minor + integer(ccl_i4) :: block_role + integer(ccl_i4) :: producer_id + integer(ccl_i4) :: consumer_id + integer(ccl_i4) :: step_id + integer(ccl_i4) :: buffer_id + integer(ccl_i4) :: state + integer(ccl_i4) :: item_count + integer(ccl_i4) :: item_stride + integer(ccl_i8) :: payload_bytes + integer(ccl_i4) :: error_code + integer(ccl_i4) :: reserved(16) +end type +``` + +注意:实际跨 C/Fortran 二进制布局实现时,应由 IPC 层提供 pack/unpack 或使用 `bind(C)` 镜像类型;算法层只读写逻辑字段。 + +## 5.4 Buffer 状态转换 + +```text +EMPTY -> WRITING -> READY -> READING -> CONSUMED + \-> ERROR +``` + +规则: + +1. producer 只能写 `EMPTY` 或 `CONSUMED` buffer; +2. consumer 只能读 `READY` buffer; +3. step_id 必须单调递增; +4. 任何一方发现版本、大小、状态非法,应置 `ERROR` 并上报 Controller。 + +## 5.5 Block Role + +第一版 role: + +```fortran +integer, parameter :: CCL_BLOCK_SPH_PARTICLE = 101 +integer, parameter :: CCL_BLOCK_SPH_FACET = 102 +integer, parameter :: CCL_BLOCK_FEM_FACET = 201 +integer, parameter :: CCL_BLOCK_TO_SPH_FORCE = 301 +integer, parameter :: CCL_BLOCK_TO_FEM_LOAD = 302 +integer, parameter :: CCL_BLOCK_DIAGNOSTIC = 900 +``` + +--- + +# 6. 共享数据布局 + +## 6.1 SPH Particle Payload + +每个 SPH 粒子记录推荐字段: + +```text +int external_id +int internal_index +int phase +int status +int material_id +int section_id +real mass +real volume +real density +real pressure +real h +real x(3) +real v(3) +real a(3) +real contact_radius +``` + +payload 可按 structure-of-arrays 或 array-of-records 实现。第一版推荐 array-of-records,便于调试;后续性能优化可改为 structure-of-arrays,但共享内存 version 必须升级。 + +## 6.2 FEM Facet Payload + +每个 FEM facet 记录推荐字段: + +```text +int facet_id +int elem_id +int face_id +int node_count +int node_ids(max_face_nodes) +real x(max_face_nodes,3) +real v(max_face_nodes,3) +real normal(3) +real area +real thickness +``` + +`max_face_nodes` 第一版可取 4 或 8,必须在 header 或配置中明确。 + +## 6.3 CCL to SPH Force Payload + +```text +int external_id +int export_index +real force(3) +real moment(3) +int contact_state +real normal(3) +real gap +real penetration +``` + +## 6.4 CCL to FEM Load Payload + +```text +int facet_id +int node_count +int node_ids(max_face_nodes) +real node_forces(max_face_nodes,3) +real pressure +real traction(3) +real resultant(3) +``` + +--- + +# 7. Controller 状态机 + +## 7.1 Controller State + +```text +CCL_CTRL_CREATED +CCL_CTRL_CASE_LOADED +CCL_CTRL_IPC_READY +CCL_CTRL_SOLVERS_STARTED +CCL_CTRL_SOLVERS_READY +CCL_CTRL_RUNNING +CCL_CTRL_FINALIZING +CCL_CTRL_DONE +CCL_CTRL_FAILED +``` + +## 7.2 Solver State + +```text +SOLVER_CREATED +SOLVER_INITIALIZING +SOLVER_READY +SOLVER_EXPORTING +SOLVER_WAITING_IMPORT +SOLVER_ADVANCING +SOLVER_DONE +SOLVER_FAILED +SOLVER_STOPPED +``` + +## 7.3 Command Enum + +```fortran +integer, parameter :: CCL_CMD_INIT = 1 +integer, parameter :: CCL_CMD_READ_INPUT = 2 +integer, parameter :: CCL_CMD_BUILD_MODEL = 3 +integer, parameter :: CCL_CMD_EXPORT_INTERFACE = 4 +integer, parameter :: CCL_CMD_IMPORT_LOADS = 5 +integer, parameter :: CCL_CMD_ADVANCE = 6 +integer, parameter :: CCL_CMD_WRITE_OUTPUT = 7 +integer, parameter :: CCL_CMD_STOP = 99 +``` + +## 7.4 显式同步 Stepper + +伪代码: + +```fortran +do step = 1, nstep + time = time0 + step * dt + + call ccl_controller_command(ctx, SOLVER_SPH, CCL_CMD_EXPORT_INTERFACE, step, ierr) + call ccl_controller_command(ctx, SOLVER_FEM, CCL_CMD_EXPORT_INTERFACE, step, ierr) + call ccl_controller_wait_both(ctx, step, ierr) + + call ccl_interface_update_views(ctx, step, ierr) + call ccl_search_build_candidates(ctx, ierr) + call ccl_contact_detect(ctx, ierr) + call ccl_contact_compute_forces(ctx, ierr) + call ccl_transfer_write_buffers(ctx, step, ierr) + + call ccl_controller_command(ctx, SOLVER_SPH, CCL_CMD_IMPORT_LOADS, step, ierr) + call ccl_controller_command(ctx, SOLVER_FEM, CCL_CMD_IMPORT_LOADS, step, ierr) + call ccl_controller_wait_both(ctx, step, ierr) + + call ccl_controller_advance(ctx, SOLVER_SPH, dt, step, ierr) + call ccl_controller_advance(ctx, SOLVER_FEM, dt, step, ierr) + call ccl_controller_wait_both(ctx, step, ierr) + + call ccl_diagnostics_write_step(ctx, step, time, ierr) +end do +``` + +--- + +# 8. Interface View 设计 + +## 8.1 SPHParticleView + +```fortran +type CCL_SPHParticleView + integer :: count + integer, pointer :: external_id(:) + integer, pointer :: export_index(:) + integer, pointer :: phase(:) + integer, pointer :: status(:) + real(ccl_r8), pointer :: mass(:) + real(ccl_r8), pointer :: x(:,:) + real(ccl_r8), pointer :: v(:,:) + real(ccl_r8), pointer :: radius(:) +end type +``` + +维度约定: + +```text +x(3, count) +v(3, count) +``` + +## 8.2 FEMFacetView + +```fortran +type CCL_FEMFacetView + integer :: count + integer :: max_face_nodes + integer, pointer :: facet_id(:) + integer, pointer :: node_count(:) + integer, pointer :: node_ids(:,:) + real(ccl_r8), pointer :: x(:,:,:) + real(ccl_r8), pointer :: v(:,:,:) + real(ccl_r8), pointer :: normal(:,:) + real(ccl_r8), pointer :: area(:) + real(ccl_r8), pointer :: thickness(:) +end type +``` + +维度约定: + +```text +node_ids(max_face_nodes, count) +x(3, max_face_nodes, count) +normal(3, count) +``` + +## 8.3 Force Buffers + +SPH force buffer: + +```fortran +type CCL_SPHForceBuffer + integer :: count + integer, allocatable :: external_id(:) + integer, allocatable :: export_index(:) + real(ccl_r8), allocatable :: force(:,:) + real(ccl_r8), allocatable :: normal(:,:) + real(ccl_r8), allocatable :: gap(:) + real(ccl_r8), allocatable :: penetration(:) +end type +``` + +FEM load buffer: + +```fortran +type CCL_FEMLoadBuffer + integer :: count + integer :: max_face_nodes + integer, allocatable :: facet_id(:) + integer, allocatable :: node_count(:) + integer, allocatable :: node_ids(:,:) + real(ccl_r8), allocatable :: node_force(:,:,:) +end type +``` + +--- + +# 9. 几何与搜索详细设计 + +## 9.1 Vec3 + +基础向量过程: + +```fortran +ccl_vec3_dot(a, b) +ccl_vec3_cross(a, b, c) +ccl_vec3_norm(a) +ccl_vec3_normalize(a, ierr) +``` + +## 9.2 AABB + +```fortran +type CCL_AABB + real(ccl_r8) :: xmin(3) + real(ccl_r8) :: xmax(3) +end type +``` + +SPH 粒子 AABB: + +```text +x - radius <= point <= x + radius +``` + +FEM facet AABB: + +```text +min/max(facet node coords) expanded by search_distance + shell_thickness/2 +``` + +## 9.3 Hash Grid + +第一版使用均匀 hash grid: + +1. cell size 取最大搜索距离; +2. FEM facet 插入 grid; +3. 每个 SPH 粒子查询邻近 cell; +4. 生成候选 pair。 + +## 9.4 最近点计算 + +必须实现: + +1. point-triangle closest point; +2. point-quad closest point,可拆成两个 triangle; +3. point-edge closest point; +4. barycentric 或 shape weight 输出。 + +## 9.5 Candidate Pair + +```fortran +type CCL_ContactCandidate + integer :: sph_index + integer :: fem_facet_index + integer :: candidate_type +end type +``` + +--- + +# 10. 接触检测详细设计 + +## 10.1 ContactPair + +```fortran +type CCL_ContactPair + integer :: pair_id + integer :: sph_index + integer :: fem_facet_index + integer :: contact_type + real(ccl_r8) :: closest_point(3) + real(ccl_r8) :: normal(3) + real(ccl_r8) :: gap + real(ccl_r8) :: penetration + real(ccl_r8) :: relative_velocity_normal + real(ccl_r8) :: shape_weight(8) + integer :: node_count +end type +``` + +## 10.2 SPH 粒子到 FEM 面 + +流程: + +1. 读取 SPH 粒子位置 `xp`、速度 `vp`、半径 `rp`; +2. 读取 FEM facet 节点坐标和速度; +3. 计算 facet 最近点 `xc`; +4. 计算面法向 `n`; +5. 计算 `gap = dot(xp - xc, n)`; +6. 若 FEM 是壳,接触距离 `rc = rp + 0.5 * thickness`; +7. 若 FEM 是实体面,接触距离 `rc = rp`; +8. 若 `gap < rc`,生成接触; +9. `penetration = rc - gap`。 + +## 10.3 边缘 fallback + +当 point-face 最近点落在 facet 外或接近边界时,执行 point-edge 检测: + +1. 遍历 facet 边; +2. 计算点到边最近点; +3. 若距离小于接触距离,生成 edge contact; +4. 法向从 edge closest point 指向 SPH 粒子。 + +## 10.4 壳厚度处理 + +FEM 壳不得简单视为零厚度面。第一版规则: + +```text +effective_distance = sph_radius + 0.5 * shell_thickness +``` + +壳法向由 FEMLite facet normal 提供,CCLite 不重构复杂壳法向。 + +--- + +# 11. 接触力详细设计 + +## 11.1 法向 penalty force + +```text +fn = kn * penetration +``` + +若 `penetration <= 0`,法向接触力为 0。 + +## 11.2 阻尼力 + +```text +fd = cn * max(0, -vn) +``` + +其中 `vn` 为法向相对速度: + +```text +vn = dot(v_sph - v_fem_closest, normal) +``` + +## 11.3 合力 + +```text +f_normal = (fn + fd) * normal +``` + +作用在 SPH 上的力为 `+f_normal` 或 `-f_normal` 取决于法向定义。设计要求:最终输出必须通过 force balance 检查验证作用-反作用。 + +## 11.4 FEM 节点分配 + +FEM 侧反力: + +```text +f_fem = -f_sph +``` + +节点力: + +```text +f_node_i = N_i * f_fem +``` + +其中 `N_i` 为最近点处形函数或由三角形 barycentric 权重得到的权重。 + +## 11.5 Force Balance + +每步计算: + +```text +sum_f_sph +sum_f_fem +force_error = norm(sum_f_sph + sum_f_fem) + +sum_m_sph +sum_m_fem +moment_error = norm(sum_m_sph + sum_m_fem) +``` + +输出到 `force_balance.csv`。 + +--- + +# 12. 传递写回设计 + +## 12.1 写入 SPH + +CCLite 将 SPH 粒子力写入 `CCL_TO_SPH`: + +```text +external_id +export_index +force(3) +normal(3) +gap +penetration +contact_state +``` + +SPHLite 根据 export index 或 external id 将载荷映射回内部粒子。 + +## 12.2 写入 FEM + +CCLite 将 FEM 节点力写入 `CCL_TO_FEM`: + +```text +facet_id +node_count +node_ids +node_forces +``` + +FEMLite 根据 facet/node id 将载荷加入外部 SPH 力缓存。 + +## 12.3 非有限保护 + +写回前必须检查: + +1. force 是否有限; +2. node force 是否有限; +3. penetration 是否非负; +4. node_count 是否在范围内; +5. facet_id/node_id 是否有效。 + +发现错误时应停止当前步并上报。 + +--- + +# 13. 诊断详细设计 + +## 13.1 contact_report.csv + +字段: + +```text +step,time,active_pairs,max_penetration,max_force, +mean_penetration,edge_pair_count,failed_candidate_count +``` + +## 13.2 force_balance.csv + +字段: + +```text +step,time, +sph_fx,sph_fy,sph_fz, +fem_fx,fem_fy,fem_fz, +force_error, +sph_mx,sph_my,sph_mz, +fem_mx,fem_my,fem_mz, +moment_error +``` + +## 13.3 ipc_report.csv + +字段: + +```text +step,solver,command,state,elapsed_ms,block_role, +buffer_id,payload_bytes,error_code +``` + +## 13.4 timestep_report.csv + +字段: + +```text +step,time,dt,sph_state,fem_state,contact_pairs,controller_state +``` + +## 13.5 日志 + +`cclite.log` 记录: + +1. 输入文件路径; +2. 进程启动参数; +3. IPC 名称; +4. 每个阶段开始/结束; +5. warning 和 error; +6. 最终统计。 + +--- + +# 14. 错误码设计 + +```fortran +integer, parameter :: CCL_OK = 0 + +integer, parameter :: CCL_ERROR_INPUT_BASE = 1000 +integer, parameter :: CCL_ERROR_INPUT_UNKNOWN_KEYWORD = 1001 +integer, parameter :: CCL_ERROR_INPUT_MISSING_PARAM = 1002 +integer, parameter :: CCL_ERROR_INPUT_BAD_VALUE = 1003 + +integer, parameter :: CCL_ERROR_IPC_BASE = 2000 +integer, parameter :: CCL_ERROR_IPC_CREATE_FAILED = 2001 +integer, parameter :: CCL_ERROR_IPC_MAP_FAILED = 2002 +integer, parameter :: CCL_ERROR_IPC_TIMEOUT = 2003 +integer, parameter :: CCL_ERROR_IPC_BAD_HEADER = 2004 +integer, parameter :: CCL_ERROR_IPC_BAD_STATE = 2005 + +integer, parameter :: CCL_ERROR_SOLVER_BASE = 3000 +integer, parameter :: CCL_ERROR_SOLVER_START_FAILED = 3001 +integer, parameter :: CCL_ERROR_SOLVER_FAILED = 3002 +integer, parameter :: CCL_ERROR_SOLVER_BAD_STEP = 3003 + +integer, parameter :: CCL_ERROR_CONTACT_BASE = 4000 +integer, parameter :: CCL_ERROR_CONTACT_NONFINITE = 4001 +integer, parameter :: CCL_ERROR_CONTACT_BAD_GEOM = 4002 +integer, parameter :: CCL_ERROR_CONTACT_OVERFLOW = 4003 +``` + +所有错误应写入 `cclite.log`,并在命令行返回非零退出码。 + +--- + +# 15. 版本实现路径 + +## 15.1 CCLite 0.1.x + +目标:主控程序、`.inp`、IPC 和空耦合闭环。 + +任务: + +1. Fortran 项目骨架; +2. `cclite_main.f90`; +3. `cclite.inp` 解析器; +4. CCLite Controller 状态机; +5. Windows IPC 薄层; +6. Fortran2018 IPC wrapper; +7. mock solver 测试; +8. SPHLite/FEMLite 进程启动; +9. 空耦合同步推进; +10. `ipc_report.csv`。 + +验收: + +1. `cclite check` 可检查输入; +2. `cclite dry-run` 可启动并停止两个求解器; +3. `cclite run` 可完成空耦合; +4. 通信错误可诊断。 + +## 15.2 CCLite 0.2.x + +目标:显式同步 SPH-FEM 接触。 + +任务: + +1. SPH particle view; +2. FEM facet view; +3. hash grid; +4. point-face/point-edge; +5. penalty damping; +6. SPH/FEM load buffer; +7. force balance; +8. 单粒子撞面验收算例。 + +## 15.3 CCLite 0.3.x + +目标:显式异步子循环。 + +任务: + +1. 子循环 stepper; +2. 宏步/子步映射; +3. 冲量累计; +4. 平均力传递; +5. 子循环诊断。 + +## 15.4 CCLite 0.4.x + +目标:SPH-FEM tied coupling。 + +任务: + +1. InterfaceBond; +2. penalty tie; +3. bond damage; +4. release 后转 contact; +5. tie 诊断。 + +## 15.5 CCLite 0.5.x + +目标:基础 FSI。 + +任务: + +1. SPH pressure projection; +2. FEM motion boundary; +3. boundary/ghost particle; +4. 水下爆炸 FSI 小算例。 + +## 15.6 CCLite 0.6+ + +预留: + +1. SPH 显式 + FEM 隐式弱耦合; +2. rollback; +3. 强耦合迭代; +4. Aitken 松弛; +5. Riemann FSI; +6. Linux/MPI 后端。 + +--- + +# 16. 测试详细设计 + +## 16.1 单元测试 + +```text +inp_keyword_parse +inp_case_validate +ipc_header_pack +buffer_state_transition +vec3_ops +closest_point_triangle +closest_point_quad +closest_point_edge +hash_grid_candidates +penalty_contact_force +force_balance +``` + +## 16.2 集成测试 + +```text +mock_solver_ipc +controller_two_mock_solvers +empty_coupling_sph_fem +sph_particle_fem_plane_contact +sph_particle_fem_shell_contact +ipc_timeout_error +nonfinite_force_error +``` + +## 16.3 验收输出检查 + +每个接触验收算例应检查: + +1. `contact_report.csv` 存在且 active pair 数合理; +2. 最大穿透非负且在预期范围; +3. 最大接触力非负且有限; +4. `force_balance.csv` 中 force_error 可接受; +5. `ipc_report.csv` 无 timeout/error; +6. 求解器进程正常停止。 + +--- + +# 17. 关键实现注意事项 + +## 17.1 不把 CCLite 写成 SPH/FEM 内部库 + +CCLite 第一版是独立主控程序。不得要求 SPHLite 或 FEMLite 直接链接 CCLite 算法核心。 + +## 17.2 不把 CCLite 写成通用接触库 + +第一版只处理 SPH-FEM 跨域接触,不处理 FEM 内部接触、SPH 内部接触或任意多体接触。 + +## 17.3 IPC 层必须薄 + +Windows API、句柄、事件、共享内存映射只在 IPC 层出现。接触算法只面对 Fortran 数组和 view。 + +## 17.4 `.inp` 第一版保持小而稳 + +只实现 `*CCLITE` 关键词子集。后续增加关键词时必须保持旧算例可读。 + +## 17.5 共享内存必须版本化 + +任何 payload 布局变化都必须升级 version,并在 check/dry-run 阶段发现不兼容。 + +--- + +# 18. 总结 + +CCLite 详细设计以三独立进程和本机共享内存为核心:CCLite 负责主控与接触算法,SPHLite/FEMLite 负责各自求解。Fortran95 保持算法核心简洁稳定,Fortran2018 与 C/C++ 薄层承担共享内存和 IPC。第一版交付重点是 `.inp` 主控、Windows/gfortran 通信闭环、显式同步 SPH-FEM penalty 接触和完整诊断。 + diff --git a/suggests.md b/suggests.md new file mode 100644 index 0000000..fd0c7a5 --- /dev/null +++ b/suggests.md @@ -0,0 +1,1694 @@ +这个定位很合适,而且比“把所有接触都做进一个大模块”更清晰。 + +**CCLite = Coupling & Contact Lite** 可以定位为: + +> 专门负责 **SPHLite 与 FEMLite 之间** 的耦合、接触、界面传递、损伤释放和 FSI 边界交互; +> 不负责 SPHLite 内部粒子接触,也不负责 FEMLite 内部单元接触。 + +这样做的好处是边界清晰、职责单一、软件更容易工业化。 + +--- + +# 1. CCLite 的核心定位 + +建议把 CCLite 定义为一个 **跨求解器界面算法库**,而不是一个独立求解器。 + +它不直接求解 SPH 动量方程,也不直接组装 FEM 刚度矩阵,而是负责: + +```text +SPHLite boundary state ++ +FEMLite boundary state + ↓ +CCLite interface algorithm + ↓ +SPH side coupling force / boundary condition ++ +FEM side coupling force / boundary condition +``` + +也就是说,CCLite 的核心输入输出是: + +```text +输入: +- SPH 粒子状态 +- SPH 壳粒子状态 +- FEM 实体表面状态 +- FEM 壳表面状态 +- 材料/厚度/法向/速度/压力等界面信息 + +输出: +- 施加给 SPH 粒子的界面力、边界速度、ghost state +- 施加给 FEM 节点/壳节点的界面力、面力、力矩 +- 接触状态、穿透量、接触能量、耦合诊断信息 +``` + +因此 CCLite 的边界应明确为: + +| 模块 | 是否由 CCLite 负责 | +| --------------------- | ------------- | +| SPH 内部粒子-粒子相互作用 | 不负责 | +| SPH 内部壳粒子接触 | 不负责 | +| FEM 内部实体接触 | 不负责 | +| FEM 内部壳接触 | 不负责 | +| SPH 粒子 ↔ FEM 实体面 | 负责 | +| SPH 粒子 ↔ FEM 壳面 | 负责 | +| SPH 壳粒子 ↔ FEM 实体面 | 负责 | +| SPH 壳粒子 ↔ FEM 壳面 | 负责 | +| SPH-FEM tied coupling | 负责 | +| SPH-FEM FSI coupling | 负责 | +| SPH-FEM 损伤释放后的接触转换 | 负责 | + +这点非常重要。否则 CCLite 很容易膨胀成一个“通用接触库”,和 FEMLite/SPHLite 职责重叠。 + +--- + +# 2. 建议的软件边界 + +建议 CCLite 只处理下面 4 类对象之间的交互: + +```text +SPH solid particles ↔ FEM solid boundary faces +SPH solid particles ↔ FEM shell faces +SPH shell particles ↔ FEM solid boundary faces +SPH shell particles ↔ FEM shell faces +``` + +进一步扩展时,可以支持: + +```text +SPH boundary particles ↔ FEM surface +SPH ghost particles ↔ FEM surface +SPH damaged particles ↔ FEM surface +SPH converted particles ↔ FEM erosion region +``` + +但仍然保持原则: + +> 只处理 **SPH 域与 FEM 域之间** 的相互作用。 + +--- + +# 3. CCLite 不应该做什么 + +建议从架构设计文档中明确写出“不负责项”。 + +## 3.1 不负责 SPH 内部算法 + +例如: + +```text +SPH particle-particle pressure force +SPH artificial viscosity +SPH tensile instability correction +SPH shell particle internal force +SPH shell self-contact +SPH damage bond breaking inside SPH +SPH neighbor summation +SPH density update +``` + +这些应该留在 SPHLite 中。 + +## 3.2 不负责 FEM 内部算法 + +例如: + +```text +FEM element stiffness/internal force +FEM shell membrane/bending/shear internal force +FEM solid-solid contact +FEM shell-shell self-contact +FEM hourglass control +FEM material constitutive update +FEM element erosion +FEM implicit contact iteration +``` + +这些应该留在 FEMLite 中。 + +## 3.3 不负责全局时间积分 + +CCLite 不应该自己推进时间步。它最多提供: + +```text +interface force +interface impulse +interface boundary condition +interface stable time step suggestion +``` + +时间推进仍由 SPHLite/FEMLite 或上层 Driver 管理。 + +--- + +# 4. CCLite 的推荐总体架构 + +建议采用下面的分层: + +```text +CCLite +├── Interface Data Layer +│ ├── SPHInterfaceView +│ ├── SPHShellInterfaceView +│ ├── FEMSolidSurfaceView +│ └── FEMShellSurfaceView +│ +├── Geometry & Search Layer +│ ├── ContactPrimitive +│ ├── AABB +│ ├── HashGrid +│ ├── BVH +│ └── PairCandidateBuilder +│ +├── Detection Layer +│ ├── ParticleFaceDetector +│ ├── ParticleShellDetector +│ ├── ShellParticleFaceDetector +│ ├── PointEdgeDetector +│ └── ThicknessAwareShellDetector +│ +├── Coupling Law Layer +│ ├── PenaltyContact +│ ├── DampedPenaltyContact +│ ├── CoulombFrictionContact +│ ├── KinematicTie +│ ├── PenaltyTie +│ ├── GhostParticleBoundary +│ ├── PressureProjectionFSI +│ └── RiemannFSI +│ +├── Transfer Layer +│ ├── SPHToFEMForceTransfer +│ ├── FEMToSPHBoundaryTransfer +│ ├── ShellMomentTransfer +│ └── EnergyMomentumMonitor +│ +└── Diagnostics Layer + ├── ContactReport + ├── CouplingReport + ├── PenetrationReport + ├── EnergyReport + └── DebugVTKOutput +``` + +简化成一句话: + +```text +CCLite = Interface View + Search + Detection + Coupling Law + Force Transfer + Diagnostics +``` + +--- + +# 5. CCLite 的核心数据抽象 + +## 5.1 SPHInterfaceView + +CCLite 不应该直接依赖 SPHLite 内部数组结构,而应该通过 view 读取必要数据。 + +```cpp +struct CCL_SPHParticleView { + int64_t id; + double x[3]; + double v[3]; + double mass; + double rho; + double volume; + double h; + double radius; + double pressure; + double stress[6]; + int material_id; + int body_id; + int active; +}; +``` + +对 CCLite 来说,SPH 实体粒子最重要的是: + +```text +位置 x +速度 v +质量 m +体积 V +光滑长度 h +等效接触半径 r +压力 p +应力 sigma +材料/体编号 +是否激活 +``` + +--- + +## 5.2 SPHShellInterfaceView + +SPH 壳粒子需要更多几何信息: + +```cpp +struct CCL_SPHShellParticleView { + int64_t id; + double x[3]; + double v[3]; + + double director[3]; + double angular_velocity[3]; + + double thickness; + double area; + double mass; + + double normal[3]; + double radius; + + double membrane_stress[3]; + double bending_moment[3]; + + int material_id; + int body_id; + int active; +}; +``` + +壳粒子对 CCLite 的关键属性是: + +```text +中面位置 +速度 +法向/director +厚度 +面积 +质量 +角速度/转角信息 +等效接触半径 +``` + +--- + +## 5.3 FEMSolidSurfaceView + +FEMLite 不需要把整个实体单元暴露给 CCLite,只暴露边界面。 + +```cpp +struct CCL_FEMSurfaceFaceView { + int64_t face_id; + int64_t elem_id; + + int node_count; // 3 or 4 + int64_t node_ids[4]; + + double x[4][3]; + double v[4][3]; + + double normal[3]; + double area; + + int material_id; + int body_id; + int active; +}; +``` + +CCLite 只需要: + +```text +边界面节点坐标 +边界面节点速度 +面法向 +面积 +所属单元/体 +材料编号 +是否激活 +``` + +--- + +## 5.4 FEMShellSurfaceView + +FEM 壳面需要额外提供厚度和转角/director。 + +```cpp +struct CCL_FEMShellFaceView { + int64_t shell_id; + + int node_count; // 3, 4, 6, 8 可逐步支持 + int64_t node_ids[8]; + + double x[8][3]; + double v[8][3]; + + double director[8][3]; + double omega[8][3]; + + double thickness; + double normal[3]; + double area; + + int material_id; + int body_id; + int active; +}; +``` + +对壳接触而言,CCLite 必须知道: + +```text +中面 +厚度 +法向 +节点速度 +节点转动信息 +正反面 +边界边 +``` + +--- + +# 6. CCLite 的输出数据 + +CCLite 不应该直接修改 SPHLite 和 FEMLite 的内部力数组,而是输出增量。 + +## 6.1 SPH 侧输出 + +```cpp +struct CCL_SPHForceOutput { + int64_t particle_id; + double force[3]; + double moment[3]; // shell particle 可用 + double boundary_velocity[3]; + double ghost_pressure; + double ghost_density; + int has_boundary_state; +}; +``` + +## 6.2 FEM 侧输出 + +```cpp +struct CCL_FEMForceOutput { + int64_t node_id; + double force[3]; + double moment[3]; // shell node 可用 +}; +``` + +这样 SPHLite/FEMLite 可以自己决定: + +```text +加入外力项 +加入接触力项 +加入 RHS +加入显式动量更新 +加入隐式残差 +``` + +--- + +# 7. CCLite 应支持的主要算法类型 + +建议分为 5 大类。 + +--- + +## 7.1 SPH-FEM penalty contact + +这是第一优先级。 + +支持组合: + +```text +SPH solid particle ↔ FEM solid face +SPH solid particle ↔ FEM shell face +SPH shell particle ↔ FEM solid face +SPH shell particle ↔ FEM shell face +``` + +基本形式: + +[ +\mathbf{f}_n = k_n \delta_n \mathbf{n} +] + +阻尼: + +[ +\mathbf{f}_d = -c_n v_n \mathbf{n} +] + +摩擦: + +[ +|\mathbf{f}_t| \le \mu |\mathbf{f}_n| +] + +其中: + +```text +δ_n:穿透量 +k_n:法向接触刚度 +c_n:接触阻尼 +μ:摩擦系数 +``` + +这是 CCLite 最基础、最通用、最容易工业试点的功能。 + +--- + +## 7.2 SPH-FEM tied coupling + +用于同一连续体的不同离散区域连接。 + +例如: + +```text +FEM 远场结构 ++ +SPH 局部破坏区 +``` + +约束形式: + +[ +\mathbf{x}_p = \sum_a N_a \mathbf{x}_a +] + +[ +\mathbf{v}_p = \sum_a N_a \mathbf{v}_a +] + +力反传: + +[ +\mathbf{f}_a += N_a \mathbf{f}_p +] + +适合: + +```text +SPH solid ↔ FEM solid tied interface +SPH shell ↔ FEM shell tied interface +SPH shell ↔ FEM solid tied interface +``` + +建议 CCLite 支持两种 tie: + +```text +Penalty tie +Kinematic interpolation tie +``` + +第一阶段可以先做 penalty tie: + +[ +\mathbf{f}*{tie} = k*{tie} +\left( +\sum_a N_a \mathbf{x}_a - \mathbf{x}_p +\right) +] + +后续再做严格运动学约束。 + +--- + +## 7.3 Damage release: tie-to-contact + +这是 CCLite 很重要的特色功能。 + +工程上经常需要: + +```text +未损伤时:SPH-FEM tied coupling +损伤达到阈值后:释放 tie +释放后:变成普通接触或自由分离 +``` + +可以设计成: + +```text +InterfaceBond +├── active tied +├── weakening +├── released +└── contact-only +``` + +典型状态转换: + +```text +damage < d0: + tied coupling + +d0 ≤ damage < d1: + degraded tie stiffness + +damage ≥ d1: + release tie + activate contact +``` + +这对以下场景很重要: + +```text +FEM 壳破坏后与 SPH 区域分离 +FEM-SPH 过渡区断裂 +复合结构粘接失效 +爆炸冲击下界面脱开 +侵彻破坏 +``` + +--- + +## 7.4 Ghost particle / boundary particle FSI + +用于 SPH 流体与 FEM 结构耦合。 + +CCLite 可以根据 FEM 边界面生成或管理 boundary particles: + +```text +FEM shell/solid surface + ↓ +CCLite boundary particle sampling + ↓ +SPHLite neighbor interaction +``` + +这些 boundary particles 由 CCLite 生成,但参与 SPH 邻域求和时由 SPHLite 使用。 + +边界粒子的状态来自 FEM: + +```text +x_b = shell / solid surface position +v_b = shell / solid surface velocity +n_b = surface normal +``` + +适合: + +```text +SPH 水 ↔ FEM 壳 +SPH 水 ↔ FEM 实体 +SPH 爆轰产物 ↔ FEM 结构 +SPH 空气/气体 ↔ FEM 结构 +``` + +这是做水下爆炸、入水砰击、冲击波-FSI 的关键路线。 + +--- + +## 7.5 Riemann FSI interface + +后续高级版本建议支持。 + +用于可压缩 SPH / Godunov SPH / 水下爆炸。 + +输入: + +```text +SPH fluid state: +ρ, v, p, c, EOS + +FEM boundary state: +v_b, n +``` + +求界面压力: + +[ +p^* +] + +然后: + +```text +p* 施加到 FEM 结构 +v_b / ghost state 反馈给 SPH 流体 +``` + +适合: + +```text +stiffened gas water +JWL explosive gas +ideal gas air +compressible SPH +underwater explosion +water hammer +slamming impact +``` + +这一类可以作为 CCLite 的高端特色。 + +--- + +# 8. 接触检测算法建议 + +CCLite 只处理 SPH-FEM,所以接触检测组合可以明显收窄。 + +## 8.1 必须支持的 narrow phase + +```text +Point ↔ Triangle +Point ↔ Quad +Point ↔ ShellFaceWithThickness +Point ↔ Edge +OrientedShellParticle ↔ ShellFace +OrientedShellParticle ↔ SolidFace +``` + +其中: + +```text +SPH solid particle = point/sphere +SPH shell particle = oriented disk/patch +FEM solid boundary = triangle/quad face +FEM shell = triangle/quad midsurface + thickness +``` + +--- + +## 8.2 壳厚度处理 + +对 FEM 壳接触,必须使用: + +[ +r_c = r_{sph} + \frac{t_{shell}}{2} +] + +对 SPH 壳粒子与 FEM 壳: + +[ +r_c = \frac{t_{sph-shell}}{2} + \frac{t_{fem-shell}}{2} +] + +不能只按中面距离判断。 + +建议 CCLite 内部使用: + +```text +ShellContactSurface +├── midsurface +├── top surface +├── bottom surface +├── edge surface +└── thickness offset +``` + +第一阶段可以不显式生成 top/bottom surface,但检测时必须考虑厚度。 + +--- + +## 8.3 边缘接触 + +SPH 粒子撞 FEM 壳边缘时,仅用 point-face 会漏掉边界接触。 + +因此至少支持: + +```text +particle ↔ shell edge +shell particle ↔ shell edge +``` + +边缘距离: + +[ +d = |\mathbf{x}*p - \mathbf{x}*{closest-edge}| +] + +若: + +[ +d < r_c +] + +则发生边缘接触。 + +--- + +# 9. 宽相搜索建议 + +由于 CCLite 只处理 SPH-FEM,宽相搜索可以比较简洁。 + +## 9.1 SPH 侧 + +使用 SPH 粒子的 hash grid / cell linked list。 + +```text +SPHLite 可提供已有邻域网格 +或 CCLite 自己构建轻量 hash grid +``` + +建议第一版 CCLite 自己构建一个独立 hash grid,避免强依赖 SPHLite 内部实现。 + +--- + +## 9.2 FEM 侧 + +FEM 边界面使用 BVH / AABB tree。 + +```text +FEM solid boundary faces → BVH +FEM shell faces → BVH +FEM shell edges → BVH or edge AABB list +``` + +推荐: + +```text +static FEM surface: + build once + +moving FEM surface: + refit BVH each time step + +large deformation/contact: + rebuild or periodic rebuild +``` + +--- + +## 9.3 混合查询 + +主流程: + +```text +for each active SPH particle: + build particle AABB with contact radius + query FEM surface BVH + get candidate faces/edges + run narrow phase + compute contact/coupling force +``` + +对于 SPH 壳粒子: + +```text +for each active SPH shell particle: + build oriented/thickness AABB + query FEM shell/solid BVH + run shell-aware narrow phase +``` + +--- + +# 10. CCLite 的推荐功能矩阵 + +## 10.1 第一层:接触 + +| 功能 | 第一版是否需要 | +| --------------------------- | ------- | +| SPH 实体粒子 ↔ FEM 实体面 | 必须 | +| SPH 实体粒子 ↔ FEM 壳面 | 必须 | +| SPH 壳粒子 ↔ FEM 壳面 | 必须 | +| SPH 壳粒子 ↔ FEM 实体面 | 建议 | +| 壳厚度接触 | 必须 | +| 边缘接触 | 必须 | +| Coulomb 摩擦 | 建议 | +| 接触阻尼 | 必须 | +| 自适应 penalty 刚度 | 建议 | +| Lagrange multiplier contact | 后续 | +| Augmented Lagrangian | 后续 | +| Mortar contact | 后续 | + +--- + +## 10.2 第二层:耦合 + +| 功能 | 第一版是否需要 | +| --------------------------------- | ------- | +| SPH solid ↔ FEM solid penalty tie | 建议 | +| SPH solid ↔ FEM shell penalty tie | 建议 | +| SPH shell ↔ FEM shell penalty tie | 建议 | +| Kinematic tie | 后续 | +| Damage release | 建议作为特色 | +| Tie-to-contact 转换 | 强烈建议 | +| Mortar tie | 后续 | +| Nitsche tie | 后续 | + +--- + +## 10.3 第三层:FSI + +| 功能 | 第一版是否需要 | +| ------------------------------ | -------- | +| FEM surface ghost particles | 建议 | +| SPH pressure projection to FEM | 必须用于 FSI | +| FEM velocity boundary to SPH | 必须用于 FSI | +| Riemann FSI | 后续重点 | +| 多介质 EOS interface | 后续 | +| 水下爆炸专用 FSI | 后续重点 | + +--- + +# 11. 建议的版本开发路线 + +下面给一个比较适合 CCLite 的版本路线。 + +--- + +## CCLite 0.1.x:最小可用接口层 + +目标:打通 SPHLite/FEMLite 数据通道。 + +### 0.1.0:项目骨架 + +实现: + +```text +CCLite C API / C++ API +SPHInterfaceView +SPHShellInterfaceView +FEMSolidSurfaceView +FEMShellSurfaceView +ForceOutputBuffer +ContactReport +``` + +验收标准: + +```text +可以从 SPHLite 读取粒子状态 +可以从 FEMLite 读取边界面状态 +可以返回 SPH/FEM 接触力输出 +``` + +--- + +### 0.1.1:FEM 边界面导入 + +实现: + +```text +FEM solid boundary face import +FEM shell face import +triangle/quad face primitive +face normal/area calculation +AABB generation +``` + +--- + +### 0.1.2:SPH 粒子导入 + +实现: + +```text +SPH solid particle import +SPH shell particle import +particle AABB +shell particle AABB +contact radius estimation +``` + +--- + +### 0.1.3:调试输出 + +实现: + +```text +candidate pair VTK +contact point VTK +penetration report +interface pair report +force report +``` + +这一版非常重要,方便后续排查接触问题。 + +--- + +## CCLite 0.2.x:基础 SPH-FEM penalty contact + +目标:完成最基础、最实用的跨域接触。 + +### 0.2.0:SPH 实体粒子 ↔ FEM 实体面 + +实现: + +```text +point-triangle contact +point-quad contact +normal penalty force +damping force +force transfer to FEM nodes +equal-opposite force to SPH particle +``` + +--- + +### 0.2.1:SPH 实体粒子 ↔ FEM 壳面 + +实现: + +```text +shell midsurface projection +shell thickness-aware gap +double-sided contact +shell node force transfer +``` + +--- + +### 0.2.2:边缘接触 + +实现: + +```text +particle-edge closest point +shell edge contact +solid face edge contact +edge fallback when projection is outside face +``` + +--- + +### 0.2.3:摩擦接触 + +实现: + +```text +relative tangential velocity +penalty tangential force +Coulomb limit +frictional energy output +``` + +--- + +### 0.2.4:自动 penalty 参数 + +实现: + +```text +user-defined stiffness +material-based stiffness +time-step-based stiffness +auto penalty scaling +``` + +--- + +## CCLite 0.3.x:壳粒子与 FEM 接触 + +目标:支持 SPH 壳粒子与 FEM 壳/实体交互。 + +### 0.3.0:SPH 壳粒子 ↔ FEM 壳面 + +实现: + +```text +oriented shell particle model +director-aware normal +thickness-aware shell-shell gap +normal penalty force +moment transfer to shell particle/FEM shell +``` + +--- + +### 0.3.1:SPH 壳粒子 ↔ FEM 实体面 + +实现: + +```text +shell particle to solid face projection +orientation filter +thickness distance +contact force and moment +``` + +--- + +### 0.3.2:壳正反面识别 + +实现: + +```text +front-side contact +back-side contact +double-sided shell contact +normal smoothing +side switching protection +``` + +--- + +### 0.3.3:壳边缘增强 + +实现: + +```text +SPH shell particle ↔ FEM shell edge +SPH shell particle ↔ FEM solid edge +edge normal construction +edge contact damping +``` + +--- + +## CCLite 0.4.x:SPH-FEM tied coupling + +目标:支持连续区域连接。 + +### 0.4.0:SPH solid ↔ FEM solid penalty tie + +实现: + +```text +SPH particle projection to FEM face/element +shape function interpolation +penalty displacement tie +penalty velocity tie +force back-transfer +``` + +--- + +### 0.4.1:SPH solid ↔ FEM shell tie + +实现: + +```text +particle to shell midsurface tie +thickness offset support +shell node force transfer +``` + +--- + +### 0.4.2:SPH shell ↔ FEM shell tie + +实现: + +```text +shell particle position tie +director tie +velocity tie +angular velocity tie +moment transfer +``` + +--- + +### 0.4.3:tie-to-contact release + +实现: + +```text +interface bond state +damage input from SPHLite/FEMLite +tie stiffness degradation +bond release +automatic contact activation after release +``` + +这会成为 CCLite 的重要亮点。 + +--- + +## CCLite 0.5.x:FSI 基础耦合 + +目标:支持水-结构、气体-结构、爆炸-结构耦合。 + +### 0.5.0:FEM surface boundary particles + +实现: + +```text +FEM 面采样 boundary particles +随 FEM 面运动更新 +boundary particle normal/velocity/area +输出给 SPHLite +``` + +--- + +### 0.5.1:SPH pressure projection to FEM + +实现: + +```text +SPH pressure sampling near FEM surface +kernel weighted pressure projection +nodal force assembly +pressure work output +``` + +--- + +### 0.5.2:FEM velocity boundary to SPH + +实现: + +```text +moving wall velocity +no-penetration boundary +slip / no-slip switch +boundary velocity ghost state +``` + +--- + +### 0.5.3:双向弱耦合 FSI + +实现: + +```text +SPH → FEM pressure force +FEM → SPH moving boundary +subcycling support +interface energy report +``` + +--- + +## CCLite 0.6.x:冲击/爆炸高级 FSI + +目标:面向水下爆炸、冲击波、可压缩 SPH。 + +### 0.6.0:Riemann FSI interface + +实现: + +```text +SPH fluid state extraction +FEM boundary state extraction +normal Riemann solver +interface pressure p* +interface velocity u* +``` + +--- + +### 0.6.1:EOS support for interface + +实现接口支持: + +```text +Ideal gas +Stiffened gas +JWL +Tait +Mie-Grüneisen +``` + +注意:EOS 可以由 SPHLite 提供,CCLite 只需要调用 EOS interface。 + +--- + +### 0.6.2:水下爆炸 FSI 场景 + +实现: + +```text +JWL explosive gas ↔ FEM shell +stiffened gas water ↔ FEM shell +multi-material SPH side state +pressure impulse report +``` + +--- + +### 0.6.3:FSI 稳定性增强 + +实现: + +```text +added-mass stabilization +interface pressure filtering +normal smoothing +time subcycling support +force relaxation +``` + +--- + +# 12. 和 SPHLite / FEMLite 的关系 + +建议采用“三层驱动关系”。 + +```text +上层 Driver / CaeLite +├── 调用 SPHLite 更新 SPH 内力 +├── 调用 FEMLite 更新 FEM 内力 +├── 调用 CCLite 计算 SPH-FEM 界面力 +├── 汇总力 +└── 时间推进 +``` + +不要让 CCLite 主控整个求解流程。否则会破坏模块边界。 + +--- + +## 12.1 显式动力学推荐流程 + +```text +for each time step: + + SPHLite: + compute SPH internal forces + + FEMLite: + compute FEM internal forces + + CCLite: + collect SPH/FEM interface states + search SPH-FEM candidate pairs + detect contact/coupling + compute interface forces + output SPH/FEM force increments + + Driver: + add forces to SPH and FEM + update acceleration + update velocity + update displacement + update damage + update interface state +``` + +--- + +## 12.2 隐式/显式混合流程 + +如果 FEMLite 是隐式,SPHLite 是显式,可以先支持弱耦合: + +```text +SPH 显式推进 +FEM 隐式推进 +CCLite 交换界面力和边界速度 +采用 staggered coupling +``` + +后续再做强耦合迭代: + +```text +while interface residual not converged: + SPH predictor + FEM solve + CCLite interface correction +``` + +但第一阶段不建议做复杂强耦合。 + +--- + +# 13. CCLite 的 API 设计建议 + +建议优先提供 C API,方便 SPHLite/FEMLite/CaeLite 调用。 + +## 13.1 基本生命周期 + +```c +CCL_Context* ccl_create_context(void); +void ccl_destroy_context(CCL_Context* ctx); + +void ccl_set_time_step(CCL_Context* ctx, double dt); +void ccl_set_contact_parameters(CCL_Context* ctx, const CCL_ContactParams* params); +void ccl_set_coupling_parameters(CCL_Context* ctx, const CCL_CouplingParams* params); +``` + +--- + +## 13.2 输入接口 + +```c +void ccl_set_sph_particles( + CCL_Context* ctx, + const CCL_SPHParticle* particles, + int count +); + +void ccl_set_sph_shell_particles( + CCL_Context* ctx, + const CCL_SPHShellParticle* particles, + int count +); + +void ccl_set_fem_solid_faces( + CCL_Context* ctx, + const CCL_FEMFace* faces, + int count +); + +void ccl_set_fem_shell_faces( + CCL_Context* ctx, + const CCL_FEMShellFace* faces, + int count +); +``` + +--- + +## 13.3 计算接口 + +```c +void ccl_build_search(CCL_Context* ctx); + +void ccl_compute_contact(CCL_Context* ctx); + +void ccl_compute_tie_coupling(CCL_Context* ctx); + +void ccl_compute_fsi_coupling(CCL_Context* ctx); + +void ccl_compute_all(CCL_Context* ctx); +``` + +--- + +## 13.4 输出接口 + +```c +int ccl_get_sph_force_count(CCL_Context* ctx); +void ccl_get_sph_forces(CCL_Context* ctx, CCL_SPHForce* out); + +int ccl_get_fem_force_count(CCL_Context* ctx); +void ccl_get_fem_forces(CCL_Context* ctx, CCL_FEMForce* out); + +void ccl_get_contact_report(CCL_Context* ctx, CCL_ContactReport* report); +void ccl_write_debug_vtk(CCL_Context* ctx, const char* filename); +``` + +--- + +# 14. CCLite 的配置文件建议 + +可以设计一个简单 JSON/YAML 配置。 + +```yaml +cclite: + mode: explicit + + contact: + enabled: true + pair_types: + - sph_solid_to_fem_shell + - sph_solid_to_fem_solid + - sph_shell_to_fem_shell + + normal_law: penalty + friction_law: coulomb + damping: true + + penalty: + mode: auto_timestep + scale: 0.2 + + friction: + mu: 0.15 + + shell: + thickness_aware: true + double_sided: true + edge_contact: true + + coupling: + tie: + enabled: true + law: penalty_tie + release_by_damage: true + + fsi: + enabled: true + method: pressure_projection + boundary_particles: true +``` + +--- + +# 15. 验证算例建议 + +CCLite 必须有独立验证算例,不能只靠完整 CaeLite 工程例子。 + +## 15.1 接触验证 + +```text +1. 单个 SPH 粒子撞刚性 FEM 平面 +2. SPH 粒子云压缩 FEM 实体表面 +3. SPH 粒子撞 FEM 壳板 +4. SPH 壳粒子撞 FEM 壳板 +5. 粒子撞壳边缘 +6. 带摩擦斜面滑移 +``` + +验收指标: + +```text +穿透量 +反弹速度 +动量守恒 +接触能量 +摩擦耗散 +接触力峰值 +``` + +--- + +## 15.2 tied coupling 验证 + +```text +1. FEM 杆 + SPH 杆拉伸 +2. FEM 板 + SPH 局部区域弯曲 +3. FEM 壳 + SPH 壳过渡拉伸 +4. tie 释放后自由分离 +5. tie 释放后再次接触 +``` + +验收指标: + +```text +界面位移连续性 +界面力平衡 +应力波透射/反射 +能量误差 +释放状态正确性 +``` + +--- + +## 15.3 FSI 验证 + +```text +1. SPH 水柱冲击 FEM 刚性壁 +2. SPH 水柱冲击 FEM 弹性板 +3. 水下冲击波作用 FEM 壳 +4. 气泡/高压区作用薄板 +5. 入水砰击简化模型 +``` + +验收指标: + +```text +压力峰值 +冲量 +板中心位移 +能量交换 +界面无明显穿透 +压力振荡水平 +``` + +--- + +# 16. CCLite 的工业级关键点 + +要想后续做成可靠模块,建议从一开始就加入这些诊断能力。 + +## 16.1 接触诊断 + +```text +最大穿透量 +平均穿透量 +接触对数量 +接触力最大值 +接触力总和 +接触能量 +摩擦耗散 +接触失效/释放数量 +``` + +--- + +## 16.2 动量和能量检查 + +每个时间步输出: + +```text +SPH side total contact force +FEM side total contact force +force balance residual +contact work +interface energy transfer +``` + +要求: + +```text +SPH 接触力总和 + FEM 接触力总和 ≈ 0 +``` + +如果不满足,说明力反传或形函数分配有问题。 + +--- + +## 16.3 可视化调试 + +建议输出: + +```text +contact_pairs.vtp +contact_normals.vtp +penetration_points.vtp +interface_forces.vtp +tie_bonds.vtp +released_bonds.vtp +boundary_particles.vtp +``` + +这对调接触算法非常关键。 + +--- + +# 17. CCLite 的最佳初期定位 + +不要一开始就追求: + +```text +通用 mortar +强耦合隐式接触 +任意壳-壳自接触 +复杂多体接触 +``` + +这些会拖慢进度。 + +最好的初期定位是: + +> **一个显式动力学友好的 SPH-FEM 跨域接触与耦合库。** + +第一阶段核心卖点: + +```text +SPH 粒子 ↔ FEM 面接触 +SPH 粒子 ↔ FEM 壳接触 +SPH 壳粒子 ↔ FEM 壳接触 +SPH-FEM penalty tie +tie-to-contact release +SPH-FEM FSI pressure transfer +``` + +这已经能支撑很多工程场景: + +```text +水下爆炸作用壳体 +水冲击薄板 +粒子/碎片撞击结构 +局部 SPH 破坏区与 FEM 结构耦合 +FEM 壳结构与 SPH 壳破坏区耦合 +``` + +--- + +# 18. 推荐的 CCLite 技术路线图 + +可以概括成下面这条路线: + +```text +CCLite 0.1 +接口和数据视图 + ↓ +CCLite 0.2 +SPH solid particle ↔ FEM solid/shell penalty contact + ↓ +CCLite 0.3 +SPH shell particle ↔ FEM solid/shell thickness-aware contact + ↓ +CCLite 0.4 +SPH-FEM tied coupling + damage release + tie-to-contact + ↓ +CCLite 0.5 +SPH-FEM FSI: pressure projection + ghost particles + ↓ +CCLite 0.6 +Riemann FSI + underwater explosion interface + ↓ +CCLite 0.7+ +mortar/Nitsche/augmented Lagrangian/high-order shell coupling +``` + +--- + +# 19. 最建议的模块名称 + +既然叫 CCLite,可以把内部模块命名为: + +```text +ccl_core +ccl_interface +ccl_geometry +ccl_search +ccl_contact +ccl_coupling +ccl_fsi +ccl_transfer +ccl_diagnostics +``` + +算法对象命名: + +```text +CCLContactPair +CCLContactLaw +CCLCouplingPair +CCLCouplingLaw +CCLInterfaceBond +CCLBoundaryParticle +CCLForceTransfer +CCLShellContact +CCLFSIInterface +``` + +--- + +# 20. 总结建议 + +CCLite 的方向非常合适。建议把它定义为: + +> **SPHLite 与 FEMLite 之间的跨域耦合与接触算法库。** + +它应该负责: + +```text +SPH solid ↔ FEM solid/shell contact +SPH shell ↔ FEM solid/shell contact +SPH-FEM tied coupling +damage release / tie-to-contact +SPH-FEM FSI pressure/velocity transfer +ghost/boundary particles +Riemann FSI +interface diagnostics +``` + +它不应该负责: + +```text +SPH 内部粒子作用 +SPH 内部壳粒子接触 +FEM 内部实体/壳接触 +FEM 单元内力 +SPH 粒子内力 +全局时间积分 +材料本构 +``` + +最稳妥的开发策略是: + +```text +先做 penalty contact +再做 shell thickness-aware contact +再做 SPH-FEM tied coupling +再做 tie-to-contact damage release +再做 FSI pressure projection +最后做 Riemann FSI / mortar / Nitsche / augmented Lagrangian +``` + +这样 CCLite 的边界清楚、算法层次清楚,也能自然服务于你已有的 **SPHLite** 和 **FEMLite**。