doc: determinant

Author: perazz

README.md

@@ -70,12 +70,35 @@ Returns the solution array \f$ x \f$ with size \f$ n \f$ (for a single right-han
 - This function relies on LAPACK's least-squares solvers, such as [`*GELSS`](@ref la_lapack::gelss).
 - If `overwrite_a` is enabled, the original contents of `a` and `b` may be lost.
 
-## `det(A)`
-**Type**: Function  
-**Description**: Determinant of a scalar or square matrix.  
-**Optional arguments**:  
-- `overwrite_a`: Option to let A be destroyed.  
-- `err`: Return state handler.
+## [det](@ref la_linalg::det) - Determinant of a scalar or rectangular matrix.
+
+### Syntax
+
+`d = det(a [, overwrite_a] [, err])`
+
+### Description
+
+This function computes the determinant of a square matrix \f$ A \f$. The matrix must be a real matrix of size \f$ [m, n] \f$, and the determinant is computed using an efficient factorization method (e.g., LU decomposition).
+
+### Arguments
+
+- `a`: A real matrix of size \f$ [m, n] \f$, representing the rectangular matrix for which the determinant is calculated. If `overwrite_a`, it is an `inout` argument and may be modified during computation.
+- `overwrite_a` (optional, default = `.false.`): A logical flag that determines whether the input matrix `a` can be overwritten. If `.true.`, the matrix `a` may be destroyed and modified in place to save memory.
+- `err` (optional): A state return flag of  [type(la_state)](@ref la_state_type::la_state). If an error occurs and `err` is not provided, the function will stop execution.
+
+### Return value
+
+The function returns a scalar value representing the determinant of the input matrix \f$ A \f$. The return type is the same as the input matrix (real precision).
+
+### Errors
+
+- Raises [LINALG_VALUE_ERROR](@ref la_state_type::linalg_value_error) if the matrix `a` is not square.
+- If `err` is not provided, the function will stop execution on errors.
+
+### Notes
+
+- The determinant of the matrix is computed using the LAPACK [getrf](@ref la_lapack::getrf) backend.
+- If `overwrite_a` is enabled, the input matrix `a` will be destroyed during the computation process.
 
 ## `inv(A)`
 **Type**: Function  

fypp/src/la_determinant.fypp

@@ -13,10 +13,24 @@ module la_determinant
 
      character(*), parameter :: this = 'determinant'
 
-     ! Numpy: det(a)
-     ! Scipy: det(a, overwrite_a=False, check_finite=True)
-     ! IMSL: DET(a)
-
+     !> @brief Compute the determinant of a rectangular matrix.
+     !!
+     !! This function computes the determinant of a real or complex rectangular matrix \f$ A \f$.
+     !! The determinant is calculated using LU factorization.
+     !!
+     !! @param[in,out] A The input square matrix of size \f$ [m, n] \f$. If `overwrite_a` is true,
+     !!                  the contents of A may be modified during computation.
+     !! @param[in] overwrite_a (Optional) If `.true.`, A may be overwritten and destroyed. Default is `.false.`.
+     !! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided, 
+     !!                 the function will stop execution.
+     !!
+     !! @return The determinant of the matrix \f$ A \f$. The result is a `real` scalar value of the same 
+     !!         kind as the input matrix.
+     !!
+     !! @note This function relies on a matrix factorization approach (e.g., LU decomposition) to compute
+     !!       the determinant efficiently from the [getrf](@ref la_lapack::getrf) backend.
+     !! @warning If `overwrite_a` is enabled, the original contents of A will be lost.
+     !!
      interface det
         #:for rk,rt,ri in ALL_KINDS_TYPES
         module procedure la_${ri}$determinant

src/la_determinant.f90

@@ -7,15 +7,28 @@ module la_determinant
      implicit none(type,external)
      private
 
-     !> Determinant of a rectangular matrix
+     !> @brief Compute the determinant of a rectangular matrix.
+     !!
+     !! This function computes the determinant of a real or complex rectangular matrix \f$ A \f$.
+     !! The determinant is calculated using LU factorization.
+     !!
+     !! @param[in,out] A The input square matrix of size \f$ [m, n] \f$. If `overwrite_a` is true,
+     !!                  the contents of A may be modified during computation.
+     !! @param[in] overwrite_a (Optional) If `.true.`, A may be overwritten and destroyed. Default is `.false.`.
+     !! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided, 
+     !!                 the function will stop execution.
+     !!
+     !! @return The determinant of the matrix \f$ A \f$. The result is a `real` scalar value of the same 
+     !!         kind as the input matrix.
+     !!
+     !! @note This function relies on a matrix factorization approach (e.g., LU decomposition) to compute
+     !!       the determinant efficiently from the [getrf](@ref la_lapack::getrf) backend.
+     !! @warning If `overwrite_a` is enabled, the original contents of A will be lost.
+     !!
      public :: det
 
      character(*),parameter :: this = 'determinant'
 
-     ! Numpy: det(a)
-     ! Scipy: det(a, overwrite_a=False, check_finite=True)
-     ! IMSL: DET(a)
-
      interface det
         module procedure la_sdeterminant
         module procedure la_ddeterminant