document QR

Author: perazz

README.md

@@ -5,7 +5,9 @@ A full and standardized implementation of the present library has been integrate
 
 # Browse API
 
-## [`solve`](@ref la_solve::solve) - Solves a linear matrix equation or a linear system of equations.
+All procedures work with all types (`real`, `complex`) and kinds (32, 64, 128-bit floats).
+
+## [`solve`](@ref la_solve::solve) - Solve a linear matrix equation or a linear system of equations.
 
 ### Syntax
 
@@ -32,7 +34,7 @@ For a full-rank matrix, returns an array value that represents the solution to t
 - Raises [`LINALG_VALUE_ERROR`](@ref la_state_type::linalg_value_error) if the matrix and rhs vectors have invalid/incompatible sizes.
 - If `err` is not present, exceptions trigger an `error stop`.
 
-## [`lstsq`](@ref la_least_squares::lstsq) - Computes a least squares solution to a system of linear equations.
+## [`lstsq`](@ref la_least_squares::lstsq) - Compute a least squares solution to a system of linear equations.
 
 ### Syntax
 
@@ -176,20 +178,83 @@ Returns the solution array \f$ x \f$ with size \f$ n \f$ (for a single right-han
 **Optional arguments**:  
 - `err`: Error handler.
 
-## `qr(A, Q, R)`
-**Type**: Subroutine  
-**Description**: QR factorization.  
-**Optional arguments**:  
-- `storage`: Pre-allocated working storage.  
-- `err`: Error handler.
+## [`qr`](@ref la_qr::qr) - Compute the QR factorization of a matrix.
 
-## `qr_space(A, lwork)`
-**Type**: Subroutine  
-**Description**: QR Working space size.  
-**Optional arguments**:  
-- `err`: Error handler.
+### Syntax
+
+`call qr(a, q, r [, overwrite_a] [, storage] [, err])`
+
+### Description
+
+This subroutine computes the QR factorization of a `real` or `complex` matrix \f$ A = Q \cdot R \f$, where \f$ Q \f$ is orthonormal and \f$ R \f$ is upper-triangular. The matrix \f$ A \f$ has size \f$ [m,n] \f$ with \f$ m \ge n \f$. The result is returned in the output matrices \f$ Q \f$ and \f$ R \f$, which have the same type and kind as \f$ A \f$. 
+
+Given \f$ k = \min(m, n) \f$, the matrix \f$ A \f$ can be written as:
+
+\f[
+A = \left( \begin{array}{cc} Q_1 & Q_2 \end{array} \right) \cdot \left( \begin{array}{cc} R_1 & 0 \end{array} \right)
+\f]
+
+Because the lower rows of \f$ R \f$ are zeros, a reduced problem \f$ A = Q_1 R_1 \f$ can be solved. The size of the input matrices determines which problem is solved:
+- For full matrices (`shape(Q) == [m,m]`, `shape(R) == [m,n]`), the full problem is solved.
+- For reduced matrices (`shape(Q) == [m,k]`, `shape(R) == [k,n]`), the reduced problem is solved.
+
+### Arguments
+
+- `a`: A `real` or `complex` matrix of size \f$ [m,n] \f$, representing the coefficient matrix. If `overwrite_a = .false.`, this is an input argument. If `overwrite_a = .true.`, it is an `inout` argument and is overwritten upon return.
+- `q`: A rank-2 array of the same type and kind as `a`, representing the orthonormal matrix \f$ Q \f$. This is an output argument with shape \f$ [m,m] \f$ (for the full problem) or \f$ [m,k] \f$ (for the reduced problem).
+- `r`: A rank-2 array of the same type and kind as `a`, representing the upper-triangular matrix \f$ R \f$. This is an output argument with shape \f$ [m,n] \f$ (for the full problem) or \f$ [k,n] \f$ (for the reduced problem).
+- `storage` (optional): A rank-1 array of the same type and kind as `a`, providing working storage for the solver. Its minimum size can be determined by a call to [`qr_space`](@ref la_qr::qr_space). This is an output argument.
+- `overwrite_a` (optional, default = `.false.`): A logical flag that determines whether the input matrix `a` can be overwritten. If `.true.`, the matrix `a` is used as temporary storage and overwritten to avoid internal memory allocation. This is an input argument.
+- `err` (optional): A [`type(la_state)`](@ref la_state_type::la_state) variable that returns the error state. If not provided, the function will stop execution on error.
+
+### Return value
+
+The QR factorization matrices \f$ Q \f$ and \f$ R \f$ are returned in the corresponding arguments.
+
+### Errors
+
+- Raises [`LINALG_VALUE_ERROR`](@ref la_state_type::linalg_value_error) if the sizes of the matrices are incompatible with the full/reduced problem.
+- Raises [`LINALG_ERROR`](@ref la_state_type::linalg_error) if there is insufficient storage space.
+- If `err` is not provided, exceptions will trigger an `error stop`.
+
+### Notes
+
+- This subroutine computes the QR factorization using LAPACK's QR decomposition algorithm [`*GEQRF`](@ref la_lapack::geqrf).
+- If `overwrite_a` is enabled, the input matrix `a` will be modified during computation.
+
+
+## [`qr_space`](@ref la_qr::qr_space) - Workspace size for QR operations.
+
+### Syntax
+
+`call qr_space(a, lwork [, err])`
+
+### Description
+
+This subroutine computes the minimum workspace size required for performing QR factorization. The size of the workspace array needed for both QR factorization and solving the reduced problem is determined based on the input matrix \f$ A \f$.
+
+The input matrix \f$ A \f$ has size \f$ [m,n] \f$, and the output value \f$ lwork \f$ represents the minimum size of the workspace array that should be allocated for QR operations.
+
+### Arguments
+
+- `a`: A `real` or `complex` matrix of size \f$ [m,n] \f$, representing the input matrix used to determine the required workspace size.
+- `lwork`: An integer variable that will return the minimum workspace size required for QR factorization.
+- `err` (optional): A [`type(la_state)`](@ref la_state_type::la_state) variable that returns the error state. If not provided, the function will stop execution on error.
+
+### Return value
+
+The workspace size \f$ lwork \f$ that should be allocated before calling the QR factorization routine is returned.
+
+### Errors
+
+- Raises [`LINALG_ERROR`](@ref la_state_type::linalg_error) if there is an issue determining the required workspace size.
+- If `err` is not provided, exceptions will trigger an `error stop`.
+
+### Notes
+
+- This subroutine is useful for preallocating memory for QR factorization in large systems.
+- It is important to ensure that the workspace size is correctly allocated before proceeding with QR factorization to avoid memory issues.
 
-All procedures work with all types (`real`, `complex`) and kinds (32, 64, 128-bit floats).
 
 # BLAS, LAPACK
 Modern Fortran modules with full explicit typing features are available as modules `la_blas` and `la_lapack`. 

fypp/src/la_qr.fypp

@@ -1,4 +1,5 @@
 #:include "common.fypp"
+!> QR factorization of a matrix
 module la_qr
      use la_constants
      use la_blas
@@ -8,13 +9,52 @@ module la_qr
      implicit none(type,external)
      private
 
-     !> QR factorization of a matrix
+     !> @brief Compute the QR factorization of a matrix.
+     !!
+     !! This subroutine computes the QR factorization of a real or complex matrix:
+     !!
+     !! \f$ A = Q \cdot R \f$
+     !!
+     !! where \f$ A \f$ is a matrix of size \f$ [m,n] \f$ with \f$ m \ge n \f$,
+     !! \f$ Q \f$ is an orthonormal matrix, and \f$ R \f$ is an upper-triangular matrix. 
+     !! The result is returned in the output matrices \f$ Q \f$ and \f$ R \f$, which are of the same type and kind as \f$ A \f$.
+     !! The function can solve both full and reduced problems depending on the sizes of the matrices.
+     !!
+     !! @param[in,out] a The input matrix of size \f$ [m,n] \f$. If `overwrite_a` is true, 
+     !!                   the contents of `a` may be modified during computation.
+     !! @param[out] q The orthonormal matrix \f$ Q \f$, with shape \f$ [m,m] \f$ for the full problem or \f$ [m,k] \f$ for the reduced problem.
+     !! @param[out] r The upper-triangular matrix \f$ R \f$, with shape \f$ [m,n] \f$ for the full problem or \f$ [k,n] \f$ for the reduced problem.
+     !! @param[in] overwrite_a (Optional) A logical flag that determines whether matrix `a` may be overwritten. Default is false.
+     !! @param[in,out] storage (Optional) Pre-allocated workspace array for intermediate calculations. Its size is checked with [`qr_space`](@ref la_qr::qr_space).
+     !! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided, the function will stop execution.
+     !!
+     !! @return The QR factorization matrices \f$ Q \f$ and \f$ R \f$ are returned in the corresponding output arguments.
+     !!
+     !! @note This subroutine uses LAPACK's QR decomposition algorithm [`*GEQRF`](@ref la_lapack::geqrf) to compute the factorization.
+     !!
+     !! @warning If `overwrite_a` is enabled, the original contents of `a` may be lost during computation.
+     !!
      public :: qr
+     
+     
+     !> @brief Get the required workspace size for QR factorization.
+     !!
+     !! This subroutine returns the minimum workspace size required for performing QR factorization.
+     !! It computes the size of the workspace array that is necessary for both QR factorization 
+     !! and solving the reduced problem, depending on the input matrix.
+     !!
+     !! @param[in] a The input matrix of size \f$ [m,n] \f$. This matrix is used to determine the required workspace size.
+     !! @param[out] lwork The minimum size of the workspace array needed for QR operations.
+     !! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided, the function will stop execution.
+     !!
+     !! @return The size of the workspace array `lwork` that should be allocated before calling the QR factorization routine.
+     !!
+     !! @note This subroutine is useful for preallocating memory for QR factorization in large systems.
+     !!
+     !! @warning If `err` is not provided, the function will stop execution on error.
+     !!
      public :: qr_space
 
-     ! Scipy: solve(a, b, lower=False, overwrite_a=False, overwrite_b=False, check_finite=True, assume_a='gen', transposed=False)[source]#
-     ! IMSL: lu_solve(a, b, transpose=False)
-
      interface qr
         #:for rk,rt,ri in ALL_KINDS_TYPES
         module procedure la_${ri}$_qr

project/doxygen/Doxyfile

@@ -379,7 +379,7 @@ GENERATE_TREEVIEW      = YES
 FULL_SIDEBAR           = NO
 TREEVIEW_WIDTH         = 250
 EXT_LINKS_IN_WINDOW    = NO
-FORMULA_FONTSIZE       = 15.6
+FORMULA_FONTSIZE       = 16
 USE_MATHJAX            = NO
 MATHJAX_RELPATH        = http://www.mathjax.org/mathjax
 SEARCHENGINE           = YES