qr#
Perform a QR decomposition.
Added in version 0.6.0.
Note
The mtie assignment forms of qr, qr_econ, and qr_solver use the normal non-JIT solver path.
CUDA JIT fusion is available through lazy projection members such as qr(A).Q, qr(A).R,
qr_econ(A).Q, qr_econ(A).R, qr_solver(A).Out, and qr_solver(A).Tau when
-DMATX_EN_MATHDX=ON is enabled and the runtime shape/type is supported by cuSolverDx. Projection JIT
currently supports ranks 2 through 4 and float, double, complex<float>, and
complex<double> inputs. The full qr projection path is limited to square matrices to preserve its full
Q/R output contract. qr_econ(A).Q JIT fusion is currently limited to non-wide matrices where m >= n;
qr_econ(A).R and qr_solver projections support rectangular matrices when cuSolverDx supports the shape.
Projections created with a solver status do not support JIT fusion.
Note
QR completes for singular and rank-deficient inputs. The info values reported by cuSolver and LAPACK only
flag illegal arguments, so rank deficiency or ill-conditioning must be detected from the diagonal of R.
-
template<typename AType>
__MATX_INLINE__ auto matx::qr(const AType &A)# Perform QR decomposition on a matrix using housholders reflections.
If rank > 2, operations are batched.
- Template Parameters:
AType – Tensor or operator type for output of A input tensors.
- Parameters:
A – Input tensor or operator for tensor A input.
- Returns:
Operator to generate Q/R outputs
Note
This function is currently not supported with host-based executors (CPU), and performs a full QR decomposition of a tensor A with shape … x m x n, where Q is shaped … x m x m and R is shaped … x m x n.
Examples#
(mtie(Q, R) = qr(A)).run(exec);
Projection Examples#
Lazy Q and R projections can be used directly with other operators. This example is included from the
ProjectionAPI unit test in QR2.cu.
auto op = qr(A);
(QR = matmul(op.Q, op.R)).run(exec);
-
template<typename OpA>
__MATX_INLINE__ auto matx::qr_econ(const OpA &a)# Perform an economic QR decomposition on a matrix using cuSolver.
If rank > 2, operations are batched.
- Template Parameters:
OpA – Data type of input a tensor or operator
- Parameters:
a – Input tensor or operator of shape
... x m x n- Returns:
Operator that produces QR outputs.
Q - Of shape
... x m x min(m, n), the reduced orthonormal basis for the span of A.R - Upper triangular matrix of shape
... x min(m, n) x n.
-
template<typename OpA>
__MATX_INLINE__ auto matx::qr_econ(const OpA &a, const SolverStatus &status)# Perform an economic QR decomposition on a matrix using cuSolver, reporting per-matrix errors through a solver status.
Same as qr_econ(a), except each matrix’s geqrf
infovalue is written to stage 0 ofstatus, its orgqrinfovalue to stage 1, and, on CUDA executors, the call does not synchronize the stream (see the Solver Status docs for when it can). Check the result after synchronizing, as for qr_solver(a, status). Not supported with CUDAJITExecutor.- Template Parameters:
OpA – Data type of input a tensor or operator
- Parameters:
a – Input tensor or operator of shape
... x m x nstatus – Solver status with at least two stages, created with make_solver_status() for an input shaped like
a, used only with qr_econ()
- Returns:
Operator that produces QR outputs.
Note
The overload that takes a solver status writes each matrix’s geqrf and orgqr info
values into the status instead of synchronizing the stream to check them. The status needs at least two stages.
Note
This function is currently not supported with host-based executors (CPU). It returns an economic QR decomposition, where Q/R are shaped m x k and k x n respectively, where k = min(m, n). This is useful when m >> n to save memory and computation time.
Examples#
(mtie(Q, R) = qr_econ(A)).run(exec);
Projection Examples#
The economic Q and R projections have shapes ... x m x k and ... x k x n, so they can be multiplied
to reconstruct the original input. This example is included from the ProjectionAPI unit test in QREcon.cu.
auto op = qr_econ(A);
(QR = matmul(op.Q, op.R)).run(exec);
-
template<typename OpA>
__MATX_INLINE__ auto matx::qr_solver(const OpA &a)# Perform a QR decomposition on a matrix using cuSolver or a LAPACK host library.
If rank > 2, operations are batched.
- Template Parameters:
OpA – Data type of input a tensor or operator
- Parameters:
a – Input tensor or operator of shape
... x m x n- Returns:
Operator that produces R/householder vectors and tau tensor outputs.
Out - Of shape
... x m x n. The householder vectors are returned in the bottom half and R is returned in the top half.Tau - The scalar factors tau of shape
... x min(m, n).
-
template<typename OpA>
__MATX_INLINE__ auto matx::qr_solver(const OpA &a, const SolverStatus &status)# Perform a QR decomposition on a matrix using cuSolver or a LAPACK host library, reporting per-matrix errors through a solver status.
Same as qr_solver(a), except each matrix’s geqrf
infovalue is written to stage 0 ofstatusand, on CUDA executors, the call does not synchronize the stream (see the Solver Status docs for when it can). Check the result after synchronizing, with status.ok(exec) or status.check(exec), or with status.ok() or status.check() after your own stream or event synchronization. Not supported with CUDAJITExecutor.- Template Parameters:
OpA – Data type of input a tensor or operator
- Parameters:
a – Input tensor or operator of shape
... x m x nstatus – Solver status created with make_solver_status() for an input shaped like
a, used only with qr_solver()
- Returns:
Operator that produces R/householder vectors and tau tensor outputs.
Note
The overload that takes a solver status writes each matrix’s geqrf info value into
the status instead of synchronizing the stream to check it.
Note
This function does not return Q explicitly as it only runs geqrf from LAPACK/cuSolver.
For full or economic Q/R, use qr or qr_econ on a CUDA executor.
Examples#
(mtie(Av, TauV) = qr_solver(Av)).run(this->exec);
Projection Examples#
qr_solver exposes the raw Out factor storage and Tau Householder coefficients. This example is included
from the CuSolverDxSingleMatrixQRSolverProjectionJIT unit test.
auto op = qr_solver(A);
(Combined = op.Out + clone<2>(op.Tau, {rows, matxKeepDim})).run(exec);