Release FemLite 0.6.4
FemLite CI / build-test (push) Has been cancelled

This commit is contained in:
shenw
2026-07-05 17:23:34 +08:00
parent 3d009d021e
commit 0440ed5a64
93 changed files with 5116 additions and 282 deletions
+203 -2
View File
@@ -1,6 +1,6 @@
# 05 接口控制文档
文档状态:0.6.3 版整理稿
文档状态:0.6.4 版整理稿
## 1. Fortran API 总则
@@ -118,7 +118,208 @@ C 数组使用 Fortran 顺序展开:
无效 C 参数返回 `-1`;Fortran 侧校验错误返回 FemLite `ierr`。
## 7. 输出接口
## 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
<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、错误路径和 100 step 空耦合。
- `femlite_cclite_transport` 提供 mock 和 Windows IPC 两个 backend 的统一 `receive/complete` facade。
## 10. 输出接口
```fortran
subroutine fem_set_output_directory(path, ierr)