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

644 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 诊断形成可测试的工程闭环。