14 KiB
14 KiB
05 接口控制文档
文档状态:0.6.5 版整理稿
1. Fortran API 总则
Fortran API 由 src/base/fem_api.f90 及其子模块提供。接口约定:
- 所有可失败过程返回
ierr。 - 不在公共 API 中直接
stop。 - 调用失败后可通过
fem_get_last_error查询错误码和错误消息。 - 多维数组使用 Fortran 原生列主序。
2. 生命周期接口
subroutine fem_initialize(ierr)
subroutine fem_finalize(ierr)
subroutine fem_get_version(major, minor, patch, ierr)
subroutine fem_get_last_error(code, message, ierr)
3. 输入、构建和求解接口
subroutine fem_read_inp(filename, ierr)
subroutine fem_build_model(ierr)
subroutine fem_compute_lumped_mass(ierr)
subroutine fem_estimate_stable_dt(dtcrit, ierr)
subroutine fem_advance_explicit(dt, ierr)
subroutine fem_solve_static_linear(ierr)
subroutine fem_solve_static_nonlinear(ierr)
subroutine fem_run_implicit_newmark(ierr)
subroutine fem_run_newmark_nonlinear(ierr)
4. 模型与状态查询
subroutine fem_get_model_size(num_nodes, num_elems, num_dof, ierr)
subroutine fem_get_current_time(time, step, ierr)
subroutine fem_get_node_kinematics(node_id, displacement, velocity, acceleration, ierr)
subroutine fem_get_node_reaction(node_id, reaction, ierr)
5. 元素 introspection Fortran API
subroutine fem_get_element_count(num_elems, ierr)
subroutine fem_get_element_metadata(elem_id, type_name, node_count, ierr)
subroutine fem_get_element_nodes(elem_id, max_nodes, node_ids, node_count, ierr)
subroutine fem_get_elem_reference_coords(elem_id, max_nodes, coords, node_count, ierr)
subroutine fem_get_elem_current_coords(elem_id, max_nodes, coords, node_count, ierr)
subroutine fem_get_element_ip_count(elem_id, ip_count, ierr)
subroutine fem_get_element_ip(elem_id, ip_index, natural, weight, ierr)
subroutine fem_get_element_shape(elem_id, ip_index, max_nodes, nshape, dndr, node_count, ierr)
subroutine fem_get_element_jacobian(elem_id, ip_index, jacobian, detj, ierr)
subroutine fem_get_element_bmat_size(elem_id, row_count, col_count, ierr)
subroutine fem_get_element_bmat(elem_id, ip_index, max_rows, max_cols, bmat, row_count, col_count, ierr)
数组形状:
coords(3,max_nodes)。natural(3)。nshape(max_nodes)。dndr(3,max_nodes)。jacobian(3,3)。bmat(max_rows,max_cols)。
6. C ABI
头文件:include/femlite_c_api.h。
常用接口:
int femlite_initialize(void);
int femlite_finalize(void);
int femlite_get_version(int *major, int *minor, int *patch);
int femlite_read_inp(const char *filename);
int femlite_build_model(void);
int femlite_get_model_size(int *num_nodes, int *num_elems, int *num_dof);
元素查询 C API:
int femlite_get_element_count(int *num_elems);
int femlite_get_element_metadata(int elem_id, char *type_name,
int type_capacity, int *node_count);
int femlite_get_element_nodes(int elem_id, int max_nodes,
int *node_ids, int *node_count);
int femlite_get_element_reference_coords(int elem_id, int max_nodes,
double *coords, int *node_count);
int femlite_get_element_current_coords(int elem_id, int max_nodes,
double *coords, int *node_count);
int femlite_get_element_integration_count(int elem_id, int *ip_count);
int femlite_get_element_integration_point(int elem_id, int ip_index,
double *natural, double *weight);
int femlite_get_element_shape(int elem_id, int ip_index, int max_nodes,
double *nshape, double *dndr, int *node_count);
int femlite_get_element_jacobian(int elem_id, int ip_index,
double *jacobian, double *detj);
int femlite_get_element_b_matrix_size(int elem_id,
int *row_count, int *col_count);
int femlite_get_element_b_matrix(int elem_id, int ip_index,
int max_rows, int max_cols, double *bmat,
int *row_count, int *col_count);
C 数组使用 Fortran 顺序展开:
coords[dim + 3 * node]。dndr[dim + 3 * node]。jacobian[row + 3 * col]。bmat[row + row_count * col]。
无效 C 参数返回 -1;Fortran 侧校验错误返回 FemLite ierr。
7. Coupling API
阶段 A 提供中立 coupling wrapper,复用已有 boundary facet 和外部载荷实现。旧 sph 命名接口保留兼容。
Fortran API:
subroutine fem_get_coupling_surface_count(num_facets, max_face_nodes, ierr)
subroutine fem_get_coupling_surface_facets(nfacet_in, max_face_nodes_in, &
facet_id, elem_id, face_id, &
facet_nnode, facet_conn, x, vnod, &
normal, area, ierr)
subroutine fem_clear_coupling_loads(ierr)
subroutine fem_apply_coupling_nodal_forces(num_loads, node_ids, forces, &
source_ids, load_mode, &
valid_flags, ierr)
subroutine fem_get_coupling_load_diag(total_force, total_moment, &
accepted_count, rejected_nonfinite, &
rejected_unknown_node, &
rejected_capacity, ierr)
C ABI:
int femlite_get_coupling_surface_count(int *num_facets, int *max_face_nodes);
int femlite_get_coupling_surface_facets(int num_facets, int max_face_nodes,
int *facet_id, int *elem_id,
int *face_id, int *facet_nnode,
int *facet_conn, double *x,
double *vnod, double *normal,
double *area);
int femlite_clear_coupling_loads(void);
int femlite_apply_coupling_nodal_forces(int num_loads, const int *node_ids,
const double *forces,
const int *source_ids,
const int *load_mode,
const int *valid_flags);
int femlite_get_coupling_load_diagnostics(double *total_force,
double *total_moment,
int *accepted_count,
int *rejected_nonfinite,
int *rejected_unknown_node,
int *rejected_capacity);
int femlite_get_coupling_source_load_diagnostics(int source_id,
double *total_force,
double *total_moment,
int *accepted_count);
int femlite_write_coupling_reports(const char *load_report,
const char *surface_report);
int femlite_get_coupling_surface_count_for_name(const char *surface_name,
int *num_facets,
int *max_face_nodes);
int femlite_get_coupling_surface_facets_ex(int num_facets,
int max_face_nodes,
int *facet_id,
int *surface_id,
int *elem_id,
int *face_id,
int *facet_nnode,
int *facet_conn,
double *x,
double *vnod,
double *normal,
double *area,
int *material_id,
int *section_id,
int *valid_flags,
double *shell_thickness,
double *mass_per_area);
int femlite_get_coupling_surface_facets_ex_for_name(
const char *surface_name,
int num_facets,
int max_face_nodes,
int *facet_id,
int *surface_id,
int *elem_id,
int *face_id,
int *facet_nnode,
int *facet_conn,
double *x,
double *vnod,
double *normal,
double *area,
int *material_id,
int *section_id,
int *valid_flags,
double *shell_thickness,
double *mass_per_area);
阶段 A 约定:
- 未指定 surface 时导出全部边界 facet,
surface_id=0,并写 warning。 surface_name过滤支持已有*SURFACE, NAME=..., TYPE=ELEMENT。facet_conn使用外部节点 id。x[dim + 3 * (local_node + max_face_nodes * facet)]。vnod[dim + 3 * (local_node + max_face_nodes * facet)]。normal[dim + 3 * facet]。forces[dim + 3 * load]。valid_flags=0的节点力记录会被跳过。- 非有限载荷、未知节点和负 metadata 会被拒绝并记录诊断计数。
- 扩展 surface 导出中,
valid_flags=1表示 facet 几何有效,0表示退化或未分类无效。 - 壳单元导出
shell_thickness和mass_per_area;实体面二者返回0。
7.1 Coupling 载荷诊断报告
- coupling 节点力导入后维护独立诊断缓存,缓存不作为公共全局力数组暴露。
femlite_clear_coupling_loads同时清空本步外部载荷和诊断缓存,worker 在每个IMPORT_LOADS步骤前调用。femlite_get_coupling_source_load_diagnostics按source_id查询本步接受记录数、总力和总力矩。femlite_write_coupling_reports写出逐记录载荷表和按 source 汇总表。当前surface_report参数名用于后续 surface/source 映射扩展,现阶段按source_id汇总。- worker mock 在
WRITE_OUTPUT时默认输出femlite_cclite_load_report.csv和femlite_cclite_surface_report.csv,并与 VTU/PVD 输出同目录保存。
8. CCLite Worker Mock
阶段 B 提供 worker mock 模式,用于验证 FemLite 侧命令状态机和空耦合闭环。该模式不是真实 Windows IPC,不打开 shared memory,也不等待 named event。
CLI:
femlite --cclite-worker --case input.inp --ipc-name mock `
--log worker_mock.log --output-dir worker_output --mock-steps 100
命令序列:
INIT
READ_INPUT
BUILD_MODEL
EXPORT_INTERFACE
IMPORT_LOADS
ADVANCE
WRITE_OUTPUT
STOP
worker 日志字段:
seq,ack_seq,command_id,step_id,substep_id,iteration_id,state,error_code
状态约定:
0:CREATED。1:READY。2:RUNNING。3:DONE。-1:ERROR。
当前边界:
- mock 模式内部顺序执行命令,不接收外部 IPC command block。
IMPORT_LOADS当前导入空载荷,用于空耦合 smoke。ADVANCE使用单步显式推进。WRITE_OUTPUT调用现有 CSV 与 VTU/PVD 输出路径。
9. CCLite Windows IPC Worker
阶段 C 提供 Windows IPC adapter 的 C 层边界。0.6.5 起主程序 worker 已接入真实 Windows IPC 后端,可由外部驱动创建 shared memory、named event 和 data block 后启动 femlite --cclite-worker --worker-backend ipc,完成 READY、INIT 到 STOP、空载荷推进和超时/异常退出闭环。
C 头文件:
#include "femlite_cclite_ipc.h"
command block 二进制布局:
typedef struct femlite_cclite_command_block {
int32_t version;
int32_t seq;
int32_t ack_seq;
int32_t command_id;
int32_t step_id;
int32_t substep_id;
int32_t iteration_id;
int32_t worker_state;
int32_t error_code;
char error_message[128];
} femlite_cclite_command_block;
命名规则:
<prefix>_COMMAND_BLOCK
<prefix>_COMMAND_EVENT
<prefix>_DONE_EVENT
adapter 约定:
- FemLite 只 open CCLite 创建的 shared memory 和 event。
- FemLite 可以 wait
COMMAND_EVENT、读取 command block、写回ack_seq/worker_state/error_code并 signalDONE_EVENT。 - FemLite 不 reset event;reset 责任属于 CCLite 侧。
- timeout 使用稳定错误码
FEMLITE_CCL_IPC_ERR_TIMEOUT。 - 当前 smoke 覆盖 open、wait/signal、不 reset event、INIT/STOP、错误路径、真实进程 1 step/100 step 空耦合和 timeout。
femlite_cclite_transport提供 mock 和 Windows IPC 两个 backend 的统一receive/completefacade。
data block 命名规则:
<data-prefix>_FEM_TO_CCL_FACET
<data-prefix>_CCL_TO_FEM_LOAD
data block 采用 AOR_V1 布局:
- header 字段包含
magic、version、layout、record_type、record_capacity、record_count、record_stride、status_code、error_code和短错误消息。 FEM_TO_CCL_FACET记录包含 facet id、surface id、element/face id、节点列表、节点位置、节点速度、法向、面积、材料/截面 id、body_id=0占位、valid flags、壳厚度和面密度。CCL_TO_FEM_LOAD记录包含 record id、step id、node id、source id、load mode、distribution mode、valid flags、节点力和预留力矩字段。- 容量不足、版本不匹配或 record stride 不匹配会返回错误,不静默截断。
- 当前中立 data block 已支持 facet 导出和节点力导入;facet pressure、moment 和 kinematic boundary 仍是后续能力。
10. 输出接口
subroutine fem_set_output_directory(path, ierr)
subroutine fem_set_output_interval(interval, ierr)
subroutine fem_write_output(step, time, ierr)
subroutine fem_write_restart(filename, ierr)
subroutine fem_read_restart(filename, ierr)
输出目录应自动创建。输出文件不属于源码交付物。