Start 0.8.0 coupling interface baseline
This commit is contained in:
@@ -0,0 +1,762 @@
|
||||
# SPHLite v8.0 开发计划
|
||||
|
||||
文档状态:0.8.0 开发计划草案
|
||||
|
||||
目标软件版本:SPHLite 0.8.0
|
||||
|
||||
## 1. 文档定位
|
||||
|
||||
本文档用于规划 SPHLite 0.8.0 版本的开发范围。0.8.0 是 SPHLite 从内部水-气-爆炸-结构 smoke 链路进入外部耦合边界的起点,目标是在 0.7.1 已完成局部爆炸稳定化 gate 的基础上,将 `CouplingInterface` 从中立占位推进到可由外部耦合模块逐步驱动的接触耦合接口。
|
||||
|
||||
0.8.0 不直接与 FEMLite 联合运行,不引用 FEMLite 模块,不修改 FEMLite,也不把外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite 作为 SPHLite 内部依赖。0.8.0 只交付 SPHLite 侧的中立数据契约、区域导出、外部载荷/运动边界导入、显式步施加路径、诊断、接口和 mock coupling gate。
|
||||
|
||||
0.8.0 的核心价值是把后续真实 FEM-SPH 接触耦合所需的 SPHLite 侧边界固定下来,使外部耦合模块可以通过稳定 C ABI 或 Fortran API 每步获取 SPH 状态、计算接触力或运动边界,再把结果导回 SPHLite。
|
||||
|
||||
## 2. 依据文件
|
||||
|
||||
本计划依据以下 01-06 号文档制定:
|
||||
|
||||
- `docs/01_requirements_specification.md`
|
||||
- `docs/02_software_architecture_design.md`
|
||||
- `docs/03_detailed_design.md`
|
||||
- `docs/04_mathematical_model_and_algorithms.md`
|
||||
- `docs/05_interface_control_document.md`
|
||||
- `docs/06_test_and_verification_plan.md`
|
||||
|
||||
同时,0.8.0 以已发布的 0.7.1 局部爆炸稳定化版本为开发基线。
|
||||
|
||||
## 3. 版本定位
|
||||
|
||||
### 3.1 与 0.7.1 的关系
|
||||
|
||||
0.7.1 已完成以下能力:
|
||||
|
||||
- Water/Gas/Explosive/Solid/Shell 小型局部爆炸 smoke 链路。
|
||||
- 多 blast region 输入、启用/禁用控制、源/目标统计和结构载荷叠加。
|
||||
- Solid/Shell 外部载荷缓存、显式推进顺序、输出和 restart 边界测试。
|
||||
- 0.7.0 blast 回归 gate、0.7.1 blast 专项 gate、完整 CTest 和 source size gate。
|
||||
|
||||
0.8.0 不重写 0.7.1 的 Blast 路径。0.8.0 应复用 0.7.1 中外部载荷进入 Solid/Shell 显式响应的经验,把载荷来源从内部 Blast 调试投影扩展为外部耦合模块导入的中立载荷和运动边界。
|
||||
|
||||
### 3.2 与 0.8.x 的关系
|
||||
|
||||
0.8.0 建议只交付接触耦合接口起步闭环。后续 0.8.x 可继续推进:
|
||||
|
||||
- 更完整的 facet 几何导出。
|
||||
- 接触法向、间隙、穿透量或接触状态诊断。
|
||||
- 真实压力载荷投影和更细的面力到粒子力分配。
|
||||
- 耦合 restart 状态加固和外部驱动示例。
|
||||
- 更完整的 C++、Python 和 CLI inspect 支持。
|
||||
|
||||
0.8.0 不需要一次性完成所有接触算法,只需要把 SPHLite 侧可稳定交换的数据和显式施加路径建立起来。
|
||||
|
||||
### 3.3 与 0.9.0 的关系
|
||||
|
||||
0.9.0 仍建议作为连续体耦合版本线起点。0.8.0 必须在输入、状态和诊断中区分接触耦合与连续体耦合,但 0.8.0 不交付 `Solid` 与 FEM 实体连续体耦合、`Shell` 与 FEM 壳连续体耦合、重叠区耦合或界面约束。
|
||||
|
||||
0.8.0 可以为连续体耦合预留 `COUPLING_TYPE_CONTINUUM`、交换量枚举和错误路径,但默认 gate 不验收连续体耦合。
|
||||
|
||||
### 3.4 与 CouplingModule 的关系
|
||||
|
||||
外部耦合模块负责:
|
||||
|
||||
- FEM 侧模型读取和区域识别。
|
||||
- SPH-FEM 匹配、搜索和投影。
|
||||
- 接触状态判断、穿透量计算和接触力算法。
|
||||
- 强耦合、弱耦合、子循环或松弛控制。
|
||||
- FEMLite 或其他外部求解器的数据适配。
|
||||
|
||||
SPHLite 负责:
|
||||
|
||||
- 导出 SPHLite 侧 coupling region 的粒子状态和边界近似。
|
||||
- 接收外部模块导入的粒子力、面力、体力或运动边界。
|
||||
- 在显式动力学步中施加这些外部交换量。
|
||||
- 记录耦合功、动量交换、能量交换、非有限值和错误诊断。
|
||||
|
||||
SPHLite C ABI 和文档中应保持中立命名,不出现 FEMLite 内部数据库、单元类或私有结构体。
|
||||
|
||||
### 3.5 0.8.0 核心目标
|
||||
|
||||
0.8.0 的核心目标是形成 SPHLite 侧接触耦合接口闭环:
|
||||
|
||||
```text
|
||||
0.7.1 Water/Gas/Explosive/Solid/Shell blast smoke baseline
|
||||
-> coupling region input and validation
|
||||
-> neutral particle export
|
||||
-> neutral boundary/facet proxy export
|
||||
-> external particle force and facet load import
|
||||
-> external motion boundary import
|
||||
-> Velocity-Verlet explicit step application
|
||||
-> coupling work, momentum and energy diagnostics
|
||||
-> Fortran API, C ABI, C++ wrapper and Python ctypes smoke
|
||||
-> mock contact coupling gate without FEMLite dependency
|
||||
```
|
||||
|
||||
## 4. 开发原则
|
||||
|
||||
### 4.1 中立接口优先
|
||||
|
||||
0.8.0 所有接口、模块名、测试名和错误消息应保持中立语义。可使用 `coupling`、`external`、`contact`、`facet`、`particle`、`region` 等命名,不使用 FEMLite 内部类型名。
|
||||
|
||||
### 4.2 不直接依赖外部耦合模块
|
||||
|
||||
SPHLite 不把 CouplingModule 作为构建依赖。默认 gate 只使用 SPHLite 仓库内的小型 mock coupling 测试,模拟外部模块每步导入载荷或运动边界。
|
||||
|
||||
### 4.3 保持求解器定位
|
||||
|
||||
SPHLite 仍是求解器,不负责几何、网格或粒子生成。0.8.0 可从输入集合、section、Shell 参考几何和已有粒子状态导出边界近似,但不得新增几何建模、网格生成、粒子生成或自动边界重构能力。
|
||||
|
||||
### 4.4 复用 Abaqus 子集优先
|
||||
|
||||
输入层应优先复用 Abaqus 子集中的 `*NSET`、`*ELSET`、`*SURFACE` 或已有 section/set 语义。Abaqus 子集无法表达的 SPHLite 侧耦合控制,使用 `*SPHLITE COUPLING REGION` 扩展关键词。
|
||||
|
||||
### 4.5 显式动力学单向步进
|
||||
|
||||
0.8.0 仍只支持 Velocity-Verlet 显式动力学。外部耦合模块可以在每个显式步前导入载荷或运动边界;SPHLite 只负责在当前显式步中施加,不引入隐式强耦合求解器。
|
||||
|
||||
### 4.6 小型可测优先
|
||||
|
||||
0.8.0 默认 gate 只覆盖小规模、可重复的中立耦合接口测试。真实 FEM-SPH 联合运行、长时间接触滑移、复杂摩擦和工程舱段破坏不进入默认 gate。
|
||||
|
||||
### 4.7 追加式接口扩展
|
||||
|
||||
C ABI、C++ wrapper、Python ctypes 和 CLI 必须追加式扩展,不改变 0.7.1 既有函数的参数、数组展开顺序、错误码或物理含义。
|
||||
|
||||
## 5. 0.8.0 交付目标
|
||||
|
||||
0.8.0 建议交付以下内容:
|
||||
|
||||
1. 将软件版本更新为 `0.8.0`。
|
||||
2. 保持 0.7.1 完整 gate 全部通过。
|
||||
3. 明确 0.8.0 为接触耦合接口起步版,而非真实 FEM-SPH 联合运行版。
|
||||
4. 加固 `*SPHLITE COUPLING REGION` 输入语义,支持 `TYPE=CONTACT`。
|
||||
5. 支持 coupling region 通过 set、phase、material、section 或受控 surface 名称选择 SPHLite 侧粒子。
|
||||
6. 支持 coupling region 的 `EXPORT=PARTICLE`、`EXPORT=FACET` 或 `EXPORT=BOTH` 控制。
|
||||
7. 支持 coupling region 的 `IMPORT=FORCE`、`IMPORT=FACET_LOAD` 或 `IMPORT=MOTION` 控制。
|
||||
8. 对重复 region、空 region、非法 type/export/import、非法 set/surface 和不支持连续体耦合请求给出明确 error。
|
||||
9. 建立 coupling region 运行时表,保存名称、类型、导出模式、导入模式、关联 set/surface、active 粒子数和状态。
|
||||
10. 导出 coupling 粒子的 external id、internal id、phase、status、material、section、质量、体积、密度、压力、内能、温度、`h`、坐标、速度和加速度。
|
||||
11. 为 Shell coupling region 导出受控边界/facet proxy,包括 facet id、局部粒子 id、坐标、速度、法向、面积和 section 信息。
|
||||
12. 为 Solid coupling region 提供 particle contact export;若输入显式给出 surface/facet 关系,可导出受控 facet proxy,否则不得自动重构体表面。
|
||||
13. 支持外部粒子力导入,并按 particle external id 或 coupling export index 映射到内部粒子。
|
||||
14. 支持外部 facet load 导入,并分配到 facet 关联粒子。
|
||||
15. 支持外部运动边界导入,包括受控速度边界或位移目标边界的第一版路径。
|
||||
16. 外部载荷和运动边界必须在 Velocity-Verlet 显式步中进入总加速度、速度或位置更新的受控位置。
|
||||
17. 支持 stale load 或重复导入诊断,避免无意复用上一耦合步载荷。
|
||||
18. 记录 coupling 总力、总力矩或等价力矩、冲量、做功、动量交换、能量交换、最大导入力、最大运动边界误差和非有限计数。
|
||||
19. 支持无 active coupling region 时安全跳过,不影响 Water/Gas/Explosive/Solid/Shell 既有路径。
|
||||
20. 将 coupling summary 写入 summary CSV 的受控字段。
|
||||
21. 在粒子 CSV 中追加必要的 coupling 调试字段,至少覆盖外部力和运动边界状态。
|
||||
22. 新增正式 `STATE_0_8` 或等价 0.8 restart 块,保存 coupling region、当前外部载荷/运动边界和累计诊断;若实现阶段决定不保存某类可重建数据,必须在文档中明确边界并配套测试。
|
||||
23. 保持 0.7.1 及更早 restart 可兼容读入,并初始化空 coupling 状态。
|
||||
24. 新增 coupling Fortran API,覆盖 region 查询、particle export、facet export、force import、facet load import、motion import 和 diagnostics 查询。
|
||||
25. 新增 coupling C ABI,采用 caller-allocated buffer 和中立命名。
|
||||
26. 新增 C++ wrapper 的 coupling 薄包装。
|
||||
27. 新增 Python `ctypes` coupling 调试入口和 mock coupling smoke。
|
||||
28. CLI 支持 coupling inspect 字段,不要求 CLI 直接驱动真实外部耦合。
|
||||
29. 新增 0.8.0 coupling 专项 CTest gate。
|
||||
30. 更新 README、06、09 和 11 号文档中的 0.8.0 测试、验收和不交付范围。
|
||||
31. 不新增 FEMLite 直接依赖,不修改 SPHLite 文件夹之外的内容。
|
||||
|
||||
## 6. 非交付范围
|
||||
|
||||
0.8.0 不交付以下内容:
|
||||
|
||||
1. 不交付真实 FEMLite 联合运行。
|
||||
2. 不交付外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite 的实现。
|
||||
3. 不交付 FEM-SPH 连续体耦合、重叠区耦合或界面约束。
|
||||
4. 不交付生产级接触搜索、摩擦、粘结、冲击接触稳定化或罚函数参数库。
|
||||
5. 不交付完整 SPH-FEM facet 自动匹配和投影算法。
|
||||
6. 不交付从 Solid 体粒子自动重构复杂外表面的算法。
|
||||
7. 不交付工程级水下接触爆炸破坏 benchmark。
|
||||
8. 不交付复杂板壳撕裂、穿孔、碎片云和碎片-流体接触。
|
||||
9. 不交付大规模并行、GPU 后端或性能优化版本。
|
||||
10. 不新增几何、网格或粒子生成能力。
|
||||
11. 不改变 0.7.1 Blast 调试接口边界,不把 Blast 调试字段强行纳入公开 C ABI。
|
||||
|
||||
## 7. 输入和 Coupling Region
|
||||
|
||||
### 7.1 输入关键词建议
|
||||
|
||||
0.8.0 建议扩展已有 `*SPHLITE COUPLING REGION`,示例语义如下:
|
||||
|
||||
```text
|
||||
*SPHLITE COUPLING REGION, NAME=HULL_CONTACT, TYPE=CONTACT,
|
||||
SET=SHELL_TARGET, EXPORT=BOTH, IMPORT=FORCE, SURFACE=SHELL_SURFACE
|
||||
```
|
||||
|
||||
建议参数:
|
||||
|
||||
- `NAME`:coupling region 名称,必填且唯一。
|
||||
- `TYPE`:第一版支持 `CONTACT`;`CONTINUUM` 可预留但默认 error 或 warning 后不启用。
|
||||
- `SET`:SPHLite 侧粒子集合名称。
|
||||
- `SURFACE`:可选 surface/facet 名称,仅在已有输入子集可表达时使用。
|
||||
- `PHASE`:可选 phase 过滤,例如 `SOLID`、`SHELL`、`WATER` 或 `GAS`。
|
||||
- `MATERIAL`:可选 material 过滤。
|
||||
- `SECTION`:可选 section 过滤。
|
||||
- `EXPORT`:`PARTICLE`、`FACET` 或 `BOTH`。
|
||||
- `IMPORT`:`FORCE`、`FACET_LOAD`、`MOTION` 或组合式受控枚举。
|
||||
- `ENABLED`:可选启用状态,默认启用。
|
||||
|
||||
0.8.0 不追求完整 Abaqus coupling 或 contact 关键词兼容。能复用 set、surface 和 section 的地方应复用;SPHLite 专有的交换控制保留在 `*SPHLITE COUPLING REGION`。
|
||||
|
||||
### 7.2 输入校验
|
||||
|
||||
0.8.0 应覆盖以下校验:
|
||||
|
||||
- region 名称为空时报 error。
|
||||
- region 名称重复时报 error。
|
||||
- `TYPE` 非 `CONTACT` 或未支持类型时报 error。
|
||||
- `SET`、`SURFACE`、`PHASE`、`MATERIAL`、`SECTION` 均无法选中粒子时报 error 或受控 warning,具体取决于是否影响运行。
|
||||
- 请求 `EXPORT=FACET` 但没有可用 facet proxy 时,应明确 error 或降级为 `PARTICLE` 并 warning;默认 gate 建议采用 error,避免静默改变耦合语义。
|
||||
- 请求 `IMPORT=MOTION` 作用于 failed 粒子或非 active 粒子时,应按受控策略跳过并记录诊断。
|
||||
- set 仍只表示集合,不作为物理类型判断依据。
|
||||
|
||||
### 7.3 Region 构建
|
||||
|
||||
0.8.0 构建模型时应建立运行时 coupling region:
|
||||
|
||||
- region 内部 id。
|
||||
- region 名称。
|
||||
- region 类型。
|
||||
- 启用状态。
|
||||
- 导出模式。
|
||||
- 导入模式。
|
||||
- 粒子索引表。
|
||||
- facet proxy 索引表。
|
||||
- 当前步导入状态。
|
||||
- 累计诊断。
|
||||
|
||||
region 构建不得破坏 0.7.1 已有 Blast region、Gas source region 或输出 region 语义。
|
||||
|
||||
## 8. 中立数据契约
|
||||
|
||||
### 8.1 粒子导出字段
|
||||
|
||||
0.8.0 coupling particle export 建议至少包含:
|
||||
|
||||
- external particle id。
|
||||
- internal particle index。
|
||||
- phase。
|
||||
- status。
|
||||
- material id。
|
||||
- section id。
|
||||
- mass。
|
||||
- volume。
|
||||
- rho。
|
||||
- pressure。
|
||||
- internal energy。
|
||||
- temperature。
|
||||
- h。
|
||||
- x(3)。
|
||||
- v(3)。
|
||||
- a(3)。
|
||||
|
||||
数组展开顺序延续 Fortran 列主序到 C 缓冲区:
|
||||
|
||||
- `x[dim + 3 * particle]`
|
||||
- `v[dim + 3 * particle]`
|
||||
- `a[dim + 3 * particle]`
|
||||
|
||||
### 8.2 Facet Proxy 导出字段
|
||||
|
||||
0.8.0 facet proxy export 建议至少包含:
|
||||
|
||||
- facet id。
|
||||
- region id。
|
||||
- facet 粒子数。
|
||||
- facet 关联 particle external id。
|
||||
- facet 关联 internal index。
|
||||
- facet center x(3)。
|
||||
- facet velocity v(3)。
|
||||
- facet normal n(3)。
|
||||
- facet area。
|
||||
- facet phase 或主 phase。
|
||||
- facet material/section。
|
||||
|
||||
Shell facet proxy 可优先由 Shell 2D 几何和 director/局部基构建。Solid facet proxy 只在输入提供明确 surface 或受控 facet 信息时构建,不自动从体粒子云推断复杂外表面。
|
||||
|
||||
### 8.3 导入字段
|
||||
|
||||
外部耦合模块导入 SPHLite 的字段建议包括:
|
||||
|
||||
- 粒子力 `force(3,n)`。
|
||||
- facet load 或分配后的 facet 粒子力。
|
||||
- 受控体力或压力等效力。
|
||||
- 目标速度 `target_velocity(3,n)`。
|
||||
- 目标位移或目标位置 `target_position(3,n)`。
|
||||
- 导入 step id 或 coupling epoch。
|
||||
|
||||
0.8.0 第一版不要求支持所有字段同时生产可用,但 API 和错误路径应清楚区分已支持和未支持输入。
|
||||
|
||||
## 9. 载荷和运动边界施加
|
||||
|
||||
### 9.1 外部粒子力
|
||||
|
||||
外部粒子力应进入统一外部力缓存,并在显式步加速度合成阶段施加:
|
||||
|
||||
```text
|
||||
a_total = a_internal + a_body + a_blast + a_coupling
|
||||
a_coupling = external_force / mass
|
||||
```
|
||||
|
||||
0.8.0 应确认:
|
||||
|
||||
- mass 非正时报 error。
|
||||
- force 非有限时报 error 或记录并拒绝导入。
|
||||
- failed 粒子按受控策略跳过或接受,但必须记录。
|
||||
- 多次导入可选择覆盖或累加,语义必须固定并测试。
|
||||
|
||||
建议第一版采用“同一 coupling epoch 内累加,不同 epoch 清零”的策略。
|
||||
|
||||
### 9.2 Facet Load
|
||||
|
||||
facet load 可由外部模块直接分配为 facet 内粒子力,也可作为总面力由 SPHLite 按权重分配。0.8.0 建议优先支持外部已分配的 facet 粒子力,以避免在 SPHLite 内部固化投影算法。
|
||||
|
||||
若实现总面力分配,第一版建议只支持:
|
||||
|
||||
- 均匀分配。
|
||||
- 按粒子面积权重分配。
|
||||
- 非有限和零面积 error。
|
||||
|
||||
复杂接触压力积分、摩擦和接触点投影不进入 0.8.0。
|
||||
|
||||
### 9.3 运动边界
|
||||
|
||||
0.8.0 的运动边界用于模拟外部 FEM facet 运动驱动 SPH 边界或接触边界。第一版建议支持:
|
||||
|
||||
- 目标速度导入。
|
||||
- 目标位置或位移导入。
|
||||
- 简单 penalty 或 direct assignment 模式的受控测试路径。
|
||||
- 运动边界粒子计数、最大速度差和最大位置差诊断。
|
||||
|
||||
运动边界不得变成隐式约束求解器。默认 gate 只检查小模型中方向、有限性、能量诊断和不污染非 coupling 粒子。
|
||||
|
||||
## 10. 显式求解器集成
|
||||
|
||||
0.8.0 推荐每步调用顺序:
|
||||
|
||||
```text
|
||||
external driver:
|
||||
sphlite_export_coupling_state(region)
|
||||
external coupling module computes contact or motion data
|
||||
sphlite_apply_coupling_forces/loads/motion(region)
|
||||
sphlite_advance_explicit(dt)
|
||||
sphlite_get_coupling_diagnostics(region)
|
||||
```
|
||||
|
||||
SPHLite 内部显式步建议:
|
||||
|
||||
1. 读取当前 coupling 外部载荷和运动边界缓存。
|
||||
2. 在加速度合成阶段叠加 external coupling force。
|
||||
3. 在 Velocity-Verlet 更新阶段施加受控运动边界。
|
||||
4. 更新 coupling 做功、冲量、动量和能量诊断。
|
||||
5. 若设置为 step-local 载荷,在步末标记为已消费。
|
||||
|
||||
0.8.0 不实现外部耦合模块的时间循环控制策略。`sphlite_run_explicit` 在无外部驱动时只能运行无耦合或 mock 输入,不应伪装真实联合仿真。
|
||||
|
||||
## 11. Diagnostics、Output 和 Restart
|
||||
|
||||
### 11.1 Diagnostics
|
||||
|
||||
0.8.0 coupling diagnostics 建议包括:
|
||||
|
||||
- coupling region 数量。
|
||||
- active coupling 粒子数。
|
||||
- active facet proxy 数量。
|
||||
- 当前步导入粒子力数量。
|
||||
- 当前步导入 facet load 数量。
|
||||
- 当前步运动边界数量。
|
||||
- 总外部力。
|
||||
- 总外部力矩或等价力矩。
|
||||
- 累计冲量。
|
||||
- 累计做功。
|
||||
- 动量交换。
|
||||
- 能量交换。
|
||||
- 最大外部力。
|
||||
- 最大 coupling 加速度。
|
||||
- 最大目标速度误差。
|
||||
- 最大目标位置误差。
|
||||
- stale load 计数。
|
||||
- skipped particle 计数。
|
||||
- nonfinite import 计数。
|
||||
|
||||
### 11.2 CSV 输出
|
||||
|
||||
summary CSV 建议追加:
|
||||
|
||||
- `coupling_regions`
|
||||
- `coupling_particles`
|
||||
- `coupling_facets`
|
||||
- `coupling_force_x`
|
||||
- `coupling_force_y`
|
||||
- `coupling_force_z`
|
||||
- `coupling_impulse_x`
|
||||
- `coupling_impulse_y`
|
||||
- `coupling_impulse_z`
|
||||
- `coupling_work`
|
||||
- `coupling_energy_exchange`
|
||||
- `coupling_nonfinite_imports`
|
||||
- `coupling_stale_loads`
|
||||
|
||||
粒子 CSV 可追加:
|
||||
|
||||
- `coupling_force_x`
|
||||
- `coupling_force_y`
|
||||
- `coupling_force_z`
|
||||
- `coupling_motion_flag`
|
||||
- `coupling_region_id`
|
||||
|
||||
若字段数量过多,0.8.0 应优先保证 Fortran API 和 C ABI 可查询,CSV 只保留 release gate 最有价值字段。
|
||||
|
||||
### 11.3 Restart
|
||||
|
||||
0.8.0 建议新增 `STATE_0_8` 或等价 0.8 restart 块。应保存或可恢复:
|
||||
|
||||
- coupling region 定义和运行时映射。
|
||||
- region 类型、导出模式、导入模式和启用状态。
|
||||
- 当前步尚未消费的外部力、facet load 和运动边界。
|
||||
- 累计冲量、做功、动量和能量诊断。
|
||||
- stale load、skipped particle 和 nonfinite import 计数。
|
||||
- 输出计数和时间控制状态。
|
||||
|
||||
兼容读入:
|
||||
|
||||
- `STATE_0_8`:完整读回 coupling 状态并可继续显式步。
|
||||
- `STATE_0_7_1` 或当前 0.7.1 状态边界:读回既有状态并初始化空 coupling 状态。
|
||||
- 更早可支持状态:初始化空 coupling 状态。
|
||||
|
||||
若当前实现仍保留较早 restart state 名称,0.8.0 应在开发阶段明确实际状态版本名,并在 06、09、11 号文档中同步记录。
|
||||
|
||||
## 12. API、C ABI、C++、Python 和 CLI
|
||||
|
||||
### 12.1 Fortran API
|
||||
|
||||
建议新增或补强以下 Fortran API:
|
||||
|
||||
- `sph_coupling_get_region_count`
|
||||
- `sph_coupling_get_region_info`
|
||||
- `sph_coupling_get_particle_count`
|
||||
- `sph_coupling_export_particles`
|
||||
- `sph_coupling_get_facet_count`
|
||||
- `sph_coupling_export_facets`
|
||||
- `sph_coupling_apply_particle_forces`
|
||||
- `sph_coupling_apply_facet_loads`
|
||||
- `sph_coupling_apply_motion_boundary`
|
||||
- `sph_coupling_clear_imports`
|
||||
- `sph_coupling_get_diagnostics`
|
||||
|
||||
Fortran API 是语义来源,C ABI 只做薄包装。
|
||||
|
||||
### 12.2 C ABI
|
||||
|
||||
C ABI 必须使用 `sphlite_` 前缀和中立命名。建议新增:
|
||||
|
||||
```c
|
||||
int sphlite_get_coupling_region_count(int *count);
|
||||
|
||||
int sphlite_get_coupling_region_info(int region_index,
|
||||
char *name,
|
||||
int name_capacity,
|
||||
int *region_type,
|
||||
int *export_mode,
|
||||
int *import_mode,
|
||||
int *enabled);
|
||||
|
||||
int sphlite_get_coupling_particle_count(const char *region,
|
||||
int *count);
|
||||
|
||||
int sphlite_get_coupling_particles(const char *region,
|
||||
int max_particles,
|
||||
int *particle_id_ext,
|
||||
int *phase,
|
||||
int *status,
|
||||
int *material_id,
|
||||
int *section_id,
|
||||
double *scalars,
|
||||
int scalar_capacity,
|
||||
double *x,
|
||||
double *v,
|
||||
double *a,
|
||||
int *count);
|
||||
|
||||
int sphlite_get_coupling_facet_count(const char *region,
|
||||
int *num_facets,
|
||||
int *max_face_particles);
|
||||
|
||||
int sphlite_get_coupling_facets(const char *region,
|
||||
int num_facets,
|
||||
int max_face_particles,
|
||||
int *facet_id,
|
||||
int *facet_npart,
|
||||
int *facet_particles,
|
||||
double *center,
|
||||
double *velocity,
|
||||
double *normal,
|
||||
double *area);
|
||||
|
||||
int sphlite_apply_coupling_particle_forces(const char *region,
|
||||
int num_particles,
|
||||
const int *particle_id_ext,
|
||||
const double *forces,
|
||||
int coupling_step);
|
||||
|
||||
int sphlite_apply_coupling_facet_loads(const char *region,
|
||||
int num_facets,
|
||||
int max_face_particles,
|
||||
const int *facet_id,
|
||||
const int *facet_npart,
|
||||
const double *particle_forces,
|
||||
int coupling_step);
|
||||
|
||||
int sphlite_apply_coupling_motion(const char *region,
|
||||
int num_particles,
|
||||
const int *particle_id_ext,
|
||||
const double *target_x,
|
||||
const double *target_v,
|
||||
int mode,
|
||||
int coupling_step);
|
||||
|
||||
int sphlite_get_coupling_diagnostics(const char *region,
|
||||
double *values,
|
||||
int value_capacity);
|
||||
```
|
||||
|
||||
数组展开顺序应在头文件注释中锁定,空指针、小容量、非法 region、非法 step、非有限值必须走既有错误路径。
|
||||
|
||||
### 12.3 C++ wrapper 和 Python ctypes
|
||||
|
||||
C++ 和 Python 继续作为 C ABI 薄包装,不重新定义 coupling 物理语义。0.8.0 建议覆盖:
|
||||
|
||||
- region count/info。
|
||||
- particle export。
|
||||
- facet export。
|
||||
- particle force import。
|
||||
- facet load import。
|
||||
- motion import。
|
||||
- diagnostics 查询。
|
||||
- mock coupling 显式步驱动。
|
||||
|
||||
Python 仍主要用于调试、示例、checker 和验收,不作为唯一入口。
|
||||
|
||||
### 12.4 CLI
|
||||
|
||||
CLI 可追加 inspect 字段:
|
||||
|
||||
- coupling region 列表。
|
||||
- coupling particle count。
|
||||
- coupling facet count。
|
||||
- coupling export/import mode。
|
||||
- coupling diagnostics summary。
|
||||
|
||||
CLI 不负责真实外部耦合主循环。真实外部耦合应通过 C ABI、Fortran API 或外部驱动程序逐步控制。
|
||||
|
||||
## 13. 模块拆分建议
|
||||
|
||||
0.8.0 建议避免继续把 `src/coupling_interface/sph_coupling_interface.f90` 扩成单一大文件。可按复杂度拆分:
|
||||
|
||||
- `sph_coupling_region`:输入后的 region 构建、过滤和校验。
|
||||
- `sph_coupling_export`:粒子和 facet proxy 导出。
|
||||
- `sph_coupling_import`:外部力、facet load 和运动边界导入。
|
||||
- `sph_coupling_apply`:显式步施加和缓存消费。
|
||||
- `sph_coupling_diagnostics`:功、动量、能量、错误计数。
|
||||
- `sph_coupling_restart`:0.8 restart 状态。
|
||||
- `sph_coupling_api`:Fortran API 聚合。
|
||||
|
||||
是否拆分以 source size gate 和依赖关系为准。拆分不得引入循环依赖,不得改变公共 API 语义。
|
||||
|
||||
## 14. 测试计划
|
||||
|
||||
### 14.1 新增 0.8.0 测试
|
||||
|
||||
建议新增以下测试:
|
||||
|
||||
- `input_coupling_region_080`:`TYPE=CONTACT`、export/import/enabled/set/surface/phase/material/section 解析。
|
||||
- `input_coupling_errors_080`:重复 region、非法 type、非法 export/import、缺失 set、空 region 和不支持 continuum error。
|
||||
- `coupling_region_build_080`:运行时 region 表、粒子索引和禁用 region。
|
||||
- `coupling_particle_export_080`:粒子 id、phase、status、material、section、状态量和有限性导出。
|
||||
- `coupling_facet_export_080`:Shell facet proxy 和受控 surface facet proxy 导出。
|
||||
- `coupling_facet_errors_080`:请求 facet 但无可用 surface/proxy 的错误路径。
|
||||
- `coupling_particle_force_import_080`:外部粒子力导入、映射、累加或覆盖语义。
|
||||
- `coupling_facet_load_import_080`:facet 粒子力导入和诊断。
|
||||
- `coupling_motion_boundary_080`:目标速度或位置边界导入和显式步影响。
|
||||
- `coupling_diagnostics_080`:总力、冲量、做功、动量、能量、stale load 和 nonfinite 计数。
|
||||
- `coupling_solver_order_080`:外部导入载荷在 Velocity-Verlet 显式步中的施加顺序。
|
||||
- `coupling_solid_response_080`:Solid coupling 粒子受外部力后速度和位置方向受控。
|
||||
- `coupling_shell_response_080`:Shell coupling 粒子受外部力或运动边界后平动响应受控。
|
||||
- `coupling_noop_regression_080`:无 active region、禁用 region、空导入时不污染既有路径。
|
||||
- `coupling_restart_080`:0.8 coupling restart 写入、读回和继续显式步。
|
||||
- `coupling_restart_071_compat`:0.7.1 或既有 restart 读入后初始化空 coupling 状态。
|
||||
- `coupling_output_080`:summary CSV 和粒子 CSV coupling 字段。
|
||||
- `coupling_fortran_api_080`:Fortran API region/export/import/diagnostics 查询。
|
||||
- `coupling_c_api_080`:C ABI 正常路径、空指针、小容量、非法 region 和非有限输入错误。
|
||||
- `coupling_cpp_api_080`:C++ wrapper 薄包装 smoke。
|
||||
- `coupling_python_080`:Python ctypes mock coupling smoke。
|
||||
- `coupling_cli_080`:CLI inspect coupling region 和 diagnostics 字段。
|
||||
- `coupling_smoke_080`:Solid/Shell 小模型 mock contact coupling 多步 smoke。
|
||||
- `coupling_source_size_080`:CouplingInterface 0.8 source size 和 stale exception 检查。
|
||||
|
||||
### 14.2 回归测试
|
||||
|
||||
0.8.0 必须继续通过 0.7.1 完整 gate,包括:
|
||||
|
||||
- Water 分类 gate。
|
||||
- Gas 分类 gate。
|
||||
- Explosive 分类 gate。
|
||||
- Solid 分类 gate。
|
||||
- Shell 分类 gate。
|
||||
- 0.7.0 blast 回归 gate。
|
||||
- 0.7.1 blast 专项 gate。
|
||||
- 既有 C API/C++/Python/CLI gate。
|
||||
- source size 相关 gate。
|
||||
|
||||
### 14.3 建议 0.8.0 Release Gate
|
||||
|
||||
建议 0.8.0 默认 gate 为:
|
||||
|
||||
```powershell
|
||||
cmake --build build-codex-unix --parallel
|
||||
ctest --test-dir build-codex-unix --output-on-failure
|
||||
ctest --test-dir build-codex-unix -R "^(input_coupling_region_080|input_coupling_errors_080|coupling_region_build_080|coupling_particle_export_080|coupling_facet_export_080|coupling_facet_errors_080|coupling_particle_force_import_080|coupling_facet_load_import_080|coupling_motion_boundary_080|coupling_diagnostics_080|coupling_solver_order_080|coupling_solid_response_080|coupling_shell_response_080|coupling_noop_regression_080|coupling_restart_080|coupling_restart_071_compat|coupling_output_080|coupling_fortran_api_080|coupling_c_api_080|coupling_cpp_api_080|coupling_python_080|coupling_cli_080|coupling_smoke_080|coupling_source_size_080)$" --output-on-failure
|
||||
ctest --test-dir build-codex-unix -R "^(source_size|explosive_source_size|explosive_041_source_size|gas_source_size_cleanup|solid_source_size|solid_051_source_size|shell_061_source_size|coupling_source_size_080)$" --output-on-failure
|
||||
git diff --check
|
||||
```
|
||||
|
||||
实际测试名称可在实现阶段微调,但 0.8.0 release gate 必须覆盖输入、region 构建、粒子导出、facet 导出、载荷导入、运动边界、显式步响应、diagnostics、restart、接口层、source size 和 mock smoke。
|
||||
|
||||
## 15. 建议开发阶段
|
||||
|
||||
若后续根据本计划生成 `todo.md`,建议按以下阶段拆分:
|
||||
|
||||
### 阶段 A:版本基线和范围收敛
|
||||
|
||||
1. 更新软件版本为 `0.8.0`。
|
||||
2. 确认 `v0.7.1` 为开发基线。
|
||||
3. 运行或复核 0.7.1 关键 gate。
|
||||
4. 更新 README 当前开发版本和 0.8.0 定位。
|
||||
5. 明确 0.8.0 不交付真实 FEMLite 联合运行或连续体耦合。
|
||||
|
||||
### 阶段 B:Coupling Region 输入和运行时表
|
||||
|
||||
1. 加固 `*SPHLITE COUPLING REGION` 输入语义。
|
||||
2. 支持 `TYPE=CONTACT`、export/import/enabled 字段。
|
||||
3. 支持 set、surface、phase、material 和 section 过滤。
|
||||
4. 实现重复、非法、空 region 和不支持 continuum 的错误路径。
|
||||
5. 建立运行时 region 表和粒子索引。
|
||||
6. 新增输入和 region 构建测试。
|
||||
|
||||
### 阶段 C:粒子和 Facet Proxy 导出
|
||||
|
||||
1. 实现 coupling 粒子 count 和 caller-allocated export。
|
||||
2. 锁定粒子导出字段和数组展开顺序。
|
||||
3. 实现 Shell facet proxy 导出。
|
||||
4. 实现受控 surface/facet proxy 导出。
|
||||
5. 明确 Solid 无 surface 时不自动重构复杂外表面。
|
||||
6. 新增 particle export、facet export 和 facet error 测试。
|
||||
|
||||
### 阶段 D:外部载荷和运动边界导入
|
||||
|
||||
1. 实现外部粒子力导入。
|
||||
2. 实现 facet load 或 facet 粒子力导入。
|
||||
3. 实现导入 step/epoch 和 stale load 诊断。
|
||||
4. 实现目标速度或目标位置运动边界导入。
|
||||
5. 处理 failed、inactive、非有限和质量非正粒子。
|
||||
6. 新增 force import、facet load import 和 motion boundary 测试。
|
||||
|
||||
### 阶段 E:显式求解器接入和诊断
|
||||
|
||||
1. 将 coupling 外部载荷接入总加速度。
|
||||
2. 将运动边界接入 Velocity-Verlet 受控更新路径。
|
||||
3. 记录当前步总力、冲量、做功、动量和能量交换。
|
||||
4. 记录 skipped、stale 和 nonfinite 计数。
|
||||
5. 确认无 active coupling 时安全跳过。
|
||||
6. 新增 solver order、Solid/Shell response、noop 和 diagnostics 测试。
|
||||
|
||||
### 阶段 F:Output、Restart 和接口层
|
||||
|
||||
1. 追加 summary CSV coupling 字段。
|
||||
2. 追加粒子 CSV coupling 调试字段。
|
||||
3. 设计并实现 `STATE_0_8` 或等价 0.8 restart 边界。
|
||||
4. 实现 0.7.1 restart 兼容读入后的空 coupling 状态。
|
||||
5. 新增 Fortran API。
|
||||
6. 新增 C ABI。
|
||||
7. 新增 C++ wrapper。
|
||||
8. 新增 Python ctypes。
|
||||
9. 新增 CLI inspect 字段。
|
||||
10. 新增 output、restart 和接口层测试。
|
||||
|
||||
### 阶段 G:Mock Coupling Smoke、门禁和文档
|
||||
|
||||
1. 新增 Solid mock contact coupling smoke。
|
||||
2. 新增 Shell mock contact coupling smoke。
|
||||
3. 新增 Solid/Shell 混合 coupling smoke。
|
||||
4. 运行完整 CTest。
|
||||
5. 运行 0.8.0 coupling 专项 gate。
|
||||
6. 运行 0.7.1 blast 回归 gate。
|
||||
7. 运行 source size 相关 gate。
|
||||
8. 运行 `git diff --check`。
|
||||
9. 检查代码、构建脚本、测试和工具目录未新增 FEMLite 直接依赖。
|
||||
10. 更新 README、06、09 和 11 号文档。
|
||||
11. 准备 0.8.0 发布记录。
|
||||
|
||||
## 16. 验收标准
|
||||
|
||||
0.8.0 应满足以下验收标准:
|
||||
|
||||
1. 软件版本为 `0.8.0`。
|
||||
2. 0.7.1 完整 gate 继续通过。
|
||||
3. `*SPHLITE COUPLING REGION` 可表达受控接触 coupling region。
|
||||
4. 非法或不支持 coupling 输入有明确 error。
|
||||
5. coupling region 运行时表可构建并可查询。
|
||||
6. coupling 粒子状态导出字段完整、有限且数组顺序稳定。
|
||||
7. Shell facet proxy 或受控 surface facet proxy 可导出。
|
||||
8. 请求无法构建的 facet proxy 时不静默降级。
|
||||
9. 外部粒子力可导入并影响显式步响应。
|
||||
10. facet load 或 facet 粒子力可导入并影响关联粒子。
|
||||
11. 运动边界可导入并在小模型中产生受控响应。
|
||||
12. stale load、重复导入、failed/inactive 粒子和非有限输入有诊断或错误路径。
|
||||
13. coupling 做功、冲量、动量交换和能量交换诊断可查询。
|
||||
14. 无 active coupling region 时不影响 Water/Gas/Explosive/Solid/Shell 既有结果。
|
||||
15. summary CSV 和粒子 CSV 的 coupling 字段可由 gate 检查。
|
||||
16. `STATE_0_8` 或实际 0.8 restart 边界可恢复 coupling 状态并继续显式步。
|
||||
17. 0.7.1 或既有 restart 兼容读入后 coupling 状态安全初始化。
|
||||
18. Fortran API、C ABI、C++ wrapper、Python ctypes 和 CLI inspect 路径可用。
|
||||
19. 0.8.0 coupling 专项 gate、完整 CTest、source size 和 `git diff --check` 通过。
|
||||
20. 文档明确 0.8.0 不交付真实 FEMLite 联合运行、连续体耦合、生产级接触算法或工程级舱段破坏 benchmark。
|
||||
21. 不新增 FEMLite 直接依赖。
|
||||
22. 不修改 SPHLite 文件夹之外的内容。
|
||||
|
||||
## 17. 风险与控制
|
||||
|
||||
| 风险 | 表现 | 控制方式 |
|
||||
|---|---|---|
|
||||
| 0.8.0 范围膨胀 | 试图实现 CouplingModule 或真实 FEMLite 联合运行 | 限定为 SPHLite 侧中立接口和 mock gate |
|
||||
| 接触与连续体耦合混淆 | 0.8.0 把连续体耦合也纳入实现 | `TYPE=CONTACT` 作为唯一启用类型,continuum 只预留错误路径 |
|
||||
| facet 语义不稳 | 自动从体粒子重构复杂表面导致结果不可控 | 只支持 Shell 或显式 surface/facet proxy |
|
||||
| 接口过早固化错误字段 | C ABI 暴露过多未验证物理量 | 只公开中立状态、载荷和诊断字段,Blast 调试字段仍不公开 |
|
||||
| 外部力重复施加 | 多次导入或 stale load 被重复消费 | 引入 coupling step/epoch 和消费状态诊断 |
|
||||
| 运动边界破坏显式稳定性 | direct assignment 导致能量跳变 | 默认 gate 只做受控小模型,并记录做功和误差 |
|
||||
| 与 Blast 外载荷路径冲突 | coupling force 和 blast force 缓存互相覆盖 | 使用独立 coupling 外力缓存,并在总加速度阶段明确叠加 |
|
||||
| restart 不完整 | 读回后导入载荷或累计诊断丢失 | `STATE_0_8` 保存 coupling 持久状态和累计量 |
|
||||
| API 兼容破坏 | 修改既有 C ABI 或 phase/status 常量 | 追加新函数,不改变 0.7.1 接口 |
|
||||
| source size 膨胀 | CouplingInterface 单文件过大 | 按 region/export/import/apply/diagnostics/restart/api 拆分 |
|
||||
|
||||
## 18. 后续版本建议
|
||||
|
||||
0.8.0 完成后,建议后续按以下路线推进:
|
||||
|
||||
1. 0.8.1:真实压力载荷投影、facet 面力分配策略、接触诊断加固和更多 mock 接触小模型。
|
||||
2. 0.8.2:外部驱动示例、C ABI 稳定性加固、Python checker 和 coupling restart 兼容性加固。
|
||||
3. 0.8.x:与外部 CouplingModule 的非默认集成测试,不进入 SPHLite 默认 gate。
|
||||
4. 0.9.0:启动连续体耦合边界,区分 `Solid`-FEM 实体连续体耦合和 `Shell`-FEM 壳连续体耦合。
|
||||
|
||||
## 19. 0.9.0 启动条件
|
||||
|
||||
满足以下条件后,可以启动 0.9.0 连续体耦合版本线:
|
||||
|
||||
1. 0.8.0 coupling region、particle export、facet export、load import 和 motion import gate 稳定。
|
||||
2. C ABI 的 coupling 数据契约被文档和测试锁定。
|
||||
3. 外部载荷和运动边界对 Solid/Shell 小模型响应可重复。
|
||||
4. coupling diagnostics 和 restart 可恢复显式步继续计算。
|
||||
5. 文档明确 0.8.0 仍不是真实 FEMLite 联合运行,也不是连续体耦合版本。
|
||||
6. source size 受控,CouplingInterface 已拆分或有明确例外登记。
|
||||
Reference in New Issue
Block a user