qr — Compute QR factorizations in MATLAB and RunMat.
qr(A) computes orthogonal/unitary-upper-triangular factorizations of matrix A. Full, economy, and pivoted output forms follow MATLAB semantics.
Syntax
R = qr(A)
R = qr(A, option)
R = qr(A, option1, option2)
[Q, R] = qr(A)
[Q, R] = qr(A, option)
[Q, R] = qr(A, option1, option2)All supported qr forms
R = qr(A)
R = qr(A, option)
R = qr(A, option1, option2)
[Q, R] = qr(A)
[Q, R] = qr(A, option)
[Q, R] = qr(A, option1, option2)
[Q, R, P] = qr(A)
[Q, R, P] = qr(A, option)
[Q, R, P] = qr(A, option1, option2)
[C, R] = qr(S, B)
[C, R] = qr(S, B, option)
[C, R] = qr(S, B, option1, option2)
[C, R, P] = qr(S, B)
[C, R, P] = qr(S, B, option)
[C, R, P] = qr(S, B, option1, option2)Inputs
A- Type
NumericArray- Required
- Yes
- Description
- Input matrix to factorize.
option- Type
StringScalar- Required
- Yes
- Description
- Option token (`0`, `econ`, `matrix`, or `vector`).
option1- Type
StringScalar- Required
- Yes
- Description
- First option token (`0`, `econ`, `matrix`, or `vector`).
option2- Type
StringScalar- Required
- Yes
- Description
- Second option token (`0`, `econ`, `matrix`, or `vector`).
S- Type
NumericArray- Required
- Yes
- Description
- Sparse single or double coefficient matrix.
B- Type
NumericArray- Required
- Yes
- Description
- Dense or sparse floating right-hand sides with the same row count as S.
option- Type
StringScalar- Required
- Yes
- Description
- Option token (0, econ, matrix, or vector).
option2- Type
StringScalar- Required
- Yes
- Description
- Second option token (0, econ, matrix, or vector).
Returns
R- Type
NumericArray- Description
- Upper triangular (or trapezoidal) factor.
Q- Type
NumericArray- Description
- Orthogonal/unitary factor.
P- Type
NumericArray- Description
- Permutation matrix or vector based on pivot mode.
C- Type
NumericArray- Description
- Dense Q' * B, truncated to the economy height when selected; Q is not materialized.
R- Type
NumericArray- Description
- Sparse upper triangular or trapezoidal factor in the coefficient class.
P- Type
NumericArray- Description
- Sparse double permutation matrix or dense one-based double column index vector.
Returned values from qr depend on how many outputs the caller requests.
Errors
RunMat:qr:InvalidArgument- When
- Options are invalid or output count exceeds supported forms.
- Message
qr currently supports at most three outputs
RunMat:qr:InvalidInput- When
- Input is non-numeric or has rank greater than two.
- Message
qr: expected a numeric 2-D input matrix
RunMat:qr:Internal- When
- QR runtime fails to materialize output values.
- Message
qr: internal runtime failure
Behavior
Single output: R = qr(A) returns the upper-triangular (or upper-trapezoidal) factor of the unpivoted decomposition A = Q * R without materializing Q.
Two outputs: [Q, R] = qr(A) yields the orthonormal/unitary factor Q and the upper-triangular R such that Q * R = A; the input columns are not permuted.
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: when m ≥ n, Q is m × n and R is n × n; for wide matrices (m < n) the economy form equals the full form. The legacy numeric-zero syntax selects vector permutation output when a third output is requested.
Public MATLAB matrix classes are single and double. RunMat mode separately admits logical matrices and every real integer class through named extensions; integer matrix values cross only after exact binary64 representability checks. Scalars and vectors are treated as 1-D or 2-D dense arrays.
Typed-integer and logical zero economy selectors are separately gated RunMat extensions. An explicit resident option is independently gated and read through its exact owner; nonzero or nonscalar numeric options reject.
Integer inputs never enter a floating provider QR kernel. Resident integer input gathers through its exact owner, computes double factors, and restores only requested outputs through checked class-preserving uploads. Unsupported transfers report an error.
Sparse factors and transformed right-hand sides
Sparse single and double coefficients, real or complex, use native-class sparse Householder factors without a dense coefficient copy. R and matrix-form P are sparse; explicit Q is dense. Complex coefficient storage remains complex even for empty or numerically real factors. Sparse integer and logical coefficients are not admitted by this route.
Three-output sparse QR chooses columns with a structural fill-reducing heuristic, not the dense descending-diagonal rank ordering. The exact pivot order is implementation-dependent. Public factors do not discard small nonzero columns using the separate minimum-norm solver's numerical-rank tolerance.
For sparse S, [C,R] = qr(S,B) returns C = Q' * B without constructing Q. B may be dense or sparse, single or double, real or complex, with the same row count as S. C uses S's floating class, is complex if either operand is complex, and is dense. The three-output form additionally satisfies S*P = Q*R. Economy size keeps the first min(m,n) rows of C and R. An m-by-zero B produces the correctly shaped empty C without a Q basis or column workspace.
Sparse factor fill, replacement overlap, output storage and permutation storage are admitted from the actual execution owner. Long sparse traversals and publication validate cooperation and the original allocation authority; errors preserve their cause and do not retry after factor execution.
Acceleration and residency
For a resident input, RunMat selects the handle's exact provider owner for the QR hook. The bundled WGPU backend computes ordinary QR through its host implementation and re-uploads only the requested output form as gpuTensor handles.
If the exact owner has no QR hook, RunMat downloads through that owner without changing the input's residency, computes CPU factors, and uploads all requested outputs with their classes and device intent preserved. Unsupported uploads and provider failures report an error; they do not return a partial or mixed-residency result.
The economy two-output power-iteration optimization uses its unpivoted device route when eligible; a three-output pivoted request uses the correctness-oriented factorization path.
Examples
Solving with sparse QR without constructing Q
S = sparse([1 0; 0 2; 1 1]); B = [1; 2; 0];
[C,R,p] = qr(S,B,'econ','vector');
y = R \ C; x = zeros(2,1); x(p) = y;Obtaining sparse R without an explicit Q
S = sparse([1 0; 0 2; 1 1]);
[C,R] = qr(S,zeros(3,0),'econ');Computing the full QR factorization of a square matrix
A = [12 -51 4; 6 167 -68; -4 24 -41];
[Q, R] = qr(A)Obtaining orthonormal Q and upper-triangular R for a tall matrix
A = [1 2; 3 4; 5 6];
[Q, R] = qr(A)Working with column pivoting when requesting three outputs
A = [1 1 0; 1 0 1; 0 1 1];
[Q, R, E] = qr(A)Using economy-size QR to reduce memory footprint
A = randn(1000, 20);
[Q, R] = qr(A, 0)Receiving the permutation vector instead of a matrix
A = magic(4);
[Q, R, p] = qr(A, 'vector')Running QR on a gpuArray input (with automatic fallback)
G = gpuArray(rand(256, 64));
[Q, R] = qr(G, 'econ');
class(Q)Using qr with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how qr changes the result.
Run a small qr example, explain the result, then change one input and compare the output.
FAQ
Does qr(A) always perform column pivoting?⌄
No. One or two outputs use the original column order and satisfy A = Q * R. Three outputs request column pivoting and return the permutation satisfying A * P = Q * R.
How do I request the reduced (economy) factors?⌄
Pass numeric 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. Complex single and double inputs use complex Householder reflectors, and Q and R retain the input floating class.
What precision do the returned factors use?⌄
For dense single input, Q and R retain single precision; double, logical, and gated exact-integer inputs produce double factors. Matrix and one-based vector permutation outputs are double. Resident factors retain the source's physical floating class, while the permutation output remains double when the exact owner supports that transfer.
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 rejects more than two option arguments. The 'matrix' and 'vector' permutation forms require three requested outputs.
Do gpuArray outputs stay on the device?⌄
The exact owner is used for the QR hook. Bundled WGPU stages ordinary QR through its host implementation and uploads the requested factors. If the hook is unavailable, host fallback restores all requested outputs through checked uploads; unsupported transfers report an error rather than silently leaving outputs on the host.
How can I verify the factorisation?⌄
For two outputs, check Q'*Q ≈ I and Q*R ≈ A. For three outputs, check Q*R ≈ A*P, or Q*R ≈ A(:,p) for a permutation vector.
Related Linalg functions
Factor
chol · decomposition · decomposition.ctranspose · decomposition.mldivide · decomposition.mrdivide · decomposition.mtimes · decomposition.rdivide · decomposition.subsref · decomposition.times · decomposition.uminus · decomposition.uplus · eig · eigs · gmres · ichol · ilu · lu · ordeig · ordqz · ordschur · pcg · qz · rsf2csf · schur · svd
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Source you can read
Every RunMat function's source is public. Read exactly how qr is executed, line by line, in Rust.
- View the source for qr in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.