Merge branch 'master' into linalg_solve

doc/specs/stdlib_linalg.md

@@ -649,3 +649,77 @@ Exceptions trigger an `error stop`.
 
 {!example/linalg/example_solve2.f90!}
 ```
+
+## `det` - Computes the determinant of a square matrix
+
+### Status
+
+Experimental
+
+### Description
+
+This function computes the determinant of a `real` or `complex` square matrix.
+
+This interface comes with a `pure` version `det(a)`, and a non-pure version `det(a,overwrite_a,err)` that
+allows for more expert control.
+
+### Syntax
+
+`c = ` [[stdlib_linalg(module):det(interface)]] `(a [, overwrite_a, err])`
+
+### Arguments
+
+`a`: Shall be a rank-2 square array
+
+`overwrite_a` (optional): Shall be an input `logical` flag. 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 a `real` scalar value of the same kind of `a` that represents the determinant of the matrix.
+
+Raises `LINALG_ERROR` if the matrix is singular.
+Raises `LINALG_VALUE_ERROR` if the matrix is non-square.
+Exceptions are returned to the `err` argument if provided; an `error stop` is triggered otherwise.
+
+### Example
+
+```fortran
+{!example/linalg/example_determinant.f90!}
+```
+
+## `.det.` - Determinant operator of a square matrix
+
+### Status
+
+Experimental
+
+### Description
+
+This operator returns the determinant of a real square matrix.
+
+This interface is equivalent to the `pure` version of determinant [[stdlib_linalg(module):det(interface)]]. 
+
+### Syntax
+
+`c = ` [[stdlib_linalg(module):operator(.det.)(interface)]] `(a)`
+
+### Arguments
+
+`a`: Shall be a rank-2 square array of any `real` or `complex` kinds. It is an `intent(in)` argument.
+
+### Return value
+
+Returns a real scalar value that represents the determinnt of the matrix.
+
+Raises `LINALG_ERROR` if the matrix is singular.
+Raises `LINALG_VALUE_ERROR` if the matrix is non-square.
+Exceptions trigger an `error stop`.
+
+### Example
+
+```fortran
+{!example/linalg/example_determinant2.f90!}
+```

example/linalg/CMakeLists.txt

@@ -20,3 +20,5 @@ ADD_EXAMPLE(blas_gemv)
 ADD_EXAMPLE(lapack_getrf)
 ADD_EXAMPLE(solve1)
 ADD_EXAMPLE(solve2)
+ADD_EXAMPLE(determinant)
+ADD_EXAMPLE(determinant2)

src/CMakeLists.txt

@@ -25,6 +25,7 @@ set(fppFiles
  stdlib_linalg_kronecker.fypp
  stdlib_linalg_cross_product.fypp
  stdlib_linalg_solve.fypp 
+ stdlib_linalg_determinant.fypp
  stdlib_linalg_state.fypp 
  stdlib_optval.fypp
  stdlib_selection.fypp

src/stdlib_linalg.fypp

@@ -278,6 +278,108 @@ module stdlib_linalg
  #:endfor 
  end interface solve
 
+ interface det
+ !! version: experimental 
+ !!
+ !! Computes the determinant of a square matrix
+ !! ([Specification](../page/specs/stdlib_linalg.html#det-computes-the-determinant-of-a-square-matrix))
+ !! 
+ !!### Summary 
+ !! Interface for computing matrix determinant.
+ !!
+ !!### Description
+ !! 
+ !! This interface provides methods for computing the determinant of a matrix.
+ !! Supported data types include `real` and `complex`.
+ !! 
+ !!@note The provided functions are intended for square matrices only. 
+ !!@note BLAS/LAPACK backends do not currently support extended precision (``xdp``).
+ !! 
+ !!### Example
+ !!
+ !!```fortran
+ !!
+ !! real(sp) :: a(3,3), d
+ !! type(linalg_state_type) :: state 
+ !! a = reshape([1, 2, 3, 4, 5, 6, 7, 8, 9], [3, 3])
+ !!
+ !! ! ...
+ !! d = det(a,err=state)
+ !! if (state%ok()) then 
+ !! print *, 'Success! det=',d
+ !! else
+ !! print *, state%print()
+ !! endif
+ !! ! ...
+ !!```
+ !! 
+ #:for rk,rt in RC_KINDS_TYPES
+ #:if rk!="xdp" 
+ module procedure stdlib_linalg_${rt[0]}$${rk}$determinant
+ module procedure stdlib_linalg_pure_${rt[0]}$${rk}$determinant
+ #:endif
+ #:endfor
+ end interface det
+
+ interface operator(.det.)
+ !! version: experimental 
+ !!
+ !! Determinant operator of a square matrix
+ !! ([Specification](../page/specs/stdlib_linalg.html#det-determinant-operator-of-a-square-matrix))
+ !!
+ !!### Summary
+ !! Pure operator interface for computing matrix determinant.
+ !!
+ !!### Description
+ !! 
+ !! This pure operator interface provides a convenient way to compute the determinant of a matrix.
+ !! Supported data types include real and complex.
+ !!
+ !!@note The provided functions are intended for square matrices.
+ !!@note BLAS/LAPACK backends do not currently support extended precision (``xdp``).
+ !!
+ !!### Example
+ !!
+ !!```fortran
+ !!
+ !! ! ...
+ !! real(sp) :: matrix(3,3), d
+ !! matrix = reshape([1, 2, 3, 4, 5, 6, 7, 8, 9], [3, 3])
+ !! d = .det.matrix
+ !! ! ...
+ !! 
+ !!```
+ ! 
+ #:for rk,rt in RC_KINDS_TYPES
+ #:if rk!="xdp"
+ module procedure stdlib_linalg_pure_${rt[0]}$${rk}$determinant
+ #:endif
+ #:endfor 
+ end interface operator(.det.)
+
+ interface
+ #:for rk,rt in RC_KINDS_TYPES
+ #:if rk!="xdp" 
+ module function stdlib_linalg_${rt[0]}$${rk}$determinant(a,overwrite_a,err) result(det)
+ !> Input matrix a[m,n]
+ ${rt}$, intent(inout), target :: a(:,:)
+ !> [optional] Can A data be overwritten and destroyed?
+ logical(lk), optional, intent(in) :: overwrite_a
+ !> State return flag. 
+ type(linalg_state_type), intent(out) :: err
+ !> Matrix determinant
+ ${rt}$ :: det
+ end function stdlib_linalg_${rt[0]}$${rk}$determinant
+ pure module function stdlib_linalg_pure_${rt[0]}$${rk}$determinant(a) result(det)
+ !> Input matrix a[m,n]
+ ${rt}$, intent(in) :: a(:,:)
+ !> Matrix determinant
+ ${rt}$ :: det 
+ end function stdlib_linalg_pure_${rt[0]}$${rk}$determinant
+ #:endif
+ #:endfor
+ end interface 
+
 contains
 
 

test/linalg/CMakeLists.txt

@@ -3,6 +3,7 @@ set(
  "test_linalg.fypp"
  "test_blas_lapack.fypp"
  "test_linalg_solve.fypp"
+ "test_linalg_determinant.fypp"
  "test_linalg_matrix_property_checks.fypp"
 )
 fypp_f90("${fyppFlags}" "${fppFiles}" outFiles)