迭代算法 — 实现¶

算子契约¶

tiny_operator_f32_t 保存 rows、cols、ctx 与 matvec/rmatvec。matvec 接收 cols 个元素并输出 rows 个；转置回调方向相反。回调返回 tiny_error_t。

Dense 初始化返回错误码，并写入调用者提供的 op 和 ctx；不按值返回算子。step 为行跨距，输入矩阵及上下文必须活到最后一次算子调用，不能保留临时局部对象的地址。

#include "tiny_iterative.h"

float A[6] = {1, 2, 3, 4, 5, 6}; // 2 rows, 3 columns
tiny_dense_operator_ctx_t ctx = {0};
tiny_operator_f32_t op = {0};
tiny_error_t err = tiny_dense_operator_init(&op, &ctx, A, 2, 3, 3);
if (err == TINY_OK) {
    float x[3] = {1, 0, 0};
    float y[2] = {0};
    err = op.matvec(x, y, op.ctx); // y = A*x
}
// A and ctx must outlive every use of op.

如何选择迭代路径¶

方法	前提与用途	需要核对
Arnoldi	方阵算子，建立 Krylov 基与 Hessenberg 矩阵	`n`、迭代数 `k`、基矩阵与输出尺寸
Lanczos	对称问题，生成三对角系数	对称性、重正交与完整 `V` 输出占用
RSVD	近似低秩分解	目标秩、随机投影、工作区及重建误差

三项都有 *_workspace_size 查询接口，工作区与输出由调用者分配。Lanczos 的短递推不代表公共接口仅占两个向量：当前接口还接收完整基矩阵 V。评估内存应计入工作区、输入、上下文和全部输出。

隐式矩阵与近似结果¶

Hankel、Block-Hankel 与协方差算子避免显式构造某些大矩阵，但底层信号/相关序列仍须存在且维度匹配。减少存储不等于乘法运算免费。随机 SVD 应同时报告秩、随机条件及重建残差；奇异值能量阈值不能单独证明物理模态数量。

先按API分配缓冲，再参照矩阵测试核对小矩阵结果与残差。

源码 / Source

当前数值路径的核对要点¶

Dense 初始化检查 step >= cols，但回调向量长度由调用者保证。当前迭代内循环调用 matvec/rmatvec 时没有统一传播回调错误码，进入迭代前应保证算子、尺寸和底层数据有效。

随机 SVD 的当前路径通过 B = AᵀQ 和小矩阵 D = BᵀB 估计奇异值；U 从基 Q 取列，Vt 从 B 的列缩放后归一化。它与下方教科书“小矩阵完整 SVD”的草图并不完全相同。使用返回结果前，应核对 ||A-UΣVᵀ|| 与两侧正交性，不能只凭 TINY_OK 或奇异值数量确认分解质量。