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 info value is written to stage 0 of status, its orgqr info value 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 n

  • status – 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 info value is written to stage 0 of status 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, 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 n

  • status – 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);