document inv

Author: perazz

doc/specs/stdlib_linalg.md

@@ -971,3 +971,39 @@ If `err` is not present, exceptions trigger an `error stop`.
 ```fortran
 {!example/linalg/example_inverse3.f90!}
 ```
+
+## `inv` - Inverse of a square matrix. 
+
+### Status
+
+Experimental
+
+### Description
+
+This function returns the inverse of a square `real` or `complex` matrix in-place.
+The inverse, \( A^{-1} \), is defined such that \( A \cdot A^{-1} = A^{-1} \cdot A = I_n \).
+
+The solver is based on LAPACK's `*GETRF` and `*GETRI` backends.
+
+### Syntax
+
+`b ` [[stdlib_linalg(module):inv(interface)]] `(a, [, err])`
+
+### Arguments
+
+`a`: Shall be a rank-2, square, `real` or `complex` array containing the coefficient matrix. It is an `intent(inout)` argument.
+
+`err` (optional): Shall be a `type(linalg_state_type)` value. This is an `intent(out)` argument.
+
+### Return value
+
+Returns an array value of the same type, kind and rank as `a`, that contains the inverse matrix \(A^{-1}\).
+
+Raises `LINALG_ERROR` if the matrix is singular or has invalid size.
+If `err` is not present, exceptions trigger an `error stop`.
+
+### Example
+
+```fortran
+{!example/linalg/example_inverse2.f90!}
+```

src/stdlib_linalg.fypp

@@ -557,6 +557,26 @@ module stdlib_linalg
 
   ! Function interface
   interface inv
+    !! version: experimental 
+    !!
+    !! Inverse of a square matrix
+    !! ([Specification](../page/specs/stdlib_linalg.html#inv-inverse-of-a-square-matrix))
+    !!
+    !!### Summary
+    !! This interface provides methods for computing the inverse of a square `real` or `complex` matrix.
+    !! The inverse \( A^{-1} \) is defined such that \( A \cdot A^{-1} = A^{-1} \cdot A = I_n \).
+    !!
+    !!### Description
+    !!     
+    !! This function interface provides methods that return the inverse of a square matrix.    
+    !! Supported data types include `real` and `complex`. 
+    !! The inverse matrix \( A^{-1} \) is returned as a function result. 
+    !! Exceptions are raised in case of singular matrix or invalid size, and trigger an `error stop` if 
+    !! the state flag `err` is not provided. 
+    !!
+    !!@note The provided functions are intended for square matrices.
+    !!@note BLAS/LAPACK backends do not currently support extended precision (``xdp``).
+    !!       
     #:for rk,rt,ri in RC_KINDS_TYPES
     #:if rk!="xdp" 
     module function stdlib_linalg_inverse_${ri}$(a,err) result(inva)
@@ -584,7 +604,7 @@ module stdlib_linalg
     !!
     !!### Description
     !!     
-    !! This operator interface provides a convenient way to compute the inverse of a matrix.    
+    !! This subroutine interface provides a way to compute the inverse of a matrix in-place.    
     !! Supported data types include `real` and `complex`. 
     !! On completion, matrix `a` is replaced by the inverse matrix. Pre-allocated storage may be provided
     !! for the array of pivot indices, `pivot`. If all pre-allocated work spaces are provided, no internal