From d2dc7ab6898ed7f0d4f7d0cb8150b2610611c74f Mon Sep 17 00:00:00 2001 From: shenw Date: Thu, 25 Jun 2026 09:07:54 +0800 Subject: [PATCH] Add convergence status diagnostics --- docs/05_interface_control_document.md | 10 ++++++ docs/06_test_and_verification_plan.md | 2 ++ docs/v4_development_plan.md | 24 ++++++++++++++ include/femlite_c_api.h | 5 +++ src/base/fem_api.f90 | 48 +++++++++++++++++++++++++++ src/base/fem_control.f90 | 10 ++++++ src/interface/fem_c_api.c | 23 +++++++++++++ src/interface/fem_fortran_bridge.f90 | 22 ++++++++++++ src/solver/fem_solver_implicit.f90 | 25 +++++++++++--- tests/interface/test_c_api.c | 14 ++++++++ tests/module/test_implicit_inp.f90 | 28 ++++++++++++++++ 11 files changed, 207 insertions(+), 4 deletions(-) diff --git a/docs/05_interface_control_document.md b/docs/05_interface_control_document.md index 88a9f6d..2b6d1d5 100644 --- a/docs/05_interface_control_document.md +++ b/docs/05_interface_control_document.md @@ -545,6 +545,15 @@ subroutine fem_get_convergence_status(increment, iteration, residual_norm, & end subroutine ``` +说明: + +- `increment` 为最近一次静力/隐式求解尝试的实际步号或增量号。 +- `iteration` 为该增量内最近一次 Newton 迭代号;求解尚未开始时为 0。 +- `residual_norm` 为最近一次力残差范数。 +- `correction_norm` 为最近一次位移修正范数;线性路径或尚未形成修正时为 0。 +- `converged` 表示最近一次记录的增量是否已满足收敛准则。 +- V4.5 起,非线性静力 Newton 迭代会实时更新该状态;后续 cutback 和多准则收敛诊断沿用同一查询口径。 + ### 12.6 接触状态 第三版提供接触结果查询接口: @@ -904,4 +913,5 @@ fem_finalize - C ABI 追加 `femlite_get_contact_search_stats`,返回 contact pair 搜索 facet/master/candidate/active/BVH 节点统计。 - C ABI 追加 `femlite_get_contact_perf_stats`,返回 contact search/force/tangent CPU 时间统计。 - C ABI 追加 `femlite_get_contact_cache_stats`,返回 BVH 候选缓存使用和溢出统计。 +- C ABI 暴露 `femlite_get_convergence_status`,其中 `converged` 使用 `int` 返回 0/1。 - 上述函数只追加新符号,不改变 `femlite_get_contact_summary` 的签名和含义。 diff --git a/docs/06_test_and_verification_plan.md b/docs/06_test_and_verification_plan.md index 6cbee2b..dc326b0 100644 --- a/docs/06_test_and_verification_plan.md +++ b/docs/06_test_and_verification_plan.md @@ -251,6 +251,7 @@ SPH总力映射测试 relative tolerance 1.0e-10 to 1.0e-8 - 线性静力实体 patch test。 - 线性静力壳 patch test。 - 非线性静力 Newton 收敛。 +- 非线性静力收敛状态查询,检查最新增量、迭代号、残差范数、修正范数和收敛标志。 - 非线性静力步长缩减。 - 非线性静力线搜索和失败回滚测试。 - 隐式 Newmark 单步预测校正。 @@ -297,6 +298,7 @@ SPH总力映射测试 relative tolerance 1.0e-10 to 1.0e-8 - `fem_get_contact_search_stats` 和 C ABI `femlite_get_contact_search_stats` 返回 contact pair 搜索 facet/master/candidate/active/BVH 节点统计。 - `fem_get_contact_perf_stats` 和 C ABI `femlite_get_contact_perf_stats` 返回 contact search/force/tangent CPU 时间统计。 - `fem_get_contact_cache_stats` 和 C ABI `femlite_get_contact_cache_stats` 返回 BVH 候选缓存使用和溢出统计。 +- `fem_get_convergence_status` 和 C ABI `femlite_get_convergence_status` 返回最近一次求解的增量、迭代、残差、修正范数和收敛标志;空模型零状态和非线性静力收敛状态均需覆盖。 - 删除单元状态可输出。 示例结果留存策略: diff --git a/docs/v4_development_plan.md b/docs/v4_development_plan.md index b2ac627..1af113a 100644 --- a/docs/v4_development_plan.md +++ b/docs/v4_development_plan.md @@ -772,3 +772,27 @@ FemLite 0.4.x 定位为: - 评估按 slave facet 的线程私有力增量和历史提交边界,进一步缩短 force 路径全局提交临界区。 - 补充更大规模 OpenMP 性能测试,继续评估分块 CSR 累加或线程私有增量合并。 + +## 26. 0.4.5 开发记录 + +### V4.5 隐式非线性收敛诊断起步 + +完成状态:V4.5 起步,新增求解收敛状态查询底座;完整自适应步长、多准则收敛和失败诊断仍继续推进。 + +已完成: + +- `fem_control` 新增最近一次收敛状态快照,记录增量号、Newton 迭代号、力残差范数、位移修正范数和收敛标志。 +- 非线性静力 Newton 迭代在每次残差评估后更新收敛状态,修正方程求解后同步记录位移修正范数。 +- 新增 Fortran API `fem_get_convergence_status`,补齐接口文档中第三版已承诺的静力/隐式收敛状态查询。 +- C ABI 新增 `femlite_get_convergence_status`,以 `int` 形式返回 `converged` 的 0/1 状态。 + +已补充测试: + +- `implicit_inp` 回归在非线性静力弹性算例后查询收敛状态,检查最后增量已收敛、残差在容限内并且迭代号有效。 +- `c_api` 回归检查初始化和建模后、尚未求解时的收敛状态为零值且未收敛。 + +后续: + +- 将非线性 Newmark Newton 的修正范数和失败状态接入同一查询口径。 +- 在 cutback 失败路径中补充失败原因、cutback 次数和最后有效时间步诊断。 +- 将 contact gap/mortar residual 纳入 V4.5 多准则收敛统计。 diff --git a/include/femlite_c_api.h b/include/femlite_c_api.h index 37c5ac4..0141834 100644 --- a/include/femlite_c_api.h +++ b/include/femlite_c_api.h @@ -17,6 +17,11 @@ int femlite_estimate_stable_dt(double *dtcrit); int femlite_advance_explicit(double dt); int femlite_get_current_time(double *time, int *step); int femlite_get_model_size(int *num_nodes, int *num_elems, int *num_dof); +int femlite_get_convergence_status(int *increment, + int *iteration, + double *residual_norm, + double *correction_norm, + int *converged); int femlite_get_contact_summary(int *active_count, double *work_step, double *work_total, diff --git a/src/base/fem_api.f90 b/src/base/fem_api.f90 index 2916a31..d1a4cc2 100644 --- a/src/base/fem_api.f90 +++ b/src/base/fem_api.f90 @@ -493,6 +493,50 @@ contains ierr = FEM_SUCCESS end subroutine fem_get_contact_cache_stats + subroutine fem_record_convergence(increment, iteration, residual_norm, & + correction_norm, converged) + integer, intent(in) :: increment + integer, intent(in) :: iteration + real(rk), intent(in) :: residual_norm + real(rk), intent(in) :: correction_norm + logical, intent(in) :: converged + + convergence_increment = increment + convergence_iteration = iteration + convergence_residual_norm = residual_norm + convergence_correction_norm = correction_norm + convergence_converged = converged + end subroutine fem_record_convergence + + subroutine fem_get_convergence_status(increment, iteration, residual_norm, & + correction_norm, converged, ierr) + integer, intent(out) :: increment + integer, intent(out) :: iteration + real(rk), intent(out) :: residual_norm + real(rk), intent(out) :: correction_norm + logical, intent(out) :: converged + integer, intent(out) :: ierr + + increment = 0 + iteration = 0 + residual_norm = ZERO + correction_norm = ZERO + converged = .false. + + if (.not. api_initialized) then + call error_set(FEM_ERR_INTERNAL, & + 'fem_get_convergence_status called before fem_initialize', ierr) + return + end if + + increment = convergence_increment + iteration = convergence_iteration + residual_norm = convergence_residual_norm + correction_norm = convergence_correction_norm + converged = convergence_converged + ierr = FEM_SUCCESS + end subroutine fem_get_convergence_status + subroutine fem_get_boundary_facet_count(num_facets, max_face_nodes, ierr) integer, intent(out) :: num_facets integer, intent(out) :: max_face_nodes @@ -1236,6 +1280,7 @@ contains call implicit_solve_linear_static(current_time, max_iter, tol, iter, res_norm, ierr) if (ierr .ne. FEM_SUCCESS) return + call fem_record_convergence(current_step + 1, iter, res_norm, ZERO, .true.) current_step = current_step + 1 call log_info('implicit linear solve completed') end subroutine fem_solve_implicit_linear @@ -1260,6 +1305,7 @@ contains call implicit_solve_linear_static(solve_time, max_iter, tol, iter, res_norm, ierr) if (ierr .ne. FEM_SUCCESS) return + call fem_record_convergence(current_step + 1, iter, res_norm, ZERO, .true.) call element_compute_internal_force(ierr, ZERO) if (ierr .ne. FEM_SUCCESS) return @@ -1324,6 +1370,7 @@ contains max_iter, tol, iter, res_norm, ierr) if (ierr .ne. FEM_SUCCESS) return + call fem_record_convergence(current_step + 1, iter, res_norm, ZERO, .true.) current_step = current_step + 1 current_time = current_time + dt call log_info('implicit Newmark step completed') @@ -1361,6 +1408,7 @@ contains max_iter, tol, iter, res_norm, ierr) if (ierr .ne. FEM_SUCCESS) return + call fem_record_convergence(current_step + 1, iter, res_norm, ZERO, .true.) current_step = current_step + 1 current_time = current_time + dt call log_info('nonlinear Newmark step completed') diff --git a/src/base/fem_control.f90 b/src/base/fem_control.f90 index 3e17149..857ddf9 100644 --- a/src/base/fem_control.f90 +++ b/src/base/fem_control.f90 @@ -34,6 +34,11 @@ module fem_control integer :: max_newton_iter = 25 integer :: max_cutback = 8 integer :: output_interval = 1 + integer :: convergence_increment = 0 + integer :: convergence_iteration = 0 + real(rk) :: convergence_residual_norm = ZERO + real(rk) :: convergence_correction_norm = ZERO + logical :: convergence_converged = .false. logical :: use_sph_coupling = .false. logical :: use_user_dt = .false. logical :: large_deformation = .true. @@ -70,6 +75,11 @@ contains max_newton_iter = 25 max_cutback = 8 output_interval = 1 + convergence_increment = 0 + convergence_iteration = 0 + convergence_residual_norm = ZERO + convergence_correction_norm = ZERO + convergence_converged = .false. use_sph_coupling = .false. use_user_dt = .false. large_deformation = .true. diff --git a/src/interface/fem_c_api.c b/src/interface/fem_c_api.c index 42207c1..dc49931 100644 --- a/src/interface/fem_c_api.c +++ b/src/interface/fem_c_api.c @@ -20,6 +20,7 @@ #define F_ADVANCE_EXPLICIT FC_GLOBAL(femlite_f_advance_explicit, FEMLITE_F_ADVANCE_EXPLICIT) #define F_GET_TIME FC_GLOBAL(femlite_f_get_time, FEMLITE_F_GET_TIME) #define F_GET_SIZE FC_GLOBAL(femlite_f_get_size, FEMLITE_F_GET_SIZE) +#define F_GET_CONVERGENCE FC_GLOBAL(femlite_f_get_convergence, FEMLITE_F_GET_CONVERGENCE) #define F_GET_CONTACT_SUMMARY FC_GLOBAL(femlite_f_get_contact_summary, FEMLITE_F_GET_CONTACT_SUMMARY) #define F_GET_CONTACT_DIAG FC_GLOBAL(femlite_f_get_contact_diag, FEMLITE_F_GET_CONTACT_DIAG) #define F_GET_CONTACT_FRICTION FC_GLOBAL(femlite_f_get_contact_friction, FEMLITE_F_GET_CONTACT_FRICTION) @@ -48,6 +49,12 @@ extern void F_ESTIMATE_DT(double *dtcrit, int *ierr); extern void F_ADVANCE_EXPLICIT(double *dt, int *ierr); extern void F_GET_TIME(double *time, int *step, int *ierr); extern void F_GET_SIZE(int *num_nodes, int *num_elems, int *num_dof, int *ierr); +extern void F_GET_CONVERGENCE(int *increment, + int *iteration, + double *residual_norm, + double *correction_norm, + int *converged, + int *ierr); extern void F_GET_CONTACT_SUMMARY(int *active_count, double *work_step, double *work_total, @@ -240,6 +247,22 @@ int femlite_get_model_size(int *num_nodes, int *num_elems, int *num_dof) return ierr; } +int femlite_get_convergence_status(int *increment, + int *iteration, + double *residual_norm, + double *correction_norm, + int *converged) +{ + int ierr = 0; + if (!increment || !iteration || !residual_norm || + !correction_norm || !converged) { + return -1; + } + F_GET_CONVERGENCE(increment, iteration, residual_norm, + correction_norm, converged, &ierr); + return ierr; +} + int femlite_get_contact_summary(int *active_count, double *work_step, double *work_total, diff --git a/src/interface/fem_fortran_bridge.f90 b/src/interface/fem_fortran_bridge.f90 index 4a5cbcf..d11a7d7 100644 --- a/src/interface/fem_fortran_bridge.f90 +++ b/src/interface/fem_fortran_bridge.f90 @@ -158,6 +158,28 @@ subroutine femlite_f_get_size(num_nodes, num_elems, num_dof, ierr) call fem_get_model_size(num_nodes, num_elems, num_dof, ierr) end subroutine femlite_f_get_size +subroutine femlite_f_get_convergence(increment, iteration, residual_norm, & + correction_norm, converged_flag, ierr) + use fem_api + use fem_precision + implicit none + integer, intent(out) :: increment + integer, intent(out) :: iteration + real(rk), intent(out) :: residual_norm + real(rk), intent(out) :: correction_norm + integer, intent(out) :: converged_flag + integer, intent(out) :: ierr + logical :: converged + + call fem_get_convergence_status(increment, iteration, residual_norm, & + correction_norm, converged, ierr) + if (converged) then + converged_flag = 1 + else + converged_flag = 0 + end if +end subroutine femlite_f_get_convergence + subroutine femlite_f_clear_sph(ierr) use fem_api implicit none diff --git a/src/solver/fem_solver_implicit.f90 b/src/solver/fem_solver_implicit.f90 index 4771329..8647e56 100644 --- a/src/solver/fem_solver_implicit.f90 +++ b/src/solver/fem_solver_implicit.f90 @@ -203,8 +203,9 @@ contains dt_try = sub_target_time - current_time end if - call nonlinear_static_increment(sub_target_time, dt_try, max_iter, tol, & - iter_inc, res_norm, ierr) + call nonlinear_static_increment(current_step + 1, sub_target_time, & + dt_try, max_iter, tol, iter_inc, & + res_norm, ierr) if (ierr .eq. FEM_SUCCESS) then iter_total = iter_total + iter_inc current_time = sub_target_time @@ -818,8 +819,10 @@ contains if (allocated(kcopy)) deallocate(kcopy) end subroutine evaluate_newmark_trial_residual - subroutine nonlinear_static_increment(target_time, dt_inc, max_iter, tol, & - iter_used, res_norm, ierr) + subroutine nonlinear_static_increment(increment_id, target_time, dt_inc, & + max_iter, tol, iter_used, res_norm, & + ierr) + integer, intent(in) :: increment_id real(rk), intent(in) :: target_time real(rk), intent(in) :: dt_inc integer, intent(in) :: max_iter @@ -836,6 +839,7 @@ contains real(rk) :: ref_norm real(rk) :: trial_res_norm real(rk) :: trial_ref_norm + real(rk) :: correction_norm integer :: iter integer :: stat integer :: state_ierr @@ -846,7 +850,13 @@ contains ref_norm = ONE trial_res_norm = ZERO trial_ref_norm = ONE + correction_norm = ZERO converged = .false. + convergence_increment = increment_id + convergence_iteration = 0 + convergence_residual_norm = ZERO + convergence_correction_norm = ZERO + convergence_converged = .false. allocate(residual(ndof), external(ndof), rhs_corr(ndof), du(ndof), & u_start(ndof), u_base(ndof), stat=stat) if (stat .ne. 0) then @@ -870,8 +880,13 @@ contains res_norm, ref_norm, ierr) if (ierr .ne. FEM_SUCCESS) go to 900 iter_used = iter + convergence_iteration = iter + convergence_residual_norm = res_norm + convergence_correction_norm = correction_norm + convergence_converged = .false. if (res_norm .le. tol .or. res_norm / ref_norm .le. tol) then converged = .true. + convergence_converged = .true. if (allocated(freaction)) freaction = fint - external exit end if @@ -880,6 +895,8 @@ contains call static_solve_correction(target_time, residual, rhs_corr, du, & max_iter, tol, ierr) if (ierr .ne. FEM_SUCCESS) go to 900 + correction_norm = sqrt(sum(du * du)) + convergence_correction_norm = correction_norm u_base = u if (use_line_search) then diff --git a/tests/interface/test_c_api.c b/tests/interface/test_c_api.c index 1b43ab5..be63e08 100644 --- a/tests/interface/test_c_api.c +++ b/tests/interface/test_c_api.c @@ -41,6 +41,9 @@ int main(void) int contact_search_bvh_nodes = -1; int contact_cache_used = -1; int contact_cache_overflow = -1; + int conv_increment = -1; + int conv_iteration = -1; + int conv_converged = -1; int node_ids[1] = {2}; int facet_id[8]; int elem_id[8]; @@ -73,6 +76,8 @@ int main(void) double contact_search_time = -1.0; double contact_force_time = -1.0; double contact_tangent_time = -1.0; + double conv_residual_norm = -1.0; + double conv_correction_norm = -1.0; ierr = femlite_initialize(); if (ierr != 0) return check_ierr(ierr, 1); @@ -90,6 +95,15 @@ int main(void) if (ierr != 0) return check_ierr(ierr, 6); if (nnode != 4 || nelem != 1 || ndof != 12) return 7; + ierr = femlite_get_convergence_status(&conv_increment, &conv_iteration, + &conv_residual_norm, + &conv_correction_norm, + &conv_converged); + if (ierr != 0) return check_ierr(ierr, 38); + if (conv_increment != 0 || conv_iteration != 0 || + conv_residual_norm != 0.0 || conv_correction_norm != 0.0 || + conv_converged != 0) return 39; + ierr = femlite_get_contact_summary(&active_contact, &contact_work_step, &contact_work_total, &contact_max_penetration, diff --git a/tests/module/test_implicit_inp.f90 b/tests/module/test_implicit_inp.f90 index ee5fac9..a54b01e 100644 --- a/tests/module/test_implicit_inp.f90 +++ b/tests/module/test_implicit_inp.f90 @@ -43,11 +43,16 @@ contains integer :: ierr integer :: iter integer :: step + integer :: conv_increment + integer :: conv_iteration real(rk) :: res_norm + real(rk) :: conv_residual_norm + real(rk) :: conv_correction_norm real(rk) :: time real(rk) :: displacement(NDIM) real(rk) :: velocity(NDIM) real(rk) :: acceleration(NDIM) + logical :: conv_converged call fem_initialize(ierr) if (ierr .ne. 0) call fail(1) @@ -63,6 +68,15 @@ contains if (iter .le. 0 .or. iter .gt. 5) call fail(5) if (res_norm .gt. TOL) call fail(6) + call fem_get_convergence_status(conv_increment, conv_iteration, & + conv_residual_norm, conv_correction_norm, conv_converged, ierr) + if (ierr .ne. 0) call fail(17) + if (.not. conv_converged) call fail(18) + if (conv_increment .ne. 1) call fail(19) + if (conv_iteration .ne. iter) call fail(1001) + call check_close(conv_residual_norm, res_norm, 1002) + call check_close(conv_correction_norm, ZERO, 1003) + call fem_get_node_kinematics(2, displacement, velocity, acceleration, ierr) if (ierr .ne. 0) call fail(7) call check_close(displacement(1), 5.0_rk / 6.0_rk, 8) @@ -169,9 +183,13 @@ contains integer :: ierr integer :: iter integer :: step + integer :: conv_increment + integer :: conv_iteration integer :: query_nodes(4) integer :: query_elems(1) real(rk) :: res_norm + real(rk) :: conv_residual_norm + real(rk) :: conv_correction_norm real(rk) :: time real(rk) :: displacement(NDIM) real(rk) :: velocity(NDIM) @@ -182,6 +200,7 @@ contains real(rk) :: plastic_strain(NSTRESS,1) real(rk) :: eqps(1) real(rk) :: damage(1) + logical :: conv_converged call fem_initialize(ierr) if (ierr .ne. 0) call fail(250) @@ -198,6 +217,15 @@ contains if (iter .le. 0 .or. iter .gt. 12) call fail(255) if (res_norm .gt. TOL) call fail(256) + call fem_get_convergence_status(conv_increment, conv_iteration, & + conv_residual_norm, conv_correction_norm, conv_converged, ierr) + if (ierr .ne. 0) call fail(277) + if (.not. conv_converged) call fail(278) + if (conv_increment .ne. 4) call fail(279) + if (conv_iteration .le. 0) call fail(280) + if (conv_residual_norm .gt. TOL) call fail(281) + if (conv_correction_norm .lt. ZERO) call fail(282) + call fem_get_node_kinematics(2, displacement, velocity, acceleration, ierr) if (ierr .ne. 0) call fail(257) call check_close(displacement(1), 5.0_rk / 6.0_rk, 258)