PivotedQrDecomposition

A QR factorization with column pivoting, A·P = Q·R (LAPACK dgeqp3), plus the numerical rank the pivoting revealed.

A separate type from QrDecomposition rather than a nullable pivot array on it, because the two are not interchangeable in the one place it matters: R here factorizes A·P, so feeding factorization to LinearAlgebra.solveLeastSquares returns a solution whose entries are in permuted order — a wrong answer that looks entirely plausible. Making it a distinct type means that mistake does not compile; use LinearAlgebra.solveLeastSquares with this object instead, which undoes the permutation.

factorization is the genuine Q and R of the permuted matrix, so LinearAlgebra.applyQ takes it directly. Nothing is copied: the buffers are the ones the factorization produced.

Column pivoting is what makes QR able to report rank at all. Unpivoted Householder QR is stable but it has no reason to put the dependent columns last, so a rank-deficient matrix leaves small R diagonal entries scattered anywhere and there is nothing to threshold. Pivoting always takes the largest remaining column, which drives |R₀₀| ≥ |R₁₁| ≥ … and pushes the dependence to the trailing entries, so rank is the count of leading diagonal entries above the tolerance.

The rank is a numerical one and the tolerance is a judgement, not a fact — see LinearAlgebra.qrPivoted. A matrix with a genuine gap in its singular values reports the same rank across any sensible tolerance; one without a gap reports whatever the tolerance says, and no factorization can do better. Pivoted QR is also not a rank oracle: it is defeated by contrived matrices (the Kahan matrix being the standard example, where every leading submatrix looks well conditioned), for which an SVD is the honest tool.