Files
SPHLite/docs/05_interface_control_document.md
T
2026-07-02 18:47:38 +08:00

275 lines
9.5 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.
# 05 接口控制文档
文档状态:规划确认稿
## 1. 接口原则
SPHLite 核心使用 Fortran 95 实现。公共接口分层如下:
- 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_restart(const char *filename);
int sphlite_read_restart(const char *filename);
```
restart 应保存完整模块级状态,包括粒子通用状态、Velocity-Verlet 所需速度/加速度/半步速度、水相、气相、炸药、Solid、Shell、诊断和耦合历史状态。
输出接口只控制输出行为,不应改变求解物理状态。
## 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 使用中立命名,必须支持每步交换。
建议 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 侧负责物理校验、数据库校验和错误消息。
字符串从 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 版本兼容策略。