# 05 接口控制文档 文档状态:0.6.4 版整理稿 ## 1. Fortran API 总则 Fortran API 由 `src/base/fem_api.f90` 及其子模块提供。接口约定: - 所有可失败过程返回 `ierr`。 - 不在公共 API 中直接 `stop`。 - 调用失败后可通过 `fem_get_last_error` 查询错误码和错误消息。 - 多维数组使用 Fortran 原生列主序。 ## 2. 生命周期接口 ```fortran 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. 输入、构建和求解接口 ```fortran 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. 模型与状态查询 ```fortran 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 ```fortran 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`。 常用接口: ```c 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: ```c 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: ```fortran 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: ```c 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: ```powershell femlite --cclite-worker --case input.inp --ipc-name mock ` --log worker_mock.log --output-dir worker_output --mock-steps 100 ``` 命令序列: ```text INIT READ_INPUT BUILD_MODEL EXPORT_INTERFACE IMPORT_LOADS ADVANCE WRITE_OUTPUT STOP ``` worker 日志字段: ```text 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 Adapter 阶段 C 提供 Windows IPC adapter 的 C 层边界,供后续真实 CCLite worker 接入。当前 adapter 已有 shared memory、named event、command block 读写和 smoke,不等同于主程序已经完成跨进程 worker 联调。 C 头文件: ```c #include "femlite_cclite_ipc.h" ``` command block 二进制布局: ```c 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; } femlite_cclite_command_block; ``` 命名规则: ```text _COMMAND_BLOCK _COMMAND_EVENT _DONE_EVENT ``` adapter 约定: - FemLite 只 open CCLite 创建的 shared memory 和 event。 - FemLite 可以 wait `COMMAND_EVENT`、读取 command block、写回 `ack_seq`/`worker_state`/`error_code` 并 signal `DONE_EVENT`。 - FemLite 不 reset event;reset 责任属于 CCLite 侧。 - timeout 使用稳定错误码 `FEMLITE_CCL_IPC_ERR_TIMEOUT`。 - 当前 smoke 覆盖 open、wait/signal、不 reset event、INIT/STOP、错误路径和 100 step 空耦合。 - `femlite_cclite_transport` 提供 mock 和 Windows IPC 两个 backend 的统一 `receive/complete` facade。 ## 10. 输出接口 ```fortran 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) ``` 输出目录应自动创建。输出文件不属于源码交付物。