Files
CCLite/FEMLite/docs/05_interface_control_document.md
2026-07-05 22:48:27 +08:00

14 KiB
Raw Permalink Blame History

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 并 signal DONE_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/complete facade。

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)

输出目录应自动创建。输出文件不属于源码交付物。