Solve with the adjoint of a sparse QR factorization

[ViralBShah]

Fixes #656, and completes the remaining half of #115 (qr(A') already works).

qr(A)' \ b previously threw

ERROR: MethodError: no method matching ldiv!(::AdjointFactorization{Float64, QRSparse{Float64, Int64}}, ::Vector{Float64})

This adds ldiv!(X, ::AdjointFactorization{<:Any,<:QRSparse}, B) plus the corresponding \ methods, so a single factorization of A can be used to solve with both A and A' — the use case from #115.

What it computes

With A[prow, pcol] == Q*R we have A' == Pcol*R'*Q'*Prow, so solving A'x = b is a forward substitution with R' followed by a multiply by Q and the inverse row permutation. It reuses the permutations, workspace and lock of the existing ldiv!, so a solve allocates only the result.

For a tall A the system A'x = b is underdetermined and the minimum-norm solution is returned (the trailing components of Q'x are zeroed), matching qr(A)' \ b for dense A and pinv(A') * b:

julia> A = sprand(3, 100, 0.1);

julia> b = randn(3);

julia> qr(sparse(A'))' \ b ≈ Matrix(A) \ b
true

When A is rank deficient, zeroing the free variables also drops the equations that the leading rank block of R cannot represent — the counterpart of the basic solution that qr(A) \ b already returns.

Wide A is rejected with the same DimensionMismatch("overdetermined systems are not supported") that dense QR throws, since that solve needs a least-squares factorization of A' rather than of A.

Also fixed

\(::Adjoint{<:Any,<:AbstractSparseMatrixCSC}, B) and the Transpose variant already routed non-square matrices through adjoint(qr(A)) \ B, so A' \ b and transpose(A) \ b threw a MethodError for any non-square sparse A. They now work for every shape: a tall A uses the new method above and returns the minimum-norm solution, while a wide A factorizes the sparse transpose and returns the least squares solution, like the dense path.

Relation to #301

#301 wants A \ b to return the minimum-norm solution for wide A, which needs exactly this method (qr(sparse(A'))' \ b). That is a behavior change to \ and is left for a separate PR; this one supplies the missing piece.

Tests

Added to the existing spqr.jl testsets: minimum-norm agreement with the dense Array(A)' \ B over the element-type matrix (real/complex factorization × Int/real/complex rhs, vector and matrix), the Transpose and A' \ b paths, coverage across all SPQR.ORDERINGS (which exercises the empty-cpiv ORDERING_FIXED case), and the dimension-mismatch errors.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CSC6hQqcWDvAuvdkXJstBM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.42%. Comparing base (f4b0d50) to head (c62f30f).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #804      +/-   ##
==========================================
+ Coverage   92.36%   92.42%   +0.05%     
==========================================
  Files          12       12              
  Lines        8632     8682      +50     
==========================================
+ Hits         7973     8024      +51     
+ Misses        659      658       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ViralBShah]

This change was accidentally included in the squash merge of #810. #817 reverts that portion from main; once it lands, this PR merges cleanly against main again and can be reviewed as intended.