Add CCLite documentation baseline

This commit is contained in:
Codex
2026-07-04 21:52:49 +08:00
commit 4ee25db7d9
6 changed files with 4325 additions and 0 deletions
@@ -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 诊断形成可测试的工程闭环。