document qr_space

Author: perazz

doc/specs/stdlib_linalg.md

@@ -898,3 +898,31 @@ Exceptions trigger an `error stop`.
 ```fortran
 {!example/linalg/example_determinant2.f90!}
 ```
+
+## `qr_space` - Compute internal working space requirements for the QR factorization.
+
+### Status
+
+Experimental
+
+### Description
+
+This subroutine computes the internal working space requirements for the QR factorization, [[stdlib_linalg(module):qr(interface)]] .
+
+### Syntax
+
+`call ` [[stdlib_linalg(module):qr_space(interface)]] `(a, lwork, [, err])`
+
+### Arguments
+
+`a`: Shall be a rank-2 `real` or `complex` array containing the coefficient matrix. It is an `intent(in)` argument.
+
+`lwork`: Shall be an `integer` scalar, that returns the minimum array size required for the working storage in [[stdlib_linalg(module):qr(interface)]] to factorize `a`.
+
+`err` (optional): Shall be a `type(linalg_state_type)` value. This is an `intent(out)` argument.
+
+### Example
+
+```fortran
+{!example/linalg/example_qr_space.f90!}
+```

src/stdlib_linalg.fypp

@@ -476,6 +476,19 @@ module stdlib_linalg
 
   ! Return the working array space required by the QR factorization solver
   interface qr_space
+    !! version: experimental 
+    !!
+    !! Computes the working array space required by the QR factorization solver
+    !! ([Specification](../page/specs/stdlib_linalg.html#qr-space-compute-internal-working-space-requirements-for-the-qr-factorization))
+    !! 
+    !!### Description
+    !! 
+    !! This interface returns the size of the `real` or `complex` working storage required by the 
+    !! QR factorization solver. The working size only depends on the kind (`real` or `complex`) and size of
+    !! the matrix being factorized. Storage size can be used to pre-allocate a working array in case several 
+    !! repeated QR factorizations to a same-size matrix are sought. If pre-allocated working arrays 
+    !! are provided, no internal allocations will take place during the factorization.
+    !!     
     #:for rk,rt,ri in RC_KINDS_TYPES
     #:if rk!="xdp" 
       pure module subroutine get_qr_${ri}$_workspace(a,lwork,err)