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