Merge branch 'cholesky' of github.com:perazz/stdlib into cholesky

Author: perazz

API-doc-FORD-file.md

@@ -43,7 +43,7 @@ project_website: https://stdlib.fortran-lang.org
 favicon: doc/media/favicon.ico
 license: by-sa
 author: fortran-lang/stdlib contributors
-author_pic: https://fortran-lang.org/assets/img/fortran_logo_512x512.png
+author_pic: https://fortran-lang.org/en/_static/fortran-logo-256x256.png 
 email: [email protected]
 github: https://github.com/fortran-lang
 twitter: https://twitter.com/fortranlang

CHANGELOG.md

@@ -1,3 +1,43 @@
+# Version 0.7.0
+
+Full release notes available at [v0.7.0] tag.
+
+[v0.7.0]: https://github.com/fortran-lang/stdlib/releases/tag/v0.7.0
+
+- new module `stdlib_constants`
+  [#800](https://github.com/fortran-lang/stdlib/pull/800)
+  - Many mathematical constants and most common physical ([codata](https://codata.org)) constants
+
+Changes to existing scripts and modules
+  - changes in CI
+    - Use of `fortran-setup` for GCC, Intel LLVM and Intel Classic
+      [#834](https://github.com/fortran-lang/stdlib/pull/834)
+  - change in module `stdlib_hashmaps`
+    - Support of hash map key generic interfaces
+      [#827](https://github.com/fortran-lang/stdlib/pull/827)
+  - changes in module `stdlib_io`
+    - Addition of a Fortran format specifier in `loadtxt`
+      [#805](https://github.com/fortran-lang/stdlib/pull/805)
+  - changes in module `stdlib_linalg`
+    - Support of extended and quad precision checking 
+      [#821](https://github.com/fortran-lang/stdlib/pull/821)
+    - Several fixes
+      [#815](https://github.com/fortran-lang/stdlib/pull/815)
+      [#818](https://github.com/fortran-lang/stdlib/pull/818)
+      [#826](https://github.com/fortran-lang/stdlib/pull/826)
+      [#830](https://github.com/fortran-lang/stdlib/pull/830)
+      [#836](https://github.com/fortran-lang/stdlib/pull/836)
+    - New procedures for Eigenvalues and Eigenvectors computation: `eig`, `eigh`, `eigvals`, `eigvalsh`
+      [#816](https://github.com/fortran-lang/stdlib/pull/816)
+    - New procedures for Singular Value Decomposition: `svd`, `svdvals`
+      [#808](https://github.com/fortran-lang/stdlib/pull/808)
+  - changes in module `stdlib_sorting`
+    - Renamed variable from `int_size` to `int_index`
+      [#824](https://github.com/fortran-lang/stdlib/pull/824)
+    - Support of `int32` `index` array in `sort_index`
+      [#829](https://github.com/fortran-lang/stdlib/pull/829)
+
+
 # Version 0.6.1
 
 Full release notes available at [v0.6.1] tag.

VERSION

@@ -1 +1 @@
-0.6.1
+0.7.0

doc/specs/stdlib_linalg.md

@@ -104,7 +104,8 @@ end interface axpy
 Note that the 128-bit functions are only provided by `stdlib` and always point to the internal implementation. 
 Because 128-bit precision is identified as [stdlib_kinds(module):qp], initials for 128-bit procedures were 
 labelled as `q` (quadruple-precision reals) and `w` ("wide" or quadruple-precision complex numbers). 
-Extended precision ([stdlib_kinds(module):xdp]) calculations are currently not supported.
+Extended precision ([stdlib_kinds(module):xdp]) calculations are labelled as `x` (extended-precision reals).
+and `y` (extended-precision complex numbers).
 
 ### Example
 
@@ -779,7 +780,7 @@ Result vector `x` returns the approximate solution that minimizes the 2-norm \(
 
 `cond` (optional): Shall be a scalar `real` value cut-off threshold for rank evaluation: `s_i >= cond*maxval(s), i=1:rank`. Shall be a scalar, `intent(in)` argument.
 
-`singvals` (optional): Shall be a `real` rank-1 array of the same kind `a` and size at least `minval(shape(a))`, returning the list of singular values `s(i)>=cond*maxval(s)`, in descending order of magnitude. It is an `intent(out)` argument.
+`singvals` (optional): Shall be a `real` rank-1 array of the same kind `a` and size at least `min(m,n)`, returning the list of singular values `s(i)>=cond*maxval(s)` from the internal SVD, in descending order of magnitude. It is an `intent(out)` argument.
 
 `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.
 
@@ -881,15 +882,15 @@ This interface is equivalent to the `pure` version of determinant [[stdlib_linal
 
 ### Syntax
 
-`c = ` [[stdlib_linalg(module):operator(.det.)(interface)]] `(a)`
+`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.
+Returns a real scalar value 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.
@@ -1260,3 +1261,124 @@ Exceptions trigger an `error stop`, unless argument `err` is present.
 {!example/linalg/example_chol.f90!}
 ```
 
+
+## `.inv.` - Inverse operator of a square matrix
+
+### Status
+
+Experimental
+
+### Description
+
+This operator returns the inverse of a `real` or `complex` square matrix \( A \).
+The inverse \( A^{-1} \) is defined such that \( A \cdot A^{-1} = A^{-1} \cdot A = I_n \).
+
+This interface is equivalent to the function  [[stdlib_linalg(module):inv(interface)]]. 
+
+### Syntax
+
+`b = ` [[stdlib_linalg(module):operator(.inv.)(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 rank-2 square array with the same type, kind and rank as `a`, that contains the inverse of `a`.
+
+If an exception occurred on input errors, or singular matrix, `NaN`s will be returned.
+For fine-grained error control in case of singular matrices prefer the `subroutine` and the `function`
+interfaces.
+
+### Example
+
+```fortran
+{!example/linalg/example_inverse_operator.f90!}
+```
+
+## `invert` - Inversion of a square matrix
+
+### Status
+
+Experimental
+
+### Description
+
+This subroutine inverts 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 \).
+
+On return, the input matrix `a` is replaced by its inverse.
+The solver is based on LAPACK's `*GETRF` and `*GETRI` backends.
+
+### Syntax
+
+`call ` [[stdlib_linalg(module):invert(interface)]] `(a, [,inva] [, pivot] [, err])`
+
+### Arguments
+
+`a`: Shall be a rank-2, square, `real` or `complex` array containing the coefficient matrix. 
+If `inva` is provided, it is an `intent(in)` argument.
+If `inva` is not provided, it is an `intent(inout)` argument: on output, it is replaced by the inverse of `a`. 
+
+`inva` (optional): Shall be a rank-2, square, `real` or `complex` array with the same size, and kind as `a`. 
+On output, it contains the inverse of `a`.
+
+`pivot` (optional): Shall be a rank-1 array of the same kind and matrix dimension as `a`, that contains the diagonal pivot indices on return. It is an `intent(inout)` argument. 
+
+`err` (optional): Shall be a `type(linalg_state_type)` value. This is an `intent(out)` argument.
+
+### Return value
+
+Computes the inverse of the matrix \( A \), \(A^{-1}\, and returns it either in \( A \) or in another matrix.
+
+Raises `LINALG_ERROR` if the matrix is singular or has invalid size.
+Raises `LINALG_VALUE_ERROR` if `inva` and `a` do not have the same size.
+If `err` is not present, exceptions trigger an `error stop`.
+
+### Example
+
+```fortran
+{!example/linalg/example_inverse_inplace.f90!}
+```
+
+```fortran
+{!example/linalg/example_inverse_subroutine.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. It 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_inverse_function.f90!}
+```
+

doc/specs/stdlib_math.md

@@ -382,6 +382,70 @@ Notes: Although the angle of the complex number `0` is undefined, `argpi((0,0))`
 {!example/math/example_math_argpi.f90!}
 ```
 
+### `deg2rad`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Elemenal function.
+
+### Description
+
+`deg2rad` converts phase angles from degrees to radians.
+
+#### Syntax
+
+`result = ` [[stdlib_math(module):deg2rad(interface)]] `(theta)`
+
+#### Arguments
+
+`theta`: Shall be a `real` scalar/array.
+
+#### Return value
+
+Returns the `real` phase angle in radians.
+
+#### Example
+
+```fortran
+{!example/math/example_math_deg2rad.f90!}
+```
+
+### `rad2deg`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Elemenal function.
+
+### Description
+
+`rad2deg` converts phase angles from radians to degrees.
+
+#### Syntax
+
+`result = ` [[stdlib_math(module):rad2deg(interface)]] `(theta)`
+
+#### Arguments
+
+`theta`: Shall be a `real` scalar/array.
+
+#### Return value
+
+Returns the `real` phase angle in degrees.
+
+#### Example
+
+```fortran
+{!example/math/example_math_rad2deg.f90!}
+```
+
 ### `is_close` function
 
 #### Description

example/linalg/CMakeLists.txt

@@ -12,6 +12,10 @@ ADD_EXAMPLE(is_skew_symmetric)
 ADD_EXAMPLE(is_square)
 ADD_EXAMPLE(is_symmetric)
 ADD_EXAMPLE(is_triangular)
+ADD_EXAMPLE(inverse_operator)
+ADD_EXAMPLE(inverse_function)
+ADD_EXAMPLE(inverse_inplace)
+ADD_EXAMPLE(inverse_subroutine)
 ADD_EXAMPLE(outer_product)
 ADD_EXAMPLE(eig)
 ADD_EXAMPLE(eigh)

example/linalg/example_inverse_function.f90

@@ -0,0 +1,22 @@
+! Matrix inversion example: function interface
+program example_inverse_function
+  use stdlib_linalg_constants, only: dp
+  use stdlib_linalg, only: inv,eye
+  implicit none
+
+  real(dp) :: A(2,2), Am1(2,2)
+
+  ! Input matrix (NB Fortran is column major! input columns then transpose)
+  A = transpose(reshape( [4, 3, &
+                          3, 2], [2,2] ))
+
+  ! Invert matrix
+  Am1 = inv(A)
+
+  print *, '         |',Am1(1,:),'|' ! | -2  3 |
+  print *, ' inv(A)= |',Am1(2,:),'|' ! |  3 -4 |
+
+  ! Final check 
+  print *, 'CHECK passed? ',matmul(A,Am1)==eye(2)
+
+end program example_inverse_function

example/linalg/example_inverse_inplace.f90

@@ -0,0 +1,23 @@
+! Matrix inversion example: in-place inversion
+program example_inverse_inplace
+  use stdlib_linalg_constants, only: dp
+  use stdlib_linalg, only: invert,eye
+  implicit none
+
+  real(dp) :: A(2,2), Am1(2,2)
+
+  ! Input matrix (NB Fortran is column major! input columns then transpose)
+  A = transpose(reshape( [4, 3, &
+                          3, 2], [2,2] ))
+  Am1 = A
+
+  ! Invert matrix
+  call invert(Am1)
+
+  print *, '         |',Am1(1,:),'|' ! | -2  3 |
+  print *, ' inv(A)= |',Am1(2,:),'|' ! |  3 -4 |
+
+  ! Final check 
+  print *, 'CHECK passed? ',matmul(A,Am1)==eye(2)
+
+end program example_inverse_inplace

example/linalg/example_inverse_operator.f90

@@ -0,0 +1,22 @@
+! Matrix inversion example: operator interface
+program example_inverse_operator
+  use stdlib_linalg_constants, only: dp
+  use stdlib_linalg, only: operator(.inv.),eye
+  implicit none
+
+  real(dp) :: A(2,2), Am1(2,2)
+
+  ! Input matrix (NB Fortran is column major! input columns then transpose)
+  A = transpose(reshape( [4, 3, &
+                          3, 2], [2,2] ))
+
+  ! Invert matrix
+  Am1 = .inv.A
+
+  print *, '         |',Am1(1,:),'|' ! | -2  3 |
+  print *, ' inv(A)= |',Am1(2,:),'|' ! |  3 -4 |
+
+  ! Final check 
+  print *, 'CHECK passed? ',matmul(A,Am1)==eye(2)
+
+end program example_inverse_operator

example/linalg/example_inverse_subroutine.f90

@@ -0,0 +1,22 @@
+! Matrix inversion example: subroutine interface
+program example_inverse_subroutine
+  use stdlib_linalg_constants, only: dp
+  use stdlib_linalg, only: invert,eye
+  implicit none
+
+  real(dp) :: A(2,2), Am1(2,2)
+
+  ! Input matrix (NB Fortran is column major! input columns then transpose)
+  A = transpose(reshape( [4, 3, &
+                          3, 2], [2,2] ))
+
+  ! Invert matrix
+  call invert(A,Am1)
+
+  print *, '         |',Am1(1,:),'|' ! | -2  3 |
+  print *, ' inv(A)= |',Am1(2,:),'|' ! |  3 -4 |
+
+  ! Final check 
+  print *, 'CHECK passed? ',matmul(A,Am1)==eye(2)
+
+end program example_inverse_subroutine