feat: add column pivoting to the QR decomposition

[tayal-sarthak]

Closes #125.

Summary

The issue asks for a QR decomposition with column pivoting, so that a least square problem whose matrix is not of full rank can be solved, the way LINEST does. The references gathered in the thread are the LAPACK guide on rank deficient least squares along with the nalgebra implementation.

The reported symptom is that QrDecomposition.solve gives up on a matrix that is not of full rank. What happens is worse than giving up. Take a 4x3 matrix whose third column is twice the second minus the first:

const a = new Matrix([[1, 2, 3], [2, 4, 6], [1, 1, 1], [3, 5, 7]]);
new QrDecomposition(a).isFullRank();                          // true
new QrDecomposition(a).solve(Matrix.columnVector([1, 2, 3, 4]));
// [[-105750241941101.58], [211500483882210.1], [-105750241941105.95]]

isFullRank compares the diagonal of R against exact zero, which rounding almost never produces, so the guard lets the matrix through and the caller receives values around 1e14 with no warning.

What pivoting gives

At each step the column carrying the largest remaining norm is moved into place. The diagonal of R then comes out non increasing, which is what makes the rank readable: the negligible entries collect at the end rather than sitting anywhere along the diagonal.

new QrDecomposition(value, { pivoting: true });

• rank counts the diagonal entries of R above max(m, n) * max|Rdiag| * EPSILON.
• columnPermutationVector gives the column of the input sitting at each position, so that A[:, columnPermutationVector] = Q R.
• solve returns the basic solution when the input is not of full rank, the one holding at most rank non zero components with the rest pinned to zero. The rows are permuted back so they line up with the columns of the input.

On the matrix above, rank reports 2, and the solution satisfies the normal equations, Aᵀ(Ax - b) coming out at 1e-14 rather than the 1e14 seen before.

Compatibility

pivoting is off by default and every existing path is untouched. Without it the permutation is the identity, solve still refuses a matrix that is not of full rank with the same message, and isFullRank keeps its exact zero comparison.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 69.59%. Comparing base (1a4a05a) to head (faf6151).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #219      +/-   ##
==========================================
+ Coverage   68.88%   69.59%   +0.70%     
==========================================
  Files          49       49              
  Lines        5904     5976      +72     
  Branches     1060     1098      +38     
==========================================
+ Hits         4067     4159      +92     
+ Misses       1824     1804      -20     
  Partials       13       13              

☔ 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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.