Skip to content

Commit b137b36

Browse files
jalveszjalvesz
authored
Merge branch 'fortran-lang:master' into activations
2 parents dd7125d + ccdba91 commit b137b36

9 files changed

+620
-20
lines changed

‎doc/specs/stdlib_linalg.md

+97-20
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,7 @@ to the original.
185185

186186
### Status
187187

188-
Experimental
188+
Stable
189189

190190
### Description
191191

@@ -231,7 +231,7 @@ Returns a diagonal array or a vector with the extracted diagonal elements.
231231

232232
### Status
233233

234-
Experimental
234+
Stable
235235

236236
### Class
237237

@@ -282,7 +282,7 @@ A = eye(2,2)/2.0 !! A == diag([0.5, 0.5])
282282

283283
### Status
284284

285-
Experimental
285+
Stable
286286

287287
### Description
288288

@@ -605,7 +605,7 @@ Specifically, upper Hessenberg matrices satisfy `a_ij = 0` when `j < i-1`, and l
605605

606606
### Status
607607

608-
Experimental
608+
Stable
609609

610610
### Description
611611

@@ -655,7 +655,7 @@ If `err` is not present, exceptions trigger an `error stop`.
655655

656656
### Status
657657

658-
Experimental
658+
Stable
659659

660660
### Description
661661

@@ -708,7 +708,7 @@ If `err` is not present, exceptions trigger an `error stop`.
708708

709709
### Status
710710

711-
Experimental
711+
Stable
712712

713713
### Description
714714

@@ -752,7 +752,7 @@ Exceptions trigger an `error stop`.
752752

753753
### Status
754754

755-
Experimental
755+
Stable
756756

757757
### Description
758758

@@ -806,7 +806,7 @@ Exceptions trigger an `error stop`.
806806

807807
### Status
808808

809-
Experimental
809+
Stable
810810

811811
### Description
812812

@@ -832,7 +832,7 @@ This subroutine computes the internal working space requirements for the least-s
832832

833833
### Status
834834

835-
Experimental
835+
Stable
836836

837837
### Description
838838

@@ -872,7 +872,7 @@ Exceptions are returned to the `err` argument if provided; an `error stop` is tr
872872

873873
### Status
874874

875-
Experimental
875+
Stable
876876

877877
### Description
878878

@@ -902,14 +902,91 @@ Exceptions trigger an `error stop`.
902902
{!example/linalg/example_determinant2.f90!}
903903
```
904904

905-
## `eig` - Eigenvalues and Eigenvectors of a Square Matrix
905+
## `qr` - Compute the QR factorization of a matrix
906906

907907
### Status
908908

909909
Experimental
910910

911911
### Description
912912

913+
This subroutine computes the QR factorization of a `real` or `complex` matrix: \( A = Q R \) where \( Q \)
914+
is orthonormal and \( R \) is upper-triangular. Matrix \( A \) has size `[m,n]`, with \( m \ge n \).
915+
916+
The results are returned in output matrices \( Q \) and \(R \), that have the same type and kind as \( A \).
917+
Given `k = min(m,n)`, one can write \( A = \( Q_1 Q_2 \) \cdot \( \frac{R_1}{0}\) \).
918+
Because the lower rows of \( R \) are zeros, a reduced problem \( A = Q_1 R_1 \) may be solved. The size of
919+
the input arguments determines what problem is solved: on full matrices (`shape(Q)==[m,m]`, `shape(R)==[m,n]`),
920+
the full problem is solved. On reduced matrices (`shape(Q)==[m,k]`, `shape(R)==[k,n]`), the reduced problem is solved.
921+
922+
### Syntax
923+
924+
`call ` [[stdlib_linalg(module):qr(interface)]] `(a, q, r, [, storage] [, overwrite_a] [, err])`
925+
926+
### Arguments
927+
928+
`a`: Shall be a rank-2 `real` or `complex` array containing the coefficient matrix of size `[m,n]`. It is an `intent(in)` argument, if `overwrite_a=.false.`. Otherwise, it is an `intent(inout)` argument, and is destroyed upon return.
929+
930+
`q`: Shall be a rank-2 array of the same kind as `a`, containing the orthonormal matrix `q`. It is an `intent(out)` argument. It should have a shape equal to either `[m,m]` or `[m,k]`, whether the full or the reduced problem is sought for.
931+
932+
`r`: Shall be a rank-2 array of the same kind as `a`, containing the upper triangular matrix `r`. It is an `intent(out)` argument. It should have a shape equal to either `[m,n]` or `[k,n]`, whether the full or the reduced problem is sought for.
933+
934+
`storage` (optional): Shall be a rank-1 array of the same type and kind as `a`, providing working storage for the solver. Its minimum size can be determined with a call to [[stdlib_linalg(module):qr_space(interface)]]. It is an `intent(out)` argument.
935+
936+
`overwrite_a` (optional): Shall be an input `logical` flag (default: `.false.`). If `.true.`, input matrix `a` will be used as temporary storage and overwritten. This avoids internal data allocation. It is an `intent(in)` argument.
937+
938+
`err` (optional): Shall be a `type(linalg_state_type)` value. It is an `intent(out)` argument.
939+
940+
### Return value
941+
942+
Returns the QR factorization matrices into the \( Q \) and \( R \) arguments.
943+
944+
Raises `LINALG_VALUE_ERROR` if any of the matrices has invalid or unsuitable size for the full/reduced problem.
945+
Raises `LINALG_ERROR` on insufficient user storage space.
946+
If the state argument `err` is not present, exceptions trigger an `error stop`.
947+
948+
### Example
949+
950+
```fortran
951+
{!example/linalg/example_qr.f90!}
952+
```
953+
954+
## `qr_space` - Compute internal working space requirements for the QR factorization.
955+
956+
### Status
957+
958+
Experimental
959+
960+
### Description
961+
962+
This subroutine computes the internal working space requirements for the QR factorization, [[stdlib_linalg(module):qr(interface)]] .
963+
964+
### Syntax
965+
966+
`call ` [[stdlib_linalg(module):qr_space(interface)]] `(a, lwork, [, err])`
967+
968+
### Arguments
969+
970+
`a`: Shall be a rank-2 `real` or `complex` array containing the coefficient matrix. It is an `intent(in)` argument.
971+
972+
`lwork`: Shall be an `integer` scalar, that returns the minimum array size required for the working storage in [[stdlib_linalg(module):qr(interface)]] to factorize `a`.
973+
974+
`err` (optional): Shall be a `type(linalg_state_type)` value. This is an `intent(out)` argument.
975+
976+
### Example
977+
978+
```fortran
979+
{!example/linalg/example_qr_space.f90!}
980+
```
981+
982+
## `eig` - Eigenvalues and Eigenvectors of a Square Matrix
983+
984+
### Status
985+
986+
Stable
987+
988+
### Description
989+
913990
This subroutine computes the solution to the eigenproblem \( A \cdot \bar{v} - \lambda \cdot \bar{v} \), where \( A \) is a square, full-rank, `real` or `complex` matrix.
914991

915992
Result array `lambda` returns the eigenvalues of \( A \). The user can request eigenvectors to be returned: if provided, on output `left` will contain the left eigenvectors, `right` the right eigenvectors of \( A \).
@@ -951,7 +1028,7 @@ If `err` is not present, exceptions trigger an `error stop`.
9511028

9521029
### Status
9531030

954-
Experimental
1031+
Stable
9551032

9561033
### Description
9571034

@@ -1000,7 +1077,7 @@ If `err` is not present, exceptions trigger an `error stop`.
10001077

10011078
### Status
10021079

1003-
Experimental
1080+
Stable
10041081

10051082
### Description
10061083

@@ -1028,7 +1105,6 @@ Raises `LINALG_ERROR` if the calculation did not converge.
10281105
Raises `LINALG_VALUE_ERROR` if any matrix or arrays have invalid/incompatible sizes.
10291106
If `err` is not present, exceptions trigger an `error stop`.
10301107

1031-
10321108
### Example
10331109

10341110
```fortran
@@ -1039,7 +1115,7 @@ If `err` is not present, exceptions trigger an `error stop`.
10391115

10401116
### Status
10411117

1042-
Experimental
1118+
Stable
10431119

10441120
### Description
10451121

@@ -1080,7 +1156,7 @@ If `err` is not present, exceptions trigger an `error stop`.
10801156

10811157
### Status
10821158

1083-
Experimental
1159+
Stable
10841160

10851161
### Description
10861162

@@ -1096,6 +1172,7 @@ If requested, `vt` contains the right singular vectors, as rows of \( V^T \).
10961172
`call ` [[stdlib_linalg(module):svd(interface)]] `(a, s, [, u, vt, overwrite_a, full_matrices, err])`
10971173

10981174
### Class
1175+
10991176
Subroutine
11001177

11011178
### Arguments
@@ -1134,7 +1211,7 @@ Exceptions trigger an `error stop`, unless argument `err` is present.
11341211

11351212
### Status
11361213

1137-
Experimental
1214+
Stable
11381215

11391216
### Description
11401217

@@ -1266,7 +1343,7 @@ Exceptions trigger an `error stop`, unless argument `err` is present.
12661343

12671344
### Status
12681345

1269-
Experimental
1346+
Stable
12701347

12711348
### Description
12721349

@@ -1301,7 +1378,7 @@ interfaces.
13011378

13021379
### Status
13031380

1304-
Experimental
1381+
Stable
13051382

13061383
### Description
13071384

@@ -1350,7 +1427,7 @@ If `err` is not present, exceptions trigger an `error stop`.
13501427

13511428
### Status
13521429

1353-
Experimental
1430+
Stable
13541431

13551432
### Description
13561433

‎example/linalg/CMakeLists.txt

+2
Original file line numberDiff line numberDiff line change
@@ -35,5 +35,7 @@ ADD_EXAMPLE(svd)
3535
ADD_EXAMPLE(svdvals)
3636
ADD_EXAMPLE(determinant)
3737
ADD_EXAMPLE(determinant2)
38+
ADD_EXAMPLE(qr)
39+
ADD_EXAMPLE(qr_space)
3840
ADD_EXAMPLE(cholesky)
3941
ADD_EXAMPLE(chol)

‎example/linalg/example_qr.f90

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
program example_qr
2+
use stdlib_linalg, only: qr
3+
implicit none(type,external)
4+
real :: A(104, 32), Q(104,32), R(32,32)
5+
6+
! Create a random matrix
7+
call random_number(A)
8+
9+
! Compute its QR factorization (reduced)
10+
call qr(A,Q,R)
11+
12+
! Test factorization: Q*R = A
13+
print *, maxval(abs(matmul(Q,R)-A))
14+
15+
end program example_qr

‎example/linalg/example_qr_space.f90

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
! QR example with pre-allocated storage
2+
program example_qr_space
3+
use stdlib_linalg_constants, only: ilp
4+
use stdlib_linalg, only: qr, qr_space, linalg_state_type
5+
implicit none(type,external)
6+
real :: A(104, 32), Q(104,32), R(32,32)
7+
real, allocatable :: work(:)
8+
integer(ilp) :: lwork
9+
type(linalg_state_type) :: err
10+
11+
! Create a random matrix
12+
call random_number(A)
13+
14+
! Prepare QR workspace
15+
call qr_space(A,lwork)
16+
allocate(work(lwork))
17+
18+
! Compute its QR factorization (reduced)
19+
call qr(A,Q,R,storage=work,err=err)
20+
21+
! Test factorization: Q*R = A
22+
print *, maxval(abs(matmul(Q,R)-A))
23+
print *, err%print()
24+
25+
end program example_qr_space

‎src/CMakeLists.txt

+1
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ set(fppFiles
3030
stdlib_linalg_eigenvalues.fypp
3131
stdlib_linalg_solve.fypp
3232
stdlib_linalg_determinant.fypp
33+
stdlib_linalg_qr.fypp
3334
stdlib_linalg_inverse.fypp
3435
stdlib_linalg_state.fypp
3536
stdlib_linalg_svd.fypp

0 commit comments

Comments
 (0)