Files
CCLite/docs/02_architectural_design_specification.md
2026-07-04 21:52:49 +08:00

14 KiB
Raw Permalink Blame History

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 的运行关系如下:

                         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 数据交换方向

第一版建议使用四类单向共享内存块:

SPH_TO_CCL
  SPHLite 写,CCLite 读

FEM_TO_CCL
  FEMLite 写,CCLite 读

CCL_TO_SPH
  CCLite 写,SPHLite 读

CCL_TO_FEM
  CCLite 写,FEMLite 读

每类数据块可配置单缓冲、双缓冲或三缓冲。第一版默认双缓冲。

2.3 控制 IPC

控制 IPC 负责小命令和状态同步:

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 采用以下分层:

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 独立入口程序

第一版主要运行形态:

cclite check cclite.inp
cclite dry-run cclite.inp
cclite run cclite.inp
cclite post cclite.inp

SPHLite 与 FEMLite 由 CCLite 按输入路径启动:

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

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 输出文件

默认输出目录:

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 流程。

主要过程:

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. 处理错误和超时。

核心状态:

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 包含三部分:

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 和数据有效性。

主要数据视图:

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 接触力。

第一版接触类型:

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 应包含:

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:

BLOCK_SPH_PARTICLES
BLOCK_SPH_FACETS
BLOCK_FEM_FACETS
BLOCK_CCL_SPH_FORCES
BLOCK_CCL_FEM_LOADS
BLOCK_DIAGNOSTICS

6.3 Buffer State

EMPTY
WRITING
READY
READING
CONSUMED
ERROR

写入者只从 EMPTY/CONSUMED 进入 WRITING,写完后置为 READY。读取者只读取 READY,读完后置为 CONSUMED。


7. 运行流程

7.1 check 流程

1. 读取 cclite.inp
2. 检查关键词和参数
3. 检查 SPHLite/FEMLite executable/input 路径
4. 检查 IPC 类型是否为第一版支持项
5. 检查 interface/contact pair 引用关系
6. 输出 check 报告

7.2 dry-run 流程

1. 执行 check
2. 创建 IPC 资源
3. 启动 SPHLite/FEMLite
4. 发送 READ_INPUT / BUILD_MODEL
5. 请求导出界面元信息
6. 构造初始 interface view
7. 可选执行初始接触搜索
8. 停止求解器并释放 IPC

7.3 run 流程

1. 执行 check
2. 创建 IPC 资源
3. 启动 SPHLite/FEMLite
4. 初始化并建模
5. 进入时间步循环
6. 请求两侧导出界面状态
7. CCLite 计算接触和界面力
8. CCLite 写入两侧 load buffer
9. 请求两侧导入载荷
10. 请求两侧推进 dt
11. 输出诊断
12. 完成后停止求解器并释放 IPC

7.4 显式同步流程

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 推荐目录

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 构建方式,例如:

mingw32-make

或:

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