From 678d2006cc4ffa173c07c1e3a90fc60b80f09c36 Mon Sep 17 00:00:00 2001 From: shenw Date: Thu, 25 Jun 2026 12:19:35 +0800 Subject: [PATCH] Document V4.8 solver and example coverage --- docs/01_requirements_specification.md | 3 ++ docs/02_software_architecture_design.md | 9 ++++ docs/03_detailed_design.md | 3 +- docs/04_mathematical_model_and_algorithms.md | 44 ++++++++++++++++++++ docs/05_interface_control_document.md | 3 +- docs/06_test_and_verification_plan.md | 10 ++--- 6 files changed, 65 insertions(+), 7 deletions(-) diff --git a/docs/01_requirements_specification.md b/docs/01_requirements_specification.md index 765e735..00aa8f2 100644 --- a/docs/01_requirements_specification.md +++ b/docs/01_requirements_specification.md @@ -172,6 +172,9 @@ - SHOULD:线性静力学求解,方程形式为 K u = f - SHOULD:非线性静力学求解,方程形式为 R(u) = 0 +- SHOULD:隐式路径通过统一线性求解器分发层求解 CSR 方程,内部至少支持 CG、BiCGSTAB 和 GMRES。 +- SHOULD:线性求解器支持 none/Jacobi 预条件选择,并可查询最近一次迭代数、残差和状态码。 +- COULD:外部稀疏线性求解器后端作为可选适配,不作为默认构建强依赖。 - SHOULD:隐式 Newmark + Newton 非线性动力学求解 - SHOULD:载荷步、增量步、Newton 迭代、线搜索、收敛准则、失败回退和可选步长缩减控制 - SHOULD:实体和壳单元均可参与线性静力学求解 diff --git a/docs/02_software_architecture_design.md b/docs/02_software_architecture_design.md index ee52a67..991dca7 100644 --- a/docs/02_software_architecture_design.md +++ b/docs/02_software_architecture_design.md @@ -297,6 +297,14 @@ recover strain and stress write output ``` +第四版起,静力和隐式路径不直接绑定单一线性求解器,而是经由 +`fem_linear_solver_cg.f90` 中的分发层求解 CSR 系统。分发层读取 +`fem_control` 中的 method/preconditioner 设置,当前内部支持 CG、 +BiCGSTAB 和 GMRES,支持 none/Jacobi 预条件,并把最近一次 method、 +preconditioner、迭代数、残差和状态码写回控制模块供 Fortran API、C ABI +和测试查询。外部 MUMPS/SuperLU/MKL Pardiso 等后端只作为后续适配层, +不得让隐式求解器直接依赖第三方库。 + 第三版非线性静力控制流: ```text @@ -469,6 +477,7 @@ coupling 层职责: - 通过 CSR 层提供矩阵和向量接口 - 隐式求解器不得直接绑定具体第三方库 - 外部库适配应单独放在 solver 或 external 子层 +- 外部库不可用时必须保留内部 CG/BiCGSTAB/GMRES 路径,构建和 CTest 不应受影响 ## 17. 构建与部署架构 diff --git a/docs/03_detailed_design.md b/docs/03_detailed_design.md index 76cdb3d..6103069 100644 --- a/docs/03_detailed_design.md +++ b/docs/03_detailed_design.md @@ -870,7 +870,7 @@ end subroutine - Robin、MPC、刚性平面 penalty contact 和面-面 contact pair 的切线进入 Newton 有效刚度。 - 静力和非线性 Newmark 均支持线搜索;可选步长缩减在失败时恢复增量起点状态后重试。 - V4.5 起,`fem_control` 保存最近一次求解收敛快照、relative residual、contact gap residual、combined norm、cutback 诊断、最后有效时间和失败原因码,供 Fortran API、C ABI 和测试直接查询。 -- V4.6 起,隐式求解器通过线性求解器分发层求解 CSR 方程;默认 CG + Jacobi,可切换 BiCGSTAB + none/Jacobi,并记录最近一次线性求解方法、预条件器、迭代数、残差和状态。 +- V4.6 起,隐式求解器通过线性求解器分发层求解 CSR 方程;默认 CG + Jacobi,可切换 BiCGSTAB/GMRES + none/Jacobi,并记录最近一次线性求解方法、预条件器、迭代数、残差和状态。 - V4.7 起,壳 drilling/S3 剪切锁定参数可配置并提供稳定性统计;壳 J2 剪切和代表性弯曲塑性路径纳入 trial/rollback 回归。 ## 17. 稀疏矩阵模块 @@ -889,6 +889,7 @@ V4.6 线性求解器抽象仍位于 `fem_linear_solver_cg.f90`,保留 `linear_ - `linear_solver_solve`:根据 `fem_control` 中的 `linear_solver_method / linear_precond_method` 分发。 - `linear_bicgstab_solve`:用于非对称或非正定 CSR 小系统的内部备用路径。 +- `linear_gmres_solve`:用于非对称 CSR 小系统的内部 Krylov 路径,构造 Arnoldi Hessenberg 基并求解小型最小二乘修正。 - `linear_solver_configure / linear_solver_get_settings / linear_solver_get_stats`:配置和查询当前/最近一次线性求解器状态。 - `LSOLVER_EXTERNAL` 当前作为外部稀疏求解器占位,配置允许,实际求解返回 unsupported 状态。 diff --git a/docs/04_mathematical_model_and_algorithms.md b/docs/04_mathematical_model_and_algorithms.md index 6dd3f18..dba9c1c 100644 --- a/docs/04_mathematical_model_and_algorithms.md +++ b/docs/04_mathematical_model_and_algorithms.md @@ -800,6 +800,50 @@ V4.5 起,静力和隐式求解共享最近一次收敛诊断状态: - 线性求解器迭代次数。 - 收敛、失败和步长缩减状态。 +### 16.4 线性求解器分发与 Krylov 算法 + +第四版隐式和静力路径通过统一线性求解器分发层求解 CSR 线性系统: + +```text +A x = b +``` + +分发层根据控制参数选择 CG、BiCGSTAB、GMRES 或外部求解器预留路径。当前 +外部求解器路径仅返回 unsupported 状态;第四版验收范围以内置求解器为准。 +预条件器当前支持 none 和 Jacobi。Jacobi 预条件器提取 CSR 对角项,求解时使用 +`z_i = r_i / A_ii`;若对角项近零则保留未缩放残差分量,避免除零。 + +CG 用于对称正定系统,采用标准三项递推,收敛判据为残差范数小于调用方给定 +容限。BiCGSTAB 用于非对称系统,使用固定初始影子残差,检测 `rho`、 +`alpha` 和 `omega` breakdown,并把 breakdown 或未收敛状态写入线性求解器统计。 + +GMRES 用于非对称 CSR 系统。当前实现采用未重启 Arnoldi 过程,最多构造 +`max_iter` 个 Krylov 基向量: + +```text +v_1 = M^{-1} r_0 / ||M^{-1} r_0|| +w = M^{-1} A v_j +h_ij = v_i^T w +w = w - h_ij v_i +h_{j+1,j} = ||w|| +``` + +每次扩展后形成小型 Hessenberg 最小二乘问题: + +```text +min || beta e_1 - H_k y || +x_k = x_0 + V_k y +``` + +最小二乘当前通过正规方程 `H_k^T H_k y = H_k^T beta e_1` 和小规模高斯消元求解, +适用于当前小型回归与隐式 smoke。若正规方程奇异或 Arnoldi breakdown, +求解器返回明确错误状态。后续大规模 GMRES 可扩展为重启 GMRES、Givens +旋转更新和 ILU/SSOR 或外部稀疏库预条件。 + +线性求解器统计包括最近一次 method、preconditioner、迭代数、最终残差和状态码。 +静力、隐式 Newmark 和非线性 Newton 修正方程均通过该分发层,保证 C ABI 与 +测试可以统一查询求解器行为。 + ## 17. 接触算法 第二版实现基础 penalty 接触。 diff --git a/docs/05_interface_control_document.md b/docs/05_interface_control_document.md index b0319c6..3b5f1e9 100644 --- a/docs/05_interface_control_document.md +++ b/docs/05_interface_control_document.md @@ -613,9 +613,10 @@ end subroutine 说明: -- `method` 使用 `LSOLVER_CG=1`、`LSOLVER_BICGSTAB=2`、`LSOLVER_EXTERNAL=100`。 +- `method` 使用 `LSOLVER_CG=1`、`LSOLVER_BICGSTAB=2`、`LSOLVER_GMRES=3`、`LSOLVER_EXTERNAL=100`。 - `preconditioner` 使用 `LPRECOND_NONE=0`、`LPRECOND_JACOBI=1`。 - `status_code` 使用 `LS_STATUS_IDLE=0`、`LS_STATUS_CONVERGED=1`、`LS_STATUS_FAILED=-1`、`LS_STATUS_UNSUPPORTED=-2`。 +- CG 主要面向对称正定系统;BiCGSTAB 和 GMRES 可用于非对称 CSR 小系统。 - `LSOLVER_EXTERNAL` 仅作为外部稀疏求解器预留路径;当前配置可记录,但实际求解返回 unsupported。 - 静力、隐式 Newmark 和非线性 Newton 修正方程均通过同一分发层求解。 diff --git a/docs/06_test_and_verification_plan.md b/docs/06_test_and_verification_plan.md index a97f144..a67a6ed 100644 --- a/docs/06_test_and_verification_plan.md +++ b/docs/06_test_and_verification_plan.md @@ -60,7 +60,7 @@ Python 环境约定: - active set、gap residual 和 augmented penalty 诊断测试。 - 摩擦正则化、摩擦功和最大累计滑移输出测试。 - 接触示例 smoke 测试应覆盖刚性平面压入、两实体块面-面压缩和壳-刚性平面接触。 -- 线性求解器分发测试应覆盖 CG、BiCGSTAB、none/Jacobi 预条件、外部求解器占位和最近一次求解统计。 +- 线性求解器分发测试应覆盖 CG、BiCGSTAB、GMRES、none/Jacobi 预条件、外部求解器占位和最近一次求解统计。 - 壳 V4.7 测试应覆盖 drilling 稳定参数、S3 剪切锁定折减诊断、J2 剪切/弯曲塑性、trial/rollback 和 Scordelis-Lo 静力基准 smoke。 ## 4. 测试目录结构 @@ -302,7 +302,7 @@ SPH总力映射测试 relative tolerance 1.0e-10 to 1.0e-8 - `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` / `fem_get_convergence_metrics` / `fem_get_convergence_diagnostics` 和 C ABI 对应包装返回最近一次求解的增量、迭代、残差、相对残差、修正范数、contact gap residual、combined norm、cutback 次数、最后步长、最后有效时间、状态码、失败原因码和收敛标志;空模型零状态、非线性静力收敛状态、contact gap 非零状态和 cutback 失败状态均需覆盖。 -- `fem_set_linear_solver` / `fem_get_linear_solver_settings` / `fem_get_linear_solver_stats` 和 C ABI 对应包装返回当前线性求解器、预条件器、最近一次迭代数、残差和状态;模块测试覆盖 BiCGSTAB 非对称小系统,`implicit_inp` 覆盖隐式路径切换到 BiCGSTAB。 +- `fem_set_linear_solver` / `fem_get_linear_solver_settings` / `fem_get_linear_solver_stats` 和 C ABI 对应包装返回当前线性求解器、预条件器、最近一次迭代数、残差和状态;模块测试覆盖 CG、BiCGSTAB 和 GMRES,BiCGSTAB/GMRES 使用非对称小系统,`implicit_inp` 覆盖隐式路径切换到 BiCGSTAB,C ABI 覆盖切换到 GMRES + Jacobi。 - 删除单元状态可输出。 示例结果留存策略: @@ -337,8 +337,8 @@ SPH总力映射测试 relative tolerance 1.0e-10 to 1.0e-8 - 法向接触功、摩擦功、stick/slip 计数、mortar 积分点历史槽、正则化摩擦切线和累计滑移 sanity check。 - V4.2 新增示例:rigid plane indentation、two blocks compression、shell rigid plane contact;每个示例应可通过目录内 `run_case.bat` 自动运行和检查结果。 - V4.3 新增示例:contact block sliding friction;检查正则化参数、累计滑移、切向力、摩擦功非负和 VTK 输出。 -- V4.8 补齐文档型示例目录的可运行输入和 `run_case.bat`,新增 `examples_layout` CTest 检查“有文档无 `.inp`”和“有 `.inp` 无双击脚本”的回退。 -- 已接入 `example_smoke` CTest 分组:shell patch S3/S4 静力 smoke、Scordelis-Lo S3/S4 静力 smoke、clamped square plate pressure pulse S4 短步数动力 smoke、rigid sphere impact plate S3/S4 短步数动力 smoke、contact block sliding friction 短步数动力 smoke、elliptic membrane 静力 smoke、membrane uniaxial 静力 smoke、shell-solid connection 静力 smoke、strength reduction slope 静力 smoke 和 golf ball impact 短步数动力 smoke;rigid/golf impact smoke 需要 final contact CSV 中出现 active contact,sliding friction smoke 需要 final contact CSV 中出现正摩擦耗散,Scordelis-Lo smoke 需要自由角竖向位移为负且超过最小量级。 +- V4.8 补齐文档型示例目录的可运行输入和 `run_case.bat`,新增 `examples_layout` CTest 检查“有文档无 `.inp`”和“有 `.inp` 无双击脚本”的回退;文档后缀包含 `.md`、`.pdf`、`.ppt`、`.pptx`、`.txt` 和 `.rst`。 +- 已接入 `example_smoke` CTest 分组:shell patch S3/S4 静力 smoke、Scordelis-Lo S3/S4 静力 smoke、clamped square plate pressure pulse S4 短步数动力 smoke、rigid sphere impact plate S3/S4 短步数动力 smoke、contact block sliding friction 短步数动力 smoke、elliptic membrane、membrane uniaxial、shell-solid connection、strength reduction slope、golf ball impact、node analytical contact、block-on-arch、cylinder roller contact、sliding wedge、roll forming、falling objects、ball adhesion contact、buckling corrugated shell、dynamic grain container、thick plate、membrane airbag、spherical cap、blasting rock、nonlinear harmonic、layered shell、two arches、pinched hemisphere 和 stress dependent elasticity smoke;接触类 smoke 检查 active contact,摩擦滑移类 smoke 检查正摩擦耗散,壳/静力基准 smoke 通过节点位移探针检查方向和最小量级。 - rigid sphere impact plate 的长步数结果保留为示例复现实验。 ## 11. 输入解析测试 @@ -690,7 +690,7 @@ V4.4 contact pair 性能 smoke: - 0.4.2 本地发布记录:Windows GCC 16 CTest 33/33,WSL Ubuntu + gfortran 13.3 CTest 33/33,Windows Intel oneAPI `ifx` 2026.0 + MSVC `cl` 19.44 CTest 33/33;Intel/NMake `/machine:x64` ifx warning 已清理。 - 0.4.3 当前 Windows GCC 16 回归记录:CTest 34/34。 - V4.4 开发态新增 `contact_omp1` / `contact_omp4`,用 `OMP_NUM_THREADS=1/4` 重跑 contact 模块回归;新增 `perf_contact_pair_smoke` 和 `perf_contact_pair_medium` 覆盖 BVH contact pair 性能 smoke;新增 `perf_contact_pair_omp_consistency` 对比性能 smoke 在 OpenMP 1/4 线程下的非计时统计;contact CSV 已覆盖 summary 和逐 pair 统计;BVH force 权重准备统计改为 OpenMP reduction 后由 contact 定向回归覆盖;BVH force 并行装配已将法向/mortar/接触面积准备移出全局提交临界区,BVH tangent 并行装配已将 mortar/切线块准备移出 CSR 临界区;`contact` 覆盖跨调用候选缓存 force/tangent 命中和失效条件。 -- V4.8 开发态新增 `examples_layout` 和五个文档派生 `example_smoke`,Python 可用时 Windows GCC 16 CTest 当前为 47 项。 +- V4.8 阶段验收新增 `examples_layout`、GMRES 回归、node analytical contact、P1 contact 性能 smoke,以及完整文档派生 `example_smoke` 矩阵;Python 可用时 Windows GCC 16 CTest 当前记录为 66/66 passed。 ## 21. 发布阻断条件