itersolve.h 文件参考

稀疏线性系统的迭代求解器（CG / BiCGSTAB / GMRES / MINRES / LSQR）。 更多...

#include <stddef.h>
#include "lmmc/numeric.h"
#include "lmmc/diagnostic.h"
#include "lmmc/precond.h"
#include "lmmc/sparse.h"

itersolve.h 的引用(Include)关系图:

此图展示该文件被哪些文件直接或间接地引用了:

浏览该文件的源代码.

结构体
struct	lmmc_itersolve_result_t
	迭代求解的结果统计。 更多...
struct	lmmc_itersolve_config_t
	迭代求解器配置。 更多...

类型定义
typedef lmmc_status_t(*)	lmmc_matvec_op_t(const lmmc_vec_t *x, lmmc_vec_t *y, void *user_data)
	矩阵-向量乘法算子回调类型（matrix-free 模式）。

函数
lmmc_status_t	lmmc_itersolve_default_config (size_t problem_size, lmmc_itersolve_config_t *out_cfg)
	根据问题规模生成迭代求解器默认配置。
lmmc_status_t	lmmc_cg_solve (const lmmc_sparse_mat_t *a, const lmmc_vec_t *b, const lmmc_precond_t *precond, const lmmc_itersolve_config_t *cfg, lmmc_vec_t *x, lmmc_itersolve_result_t *out_result)
	共轭梯度法（CG）求解对称正定稀疏系统 A*x = b。
lmmc_status_t	lmmc_bicgstab_solve (const lmmc_sparse_mat_t *a, const lmmc_vec_t *b, const lmmc_precond_t *precond, const lmmc_itersolve_config_t *cfg, lmmc_vec_t *x, lmmc_itersolve_result_t *out_result)
	稳定双共轭梯度法（BiCGSTAB）求解一般非对称稀疏系统 A*x = b。
lmmc_status_t	lmmc_gmres_solve (const lmmc_sparse_mat_t *a, const lmmc_vec_t *b, const lmmc_precond_t *precond, const lmmc_itersolve_config_t *cfg, lmmc_vec_t *x, lmmc_itersolve_result_t *out_result)
	重启型 GMRES 求解一般非对称稀疏系统 A*x = b。
lmmc_status_t	lmmc_minres_solve (const lmmc_sparse_mat_t *a, const lmmc_vec_t *b, const lmmc_precond_t *precond, const lmmc_itersolve_config_t *cfg, lmmc_vec_t *x, lmmc_itersolve_result_t *out_result)
	MINRES 求解对称（可能不定）稀疏系统 A x = b 。
lmmc_status_t	lmmc_lsqr_solve (const lmmc_sparse_mat_t *a, const lmmc_vec_t *b, const lmmc_itersolve_config_t *cfg, lmmc_vec_t *x, lmmc_itersolve_result_t *out_result)
	LSQR 求解最小二乘问题 min ||Ax - b||_2 。

详细描述

稀疏线性系统的迭代求解器（CG / BiCGSTAB / GMRES / MINRES / LSQR）。

通用工作流程：

1. 调用 lmmc_itersolve_default_config 取得默认参数。
2. 根据需要修改容差、最大步数、日志回调等。
3. 调用具体求解器并检查 lmmc_itersolve_result_t 。

在文件 itersolve.h 中定义.

---

结构体说明

lmmc_itersolve_result_t

struct lmmc_itersolve_result_t

迭代求解的结果统计。

在文件 itersolve.h 第 26 行定义.

lmmc_itersolve_result_t 的协作图:

成员变量
int	converged	是否收敛（非 0 表示已满足容差）。
size_t	num_iter	实际迭代步数。
lmmc_real_t	initial_residual_norm	初始残差 2-范数。
lmmc_real_t	final_residual_norm	终止时的残差 2-范数。

lmmc_itersolve_config_t

struct lmmc_itersolve_config_t

迭代求解器配置。

abs_tol、rel_tol 必须有限且非负，max_iter 必须大于零；无效配置在调用算子 或修改 x 前返回 INVALID_ARGUMENT。MINRES / LSQR 也检查 abs_tol + rel_tol * ||b||_2 有限，否则返回 NUMERICAL_FAILURE。

在文件 itersolve.h 第 53 行定义.

lmmc_itersolve_config_t 的协作图:

成员变量
lmmc_real_t	abs_tol	残差绝对容差。
lmmc_real_t	rel_tol	相对容差（残差判据相对于 ||b||_2）。
size_t	max_iter	最大迭代步数。
size_t	restart	GMRES 重启长度（其它求解器忽略）。
lmmc_diagnostic_sink_t	diagnostics	统一诊断出口。
lmmc_matvec_op_t	apply_op	矩阵-向量乘法算子回调，NULL 表示使用稀疏矩阵。
void *	op_user_data	传递给矩阵算子回调的共享上下文。
lmmc_matvec_op_t	apply_transpose_op	转置矩阵-向量乘法回调；仅 LSQR matrix-free 模式使用。

类型定义说明

lmmc_matvec_op_t

typedef lmmc_status_t(*) lmmc_matvec_op_t(const lmmc_vec_t *x, lmmc_vec_t *y, void *user_data)

矩阵-向量乘法算子回调类型（matrix-free 模式）。

用户提供的回调函数，计算 y = A * x 而无需显式存储矩阵 A 。

参数

[in]	x	输入向量。
[out]	y	输出向量（由调用方预分配）。
[in]	user_data	用户透明上下文。

返回

LMMC_STATUS_OK 成功；其它状态码表示失败。

在文件 itersolve.h 第 43 行定义.

函数说明

lmmc_itersolve_default_config()

lmmc_status_t lmmc_itersolve_default_config	(	size_t	problem_size,
		lmmc_itersolve_config_t *	out_cfg )

根据问题规模生成迭代求解器默认配置。

默认值：abs_tol=1e-12, rel_tol=1e-8, max_iter=max(100, 20*n), restart=min(n,30)。

参数

[in]	problem_size	问题维度 n，必须 > 0。
[out]	out_cfg	输出配置结构体。

返回

• LMMC_STATUS_OK — 成功。
• LMMC_STATUS_INVALID_ARGUMENT — problem_size==0 或 out_cfg==NULL。

副作用

• 覆写 out_cfg 的所有字段。无内存分配。

在文件 itersolve.c 第 57 行定义.

引用了 lmmc_itersolve_config_t::abs_tol, lmmc_itersolve_config_t::apply_op, lmmc_itersolve_config_t::apply_transpose_op, lmmc_itersolve_config_t::diagnostics, LMMC_DEFAULT_ABS_TOL, lmmc_itersolve_default_config(), LMMC_REAL_INIT, LMMC_REAL_SET_D, LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK, lmmc_itersolve_config_t::max_iter, lmmc_itersolve_config_t::op_user_data, lmmc_itersolve_config_t::rel_tol , 以及 lmmc_itersolve_config_t::restart.

被这些函数引用 lmmc_itersolve_default_config(), lmmc_itersolve_dispatch_config() , 以及 lmmc_itersolve_validate().

函数调用图:

这是这个函数的调用关系图:

lmmc_cg_solve()

lmmc_status_t lmmc_cg_solve	(	const lmmc_sparse_mat_t *	a,
		const lmmc_vec_t *	b,
		const lmmc_precond_t *	precond,
		const lmmc_itersolve_config_t *	cfg,
		lmmc_vec_t *	x,
		lmmc_itersolve_result_t *	out_result )

共轭梯度法（CG）求解对称正定稀疏系统 A*x = b。

要求 A 对称正定。x 作为初始猜测输入，收敛后存储解。 收敛判据：||r||_2 <= abs_tol + rel_tol * ||b||_2。

参数

[in]	a	对称正定稀疏矩阵（不被修改）。
[in]	b	右端向量（不被修改）。
[in]	precond	预处理子，可为 NULL（无预处理）。
[in]	cfg	配置参数，可为 NULL（使用默认值）。
[in,out]	x	初始猜测 / 输出解向量。
[out]	out_result	迭代统计结果，可为 NULL。

返回

• LMMC_STATUS_OK — 成功（含收敛和达到最大步数两种情况，通过 out_result->converged 区分）。
• LMMC_STATUS_INVALID_ARGUMENT — 指针为 NULL 或维度为 0。
• LMMC_STATUS_DIMENSION_MISMATCH — 矩阵/向量/预处理子维度不匹配。
• LMMC_STATUS_NUMERICAL_FAILURE — 出现 NaN/Inf 或分母退化。

副作用

• 就地修改 x->data。分配并释放 4 个长度为 n 的临时向量。

在文件 itersolve_cg.c 第 113 行定义.

引用了 lmmc_cg_state_t::ap, lmmc_cg_solve(), lmmc_itersolve_do_log(), lmmc_itersolve_finish(), lmmc_itersolve_initial(), lmmc_itersolve_validate(), lmmc_itersolve_workspace(), lmmc_memory_free(), LMMC_STATUS_OK, lmmc_cg_state_t::norm, lmmc_cg_state_t::p, lmmc_cg_state_t::r, lmmc_vec_t::size, lmmc_cg_state_t::threshold , 以及 lmmc_cg_state_t::z.

被这些函数引用 lmmc_cg_solve().

函数调用图:

这是这个函数的调用关系图:

lmmc_bicgstab_solve()

lmmc_status_t lmmc_bicgstab_solve	(	const lmmc_sparse_mat_t *	a,
		const lmmc_vec_t *	b,
		const lmmc_precond_t *	precond,
		const lmmc_itersolve_config_t *	cfg,
		lmmc_vec_t *	x,
		lmmc_itersolve_result_t *	out_result )

稳定双共轭梯度法（BiCGSTAB）求解一般非对称稀疏系统 A*x = b。

适用于非对称或不定矩阵。x 作为初始猜测输入。

参数

[in]	a	稀疏矩阵（不被修改）。
[in]	b	右端向量（不被修改）。
[in]	precond	预处理子，可为 NULL。
[in]	cfg	配置参数，可为 NULL。
[in,out]	x	初始猜测 / 输出解向量。
[out]	out_result	迭代统计结果，可为 NULL。

返回

同 ::lmmc_cg_solve。

副作用

• 就地修改 x->data。分配并释放 9 个长度为 n 的临时向量。

在文件 itersolve_bicgstab.c 第 186 行定义.

引用了 lmmc_bicgstab_state_t::alpha, lmmc_bicgstab_state_t::ax, lmmc_bicgstab_solve(), lmmc_itersolve_do_log(), lmmc_itersolve_finish(), lmmc_itersolve_initial(), lmmc_itersolve_validate(), lmmc_itersolve_workspace(), lmmc_memory_free(), LMMC_STATUS_OK, lmmc_bicgstab_state_t::norm, lmmc_bicgstab_state_t::omega, lmmc_bicgstab_state_t::p, lmmc_bicgstab_state_t::r, lmmc_bicgstab_state_t::r_hat, lmmc_bicgstab_state_t::rho, lmmc_bicgstab_state_t::s, lmmc_vec_t::size, lmmc_bicgstab_state_t::t, lmmc_bicgstab_state_t::threshold, lmmc_bicgstab_state_t::v, lmmc_bicgstab_state_t::y , 以及 lmmc_bicgstab_state_t::z.

被这些函数引用 lmmc_bicgstab_solve().

函数调用图:

这是这个函数的调用关系图:

lmmc_gmres_solve()

lmmc_status_t lmmc_gmres_solve	(	const lmmc_sparse_mat_t *	a,
		const lmmc_vec_t *	b,
		const lmmc_precond_t *	precond,
		const lmmc_itersolve_config_t *	cfg,
		lmmc_vec_t *	x,
		lmmc_itersolve_result_t *	out_result )

重启型 GMRES 求解一般非对称稀疏系统 A*x = b。

使用 Arnoldi 过程构建 Krylov 子空间，Givens 旋转求解最小残差。 重启长度由 cfg->restart 控制（默认 30）。

参数

[in]	a	稀疏矩阵（不被修改）。
[in]	b	右端向量（不被修改）。
[in]	precond	预处理子，可为 NULL。
[in]	cfg	配置参数，可为 NULL。cfg->restart 控制重启长度。
[in,out]	x	初始猜测 / 输出解向量。
[out]	out_result	迭代统计结果，可为 NULL。

返回

同 ::lmmc_cg_solve。

副作用

• 就地修改 x->data。
• 分配 (restart+1) 个长度为 n 的 Arnoldi 基向量 + Hessenberg 矩阵等工作空间。

在文件 itersolve_gmres.c 第 131 行定义.

引用了 lmmc_gmres_state_t::basis, lmmc_gmres_solve(), lmmc_gmres_workspace(), lmmc_itersolve_do_log(), lmmc_itersolve_finish(), lmmc_itersolve_initial(), lmmc_itersolve_validate(), lmmc_memory_free(), LMMC_STATUS_OK, lmmc_itersolve_config_t::max_iter, lmmc_gmres_state_t::norm, lmmc_itersolve_config_t::restart, lmmc_vec_t::size , 以及 lmmc_gmres_state_t::threshold.

被这些函数引用 lmmc_gmres_solve().

函数调用图:

这是这个函数的调用关系图:

lmmc_minres_solve()

lmmc_status_t lmmc_minres_solve	(	const lmmc_sparse_mat_t *	a,
		const lmmc_vec_t *	b,
		const lmmc_precond_t *	precond,
		const lmmc_itersolve_config_t *	cfg,
		lmmc_vec_t *	x,
		lmmc_itersolve_result_t *	out_result )

MINRES 求解对称（可能不定）稀疏系统 A x = b 。

当 cfg->apply_op 非 NULL 时使用 matrix-free 模式（此时 a 必须为 NULL）。 若同时提供 a 和 cfg->apply_op ，返回 LMMC_STATUS_INVALID_ARGUMENT 。

precond 表示求解 M*z=r；仅接受 NULL / NONE 或有限严格正的 Jacobi。 ILU0 / ILUT 返回 INVALID_ARGUMENT，非正 Jacobi 返回 NOT_POSITIVE_DEFINITE， 非有限内部数据返回 NUMERICAL_FAILURE，尺寸不符返回 DIMENSION_MISMATCH。

初始及每次完成 x 更新后计算真实残差 r=b-A*x，仅在 ||r||_2 <= abs_tol + rel_tol * ||b||_2 时标记收敛。统计和诊断报告真实范数， num_iter 计完成的解更新次数；达到 max_iter 或基空间耗尽仍返回 OK， converged 为零。错误保留最近成功计算的残差统计，算子错误原样传播。 每步额外执行一次前向算子以检查真实残差。一次分配九个长度 n 的工作向量， 迭代中不分配；restart 被忽略。

在文件 itersolve_minres.c 第 215 行定义.

引用了 lmmc_minres_state_t::lanczos_tmp, lmmc_itersolve_do_log(), lmmc_itersolve_finish(), lmmc_itersolve_initial(), lmmc_itersolve_result_init(), lmmc_itersolve_workspace(), lmmc_memory_free(), lmmc_minres_solve(), LMMC_STATUS_OK, lmmc_minres_state_t::norm_r, lmmc_minres_state_t::r_curr, lmmc_minres_state_t::r_prev, lmmc_vec_t::size, lmmc_minres_state_t::threshold, lmmc_minres_state_t::true_r, lmmc_minres_state_t::v, lmmc_minres_state_t::w_next, lmmc_minres_state_t::w_prev, lmmc_minres_state_t::w_prev2 , 以及 lmmc_minres_state_t::y.

被这些函数引用 lmmc_minres_solve().

函数调用图:

这是这个函数的调用关系图:

lmmc_lsqr_solve()

lmmc_status_t lmmc_lsqr_solve	(	const lmmc_sparse_mat_t *	a,
		const lmmc_vec_t *	b,
		const lmmc_itersolve_config_t *	cfg,
		lmmc_vec_t *	x,
		lmmc_itersolve_result_t *	out_result )

LSQR 求解最小二乘问题 min ||Ax - b||_2 。

基于 Golub-Kahan 双对角化。matrix-free 模式要求 cfg->apply_op 和 cfg->apply_transpose_op 同时非 NULL，并分别计算 A*x 和 A^T*x，共享 cfg->op_user_data；此时 a 必须为 NULL。显式矩阵模式要求两个回调均为 NULL。

初始及每次完成 x 更新后计算真实残差 r=b-A*x，统计和诊断均报告其 2-范数。 收敛条件为 ||r||_2 <= abs_tol + rel_tol * ||b||_2，或 ||A^T*r||_2 <= rel_tol * anorm * ||r||_2，其中 anorm 为双对角化的 Frobenius 范数估计。后者通过归一化残差计算以避免下溢，因此最小二乘 收敛时 final_residual_norm 可以非零；abs_tol 始终具有残差量纲。

num_iter 计完成的解更新次数。达到 max_iter 或基空间耗尽且未满足停止式， 返回 OK / converged=0；非有限状态返回 NUMERICAL_FAILURE，算子错误原样 传播，错误统计保留最近成功计算的真残差。每步额外计算一次前向算子， 需要驻点检查时再计算一次转置算子。一次分配工作区，迭代中不分配； restart 被忽略。

在文件 itersolve_lsqr.c 第 232 行定义.

引用了 lmmc_lsqr_state_t::av_tmp, lmmc_itersolve_do_log(), lmmc_itersolve_finish(), lmmc_itersolve_initial(), lmmc_itersolve_result_init(), lmmc_itersolve_workspace(), lmmc_lsqr_solve(), lmmc_memory_free(), LMMC_STATUS_OK, lmmc_lsqr_state_t::norm_r, lmmc_vec_t::size, lmmc_lsqr_state_t::threshold, lmmc_lsqr_state_t::tmp_vec, lmmc_lsqr_state_t::u, lmmc_lsqr_state_t::v , 以及 lmmc_lsqr_state_t::w.

被这些函数引用 lmmc_lsqr_solve().

函数调用图:

这是这个函数的调用关系图: