eigen.h 文件参考

特征值 / 奇异值分解,伪逆与条件数接口. 更多...

#include "lmmc/dense.h"
#include "lmmc/status.h"

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

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

浏览该文件的源代码.

结构体
struct	lmmc_eigen_sym_result_t
	对称矩阵特征分解结果. 更多...
struct	lmmc_eigen_gen_result_t
	一般实矩阵特征分解结果(仅特征值,使用实部 / 虚部分别存储). 更多...
struct	lmmc_eigen_gen_full_result_t
	一般实矩阵完整特征分解结果(特征值 + 特征向量). 更多...
struct	lmmc_svd_result_t
	奇异值分解结果: \(A = U \Sigma V^T\) . 更多...

函数
lmmc_status_t	lmmc_eigen_symmetric (const lmmc_mat_t *a, lmmc_eigen_sym_result_t *out_result)
	计算实对称矩阵的全部特征值与特征向量.
lmmc_status_t	lmmc_eigen_general (const lmmc_mat_t *a, lmmc_eigen_gen_result_t *out_result)
	计算一般实矩阵的特征值(不输出特征向量).
lmmc_status_t	lmmc_svd (const lmmc_mat_t *a, lmmc_svd_result_t *out_result)
	计算奇异值分解:A = U * Σ * V^T.
lmmc_status_t	lmmc_pinv (const lmmc_mat_t *a, lmmc_real_t tol, lmmc_mat_t *out_pinv)
	计算 Moore-Penrose 伪逆 A^+。
lmmc_status_t	lmmc_cond (const lmmc_mat_t *a, lmmc_real_t *out_cond)
	计算矩阵的 2-范数条件数:κ_2(A) = sigma_max / sigma_min.
lmmc_status_t	lmmc_eigen_general_full (const lmmc_mat_t *a, lmmc_eigen_gen_full_result_t *out_result)
	计算一般实矩阵的特征值与特征向量.
void	lmmc_eigen_sym_result_destroy (lmmc_eigen_sym_result_t *result)
	释放 lmmc_eigen_symmetric 输出结果.
void	lmmc_eigen_gen_result_destroy (lmmc_eigen_gen_result_t *result)
	释放 lmmc_eigen_general 输出结果.
void	lmmc_eigen_gen_full_result_destroy (lmmc_eigen_gen_full_result_t *result)
	释放 lmmc_eigen_general_full 输出结果.
void	lmmc_svd_result_destroy (lmmc_svd_result_t *result)
	释放 lmmc_svd 输出结果.

详细描述

特征值 / 奇异值分解,伪逆与条件数接口.

在文件 eigen.h 中定义.

---

结构体说明

lmmc_eigen_sym_result_t

struct lmmc_eigen_sym_result_t

对称矩阵特征分解结果.

第 i 个特征值对应 eigenvectors 的第 i 列.

在文件 eigen.h 第 20 行定义.

lmmc_eigen_sym_result_t 的协作图:

成员变量
lmmc_vec_t	eigenvalues	升序特征值向量,长度 n .
lmmc_mat_t	eigenvectors	正交特征向量矩阵,nxn .

lmmc_eigen_gen_result_t

struct lmmc_eigen_gen_result_t

一般实矩阵特征分解结果(仅特征值,使用实部 / 虚部分别存储).

在文件 eigen.h 第 28 行定义.

lmmc_eigen_gen_result_t 的协作图:

成员变量
lmmc_vec_t	real_parts	特征值实部数组,长度 n .
lmmc_vec_t	imag_parts	特征值虚部数组,长度 n .

lmmc_eigen_gen_full_result_t

struct lmmc_eigen_gen_full_result_t

一般实矩阵完整特征分解结果(特征值 + 特征向量).

对于实特征值 lambda_i,对应特征向量存储在 vectors_real 的第 i 列, vectors_imag 的第 i 列全为零. 对于共轭复数对 lambda_i = a + bi, lambda_{i+1} = a - bi, 特征向量的实部存储在 vectors_real 的第 i 和 i+1 列, 虚部存储在 vectors_imag 的第 i 列(正号)和第 i+1 列(负号).

在文件 eigen.h 第 42 行定义.

lmmc_eigen_gen_full_result_t 的协作图:

成员变量
lmmc_vec_t	real_parts	特征值实部数组,长度 n .
lmmc_vec_t	imag_parts	特征值虚部数组,长度 n .
lmmc_mat_t	vectors_real	特征向量实部矩阵,nxn .
lmmc_mat_t	vectors_imag	特征向量虚部矩阵,nxn .

lmmc_svd_result_t

struct lmmc_svd_result_t

奇异值分解结果: \(A = U \Sigma V^T\) .

在文件 eigen.h 第 52 行定义.

lmmc_svd_result_t 的协作图:

成员变量
lmmc_mat_t	U	左奇异向量矩阵,mxm .
lmmc_vec_t	sigma	奇异值(降序),长度 min(m,n) .
lmmc_mat_t	Vt	右奇异向量矩阵的转置 V^T ,nxn .

函数说明

lmmc_eigen_symmetric()

lmmc_status_t lmmc_eigen_symmetric	(	const lmmc_mat_t *	a,
		lmmc_eigen_sym_result_t *	out_result )

计算实对称矩阵的全部特征值与特征向量.

算法:公共尺度归一化 -> 安全缩放的 Householder 三对角化 -> 隐式 QL 迭代.特征值按升序排列,第 i 个特征值对应 eigenvectors 的第 i 列.

参数

[in]	a	nxn 对称矩阵(不被修改).
[out]	out_result	输出结果,调用方需配对调用 lmmc_eigen_sym_result_destroy 释放.

返回

• LMMC_STATUS_OK - 成功.
• LMMC_STATUS_INVALID_ARGUMENT - 指针为 NULL 或矩阵非方阵.
• LMMC_STATUS_CONVERGENCE_FAILED - QL 迭代未收敛(超过 30 次).
• LMMC_STATUS_NUMERICAL_FAILURE - 输入含非有限值或结果超出有限数值范围.
• LMMC_STATUS_ALLOCATION_FAILED - 内存分配失败.

副作用

• 分配堆内存(eigenvalues 向量 + eigenvectors 矩阵 + 临时工作空间).
• a 不被修改.

在文件 eigen_symmetric.c 第 334 行定义.

引用了 lmmc_mat_t::cols, lmmc_vec_t::data, lmmc_eigen_sym_result_t::eigenvalues, lmmc_eigen_sym_result_t::eigenvectors, lmmc_eigen_matrix_scale(), lmmc_eigen_sym_result_destroy(), lmmc_eigen_symmetric(), lmmc_mat_create(), lmmc_mat_destroy(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_NUMERICAL_FAILURE, LMMC_STATUS_OK, lmmc_vec_create(), lmmc_vec_destroy(), MAT_ELEM , 以及 lmmc_mat_t::rows.

被这些函数引用 lmmc_eigen_symmetric().

函数调用图:

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

lmmc_eigen_general()

lmmc_status_t lmmc_eigen_general	(	const lmmc_mat_t *	a,
		lmmc_eigen_gen_result_t *	out_result )

计算一般实矩阵的特征值(不输出特征向量).

算法:公共尺度归一化 -> 安全缩放的 Householder Hessenberg 约化 -> Francis 双移位 QR 迭代.复数特征值以共轭对形式出现在 real_parts/imag_parts 中.

参数

[in]	a	nxn 实矩阵(不被修改).
[out]	out_result	输出结果,调用方需配对调用 lmmc_eigen_gen_result_destroy 释放.

返回

• LMMC_STATUS_OK - 成功.
• LMMC_STATUS_INVALID_ARGUMENT - 指针为 NULL 或矩阵非方阵.
• LMMC_STATUS_CONVERGENCE_FAILED - QR 迭代未收敛.
• LMMC_STATUS_ALLOCATION_FAILED - 内存分配失败.
• LMMC_STATUS_NUMERICAL_FAILURE - 输入含非有限值或结果超出有限数值范围.

副作用

• 分配堆内存.a 不被修改.

在文件 eigen_general.c 第 138 行定义.

引用了 lmmc_mat_t::cols, lmmc_eigen_gen_result_t::imag_parts, lmmc_eigen_gen_result_destroy(), lmmc_eigen_general(), lmmc_eigen_matrix_scale(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK, lmmc_vec_create(), lmmc_vec_destroy(), lmmc_eigen_gen_result_t::real_parts , 以及 lmmc_mat_t::rows.

被这些函数引用 lmmc_eigen_general().

函数调用图:

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

lmmc_svd()

lmmc_status_t lmmc_svd	(	const lmmc_mat_t *	a,
		lmmc_svd_result_t *	out_result )

计算奇异值分解:A = U * Σ * V^T.

算法:Householder 双对角化 -> Golub-Kahan 隐式 QR 迭代. 奇异值按降序排列. 有限输入先按最大绝对元素缩放到安全范围，分解后再恢复奇异值尺度， 避免双对角化和 QR 位移中的平方发生中间溢出。

参数

[in]	a	mxn 矩阵(不被修改).
[out]	out_result	输出 U(mxm),sigma(min(m,n)),Vt(nxn). 调用方需配对调用 lmmc_svd_result_destroy 释放.

返回

• LMMC_STATUS_OK - 成功.
• LMMC_STATUS_INVALID_ARGUMENT - 矩阵描述符无效或输出指针为 NULL.
• LMMC_STATUS_NUMERICAL_FAILURE - 输入含非有限值或奇异值不可表示.
• LMMC_STATUS_CONVERGENCE_FAILED - 迭代未收敛.
• LMMC_STATUS_ALLOCATION_FAILED - 内存分配失败.

副作用

• 分配堆内存.a 不被修改.

在文件 eigen_svd.c 第 75 行定义.

引用了 lmmc_mat_t::cols, lmmc_eigen_matrix_scale(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK, lmmc_svd(), lmmc_svd_result_destroy(), lmmc_svd_tall(), lmmc_mat_t::rows , 以及 lmmc_svd_result_t::sigma.

被这些函数引用 lmmc_cond(), lmmc_mat_rank(), lmmc_pinv(), lmmc_std_linalg_svd() , 以及 lmmc_svd().

函数调用图:

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

lmmc_pinv()

lmmc_status_t lmmc_pinv	(	const lmmc_mat_t *	a,
		lmmc_real_t	tol,
		lmmc_mat_t *	out_pinv )

计算 Moore-Penrose 伪逆 A^+。

内部通过 SVD 实现:A^+ = V * Σ^{-1}_trunc * U^T, 仅保留严格大于截断阈值的奇异值，其余项截断为零。

参数

[in]	a	mxn 矩阵(不被修改)。
[in]	tol	奇异值截断阈值;<=0 时使用 max(m,n)*eps*sigma_max。
[out]	out_pinv	nxm 输出矩阵,须已创建。

返回

• LMMC_STATUS_OK - 成功。
• LMMC_STATUS_INVALID_ARGUMENT - 指针为 NULL 或矩阵描述符无效。
• LMMC_STATUS_DIMENSION_MISMATCH - out_pinv 维度与 nxm 不匹配。
• LMMC_STATUS_ALLOCATION_FAILED - 内存分配失败。
• LMMC_STATUS_CONVERGENCE_FAILED - SVD 迭代未收敛。
• LMMC_STATUS_NUMERICAL_FAILURE - 输入、tol、阈值、奇异值、向量因子、 被保留奇异值的倒数或重构中间量非有限。

注解

仅在成功时提交有限结果到 out_pinv->data，保留行步长和填充区。 失败时 out_pinv 保持不变，允许输入与输出存储重叠。 内部分配并释放 SVD 工作空间及临时输出缓冲区。

在文件 eigen_svd.c 第 203 行定义.

引用了 lmmc_mat_t::cols, lmmc_mat_t::data, lmmc_mat_create(), lmmc_mat_destroy(), lmmc_pinv(), LMMC_STATUS_OK, lmmc_svd(), lmmc_svd_result_destroy(), lmmc_mat_t::rows , 以及 lmmc_mat_t::stride.

被这些函数引用 lmmc_pinv().

函数调用图:

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

lmmc_cond()

lmmc_status_t lmmc_cond	(	const lmmc_mat_t *	a,
		lmmc_real_t *	out_cond )

计算矩阵的 2-范数条件数:κ_2(A) = sigma_max / sigma_min.

内部通过 SVD 计算.若 sigma_min ~= 0 则条件数为 Inf.

参数

[in]	a	输入矩阵(不被修改).
[out]	out_cond	输出条件数.

返回

• LMMC_STATUS_OK - 成功.
• LMMC_STATUS_INVALID_ARGUMENT - 指针为 NULL.
• LMMC_STATUS_ALLOCATION_FAILED - 内存分配失败.

副作用

• 内部分配并释放 SVD 工作空间.a 不被修改.

在文件 eigen_svd.c 第 237 行定义.

引用了 lmmc_mat_t::cols, lmmc_mat_t::data, lmmc_vec_t::data, lmmc_cond(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK, lmmc_svd(), lmmc_svd_result_destroy(), lmmc_mat_t::rows, lmmc_svd_result_t::sigma , 以及 lmmc_vec_t::size.

被这些函数引用 lmmc_cond().

函数调用图:

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

lmmc_eigen_general_full()

lmmc_status_t lmmc_eigen_general_full	(	const lmmc_mat_t *	a,
		lmmc_eigen_gen_full_result_t *	out_result )

计算一般实矩阵的特征值与特征向量.

特征值计算复用 lmmc_eigen_general 的公共尺度归一化、稳定 2x2 特征根及 Hessenberg/Francis QR 路径；逆迭代在同一归一化矩阵上执行， 最后只恢复特征值尺度。这样避免维护第二套数值算法及大尺度中间溢出。

参数

[in]	a	含有限元素的 nxn 实矩阵.
[out]	out_result	调用方需用 lmmc_eigen_gen_full_result_destroy 释放.

在文件 eigen_general_vectors.c 第 77 行定义.

引用了 lmmc_mat_t::cols, lmmc_vec_t::data, lmmc_eigen_gen_full_result_t::imag_parts, lmmc_eigen_gen_full_result_destroy(), lmmc_eigen_general_full(), lmmc_eigen_matrix_scale(), lmmc_eigen_vectors_2x2(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK, MAT_ELEM, lmmc_eigen_gen_full_result_t::real_parts, lmmc_mat_t::rows, lmmc_eigen_gen_full_result_t::vectors_imag , 以及 lmmc_eigen_gen_full_result_t::vectors_real.

被这些函数引用 lmmc_eigen_general_full() , 以及 lmmc_std_linalg_eig().

函数调用图:

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

lmmc_eigen_sym_result_destroy()

void lmmc_eigen_sym_result_destroy

(

lmmc_eigen_sym_result_t *

result

)

释放 lmmc_eigen_symmetric 输出结果.

在文件 eigen_symmetric.c 第 377 行定义.

引用了 lmmc_eigen_sym_result_t::eigenvalues, lmmc_eigen_sym_result_t::eigenvectors, lmmc_eigen_sym_result_destroy(), lmmc_mat_destroy() , 以及 lmmc_vec_destroy().

被这些函数引用 lmmc_eigen_sym_result_destroy() , 以及 lmmc_eigen_symmetric().

函数调用图:

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

lmmc_eigen_gen_result_destroy()

void lmmc_eigen_gen_result_destroy

(

lmmc_eigen_gen_result_t *

result

)

释放 lmmc_eigen_general 输出结果.

在文件 eigen_general.c 第 172 行定义.

引用了 lmmc_eigen_gen_result_t::imag_parts, lmmc_eigen_gen_result_destroy(), lmmc_vec_destroy() , 以及 lmmc_eigen_gen_result_t::real_parts.

被这些函数引用 lmmc_eigen_gen_result_destroy() , 以及 lmmc_eigen_general().

函数调用图:

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

lmmc_eigen_gen_full_result_destroy()

void lmmc_eigen_gen_full_result_destroy

(

lmmc_eigen_gen_full_result_t *

result

)

释放 lmmc_eigen_general_full 输出结果.

释放通用特征分解结果持有的向量与矩阵缓冲区。

释放 lmmc_eigen_general_full 输出结果.

在文件 eigen_general_vectors.c 第 14 行定义.

引用了 lmmc_eigen_gen_full_result_t::imag_parts, lmmc_eigen_gen_full_result_destroy(), lmmc_mat_destroy(), lmmc_vec_destroy(), lmmc_eigen_gen_full_result_t::real_parts, lmmc_eigen_gen_full_result_t::vectors_imag , 以及 lmmc_eigen_gen_full_result_t::vectors_real.

被这些函数引用 lmmc_eigen_gen_full_result_destroy(), lmmc_eigen_general_full(), lmmc_std_linalg_eig() , 以及 lmmc_std_linalg_eig_table().

函数调用图:

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

lmmc_svd_result_destroy()

void lmmc_svd_result_destroy

(

lmmc_svd_result_t *

result

)

释放 lmmc_svd 输出结果.

在文件 eigen_svd.c 第 262 行定义.

引用了 lmmc_mat_destroy(), lmmc_svd_result_destroy(), lmmc_vec_destroy(), lmmc_svd_result_t::sigma, lmmc_svd_result_t::U , 以及 lmmc_svd_result_t::Vt.

被这些函数引用 lmmc_cond(), lmmc_mat_rank(), lmmc_pinv(), lmmc_std_linalg_svd(), lmmc_std_linalg_svd_table(), lmmc_svd(), lmmc_svd_result_destroy() , 以及 lmmc_svd_tall().

函数调用图:

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