# 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_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 当前稳定 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 版本兼容策略。