Added matrix_exp to specs.

Author: loiseaujc

doc/specs/stdlib_linalg.md

@@ -1896,24 +1896,60 @@ Given a matrix \(A\), this function computes its matrix exponential \(E = \exp(A
 
 ### Syntax
 
-`E = ` [[stdlib_linalg(module):expm(interface)]] `(a [, order, err])`
+`E = ` [[stdlib_linalg(module):expm(interface)]] `(a [, order])`
 
 ### Arguments
 
 `a`: Shall be a rank-2 `real` or `complex` array containing the data. It is an `intent(in)` argument.
 
 `order` (optional): Shall be a non-negative `integer` value specifying the order of the Pade approximation. By default `order=10`. It is an `intent(in)` argument. 
 
+### Return value
+
+The returned array `E` contains the Pade approximation of \(\exp(A)\).
+
+If `A` is non-square or `order` is negative, it raises a `LINALG_VALUE_ERROR`.
+
+### Example
+
+```fortran
+{!example/linalg/example_expm.f90!}
+```
+
+## `matrix_exp` - Computes the matrix exponential {#matrix_exp}
+
+### Status
+
+Experimental
+
+### Description
+
+Given a matrix \(A\), this function computes its matrix exponential \(E = \exp(A)\) using a Pade approximation.
+
+### Syntax
+
+`call ` [[stdlib_linalg(module):matrix_exp(interface)]] `(a [, e, order, err])`
+
+### Arguments
+
+`a`: Shall be a rank-2 `real` or `complex` array containing the data. If `e` is not passed, it is an `intent(inout)` argument and is overwritten on exit by the matrix exponential. If `e` is passed, it is an `intent(in)` argument and is left unchanged.
+
+`e` (optional): Shall be a rank-2 `real` or `complex` array with the same dimensions as `a`. It is an `intent(out)` argument. On exit, it contains the matrix exponential of `a`.
+
+`order` (optional): Shall be a non-negative `integer` value specifying the order of the Pade approximation. By default `order=10`. It is an `intent(in)` argument. 
+
 `err` (optional): Shall be a `type(linalg_state_type)` value. This is an `intent(out)` argument. 
 
 ### Return value
 
-The returned array `E` contains the Pade approximation of \(\exp(A)\).
+The returned array `A` (in-place) or `E` (out-of-place) contains the Pade approximation of \(\exp(A)\).
 
 If `A` is non-square or `order` is negative, it raises a `LINALG_VALUE_ERROR`.
 If `err` is not present, exceptions trigger an `error stop`.
 
 ### Example
 
 ```fortran
-{!example/linalg/example_expm.f90!}
+{!example/linalg/example_matrix_exp.f90!}
+```
+

example/linalg/example_expm.f90

@@ -2,6 +2,17 @@ program example_expm
    use stdlib_linalg, only: expm
    implicit none
    real :: A(3, 3), E(3, 3)
+   integer :: i
    A = reshape([1, 2, 3, 4, 5, 6, 7, 8, 9], [3, 3])
    E = expm(A)
+
+   print *, "Matrix A :"
+   do i = 1, 3
+      print *, A(i, :)
+   end do
+
+   print *, "Matrix exponential E = exp(A):"
+   do i = 1, 3
+      print *, E(i, :)
+   end do
 end program example_expm

example/linalg/example_matrix_exp.f90

@@ -0,0 +1,20 @@
+program example_expm
+   use stdlib_linalg, only: matrix_exp
+   implicit none
+   real :: A(3, 3), E(3, 3)
+   integer :: i
+
+   print *, "Matrix A :"
+   do i = 1, 3
+      print *, A(i, :)
+   end do
+
+   A = reshape([1, 2, 3, 4, 5, 6, 7, 8, 9], [3, 3])
+   call matrix_exp(A) ! In-place computation.
+   ! For out-of-place, use call matrix_exp(A, E).
+
+   print *, "Matrix exponential E = exp(A):"
+   do i = 1, 3
+      print *, E(i, :)
+   end do
+end program example_expm