Files
FemLite/docs/05_interface_control_document.md
T
shenw 3d009d021e
FemLite CI / build-test (push) Has been cancelled
Release FemLite 0.6.3
2026-07-02 12:40:31 +08:00

132 lines
4.7 KiB
Markdown
Raw 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.3 版整理稿
## 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. 输出接口
```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)
```
输出目录应自动创建。输出文件不属于源码交付物。