Skip to content

Commit ddfa285

Browse files
perazzperazz
authored
Doxygen improvements (#71)
2 parents 40dbef8 + ca734e3 commit ddfa285

File tree

10 files changed

+308
-84
lines changed

10 files changed

+308
-84
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,4 @@ assets/lapack_sources
77
build/
88
project/bin
99
project/doxygen/html
10+
project/doxygen/doxygen.log

‎README.md

Lines changed: 157 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,163 @@ A full and standardized implementation of the present library has been integrate
55

66
# Current API
77

8-
[The documentation site](https://perazz.github.io/fortran-lapack/index.html) contains full documentation for the library.
9-
10-
Procedure | Type | Description | Optional arguments
11-
--- | --- | --- | ---
12-
`solve(A,b)` | function | Solve linear systems - one (`b(:)`) or many (`b(:,:)`) | `solve(A,b,overwrite_a,err)`: option to let A be destroyed, return state handler `err`
13-
`lstsq(A,b)` | function | Solve non-square systems in a least squares sense - one (`b(:)`) or many (`b(:,:)`) | `lstsq(A,b,cond,overwrite_a,rank,err)`: `cond` is optional SVD cutoff; `rank` to return matrix rank, `err` to return state handler
14-
`det(A)` | function | Determinant of a scalar or square matrix | `det(A,overwrite_a,err=err)`: option to let A be destroyed, return state handler `err`
15-
`inv(A)` | function | Inverse of a scalar or square matrix | `inv(A,err=err)`: A is not destroyed; return state handler `err`
16-
`pinv(A)` | function | Moore-Penrose Pseudo-Inverse of a matrix | `pinv(A,rtol,err=err)`: A is not destroyed; optional singular value threshold `rtol`; return state handler `err`
17-
`invert(A)` | subroutine | In-place inverse of a scalar or square matrix | `call invert(A,err=err)`: A is replaced with $A^{-1}$, return state handler `err`
18-
`.inv.A` | operator | Inverse of a scalar or square matrix | A is replaced with $A^{-1}$
19-
`.pinv.A` | operator | Moore-Penrose Pseudo-Inverse | A is replaced with $A^{-1}$
20-
`svd(A)` | subroutine | Singular value decomposition of $A = U S V^t$ | `call svd(A,s,u,vt,full_matrices=.false.,err=state)`, all optional arguments but `A,s`
21-
`svdvals(A)` | function | Singular values $S$ from $A = U S V^t$ | `s = svdvals(A)`, real array with same precision as `A`
22-
`eye(m)` | function | Identity matrix of size `m` | `eye(m,n,mold,err)`: Optional column size `n`, datatype `dtype` (default: real64), error handler
23-
`eigvals(A)` | function | Eigenvalues of matrix $A$ | `eigvals(A,err)`: Optional state handler `err`
24-
`eig(A,lambda)` | subroutine | Eigenproblem of matrix $A$ | `eig(A,lambda,left,right,overwrite_a,err)`: optional output eigenvector matrices (left and/or right)
25-
`eigvalsh(A)` | function | Eigenvalues of symmetric or hermitian matrix $A$ | `eigvalsh(A,upper_a,err)`: Choose to use upper or lower triangle; optional state handler `err`
26-
`eigh(A,lambda)` | subroutine | Eigenproblem of symmetric or hermitianmatrix $A$ | `eigh(A,lambda,vector,upper_a,overwrite_a,err)`: optional output eigenvectors
27-
`diag(n,source)` | function | Diagonal matrix from scalar input value | `diag(n,source,err)`: Optional error handler
28-
`diag(source)` | function | Diagonal matrix from array input values | `diag(source,err)`: Optional error handler
29-
`qr(A,Q,R)` | subroutine | QR factorization | `qr(A,Q,R,storage=work,err=err)`: Optional pre-allocated working storage, error handler
30-
`qr_space(A,lwork)` | subroutine | QR Working space size | `qr_space(A,lwork,err)`: Optional error handler
8+
## [`solve`](@ref la_solve::solve) - Solves a linear matrix equation or a linear system of equations.
9+
10+
### Syntax
11+
12+
`x = solve(a, b [, overwrite_a] [, err])`
13+
14+
### Description
15+
16+
Solve linear systems - one (`b(:)`) or many (`b(:,:)`).
17+
18+
### Arguments
19+
20+
- `a`: A `real` or `complex` coefficient matrix. If `overwrite_a=.true.`, it is destroyed by the call.
21+
- `b`: A rank-1 (one system) or rank-2 (many systems) array of the same kind as `a`, containing the right-hand-side vector(s).
22+
- `overwrite_a` (optional, default = `.false.`): If `.true.`, input matrix `a` will be used as temporary storage and overwritten, to avoid internal data allocation.
23+
- `err` (optional): A [`type(la_state)`](@ref la_state_type::la_state) variable.
24+
25+
### Return value
26+
27+
For a full-rank matrix, returns an array value that represents the solution to the linear system of equations.
28+
29+
### Errors
30+
31+
- Raises [`LINALG_ERROR`](@ref la_state_type::linalg_error) if the matrix is singular to working precision.
32+
- Raises [`LINALG_VALUE_ERROR`](@ref la_state_type::linalg_value_error) if the matrix and rhs vectors have invalid/incompatible sizes.
33+
- If `err` is not present, exceptions trigger an `error stop`.
34+
35+
36+
## `lstsq(A, b)`
37+
**Type**: Function
38+
**Description**: Solve non-square systems in a least squares sense - one (`b(:)`) or many (`b(:,:)`).
39+
**Optional arguments**:
40+
- `cond`: Optional SVD cutoff.
41+
- `overwrite_a`: Option to let A be destroyed.
42+
- `rank`: Return matrix rank.
43+
- `err`: Return state handler.
44+
45+
## `det(A)`
46+
**Type**: Function
47+
**Description**: Determinant of a scalar or square matrix.
48+
**Optional arguments**:
49+
- `overwrite_a`: Option to let A be destroyed.
50+
- `err`: Return state handler.
51+
52+
## `inv(A)`
53+
**Type**: Function
54+
**Description**: Inverse of a scalar or square matrix.
55+
**Optional arguments**:
56+
- `err`: Return state handler.
57+
58+
## `pinv(A)`
59+
**Type**: Function
60+
**Description**: Moore-Penrose Pseudo-Inverse of a matrix.
61+
**Optional arguments**:
62+
- `rtol`: Optional singular value threshold.
63+
- `err`: Return state handler.
64+
65+
## `invert(A)`
66+
**Type**: Subroutine
67+
**Description**: In-place inverse of a scalar or square matrix.
68+
**Optional arguments**:
69+
- `err`: Return state handler.
70+
71+
**Usage**: `call invert(A, err=err)` where `A` is replaced with $A^{-1}$.
72+
73+
## `.inv.A`
74+
**Type**: Operator
75+
**Description**: Inverse of a scalar or square matrix.
76+
77+
**Effect**: `A` is replaced with $A^{-1}$.
78+
79+
## `.pinv.A`
80+
**Type**: Operator
81+
**Description**: Moore-Penrose Pseudo-Inverse.
82+
83+
**Effect**: `A` is replaced with $A^{-1}$.
84+
85+
## `svd(A)`
86+
**Type**: Subroutine
87+
**Description**: Singular value decomposition of $A = U S V^t$.
88+
**Optional arguments**:
89+
- `s`: Singular values.
90+
- `u`: Left singular vectors.
91+
- `vt`: Right singular vectors.
92+
- `full_matrices`: Defaults to `.false.`.
93+
- `err`: State handler.
94+
95+
**Usage**: `call svd(A, s, u, vt, full_matrices=.false., err=state)`.
96+
97+
## `svdvals(A)`
98+
**Type**: Function
99+
**Description**: Singular values $S$ from $A = U S V^t$.
100+
**Usage**: `s = svdvals(A)` where `s` is a real array with the same precision as `A`.
101+
102+
## `eye(m)`
103+
**Type**: Function
104+
**Description**: Identity matrix of size `m`.
105+
**Optional arguments**:
106+
- `n`: Optional column size.
107+
- `mold`: Optional datatype (default: real64).
108+
- `err`: Error handler.
109+
110+
## `eigvals(A)`
111+
**Type**: Function
112+
**Description**: Eigenvalues of matrix $A$.
113+
**Optional arguments**:
114+
- `err`: State handler.
115+
116+
## `eig(A, lambda)`
117+
**Type**: Subroutine
118+
**Description**: Eigenproblem of matrix $A`.
119+
**Optional arguments**:
120+
- `left`: Output left eigenvector matrix.
121+
- `right`: Output right eigenvector matrix.
122+
- `overwrite_a`: Option to let A be destroyed.
123+
- `err`: Return state handler.
124+
125+
## `eigvalsh(A)`
126+
**Type**: Function
127+
**Description**: Eigenvalues of symmetric or Hermitian matrix $A$.
128+
**Optional arguments**:
129+
- `upper_a`: Choose to use upper or lower triangle.
130+
- `err`: State handler.
131+
132+
## `eigh(A, lambda)`
133+
**Type**: Subroutine
134+
**Description**: Eigenproblem of symmetric or Hermitian matrix $A`.
135+
**Optional arguments**:
136+
- `vector`: Output eigenvectors.
137+
- `upper_a`: Choose to use upper or lower triangle.
138+
- `overwrite_a`: Option to let A be destroyed.
139+
- `err`: Return state handler.
140+
141+
## `diag(n, source)`
142+
**Type**: Function
143+
**Description**: Diagonal matrix from scalar input value.
144+
**Optional arguments**:
145+
- `err`: Error handler.
146+
147+
## `diag(source)`
148+
**Type**: Function
149+
**Description**: Diagonal matrix from array input values.
150+
**Optional arguments**:
151+
- `err`: Error handler.
152+
153+
## `qr(A, Q, R)`
154+
**Type**: Subroutine
155+
**Description**: QR factorization.
156+
**Optional arguments**:
157+
- `storage`: Pre-allocated working storage.
158+
- `err`: Error handler.
159+
160+
## `qr_space(A, lwork)`
161+
**Type**: Subroutine
162+
**Description**: QR Working space size.
163+
**Optional arguments**:
164+
- `err`: Error handler.
31165

32166
All procedures work with all types (`real`, `complex`) and kinds (32, 64, 128-bit floats).
33167

‎fypp/src/la_least_squares.fypp

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
#:include "common.fypp"
2+
!> Least squares solution interface
23
module la_least_squares
34
use la_constants
45
use la_blas
@@ -8,12 +9,35 @@ module la_least_squares
89
implicit none(type,external)
910
private
1011

11-
!> Compute a least squares solution to system Ax=b, i.e. such that the 2-norm abs(b-Ax) is minimized.
12+
!> @brief Compute a least squares solution to system \f$ A \cdot x = b \f$,
13+
!! i.e. such that the 2-norm \f$ \|b - A \cdot x\| \f$ is minimized.
14+
!!
15+
!! This function computes the least-squares solution to a real system of linear equations:
16+
!!
17+
!! \f$ A \cdot x = b \f$
18+
!!
19+
!! where A is an `n x n` matrix and b is either a vector (`n`) or a matrix (`n x nrhs`).
20+
!! The solution `x` is returned as an allocatable array.
21+
!!
22+
!! @param[in,out] a The input matrix of size `n x n`. If `overwrite_a` is true,
23+
!! the contents of A may be modified during computation.
24+
!! @param[in] b The right-hand side vector (`n`) or matrix (`n x nrhs`).
25+
!! @param[in] cond (Optional) A cutoff for rank evaluation: singular values \f$ s(i) \f$ such that
26+
!! \f$ s(i) \leq \text{cond} \cdot \max(s) \f$ are considered zero.
27+
!! @param[in] overwrite_a (Optional) If true, A and B may be overwritten and destroyed. Default is false.
28+
!! @param[out] rank (Optional) The rank of the matrix A.
29+
!! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided,
30+
!! the function will stop execution.
31+
!!
32+
!! @return Solution matrix `x` of size `n` (for a single right-hand side) or `n x nrhs`.
33+
!!
34+
!! @note This function relies on LAPACK least-squares solvers such as `[*GELSS](@ref la_lapack::gelss)`.
35+
!!
36+
!! @warning If `overwrite_a` is enabled, the original contents of A and B may be lost.
37+
!!
1238
public :: lstsq
1339

14-
! NumPy: lstsq(a, b, rcond='warn')
15-
! Scipy: lstsq(a, b, cond=None, overwrite_a=False, overwrite_b=False, check_finite=True, lapack_driver=None)
16-
! IMSL: Result = IMSL_QRSOL(B, [A] [, AUXQR] [, BASIS] [, /DOUBLE] [, QR] [, PIVOT] [, RESIDUAL] [, TOLERANCE])
40+
public :: lstsq
1741

1842
interface lstsq
1943
#:for nd,ndsuf,nde in ALL_RANKS
@@ -27,7 +51,7 @@ module la_least_squares
2751
contains
2852

2953
#:for rk,rt,ri in ALL_KINDS_TYPES
30-
! Workspace needed by gesv
54+
!> Workspace needed by gesv
3155
subroutine ${ri}$gesv_space(m,n,nrhs,lrwork,liwork,lcwork)
3256
integer(ilp), intent(in) :: m,n,nrhs
3357
integer(ilp), intent(out) :: lrwork,liwork,lcwork
@@ -68,7 +92,7 @@ module la_least_squares
6892
#:for nd,ndsuf,nde in ALL_RANKS
6993
#:for rk,rt,ri in ALL_KINDS_TYPES
7094

71-
! Compute the least-squares solution to a real system of linear equations Ax = B
95+
!> Compute the least-squares solution to a real system of linear equations Ax = B
7296
function la_${ri}$lstsq${ndsuf}$(a,b,cond,overwrite_a,rank,err) result(x)
7397
!> Input matrix a[n,n]
7498
${rt}$, intent(inout), target :: a(:,:)

‎fypp/src/la_solve.fypp

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,30 @@ module la_solve
88
implicit none(type,external)
99
private
1010

11-
!> Solve a linear system
11+
!> @brief Solve a system of linear equations A * X = B.
12+
!!
13+
!! This function computes the solution to a real system of linear equations:
14+
!!
15+
!! \f$ A \cdot X = B \f$
16+
!!
17+
!! where A is an `n x n` square matrix, and B is either a vector (`n`) or a matrix (`n x nrhs`).
18+
!! The solution X is returned as an allocatable array.
19+
!!
20+
!! @param[in,out] A The input square matrix of size `n x n`. If `overwrite_a` is true,
21+
!! the contents of A may be modified during computation.
22+
!! @param[in] B The right-hand side vector (size `n`) or matrix (size `n x nrhs`).
23+
!! @param[in] overwrite_a (Optional) If true, A may be overwritten and destroyed. Default is false.
24+
!! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided,
25+
!! the function will stop execution.
26+
!!
27+
!! @return Solution matrix X of size `n` (for a single right-hand side) or `n x nrhs`.
28+
!!
29+
!! @note This function relies on LAPACK LU decomposition based solvers `*GESV`.
30+
!!
31+
!! @warning If `overwrite_a` is enabled, the original contents of A may be lost.
32+
!!
1233
public :: solve
1334

14-
15-
! Scipy: solve(a, b, lower=False, overwrite_a=False, overwrite_b=False, check_finite=True, assume_a='gen', transposed=False)[source]#
16-
! IMSL: lu_solve(a, b, transpose=False)
17-
1835
interface solve
1936
#:for nd,ndsuf,nde in ALL_RANKS
2037
#:for rk,rt,ri in ALL_KINDS_TYPES
@@ -55,7 +72,7 @@ module la_solve
5572

5673
#:for nd,ndsuf,nde in ALL_RANKS
5774
#:for rk,rt,ri in ALL_KINDS_TYPES
58-
! Compute the solution to a real system of linear equations A * X = B
75+
!> Linear system solve, ${ndsuf}$, ${rt}$
5976
function la_${ri}$solve${ndsuf}$(a,b,overwrite_a,err) result(x)
6077
!> Input matrix a[n,n]
6178
${rt}$, intent(inout), target :: a(:,:)

‎project/doxygen/Doxyfile

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ ABBREVIATE_BRIEF = "The $name class" \
4040
an \
4141
the
4242

43-
ALWAYS_DETAILED_SEC = NO
43+
ALWAYS_DETAILED_SEC = YES
4444
INLINE_INHERITED_MEMB = NO
4545
FULL_PATH_NAMES = NO
4646
STRIP_FROM_PATH =
@@ -104,6 +104,7 @@ OPTIMIZE_OUTPUT_VHDL = NO
104104

105105

106106
EXTENSION_MAPPING = .F90=Fortran
107+
EXTENSION_MAPPING += .f90=Fortran
107108

108109
# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
109110
# according to the Markdown format, which allows for more readable
@@ -289,14 +290,16 @@ EXCLUDE_PATTERNS =
289290
# Note that the wildcards are matched against the file with absolute path, so to
290291
# exclude all test directories use the pattern */test/*
291292

292-
EXCLUDE_SYMBOLS = la_blas_s
293-
EXCLUDE_SYMBOLS += la_blas_d
294-
EXCLUDE_SYMBOLS += la_blas_q
295-
EXCLUDE_SYMBOLS += la_blas_c
296-
EXCLUDE_SYMBOLS += la_blas_z
297-
EXCLUDE_SYMBOLS += la_blas_w
298-
EXCLUDE_SYMBOLS += la_blas_aux
299-
EXCLUDE_SYMBOLS += la_lapack_aux
293+
EXCLUDE_SYMBOLS =
294+
295+
#EXCLUDE_SYMBOLS = la_blas_s
296+
#EXCLUDE_SYMBOLS += la_blas_d
297+
#EXCLUDE_SYMBOLS += la_blas_q
298+
#EXCLUDE_SYMBOLS += la_blas_c
299+
#EXCLUDE_SYMBOLS += la_blas_z
300+
#EXCLUDE_SYMBOLS += la_blas_w
301+
#EXCLUDE_SYMBOLS += la_blas_aux
302+
#EXCLUDE_SYMBOLS += la_lapack_aux
300303

301304
EXAMPLE_PATH = "../../example/"
302305
EXAMPLE_PATTERNS =
@@ -407,7 +410,8 @@ PAPER_TYPE = a4
407410
# If left blank no extra packages will be included.
408411
# This tag requires that the tag GENERATE_LATEX is set to YES.
409412

410-
EXTRA_PACKAGES ={amsmath,amssymb}
413+
EXTRA_PACKAGES = {amsmath}
414+
EXTRA_PACKAGES += {amssymb}
411415

412416
LATEX_HEADER =
413417
PDF_HYPERLINKS = YES

‎project/fortran-lapack.cbp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -187,7 +187,7 @@
187187
<doxyfile_project />
188188
<doxyfile_build extract_all="1" />
189189
<doxyfile_warnings />
190-
<doxyfile_output />
190+
<doxyfile_output latex="1" />
191191
<doxyfile_dot />
192192
<general />
193193
</DoxyBlocks>

‎src/la_blas.F90

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
!> Precision-agnostic BLAS interface
12
module la_blas
23
use la_constants
34
use la_blas_aux

‎src/la_lapack.f90

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
!> Precision-agnostic LAPACK interface
12
module la_lapack
23
use la_constants
34
use la_blas

0 commit comments

Comments
 (0)