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

555 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
**软件全称**:Coupling & Contact Lite
**设计基线**:独立主控程序、Fortran95 算法核心、Fortran2018/C IPC 通信层、Abaqus 风格 `.inp` 输入
**关联软件**:SPHLite、FEMLite
**第一阶段平台**:Windows / gfortran / 本机共享内存
---
# 1. 引言
## 1.1 编写目的
本文档定义 CCLite 的软件需求边界、运行形态、输入输出、通信方式、耦合与接触能力、版本目标和验收要求。
CCLite 面向已有的 SPHLite 与 FEMLite,是二者之间的 SPH-FEM 跨域耦合与接触主控程序。CCLite、SPHLite、FEMLite 均保持独立可执行程序形态;CCLite 负责启动、同步调度、数据交换、接触/耦合算法和诊断输出。
## 1.2 软件背景
SPHLite 已具备 SPH 水、气、炸药、实体粒子和壳粒子等计算能力,并提供 coupling region 的粒子/facet 导出、外部载荷导入、接触状态导入和诊断接口。
FEMLite 已具备有限元实体/壳单元、显式动力学、静力、非线性静力、隐式 Newmark、接触、restart、Fortran API 和 C ABI,并提供边界 facet 查询与 SPH 外载荷施加接口。
工程场景中常见的水下爆炸、流固耦合、局部破坏、碎片冲击、SPH 局部区域与 FEM 远场结构耦合,需要在两个独立求解器之间建立受控的数据交换和界面算法。CCLite 的任务就是建立这一层。
## 1.3 软件定位
CCLite 定位为:
> 面向 SPHLite 与 FEMLite 的独立 SPH-FEM 耦合与接触主控程序。
CCLite 负责:
1. 读取 CCLite 自身 `.inp` 控制文件;
2. 启动或连接 SPHLite 与 FEMLite 独立进程;
3. 建立控制 IPC 与共享内存数据区;
4. 同步调度两个求解器;
5. 从 SPHLite/FEMLite 获取界面状态;
6. 执行 SPH-FEM 接触搜索、接触判定和接触力计算;
7. 执行界面力、压力、牵引、运动边界和接触状态传递;
8. 输出接触、耦合、通信、时间步、能量和动量诊断。
CCLite 不负责:
1. SPH 内部粒子相互作用;
2. SPH 内部壳粒子接触;
3. SPH 材料本构、EOS、邻域求和;
4. FEM 单元刚度、质量、内力、本构更新;
5. FEM 内部实体/壳接触;
6. SPHLite/FEMLite 网格、粒子和几何前处理;
7. 第一阶段不负责 Linux/MPI 生产实现,只预留接口。
## 1.4 技术基线
CCLite 第一版采用以下技术基线:
| 项目 | 需求 |
| --- | --- |
| 软件形态 | CCLite、SPHLite、FEMLite 均为独立主控程序 |
| 核心语言 | 接触、几何、搜索、传递算法核心使用 Fortran95 风格实现 |
| 通信语言 | 数据映射和进程通信层可使用 Fortran2018 |
| 系统 IPC | Windows 共享内存、事件、信号量、管道等系统调用可由 C/C++ 薄层封装 |
| 编译器 | 默认 gfortran |
| 输入格式 | Abaqus 风格 `.inp`,不使用 YAML 作为第一版主控输入 |
| 第一版平台 | Windows 本机三进程共享内存 |
| 预留平台 | Linux 共享内存、MPI、socket 分布式通信 |
---
# 2. 总体需求
## 2.1 总体目标
CCLite 应构建一个轻量、可测试、可扩展的 SPH-FEM 耦合运行系统,使 SPHLite 和 FEMLite 能够在互不嵌入、互不直接依赖内部数据结构的前提下完成联合仿真。
第一阶段目标为:
1. CCLite 可读取 Abaqus 风格 `cclite.inp`;
2. CCLite 可启动 SPHLite 与 FEMLite 独立进程;
3. CCLite 可创建并管理本机共享内存与控制 IPC;
4. SPHLite 与 FEMLite 可按 CCLite 命令完成初始化、导出、导入、推进和停止;
5. CCLite 可完成显式同步 SPH-FEM 接触;
6. CCLite 可输出可追踪的接触与通信诊断。
## 2.2 运行模式
CCLite 应支持以下运行模式:
| 模式 | 命令示例 | 说明 |
| --- | --- | --- |
| check | `cclite check cclite.inp` | 检查 CCLite 输入、SPHLite/FEMLite 路径、关键词和通信配置 |
| dry-run | `cclite dry-run cclite.inp` | 建立通信区、读取模型元信息、构造界面但不推进时间 |
| run | `cclite run cclite.inp` | 正式执行耦合仿真 |
| post | `cclite post cclite.inp` | 汇总接触/耦合/通信历史输出 |
第一版不要求 `replay-coupling`,但输出格式应为后续重放保留 step、region、pair、force 和状态字段。
## 2.3 三程序关系
三程序关系如下:
```text
CCLite
Controller / IPC / Contact
/ \
control IPC control IPC
/ \
SPHLite FEMLite
independent exe independent exe
shared memory:
SPH_to_CCLite
FEM_to_CCLite
CCLite_to_SPH
CCLite_to_FEM
```
基本原则:
1. CCLite 拥有同步调度权;
2. SPHLite 和 FEMLite 不直接调度对方;
3. 大数据通过共享内存交换;
4. 小命令和状态通过控制 IPC 交换;
5. CCLite 不直接访问求解器私有内存;
6. SPHLite/FEMLite 通过通信接口层把公开数据写入共享内存。
---
# 3. 输入需求
## 3.1 三文件输入体系
CCLite 第一版采用三份 `.inp`:
| 文件 | 责任 |
| --- | --- |
| `cclite.inp` | CCLite 主控、通信、时间、界面、接触、输出 |
| `sphlite.inp` | SPHLite 粒子、材料、section、时间和 coupling region |
| `femlite.inp` | FEMLite 节点、单元、材料、边界、surface 和输出 |
CCLite 只解析 `cclite.inp` 和必要的模型元信息;SPHLite/FEMLite 自身输入仍由各自程序解析。
## 3.2 关键词风格
CCLite 输入采用 Abaqus 风格关键词。关键词以 `*CCLITE` 前缀区分 CCLite 专有控制项。
第一版必须支持:
```text
*CCLITE CONTROL
*CCLITE SOLVER
*CCLITE IPC
*CCLITE TIME
*CCLITE INTERFACE
*CCLITE CONTACT PAIR
*CCLITE SURFACE INTERACTION
*CCLITE OUTPUT
*END STEP
```
关键词示例:
```text
*CCLITE CONTROL, NAME=CASE_001
MODE=EXPLICIT_EXPLICIT_SYNC
*CCLITE SOLVER, NAME=SPH, TYPE=SPHLITE
EXECUTABLE=SPHLite/cpu_release/bin/sphlite.exe
INPUT=sphlite.inp
WORKDIR=work/sph
*CCLITE SOLVER, NAME=FEM, TYPE=FEMLITE
EXECUTABLE=FEMLite/cpu_release/bin/femlite.exe
INPUT=femlite.inp
WORKDIR=work/fem
*CCLITE IPC, TYPE=WINDOWS_SHMEM
PREFIX=CCLITE_CASE_001
CONTROL=EVENT
BUFFERING=DOUBLE
*CCLITE TIME
START=0.0, END=1.0E-3, DT=1.0E-7
*CCLITE INTERFACE, NAME=HULL_IMPACT
SPH_REGION=WATER_CONTACT
FEM_SURFACE=HULL_OUTER
*CCLITE SURFACE INTERACTION, NAME=PENALTY_1
NORMAL=Penalty, KN=1.0E9, CN=1.0E4, FRICTION=0.0
*CCLITE CONTACT PAIR, NAME=PAIR_1
INTERFACE=HULL_IMPACT, INTERACTION=PENALTY_1
TYPE=SPH_PARTICLE_TO_FEM_FACE
*CCLITE OUTPUT
FREQUENCY=10
CONTACT=YES, COUPLING=YES, IPC=YES
```
## 3.3 SPHLite 输入要求
SPHLite 输入文件应提供可供 CCLite 识别的 coupling region。第一版要求 SPHLite 能导出:
1. region 名称;
2. region 类型;
3. 粒子 external id 和 internal index;
4. phase、status、material、section;
5. 质量、体积、密度、压力、内能、温度、光滑长度;
6. 坐标、速度、加速度;
7. 可选 facet proxy,包括 facet id、粒子连接、法向和面积。
SPHLite 应能接收:
1. 粒子力;
2. facet 载荷;
3. facet 压力;
4. facet 牵引;
5. 接触状态;
6. 运动边界。
## 3.4 FEMLite 输入要求
FEMLite 输入文件应提供可供 CCLite 识别的 surface 或边界 facet。第一版要求 FEMLite 能导出:
1. 边界 facet 数量;
2. facet id、element id、face id;
3. facet 节点数与节点连接;
4. facet 节点当前坐标和速度;
5. facet 法向和面积;
6. 节点运动学状态。
FEMLite 应能接收:
1. 节点力;
2. facet 压力;
3. facet 牵引;
4. facet 节点载荷。
---
# 4. 通信需求
## 4.1 第一版通信范围
第一版通信只要求支持:
```text
Windows + gfortran + 本机共享内存
```
Linux 共享内存、MPI、socket 分布式通信只作为预留设计,不进入第一版验收。
## 4.2 通信架构
CCLite 应采用“大数据共享内存、小命令控制 IPC”的通信架构。
```text
大数据:
SPH_to_CCLite
FEM_to_CCLite
CCLite_to_SPH
CCLite_to_FEM
小命令:
INIT
BUILD
EXPORT
IMPORT
ADVANCE
WRITE_OUTPUT
STOP
```
## 4.3 共享内存数据块
共享内存数据块应采用固定二进制布局:
```text
Header
magic
version
block_role
step_id
buffer_id
state
item_count
item_stride
payload_bytes
error_code
Payload
plain numeric arrays
```
payload 不得包含 Fortran pointer、C++ object、可变长字符串或进程私有地址。
## 4.4 控制状态
每个求解器进程应支持以下状态:
```text
CREATED
INITIALIZING
READY
EXPORTING
WAITING_IMPORT
ADVANCING
DONE
FAILED
STOPPED
```
CCLite 应检测超时、异常退出、错误码和共享内存版本不匹配。
---
# 5. 功能需求
## 5.1 CCLite Controller
CCLite Controller 应提供:
1. 解析 `cclite.inp`;
2. 创建工作目录;
3. 创建共享内存和同步对象;
4. 启动 SPHLite/FEMLite;
5. 发送控制命令;
6. 等待求解器完成;
7. 管理 step_id 和 buffer_id;
8. 处理超时、错误和停止;
9. 汇总输出诊断。
## 5.2 接口数据管理
CCLite 应从共享内存中构造以下界面视图:
1. SPH particle view;
2. SPH facet proxy view;
3. FEM boundary facet view;
4. FEM node kinematics view;
5. CCLite contact force buffer;
6. CCLite facet load buffer。
## 5.3 接触搜索与检测
第一版必须支持:
1. SPH 粒子到 FEM 三角形/四边形面的候选搜索;
2. point-face 最近点;
3. point-edge fallback;
4. FEM 壳厚度接触距离;
5. 接触法向、gap、penetration 计算;
6. 接触对持久编号和诊断输出。
第一版不要求:
1. 通用 mortar;
2. Nitsche;
3. 任意壳自接触;
4. 多体复杂接触;
5. GPU 或大规模并行搜索。
## 5.4 接触力模型
第一版必须支持 penalty damping 接触:
```text
fn = kn * penetration + cn * normal_relative_velocity
```
可选支持 Coulomb 摩擦,但不作为第一版硬性验收项。
接触力必须满足:
1. SPH 侧与 FEM 侧作用-反作用平衡;
2. FEM face 载荷按形函数或面积权重分配至节点;
3. 输出总力误差和总力矩误差;
4. 非有限值、异常大穿透、异常大接触力必须进入诊断。
## 5.5 时间同步
第一版支持显式-显式同步:
```text
for step = 1..n:
SPHLite export interface state
FEMLite export interface state
CCLite search and compute contact
CCLite write loads to shared memory
SPHLite import loads
FEMLite import loads
SPHLite advance explicit dt
FEMLite advance explicit dt
CCLite write diagnostics
```
后续版本预留:
1. 显式-显式异步子循环;
2. SPH 显式 + FEM 隐式弱耦合;
3. SPH 显式 + FEM 隐式强耦合;
4. rollback 与 Aitken 松弛。
## 5.6 输出需求
CCLite 应输出:
| 文件 | 内容 |
| --- | --- |
| `cclite.log` | 主控流程、错误、警告 |
| `ipc_report.csv` | 命令、状态、耗时、共享内存统计 |
| `contact_report.csv` | 接触对数、最大穿透、最大接触力 |
| `force_balance.csv` | SPH/FEM 总力、总力矩和平衡误差 |
| `timestep_report.csv` | dt、step、求解器状态 |
| `interface_snapshot_*.csv` | 可选调试用界面快照 |
---
# 6. 非功能需求
## 6.1 可维护性
1. Fortran95 算法核心不得依赖 Windows API;
2. Windows IPC 细节必须限制在薄 C/C++ 层和 Fortran2018 wrapper;
3. 共享内存布局必须版本化;
4. 输入关键词必须可扩展且向后兼容。
## 6.2 稳定性
CCLite 必须检查:
1. 共享内存 magic/version;
2. payload 大小;
3. step_id 顺序;
4. buffer 状态;
5. 求解器错误码;
6. 非有限数;
7. 接触力异常;
8. 通信超时。
## 6.3 性能
第一版目标:
1. 接触搜索复杂度接近 O(N) 或 O(N log M);
2. 大数组不通过文本文件交换;
3. 每步数据交换避免重复分配;
4. 双缓冲应可配置;
5. 输出频率可控。
---
# 7. 版本规划
## 7.1 CCLite 0.1:主控与通信闭环
目标:
1. `cclite.inp` 解析;
2. Windows/gfortran 本机共享内存;
3. 控制 IPC;
4. 启动 SPHLite/FEMLite;
5. 空耦合同步推进;
6. 通信诊断输出。
验收:
1. CCLite 能启动两个独立求解器;
2. 三进程状态机可稳定运行;
3. 空耦合运行结果与各自独立运行一致;
4. 通信错误能被明确报告。
## 7.2 CCLite 0.2:显式同步 SPH-FEM 接触
目标:
1. SPH particle view;
2. FEM boundary facet view;
3. point-face/point-edge 检测;
4. penalty damping 接触;
5. SPH/FEM 力传递;
6. force balance 诊断。
验收:
1. 单粒子撞 FEM 面可产生正确方向接触力;
2. 壳厚度接触距离正确;
3. 作用-反作用误差可控;
4. 接触报告可复核。
## 7.3 CCLite 0.3:异步子循环
目标:
1. SPH 子循环;
2. FEM 宏步平均力;
3. 冲量累计;
4. 子循环诊断。
## 7.4 CCLite 0.4:tied coupling 与 release
目标:
1. SPH-FEM penalty tie;
2. InterfaceBond;
3. damage release;
4. release 后转接触。
## 7.5 CCLite 0.5:FSI 基础能力
目标:
1. SPH 压力投影到 FEM;
2. FEM 边界运动传递给 SPH;
3. boundary/ghost particle 支持;
4. 水下爆炸 FSI 小型验证。
## 7.6 CCLite 0.6+:高级耦合
预留:
1. SPH 显式 + FEM 隐式弱耦合;
2. 强耦合 rollback;
3. Aitken 松弛;
4. Riemann FSI;
5. Linux/MPI 通信后端;
6. 大规模并行和性能优化。
---
# 8. 第一阶段验收清单
CCLite 第一阶段完成时应满足:
1. 文档、输入关键词、代码目录和测试命名均以 Fortran/IPC/.inp 方案为基线;
2. 不再以 YAML 作为第一版主控输入;
3. 不再以 C++ class/`std::vector` 作为内部设计基线;
4. CCLite、SPHLite、FEMLite 均可作为独立可执行程序存在;
5. Windows/gfortran/本机共享内存通信闭环可运行;
6. 显式同步接触最小算例可运行;
7. 接触力、穿透量、通信状态、时间步和错误可诊断;
8. Linux/MPI 只作为接口预留,不作为第一版交付承诺。
---
# 9. 总结
CCLite 应作为 SPHLite 与 FEMLite 之间的独立 SPH-FEM 耦合与接触主控程序。第一版重点不是追求完整工业级接触库,而是建立可靠的三进程通信、`.inp` 控制、显式同步、界面数据交换、基础 penalty 接触和诊断闭环。