281 lines
10 KiB
Markdown
281 lines
10 KiB
Markdown
# 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 侧负责物理校验、数据库校验和错误消息。
|
||
|
||
### 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 版本兼容策略。
|