14 KiB
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_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 常量:
#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 使用中立命名,必须支持每步交换。
0.8.1/0.8.2 当前稳定 C ABI 清单:
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:
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 保持一致。
建议最小用法:
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 版本兼容策略。