Files
SPHLite/docs/v8.0_development_plan.md
T
2026-07-04 08:22:21 +08:00

763 lines
34 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.
# 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 已拆分或有明确例外登记。