document solve_lu

doc/specs/stdlib_linalg.md

@@ -610,7 +610,9 @@ Experimental
 
 This function computes the solution to a linear matrix equation \( A \cdot x = b \), where \( A \) is a square, full-rank, `real` or `complex` matrix.
 
-Result vector or array `x` returns the exact solution to within numerical precision, provided that the matrix is not ill-conditioned. The solver is based on LAPACK's `*GESV` backends.
+Result vector or array `x` returns the exact solution to within numerical precision, provided that the matrix is not ill-conditioned. 
+An error is returned if the matrix is rank-deficient or singular to working precision. 
+The solver is based on LAPACK's `*GESV` backends.
 
 ### Syntax
 
@@ -640,7 +642,57 @@ For a full-rank matrix, returns an array value that represents the solution to t
 
 Raises `LINALG_ERROR` if the matrix is singular to working precision.
 Raises `LINALG_VALUE_ERROR` if the matrix and rhs vectors have invalid/incompatible sizes.
-Exceptions trigger an `error stop`.
+If `err` is not present, exceptions trigger an `error stop`.
+
+### Example
+
+```fortran
+{!example/linalg/example_solve1.f90!}
+
+{!example/linalg/example_solve2.f90!}
+```
+
+## `solve_lu` - Solves a linear matrix equation or a linear system of equations (subroutine interface). 
+
+### Status
+
+Experimental
+
+### Description
+
+This subroutine computes the solution to a linear matrix equation \( A \cdot x = b \), where \( A \) is a square, full-rank, `real` or `complex` matrix.
+
+Result vector or array `x` returns the exact solution to within numerical precision, provided that the matrix is not ill-conditioned. 
+An error is returned if the matrix is rank-deficient or singular to working precision. 
+The solver is based on LAPACK's `*GESV` backends.
+
+### Syntax
+
+`Pure` interface:
+
+`x = ` [[stdlib_linalg(module):solve_lu(interface)]] `(a, b, x, pivot [, overwrite_a, err])`
+
+### Arguments
+
+Two 
+
+`a`: Shall be a rank-2 `real` or `complex` square array containing the coefficient matrix. It is normally an `intent(in)` argument. If `overwrite_a=.true.`, it is an `intent(inout)` argument and is destroyed by the call. 
+
+`b`: Shall be a rank-1 or rank-2 array of the same kind as `a`, containing the right-hand-side vector(s). It is an `intent(in)` argument.
+
+`x`: Shall be a rank-1 or rank-2 array of the same kind and size as `b`, that returns the solution(s) to the system. It is an `intent(inout)` argument, and must have the `contiguous` property. 
+
+`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
+
+For a full-rank matrix, returns an array value that represents the solution to the linear system of equations.
+
+Raises `LINALG_ERROR` if the matrix is singular to working precision.
+Raises `LINALG_VALUE_ERROR` if the matrix and rhs vectors have invalid/incompatible sizes.
+If `err` is not present, exceptions trigger an `error stop`.
 
 ### Example