Add CCLite documentation baseline
This commit is contained in:
@@ -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 诊断形成可测试的工程闭环。
|
||||
|
||||
Reference in New Issue
Block a user