# 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 诊断形成可测试的工程闭环。