Skip to content

Commit f03295d

Browse files
perazzperazz
committed
more docs
1 parent f1aba81 commit f03295d

File tree

8 files changed

+137
-91
lines changed

8 files changed

+137
-91
lines changed

‎fypp/src/la_determinant.fypp‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
#:include "common.fypp"
2+
!> Determinant of a rectangular matrix
23
module la_determinant
34
use la_constants
45
use la_blas
@@ -8,10 +9,9 @@ module la_determinant
89
implicit none(type,external)
910
private
1011

11-
!> Determinant of a rectangular matrix
1212
public :: det
1313

14-
character(*), parameter :: this = 'determinant'
14+
character(*),parameter :: this = 'determinant'
1515

1616
!> @brief Compute the determinant of a rectangular matrix.
1717
!!

‎fypp/src/la_lapack.fypp‎

Lines changed: 51 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
#:include "common.fypp"
2+
!> Kind-agnostic LAPACK interface linking to internal or external implementations
23
module la_lapack
34
use la_constants
45
use la_blas
@@ -14,27 +15,57 @@ module la_lapack
1415
implicit none(type,external)
1516
public
1617

17-
!> BBCSD: computes the CS decomposition of a unitary matrix in
18-
!> bidiagonal-block form,
19-
!> [ B11 | B12 0 0 ]
20-
!> [ 0 | 0 -I 0 ]
21-
!> X = [----------------]
22-
!> [ B21 | B22 0 0 ]
23-
!> [ 0 | 0 0 I ]
24-
!> [ C | -S 0 0 ]
25-
!> [ U1 | ] [ 0 | 0 -I 0 ] [ V1 | ]**H
26-
!> = [---------] [---------------] [---------] .
27-
!> [ | U2 ] [ S | C 0 0 ] [ | V2 ]
28-
!> [ 0 | 0 0 I ]
29-
!> X is M-by-M, its top-left block is P-by-Q, and Q must be no larger
30-
!> than P, M-P, or M-Q. (If Q is not the smallest index, then X must be
18+
19+
!> @brief BBCSD computes the CS decomposition of a unitary matrix in
20+
!> bidiagonal-block form.
21+
!>
22+
!> \f[
23+
!> \renewcommand\arraystretch{1.3}
24+
!> \left[
25+
!> \begin{array}{c|ccc}
26+
!> B_{11} & B_{12} & 0 & 0 \\
27+
!> 0 & 0 & -I & 0 \\
28+
!> \hline
29+
!> B_{21} & B_{22} & 0 & 0 \\
30+
!> 0 & 0 & 0 & I \\
31+
!> C & -S & 0 & 0
32+
!> \end{array}
33+
!> \right] =
34+
!> \left[
35+
!> \begin{array}{c|c}
36+
!> U_1 & 0 \\
37+
!> \hline
38+
!> 0 & U_2
39+
!> \end{array}
40+
!> \right]
41+
!> \left[
42+
!> \begin{array}{c|ccc}
43+
!> 0 & 0 & -I & 0 \\
44+
!> \hline
45+
!> S & C & 0 & 0 \\
46+
!> 0 & 0 & 0 & I
47+
!> \end{array}
48+
!> \right]
49+
!> \left[
50+
!> \begin{array}{c|c}
51+
!> V_1^H & 0 \\
52+
!> \hline
53+
!> 0 & V_2^H
54+
!> \end{array}
55+
!> \right]
56+
!> \f]
57+
!>
58+
!> X is \f$M \times M\f$, its top-left block is \f$P \times Q\f$, and \f$Q\f$ must be no larger
59+
!> than \f$P\f$, \f$M-P\f$, or \f$M-Q\f$. (If \f$Q\f$ is not the smallest index, then X must be
3160
!> transposed and/or permuted. This can be done in constant time using
3261
!> the TRANS and SIGNS options. See CUNCSD for details.)
33-
!> The bidiagonal matrices B11, B12, B21, and B22 are represented
34-
!> implicitly by angles THETA(1:Q) and PHI(1:Q-1).
35-
!> The unitary matrices U1, U2, V1T, and V2T are input/output.
36-
!> The input matrices are pre- or post-multiplied by the appropriate
37-
!> singular vector matrices.
62+
!>
63+
!> The bidiagonal matrices \f$B_{11}\f$, \f$B_{12}\f$, \f$B_{21}\f$, and \f$B_{22}\f$ are represented
64+
!> implicitly by angles \f$\theta(1:Q)\f$ and \f$\phi(1:Q-1)\f$.
65+
!>
66+
!> The unitary matrices \f$U_1\f$, \f$U_2\f$, \f$V_1^T\f$, and \f$V_2^T\f$ are input/output.
67+
!>
68+
!> The input matrices are pre- or post-multiplied by the appropriate singular vector matrices.
3869
interface bbcsd
3970
#ifdef LA_EXTERNAL_LAPACK
4071
pure subroutine cbbcsd( jobu1, jobu2, jobv1t, jobv2t, trans, m, p, q,theta, phi, &
@@ -49,7 +80,7 @@ module la_lapack
4980
*),b22e(*),rwork(*)
5081
real(sp), intent(inout) :: phi(*),theta(*)
5182
complex(sp), intent(inout) :: u1(ldu1,*),u2(ldu2,*),v1t(ldv1t,*),v2t(ldv2t,*)
52-
83+
5384
end subroutine cbbcsd
5485
#else
5586
module procedure la_cbbcsd

‎fypp/src/la_lapack_d.fypp‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -24180,16 +24180,16 @@ module la_lapack_d
2418024180

2418124181
!> DBBCSD: computes the CS decomposition of an orthogonal matrix in
2418224182
!> bidiagonal-block form,
24183-
!> [ B11 | B12 0 0 ]
24184-
!> [ 0 | 0 -I 0 ]
24183+
!> [ B11 | B12 0 0 ]
24184+
!> [ 0 | 0 -I 0 ]
2418524185
!> X = [----------------]
24186-
!> [ B21 | B22 0 0 ]
24187-
!> [ 0 | 0 0 I ]
24188-
!> [ C | -S 0 0 ]
24189-
!> [ U1 | ] [ 0 | 0 -I 0 ] [ V1 | ]**T
24186+
!> [ B21 | B22 0 0 ]
24187+
!> [ 0 | 0 0 I ]
24188+
!> [ C | -S 0 0 ]
24189+
!> [ U1 | ] [ 0 | 0 -I 0 ] [ V1 | ]**T
2419024190
!> = [---------] [---------------] [---------] .
24191-
!> [ | U2 ] [ S | C 0 0 ] [ | V2 ]
24192-
!> [ 0 | 0 0 I ]
24191+
!> [ | U2 ] [ S | C 0 0 ] [ | V2 ]
24192+
!> [ 0 | 0 0 I ]
2419324193
!> X is M-by-M, its top-left block is P-by-Q, and Q must be no larger
2419424194
!> than P, M-P, or M-Q. (If Q is not the smallest index, then X must be
2419524195
!> transposed and/or permuted. This can be done in constant time using

‎fypp/src/la_norms.fypp‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ ${indent}$do ${varname}$${n+1+dim_offset-i}$ = lbound(${matname}$, ${n+1+dim_off
105105
#:endcall
106106
#:enddef
107107

108-
! Vector norms
108+
!> Matrix and Vector norms
109109
module la_norms
110110
use la_constants
111111
use la_blas, only: nrm2
@@ -119,19 +119,19 @@ module la_norms
119119

120120
character(*), parameter :: this = 'norm'
121121

122-
!> List of internal norm flags
122+
! List of internal norm flags
123123
integer(ilp), parameter :: NORM_ONE = 1_ilp
124124
integer(ilp), parameter :: NORM_TWO = 2_ilp
125125
integer(ilp), parameter :: NORM_POW_FIRST = 3_ilp
126126
integer(ilp), parameter :: NORM_INF = +huge(0_ilp) ! infinity norm
127127
integer(ilp), parameter :: NORM_POW_LAST = NORM_INF - 1_ilp
128128
integer(ilp), parameter :: NORM_MINUSINF = -huge(0_ilp)
129129

130-
!> List of *LANGE norm flags
131-
character, parameter :: LANGE_NORM_MAT = 'M' ! maxval(sum(abs(a))) ! over whole matrix: unused
132-
character, parameter :: LANGE_NORM_ONE = '1' ! maxval(sum(abs(a),1)) ! over columns
133-
character, parameter :: LANGE_NORM_INF = 'I' ! maxval(sum(abs(a),2)) ! over rows
134-
character, parameter :: LANGE_NORM_TWO = 'E' ! "Euclidean" or "Frobenius"
130+
! List of *LANGE norm flags
131+
character, parameter :: LANGE_NORM_MAT = 'M' !> maxval(sum(abs(a))), over whole matrix: unused
132+
character, parameter :: LANGE_NORM_ONE = '1' !> maxval(sum(abs(a),1)), over columns
133+
character, parameter :: LANGE_NORM_INF = 'I' !> maxval(sum(abs(a),2)), over rows
134+
character, parameter :: LANGE_NORM_TWO = 'E' !> "Euclidean" or "Frobenius"
135135

136136

137137
!> Vector norm: function interface

‎src/la_constants.f90‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
!> Supported kind parameters
12
module la_constants
23
use iso_fortran_env,only:real32,real64,real128,int32,int64
34
use,intrinsic :: ieee_arithmetic,only:ieee_is_nan
@@ -7,12 +8,21 @@ module la_constants
78
implicit none(type,external)
89
public
910

11+
!> Single-precision floats
1012
integer,parameter :: sp = real32
13+
14+
!> Double-precision floats
1115
integer,parameter :: dp = real64
16+
17+
!> Quadruple-precision floats
1218
integer,parameter :: qp = real128
19+
20+
!> Internal logical kind
1321
integer,parameter :: lk = kind(.true.)
14-
! Integer size support for ILP64 builds should be done here
22+
23+
!> 32-bit integer size type
1524
integer,parameter :: ilp = int32
25+
1626
private :: int32,int64
1727

1828
end module la_constants

‎src/la_determinant.f90‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
!> Determinant of a rectangular matrix
12
module la_determinant
23
use la_constants
34
use la_blas
@@ -7,6 +8,10 @@ module la_determinant
78
implicit none(type,external)
89
private
910

11+
public :: det
12+
13+
character(*),parameter :: this = 'determinant'
14+
1015
!> @brief Compute the determinant of a rectangular matrix.
1116
!!
1217
!! This function computes the determinant of a real or complex rectangular matrix \f$ A \f$.
@@ -25,10 +30,6 @@ module la_determinant
2530
!! the determinant efficiently from the [getrf](@ref la_lapack::getrf) backend.
2631
!! @warning If `overwrite_a` is enabled, the original contents of A will be lost.
2732
!!
28-
public :: det
29-
30-
character(*),parameter :: this = 'determinant'
31-
3233
interface det
3334
module procedure la_sdeterminant
3435
module procedure la_ddeterminant

‎src/la_lapack.f90‎

Lines changed: 52 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
! LAPACK interface
1+
!> Kind-agnostic LAPACK interface linking to internal or external implementations
22
module la_lapack
33
use la_constants
44
use la_blas
@@ -11,52 +11,57 @@ module la_lapack
1111
use la_lapack_w
1212
implicit none(type,external)
1313
public
14-
15-
!> BBCSD: computes the CS decomposition of a unitary matrix in
16-
!! bidiagonal-block form,
17-
!! [ B11 | B12 0 0 ]
18-
!! [ 0 | 0 -I 0 ]
19-
!! X = [----------------]
20-
!! [ B21 | B22 0 0 ]
21-
!! [ 0 | 0 0 I ]
22-
!! [ C | -S 0 0 ]
23-
!! [ U1 | ] [ 0 | 0 -I 0 ] [ V1 | ]**H
24-
!! = [---------] [---------------] [---------] .
25-
!! [ | U2 ] [ S | C 0 0 ] [ | V2 ]
26-
!! [ 0 | 0 0 I ]
27-
!! X is M-by-M, its top-left block is P-by-Q, and Q must be no larger
28-
!! than P, M-P, or M-Q. (If Q is not the smallest index, then X must be
29-
!! transposed and/or permuted. This can be done in constant time using
30-
!! the TRANS and SIGNS options. See CUNCSD for details.)
31-
!! The bidiagonal matrices B11, B12, B21, and B22 are represented
32-
!! implicitly by angles THETA(1:Q) and PHI(1:Q-1).
33-
!! The unitary matrices U1, U2, V1T, and V2T are input/output.
34-
!! The input matrices are pre- or post-multiplied by the appropriate
35-
!! singular vector matrices.
36-
public :: bbcsd
37-
38-
39-
!> BBCSD: computes the CS decomposition of a unitary matrix in
40-
!! bidiagonal-block form,
41-
!! [ B11 | B12 0 0 ]
42-
!! [ 0 | 0 -I 0 ]
43-
!! X = [----------------]
44-
!! [ B21 | B22 0 0 ]
45-
!! [ 0 | 0 0 I ]
46-
!! [ C | -S 0 0 ]
47-
!! [ U1 | ] [ 0 | 0 -I 0 ] [ V1 | ]**H
48-
!! = [---------] [---------------] [---------] .
49-
!! [ | U2 ] [ S | C 0 0 ] [ | V2 ]
50-
!! [ 0 | 0 0 I ]
51-
!! X is M-by-M, its top-left block is P-by-Q, and Q must be no larger
52-
!! than P, M-P, or M-Q. (If Q is not the smallest index, then X must be
53-
!! transposed and/or permuted. This can be done in constant time using
54-
!! the TRANS and SIGNS options. See CUNCSD for details.)
55-
!! The bidiagonal matrices B11, B12, B21, and B22 are represented
56-
!! implicitly by angles THETA(1:Q) and PHI(1:Q-1).
57-
!! The unitary matrices U1, U2, V1T, and V2T are input/output.
58-
!! The input matrices are pre- or post-multiplied by the appropriate
59-
!! singular vector matrices.
14+
15+
!> @brief BBCSD computes the CS decomposition of a unitary matrix in
16+
!> bidiagonal-block form.
17+
!>
18+
!> \f[
19+
!> \renewcommand\arraystretch{1.3}
20+
!> \left[
21+
!> \begin{array}{c|ccc}
22+
!> B_{11} & B_{12} & 0 & 0 \\
23+
!> 0 & 0 & -I & 0 \\
24+
!> \hline
25+
!> B_{21} & B_{22} & 0 & 0 \\
26+
!> 0 & 0 & 0 & I \\
27+
!> C & -S & 0 & 0
28+
!> \end{array}
29+
!> \right] =
30+
!> \left[
31+
!> \begin{array}{c|c}
32+
!> U_1 & 0 \\
33+
!> \hline
34+
!> 0 & U_2
35+
!> \end{array}
36+
!> \right]
37+
!> \left[
38+
!> \begin{array}{c|ccc}
39+
!> 0 & 0 & -I & 0 \\
40+
!> \hline
41+
!> S & C & 0 & 0 \\
42+
!> 0 & 0 & 0 & I
43+
!> \end{array}
44+
!> \right]
45+
!> \left[
46+
!> \begin{array}{c|c}
47+
!> V_1^H & 0 \\
48+
!> \hline
49+
!> 0 & V_2^H
50+
!> \end{array}
51+
!> \right]
52+
!> \f]
53+
!>
54+
!> X is \f$M \times M\f$, its top-left block is \f$P \times Q\f$, and \f$Q\f$ must be no larger
55+
!> than \f$P\f$, \f$M-P\f$, or \f$M-Q\f$. (If \f$Q\f$ is not the smallest index, then X must be
56+
!> transposed and/or permuted. This can be done in constant time using
57+
!> the TRANS and SIGNS options. See CUNCSD for details.)
58+
!>
59+
!> The bidiagonal matrices \f$B_{11}\f$, \f$B_{12}\f$, \f$B_{21}\f$, and \f$B_{22}\f$ are represented
60+
!> implicitly by angles \f$\theta(1:Q)\f$ and \f$\phi(1:Q-1)\f$.
61+
!>
62+
!> The unitary matrices \f$U_1\f$, \f$U_2\f$, \f$V_1^T\f$, and \f$V_2^T\f$ are input/output.
63+
!>
64+
!> The input matrices are pre- or post-multiplied by the appropriate singular vector matrices.
6065
interface bbcsd
6166
#ifdef LA_EXTERNAL_LAPACK
6267
pure subroutine cbbcsd(jobu1,jobu2,jobv1t,jobv2t,trans,m,p,q,theta,phi, &

‎src/la_norms.f90‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
2-
! Vector norms
1+
!> Matrix and Vector norms
32
module la_norms
43
use la_constants
54
use la_blas,only:nrm2

0 commit comments

Comments
 (0)