Files
FemLite/docs/05_interface_control_document.md
shenw a2126f360c
FemLite CI / build-test (push) Has been cancelled
Release 0.6.5 real IPC worker
2026-07-05 21:09:37 +08:00

349 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 05 接口控制文档
文档状态:0.6.5 版整理稿
## 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 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 头文件:
```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;
char error_message[128];
} femlite_cclite_command_block;
```
命名规则:
```text
<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 命名规则:
```text
<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. 输出接口
```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)
```
输出目录应自动创建。输出文件不属于源码交付物。