Files
SPHLite/docs/05_interface_control_document.md
2026-07-05 21:41:34 +08:00

348 lines
14 KiB
Markdown
Raw Permalink 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.
# 05 接口控制文档
文档状态:规划确认稿
## 1. 接口原则
SPHLite 算法核心使用 Fortran 95 实现,包括求解器、粒子/单元语义、材料和物理模块;worker、CLI、IPC 等外围集成层及其测试/工具性 Fortran 代码可放宽到 Fortran 2018。公共接口分层如下:
- Fortran API:核心主接口,由 Fortran 模块提供。
- C ABI:长期稳定公共接口,统一使用 `sphlite_` 前缀。
- C++ API:薄包装 C ABI,不重新定义物理语义。
- Python API:优先使用 `ctypes` 包装 C ABI。
- CLI:命令行入口,语法风格与 FEMLite 保持一致。
所有可失败接口必须返回错误码。调用失败后应能查询最近错误码和错误消息。
C ABI 第一阶段只支持 host 内存指针,不设计 GPU 内存接口。多维数组按 Fortran 顺序展平到 C 缓冲区。
## 2. 错误和生命周期接口
生命周期接口沿用 FEMLite 风格:
```c
int sphlite_initialize(void);
int sphlite_finalize(void);
int sphlite_get_version(int *major, int *minor, int *patch);
int sphlite_get_last_error(int *code, char *message, int message_capacity);
```
错误约定:
- C 参数错误,如空指针、非正容量或非法数组尺寸,返回 `-1`。
- 输入、物理模型、求解流程或数据库校验错误返回 SPHLite 错误码。
- 错误消息由 `sphlite_get_last_error` 查询。
- 不支持且影响继续计算的能力必须报 error。
- 不影响程序运行的未支持输入项可 warning 后跳过。
## 3. 输入、构建和显式求解接口
SPHLite 只提供显式动力学接口,不提供 static、implicit 或 nonlinear static 接口。
建议 C ABI:
```c
int sphlite_read_inp(const char *filename);
int sphlite_build_model(void);
int sphlite_estimate_stable_dt(double *dtcrit);
int sphlite_advance_explicit(double dt);
int sphlite_run_explicit(void);
int sphlite_get_current_time(double *time, int *step);
```
接口语义:
- `sphlite_read_inp` 读取 Abaqus `.inp` 支持子集和 `*SPHLITE ...` 扩展关键词。
- `sphlite_build_model` 校验数据库,构建运行时 region、邻域搜索参数、section/material 映射等派生数据。
- `sphlite_estimate_stable_dt` 返回当前状态下的显式稳定时间步估计。
- `sphlite_advance_explicit` 执行一个 Velocity-Verlet 显式步,供外部耦合模块逐步驱动。
- `sphlite_run_explicit` 按输入文件时间控制连续运行。
## 4. 输出和 Restart 接口
建议 C ABI:
```c
int sphlite_set_output_directory(const char *path);
int sphlite_set_output_interval(int interval);
int sphlite_write_output(int step, double time);
int sphlite_write_csv(const char *filename);
int sphlite_write_vtu(const char *filename);
int sphlite_write_restart(const char *filename);
int sphlite_read_restart(const char *filename);
```
restart 应保存完整模块级状态,包括粒子通用状态、Velocity-Verlet 所需速度/加速度/半步速度、水相、气相、炸药、Solid、Shell、诊断和耦合历史状态。
输出接口只控制输出行为,不应改变求解物理状态。`sphlite_write_output` 当前写出 CSV、summary CSV、VTU 和 PVD;`sphlite_write_csv` 与 `sphlite_write_vtu` 可作为直接格式输出入口。
## 5. Phase 和 Status 常量
C 头文件应暴露 phase/status 常量,便于 C++、Python、外部耦合模块和后处理工具解释粒子状态。
建议 phase 常量:
```c
#define SPHLITE_PHASE_WATER 1
#define SPHLITE_PHASE_GAS 2
#define SPHLITE_PHASE_EXPLOSIVE 3
#define SPHLITE_PHASE_SOLID 4
#define SPHLITE_PHASE_SHELL 5
#define SPHLITE_PHASE_BOUNDARY 6
#define SPHLITE_PHASE_COUPLING 7
#define SPHLITE_PHASE_SOLID_FAILED 8
#define SPHLITE_PHASE_SHELL_FAILED 9
```
具体整数值可在实现前最终锁定,但文档、C 头文件、Fortran 常量和 Python 包装必须保持一致。
## 6. 粒子查询接口
粒子查询采用 dimension query + caller-allocated buffer 风格。
建议 C ABI:
```c
int sphlite_get_particle_count(int *count);
int sphlite_get_particle_state(int max_particles,
int *particle_id_ext,
int *phase,
int *status,
int *material_id,
int *section_id,
double *x,
double *v,
double *a,
double *rho,
double *pressure,
double *internal_energy,
double *temperature,
double *h,
int *count);
```
数组展开顺序:
- `x[dim + 3 * particle]`
- `v[dim + 3 * particle]`
- `a[dim + 3 * particle]`
其中 `dim = 0,1,2`,`particle = 0 .. count-1`。该顺序对应 Fortran 数组 `x(3,npart)` 的列主序展开。
## 7. Gas 和爆炸诊断接口
Gas 诊断接口应体现气泡只是 Gas 在水介质中的现象和诊断分支。
建议 C ABI:
```c
int sphlite_get_gas_summary(double *volume,
double *center,
double *mean_pressure,
double *max_pressure);
int sphlite_get_gas_bubble_metrics(double *equivalent_radius,
double *radius_rate,
double *center);
```
`center` 使用三维向量缓冲区,展开为:
- `center[dim]`
Explosive 的主输入来自 `.inp`。为调试和测试可保留起爆点设置接口:
```c
int sphlite_set_ignition_point(double x, double y, double z, double time);
```
该接口不替代 `.inp` 输入语义,主要用于单元测试、Python 调试和小型 smoke。
## 8. CouplingInterface 接口
SPHLite 不直接依赖 FEMLite,也不依赖外部 CouplingModule。C ABI 中不得出现 `fem` 命名或 FEMLite 内部数据结构。
CouplingInterface 使用中立命名,必须支持每步交换。
0.8.1/0.8.2/0.8.3 当前稳定 C ABI 清单:
```c
int sphlite_coupling_get_region_count(int *count);
int sphlite_coupling_get_region_info(int region_index, char *name,
int name_capacity, int *region_type,
int *export_mode, int *import_mode,
int *enabled, int *particle_count,
int *facet_count);
int sphlite_coupling_get_region_modes(int region_index, int *load_mode,
int *distribution_mode,
int *contact_state_mode);
int sphlite_coupling_export_particles(int region_index, int capacity,
int *count, int *ext_ids,
int *internal_indices, int *phases,
int *statuses, int *materials,
int *sections, double *scalar_values,
double *vector_values);
int sphlite_coupling_export_facets(int region_index, int capacity,
int *count, int *facet_ids,
int *particle_ids, int *materials,
int *sections, double *vector_values,
double *area_values);
int sphlite_coupling_apply_particle_forces(int region_index,
int force_count,
const int *export_indices,
const double *forces);
int sphlite_coupling_apply_facet_pressures(int region_index, int load_count,
const int *facet_ids,
const double *pressures,
int distribution_mode,
int coupling_step);
int sphlite_coupling_apply_facet_tractions(int region_index, int load_count,
const int *facet_ids,
const double *tractions,
int distribution_mode,
int coupling_step);
int sphlite_coupling_apply_facet_resultants(int region_index, int load_count,
const int *facet_ids,
const double *resultants,
int distribution_mode,
int coupling_step);
int sphlite_coupling_apply_contact_state(int region_index, int contact_count,
const int *facet_ids,
const double *normals,
const double *gaps,
const double *penetrations,
const double *contact_pressures,
int coupling_step);
int sphlite_coupling_apply_motion_boundary(int region_index, int export_index,
int target_kind, int mode,
const double *target);
int sphlite_coupling_get_load_balance(double *input_force,
double *distributed_force,
double *force_error,
double *input_moment,
double *distributed_moment,
double *moment_error);
int sphlite_coupling_get_contact_diagnostics(int *counts, int count_capacity,
double *values,
int value_capacity);
int sphlite_coupling_get_diagnostics(double *values, int value_capacity,
int *counts, int count_capacity);
```
建议 C ABI:
```c
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 *material_id,
int *section_id,
double *x,
double *v,
double *pressure,
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 *x,
double *v,
double *normal,
double *area);
int sphlite_apply_coupling_particle_forces(int num_particles,
const int *particle_id_ext,
const double *forces);
int sphlite_apply_coupling_facet_loads(int num_facets,
int max_face_particles,
const int *facet_id,
const int *facet_npart,
const double *particle_forces);
```
数组展开顺序:
- `x[dim + 3 * particle]` for particle arrays。
- `forces[dim + 3 * particle]`。
- `facet_particles[local + max_face_particles * facet]`。
- `particle_forces[dim + 3 * (local + max_face_particles * facet)]`。
- `normal[dim + 3 * facet]`。
接口语义:
- `region` 为 SPHLite 侧 coupling region 名称。
- 外部耦合模块负责 FEM-SPH 匹配、投影和强/弱耦合控制策略。
- SPHLite 只导出状态和边界近似,导入外部载荷或约束。
- 接触耦合和连续体耦合应在 region 或后续接口参数中区分。
## 9. Fortran API 和 C ABI 关系
Fortran API 是核心语义来源。C ABI 只做薄包装:
- 不改变 Fortran API 的物理含义。
- 不暴露 Fortran 内部 allocatable 数组指针。
- 所有输出数组由调用方分配。
- C wrapper 负责空指针、容量和字符串长度检查。
- Fortran 侧负责物理校验、数据库校验和错误消息。
### 9.1 0.7.0 局部爆炸调试接口边界
0.7.0 的局部爆炸诊断先作为 Fortran API 和 CSV 调试输出提供,不进入公开 C ABI、C++ wrapper 或 Python `ctypes` 稳定接口。原因是局部爆炸载荷投影、Shell 外载荷闭环、restart 状态和后续 CouplingModule 交互语义尚未冻结,过早暴露 C ABI 会把调试字段固化为长期契约。
0.7.0 也不写入正式 `STATE_0_7` restart。局部爆炸控制和诊断在该版本属于可重建的调试状态;restart 继续保持既有 `STATE_0_5_1` 边界,后续版本再决定是否新增正式 blast state。
字符串从 C 传入 Fortran 时应按 FEMLite 风格传递字符缓冲区和长度,避免依赖编译器私有字符串 ABI。
## 10. C++ 和 Python 接口
C++ API 是 C ABI 的薄包装,主要提供 RAII 生命周期管理和类型更友好的调用封装,不维护独立物理语义。
Python API 第一阶段使用 `ctypes` 包装 C ABI,用于:
- 调试。
- 示例生成和运行。
- smoke/checker。
- 后处理和诊断读取。
Python API 不应成为唯一可用入口;CLI 和 C ABI 必须保持完整可用。
## 11. CLI 接口原则
命令行程序 `sphlite` 作为一等入口,语法风格与 FEMLite 保持一致。
建议最小用法:
```powershell
sphlite model.inp --run
```
后续可扩展:
- 输出目录参数。
- restart 读写参数。
- 只检查输入/模型的 inspect 模式。
- 调试诊断开关。
CLI 内部应调用 Fortran API 或 C ABI 等稳定入口,不绕过公共生命周期和错误处理。
## 12. 待讨论问题
- 第一批 `*SPHLITE ...` 扩展关键词与 C API 字段的对应关系。
- phase/status 具体整数值和头文件宏名是否在 0.1 锁定。
- coupling region 的字符串命名规则。
- facet 近似生成方式和 facet id 稳定性。
- restart 文件格式和 C API 版本兼容策略。