document qr

Author: perazz

doc/specs/stdlib_linalg.md

@@ -899,6 +899,54 @@ Exceptions trigger an `error stop`.
 {!example/linalg/example_determinant2.f90!}
 ```
 
+## `qr` - Compute the QR factorization of a matrix. 
+
+### Status
+
+Experimental
+
+### Description
+
+This subroutine computes the QR factorization of a `real` or `complex` matrix: \( A = Q R \). where \( Q \) 
+is orthonormal and \( R \) is upper-triangular. Matrix \( A \) has size `[m,n]`, with \( m \ge n \). 
+
+The results are returned in output matrices \( Q \) and \(R \), that have the same type and kind as \( A \). 
+Given `k = min(m,n)`, one can write \( A = \( Q_1  Q_2 \) \cdot \( \frac{R_1}{0}\) \). 
+Because the lower rows of \( R \) are zeros, the user may require to return full matrices (provide `shape(Q)==[m,m]`, `shape(R)==[m,n]`) 
+or reduced matrices: \( A = Q_1 R_1 \) (provide `shape(Q)==[m,k]`, `shape(R)==[k,n]`).
+
+### Syntax
+
+`call ` [[stdlib_linalg(module):qr(interface)]] `(a, q, r, [, storage] [, overwrite_a] [, err])`
+
+### Arguments
+
+`a`: Shall be a rank-2 `real` or `complex` array containing the coefficient matrix of size `[m,n]`. It is normally an `intent(in)` argument. If `overwrite_a=.true.`, it is an `intent(inout)` argument, and is destroyed upon return.
+
+`q`: Shall be a rank-2 array of the same kind as `a`, containing the orthonormal matrix `q`. It is an `intent(out)` argument. It should have shape either `[m,m]` or `[m,k]` whether the full or the reduced problem is sought for.
+
+`r`: Shall be a rank-2 array of the same kind as `a`, containing the upper triangular matrix `r`. It is an `intent(out)` argument. It should have shape either `[m,n]` or `[k,n]` whether the full or the reduced problem is sought for.
+
+`storage` (optional): Shall be a rank-1 array of the same type and kind as `a`, providing working storage for the solver. It minimum size can be determined with a call to [[stdlib_linalg(module):qr_space(interface)]]. It is an `intent(inout)` argument.
+
+`overwrite_a` (optional): Shall be an input `logical` flag (default: `.false.`). If `.true.`, input matrix `A` will be used as temporary storage and overwritten. This avoids internal data allocation. This is an `intent(in)` argument.
+
+`err` (optional): Shall be a `type(linalg_state_type)` value. This is an `intent(out)` argument.
+
+### Return value
+
+Returns the QR factorization matrices into the \( Q \) and \( R \) arguments. 
+
+Raises `LINALG_VALUE_ERROR` if any of the matrices has invalid or unsuitable size for the full/reduced problem.
+Raises `LINALG_ERROR` on insufficient user storage space.
+If the state argument `err` is not present, exceptions trigger an `error stop`.
+
+### Example
+
+```fortran
+{!example/linalg/example_qr.f90!}
+```
+
 ## `qr_space` - Compute internal working space requirements for the QR factorization.
 
 ### Status

src/stdlib_linalg.fypp

@@ -454,6 +454,28 @@ module stdlib_linalg
 
   ! QR factorization of rank-2 array A
   interface qr
+    !! version: experimental 
+    !!
+    !! Computes the QR factorization of matrix \( A = Q R \). 
+    !! ([Specification](../page/specs/stdlib_linalg.html#qr-compute-the-qr-factorization-of-a-matrix))
+    !! 
+    !!### Summary 
+    !! Compute the QR factorization of a `real` or `complex` matrix: \( A = Q R \), where \( Q \)  is orthonormal 
+    !! and \( R \) is upper-triangular. Matrix \( A \) has size `[m,n]`, with \( m\ge n \). 
+    !!
+    !!### Description
+    !! 
+    !! This interface provides methods for computing the QR factorization of a matrix. 
+    !! Supported data types include `real` and `complex`. If a pre-allocated work space 
+    !! is provided, no internal memory allocations take place when using this interface.
+    !!
+    !! Given `k = min(m,n)`, one can write \( A = \( Q_1  Q_2 \) \cdot \( \frac{R_1}{0}\) \). 
+    !! The user may want the full problem (provide `shape(Q)==[m,m]`, `shape(R)==[m,n]`) or the reduced  
+    !! problem only: \( A = Q_1 R_1 \) (provide `shape(Q)==[m,k]`, `shape(R)==[k,n]`).
+    !! 
+    !!@note The solution is based on LAPACK's QR factorization (`*GEQRF`) and ordered matrix output (`*ORGQR`, `*UNGQR`). 
+    !!@note BLAS/LAPACK backends do not currently support extended precision (``xdp``).
+    !!     
     #:for rk,rt,ri in RC_KINDS_TYPES
     #:if rk!="xdp" 
       pure module subroutine stdlib_linalg_${ri}$_qr(a,q,r,overwrite_a,storage,err)