349 lines
14 KiB
Markdown
349 lines
14 KiB
Markdown
# 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)
|
||
```
|
||
|
||
输出目录应自动创建。输出文件不属于源码交付物。
|