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

9.5 KiB
Raw Blame History

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 风格:

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:

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:

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 常量:

#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:

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:

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。为调试和测试可保留起爆点设置接口:

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:

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 保持一致。

建议最小用法:

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 版本兼容策略。