What does the `qr` function do in MATLAB / RunMat?

qr(A) computes an orthogonal (or unitary)–upper-triangular factorization of a real or complex matrix A. It matches MATLAB’s dense semantics, supporting full-size, economy-size, and column-pivoted variants.

How does the `qr` function behave in MATLAB / RunMat?

Single output: R = qr(A) returns the upper-triangular (or upper-trapezoidal) factor. Column pivoting is applied implicitly for numerical stability.
Two outputs: [Q, R] = qr(A) yields the orthonormal/unitary factor Q and the upper-triangular R such that Q * R = A * E, where E is the column permutation matrix selected during factorization. When you omit E, the columns of R already appear in that permuted order.
Three outputs: [Q, R, E] = qr(A) additionally returns the column permutation so that A * E = Q * R. Use the 'vector' option to receive a pivot vector instead of a permutation matrix.
Economy size: qr(A, 0) or qr(A, 'econ') returns the reduced-size factors, mirroring MATLAB’s behaviour: when m ≥ n, Q is m × n and R is n × n. For wide matrices (m < n) the economy form equals the full form.
Logical inputs are promoted to double precision. Scalars and vectors are treated as 1-D or 2-D dense arrays.

GPU execution in RunMat

When the active acceleration provider exposes the dedicated QR hook (the bundled WGPU backend does), RunMat stages the input through the provider, performs the factorisation via the runtime implementation, and re-uploads all outputs so they remain resident as gpuTensor handles.
If no provider hook is present, RunMat gathers the input to the host, performs the CPU factorisation, and leaves the outputs on the host until an explicit gpuArray request.

Examples of using the `qr` function in MATLAB / RunMat

Computing the full QR factorization of a square matrix

A = [12 -51 4; 6 167 -68; -4 24 -41];
[Q, R] = qr(A);

Q is orthogonal and R is upper-triangular. The product Q * R reconstructs A.

Obtaining orthonormal Q and upper-triangular R for a tall matrix

A = [1 2; 3 4; 5 6];
[Q, R] = qr(A);

Q is 3×3, R is 3×2, and Q * R equals A.

Working with column pivoting when requesting three outputs

A = [1 1 0; 1 0 1; 0 1 1];
[Q, R, E] = qr(A);

E is a permutation matrix that reorders the columns of A to maximise numerical stability.

Using economy-size QR to reduce memory footprint

A = randn(1000, 20);
[Q, R] = qr(A, 0);

Here Q is 1000×20 and R is 20×20, reducing memory usage compared with the full factors.

Receiving the permutation vector instead of a matrix

A = magic(4);
[Q, R, p] = qr(A, 'vector');

p is a column vector of 1-based indices satisfying A(:,p) = Q*R.

Running QR on a gpuArray input (with automatic fallback)

G = gpuArray(rand(256, 64));
[Q, R] = qr(G, 'econ');
class(Q)

The default WGPU provider keeps the operands on the device by staging through its upload path, while other providers fall back to the CPU implementation and re-upload results automatically when possible.

FAQ

Does `qr(A)` always perform column pivoting?

Yes. MATLAB switched to pivoted QR for the single-output form many releases ago; RunMat mirrors that behaviour for improved numerical stability.

How do I request the reduced (economy) factors?

Pass 0, '0', or 'econ' as the second argument. For example, [Q,R] = qr(A,0) or [Q,R] = qr(A,'econ').

How can I obtain the permutation vector instead of a matrix?

Add the option 'vector', e.g., [Q,R,p] = qr(A,'vector'). When you also request economy size, use [Q,R,p] = qr(A,'econ','vector').

Are complex matrices supported?

Yes. Inputs of type complex double produce complex orthonormal factors using complex Householder reflectors.

What precision do the returned factors use?

The builtin always produces double-precision (or complex double) outputs, matching MATLAB’s dense QR behaviour.

Can I call `qr` on logical arrays?

Yes. Logical inputs are converted to double precision before factorisation.

What happens if I pass more than two option arguments?

The builtin raises a MATLAB-compatible error (qr: too many option arguments). Only one size option and one permutation option are accepted.

Do gpuArray outputs stay on the device?

Yes when an acceleration provider exposes the QR hook; the bundled WGPU backend does so by staging through the host implementation and re-uploading the factors. Otherwise RunMat gathers the data to the host, factors it there, and uploads the results back automatically.

How can I verify the factorisation?

Check that Q'*Q is (approximately) the identity matrix and that Q*R equals A*E. For vector permutations, A(:,p) reproduces the pivoted columns.

Source & Feedback

Source: crates/runmat-runtime/src/builtins/math/linalg/factor/qr.rs
Issues & feedback: RunMat issue tracker

What does the qr function do in MATLAB / RunMat?

How does the qr function behave in MATLAB / RunMat?