Skip to content

Commit 30d4ec7

Browse files
perazzperazz
authored
Further docs: Cholesky, eigenvalues (#76)
2 parents bbde965 + fac85f9 commit 30d4ec7

File tree

5 files changed

+772
-149
lines changed

5 files changed

+772
-149
lines changed

‎README.md

Lines changed: 271 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,277 @@ A full and standardized implementation of the present library has been integrate
77

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

10+
## [chol](@ref la_cholesky::chol) - Cholesky factorization of a matrix (function).
11+
12+
### Syntax
13+
14+
`c = chol(a [, lower] [, other_zeroed])`
15+
16+
### Description
17+
18+
This function computes the Cholesky factorization of a real symmetric or complex Hermitian matrix \f$ A \f$:
19+
20+
\f[
21+
A = L L^T = U^T U
22+
\f]
23+
24+
where \f$ L \f$ is a lower triangular matrix and \f$ U \f$ is an upper triangular matrix.
25+
The function returns the factorized matrix as a new allocation, without modifying the input matrix.
26+
27+
### Arguments
28+
29+
- `a`: A `real` or `complex` matrix of size \f$ [n,n] \f$, representing the symmetric/Hermitian input matrix.
30+
- `lower` (optional): A logical flag indicating whether the lower (\f$ L \f$) or upper (\f$ U \f$) triangular factor should be computed. Defaults to `lower = .true.`.
31+
- `other_zeroed` (optional): A logical flag determining whether the unused half of the returned matrix should be explicitly zeroed. Defaults to `other_zeroed = .true.`.
32+
33+
### Return value
34+
35+
- `c`: A `real` or `complex` matrix of size \f$ [n,n] \f$, containing the Cholesky factors. The returned matrix is triangular (upper or lower, as selected).
36+
37+
### Errors
38+
39+
- Raises [LINALG_VALUE_ERROR](@ref la_state_type::linalg_value_error) if the input matrix ihas invalid size.
40+
- Raises [LINALG_ERROR](@ref la_state_type::linalg_error) if numerical instability prevents factorization.
41+
- If error handling is not provided, exceptions will trigger an `error stop`.
42+
43+
### Notes
44+
45+
- The function is based on LAPACK's [POTRF](@ref la_lapack::potrf) routines.
46+
- This function allocates a new matrix to store the factorization. For an in-place version, use [cholesky](@ref la_cholesky::cholesky).
47+
48+
## [cholesky](@ref la_cholesky::cholesky) - Cholesky factorization of a matrix (subroutine).
49+
50+
### Syntax
51+
52+
`call cholesky(a [, c] [, lower] [, other_zeroed])`
53+
54+
### Description
55+
56+
This subroutine computes the Cholesky factorization of a real symmetric or complex Hermitian matrix \f$ A \f$:
57+
58+
\f[
59+
A = L L^T = U^T U
60+
\f]
61+
62+
where \f$ L \f$ is a lower triangular matrix and \f$ U \f$ is an upper triangular matrix. The factorization is performed in-place, modifying the input matrix `a`,
63+
or on a pre-allocated matrix `c` with the same type and kind as `a`.
64+
65+
### Arguments
66+
67+
- `a`: A `real` or `complex` matrix of size \f$ [n,n] \f$, representing the symmetric/Hermitian input matrix. if `c` is not provided, on return it contains the Cholesky factorization.
68+
- `c` (optional): A matrix of size \f$ [n,n] \f$, of the same type and kind as `a`, containing the Cholesky factorization. If provided, `a` is unchanged.
69+
- `lower` (optional): A logical flag indicating whether the lower (\f$ L \f$) or upper (\f$ U \f$) triangular factor should be computed. Defaults to `lower = .true.`.
70+
- `other_zeroed` (optional): A logical flag determining whether the unused half of the matrix should be explicitly zeroed. Defaults to `other_zeroed = .true.`.
71+
72+
### Errors
73+
74+
- Raises [LINALG_VALUE_ERROR](@ref la_state_type::linalg_value_error) if the input matrix is not positive definite.
75+
- Raises [LINALG_ERROR](@ref la_state_type::linalg_error) if numerical instability prevents factorization.
76+
- If error handling is not provided, exceptions will trigger an `error stop`.
77+
78+
### Notes
79+
80+
- The returned Cholesky factorization matrix is triangular (upper or lower, as selected).
81+
- The subroutine is based on LAPACK's [POTRF](@ref la_lapack::potrf) routines.
82+
- This subroutine modifies the input matrix in-place. For a version that returns a newly allocated matrix, use [chol](@ref la_cholesky::chol).
83+
84+
## [eig](@ref la_eig::eig) - Eigendecomposition of a square matrix.
85+
86+
### Syntax
87+
88+
`call eig(a [, b] [, lambda] [, right] [, left] [, overwrite_a] [, overwrite_b] [, err])`
89+
90+
### Description
91+
92+
This interface provides methods for computing the eigenvalues and eigenvectors of a real or complex matrix.
93+
It supports both standard and generalized eigenvalue problems, allowing for the decomposition of a matrix `A` alone or a pair of matrices `(A, B)` in the generalized case.
94+
95+
Given a square matrix \f$ A \f$, this routine computes its eigenvalues \f$ \lambda \f$ and, optionally, its right or left eigenvectors:
96+
97+
\f[
98+
A v = \lambda v
99+
\f]
100+
101+
where \f$ v \f$ represents an eigenvector corresponding to eigenvalue \f$ \lambda \f$.
102+
103+
In the generalized eigenvalue problem case, the routine solves:
104+
105+
\f[
106+
A v = \lambda B v
107+
\f]
108+
109+
The computation supports both `real` and `complex` matrices. If requested, eigenvectors are returned as additional output arguments. The function provides options to allow in-place modification of `A` and `B` for performance optimization.
110+
111+
**Note:** The solution is based on LAPACK's [GEEV](@ref la_lapack::geev) and [GGEV](@ref la_lapack::ggev) routines.
112+
113+
### Arguments
114+
115+
- `a`: A `real` or `complex` matrix of size \f$[n,n]\f$, representing the input matrix to be decomposed.
116+
- `b` (optional): A `real` or `complex` matrix of size \f$[n,n]\f$, same type and kind as `a`, representing the second matrix in the generalized eigenvalue problem.
117+
- `lambda`: A `complex` or `real` array of length \f$ n \f$, containing the computed eigenvalues.
118+
- `right` (optional): A `complex` matrix of size \f$[n,n]\f$ containing the right eigenvectors as columns.
119+
- `left` (optional): A `complex` matrix of size \f$[n,n]\f$ containing the left eigenvectors as columns.
120+
- `overwrite_a` (optional): A logical flag indicating whether `A` can be overwritten for performance optimization.
121+
- `overwrite_b` (optional): A logical flag indicating whether `B` can be overwritten (only in the generalized case).
122+
- `err` (optional): A [type(la_state)](@ref la_state_type::la_state) variable to handle errors. If not provided, execution will stop on errors.
123+
124+
### Errors
125+
126+
- Raises [LINALG_VALUE_ERROR](@ref la_state_type::linalg_value_error) if the matrices have invalid/incompatible sizes.
127+
- Raises [LINALG_ERROR](@ref la_state_type::linalg_error) if the eigendecomposition fails.
128+
- If `err` is not provided, exceptions will trigger an `error stop`.
129+
130+
### Notes
131+
132+
- The computed eigenvectors are normalized.
133+
- If computing real eigenvalues, an error is returned if eigenvalues have nonzero imaginary parts.
134+
- This routine is based on LAPACK's [GEEV](@ref la_lapack::geev) and [GGEV](@ref la_lapack::ggev) routines.
135+
- Overwriting `A` or `B` can improve performance but destroys the original matrix data.
136+
137+
## [eigh](@ref la_eig::eigh) - Eigendecomposition of a real symmetric or complex Hermitian matrix.
138+
139+
### Syntax
140+
141+
`call eigh(a, lambda [, vectors] [, upper_a] [, overwrite_a] [, err])`
142+
143+
### Description
144+
145+
This interface provides methods for computing the eigenvalues and optionally the eigenvectors of a real symmetric or complex Hermitian matrix.
146+
147+
Given a real symmetric or complex Hermitian matrix \f$ A \f$, this routine computes its eigenvalues \f$ \lambda \f$ and, optionally, its right eigenvectors:
148+
149+
\f[
150+
A v = \lambda v
151+
\f]
152+
153+
where \f$ v \f$ represents an eigenvector corresponding to eigenvalue \f$ \lambda \f$.
154+
155+
The computation supports both real and complex matrices, and the eigenvectors, if requested, are returned as orthonormal vectors.
156+
157+
**Note:** The solution is based on LAPACK's [SYEVD](@ref la_lapack::syevd) and [HEEVD](@ref la_lapack::heevd) routines.
158+
159+
### Arguments
160+
161+
- `a`: A `real` or `complex` matrix of size \f$[n,n]\f$, representing the input matrix to be decomposed. The matrix is overwritten with the eigenvalues on output.
162+
- `lambda`: A `real` array of length \f$ n \f$, with the same kind as `a`, containing the computed eigenvalues.
163+
- `vectors` (optional): A matrix of size \f$[n,n]\f$, with the same type and kind as `a`, containing the right eigenvectors stored as columns.
164+
- `overwrite_a` (optional): A logical flag indicating whether the matrix `A` can be overwritten for performance optimization.
165+
- `upper_a` (optional): A logical flag indicating whether the upper half of matrix `A` should be used for computation (default is the lower half).
166+
- `err` (optional): A [type(la_state)](@ref la_state_type::la_state) variable to handle errors. If not provided, execution will stop on errors.
167+
168+
### Errors
169+
170+
- Raises [LINALG_VALUE_ERROR](@ref la_state_type::linalg_value_error) if the matrices have invalid/incompatible sizes.
171+
- Raises [LINALG_ERROR](@ref la_state_type::linalg_error) if the eigendecomposition fails.
172+
- If `err` is not provided, exceptions will trigger an `error stop`.
173+
174+
### Notes
175+
176+
- The computed eigenvectors are orthonormal.
177+
- Eigenvalues are real for symmetric or Hermitian matrices.
178+
- This routine is based on LAPACK's [SYEVD](@ref la_lapack::syevd) and [HEEVD](@ref la_lapack::heevd) routines.
179+
- Overwriting the matrix `A` can improve performance but destroys the original matrix data.
180+
181+
## [eigvals](@ref la_eig::eigvals) - Eigenvalues of a square matrix (interface).
182+
183+
### Syntax
184+
185+
`lambda = eigvals(a [, b] [, err])`
186+
187+
### Description
188+
189+
This interface provides methods for computing the eigenvalues of a real or complex square matrix.
190+
It supports both standard and generalized eigenvalue problems.
191+
192+
- In the standard eigenvalue problem, the function computes the eigenvalues \f$\lambda\f$ of the matrix \f$A\f$ such that:
193+
194+
\f[
195+
A v = \lambda v
196+
\f]
197+
198+
where \f$v\f$ is the eigenvector corresponding to eigenvalue \f$\lambda\f$.
199+
200+
- In the generalized eigenvalue problem, the function solves:
201+
202+
\f[
203+
A v = \lambda B v
204+
\f]
205+
206+
where \f$A\f$ and \f$B\f$ are the input matrices and \f$\lambda\f$ is the eigenvalue.
207+
208+
The function returns an array of eigenvalues computed for the input matrix \f$A\f$, and optionally the matrix \f$B\f$ for the generalized case.
209+
210+
**Note:** The solution is based on LAPACK's [GEEV](@ref la_lapack::geev) and [GGEV](@ref la_lapack::ggev) routines.
211+
212+
### Arguments
213+
214+
- `a`: A `real` or `complex` matrix of size \f$[n,n]\f$, representing the input matrix to be decomposed.
215+
- `b` (optional, generalized case): A matrix of size \f$[n,n]\f$ and same type and kind as `a`, representing the second matrix in the generalized eigenvalue problem.
216+
- `err` (optional): A [type(la_state)](@ref la_state_type::la_state) variable to handle errors. If not provided, execution will stop on errors.
217+
218+
### Return value
219+
220+
- `lambda`: A `complex` array of eigenvalues, computed from the input matrix \f$A\f$ (and \f$B\f$ if in the generalized case).
221+
222+
### Errors
223+
224+
- Raises [LINALG_VALUE_ERROR](@ref la_state_type::linalg_value_error) if the matrices have invalid/incompatible sizes.
225+
- Raises [LINALG_ERROR](@ref la_state_type::linalg_error) if the eigendecomposition fails.
226+
- If `err` is not provided, exceptions will trigger an `error stop`.
227+
228+
### Notes
229+
230+
- The eigenvalues are returned in a complex array, even for real matrices.
231+
- For the generalized eigenvalue problem, matrix \f$B\f$ must be provided and will be modified in-place.
232+
- This routine is based on LAPACK's [GEEV](@ref la_lapack::geev) and [GGEV](@ref la_lapack::ggev) routines.
233+
234+
## [eigvalsh](@ref la_eig::eigvalsh) - Eigenvalues of a real symmetric or complex Hermitian matrix.
235+
236+
### Syntax
237+
238+
`lambda = eigvalsh(a [, upper_a] [, err])`
239+
240+
### Description
241+
242+
This interface provides methods for computing the eigenvalues of a real symmetric or complex Hermitian matrix.
243+
The function computes the eigenvalues of the matrix \f$A\f$, and returns them in an array.
244+
The user can specify whether to use the upper or lower half of the matrix for computation.
245+
246+
- The function solves the eigenvalue problem:
247+
248+
\f[
249+
A v = \lambda v
250+
\f]
251+
252+
where \f$v\f$ is the eigenvector corresponding to eigenvalue \f$\lambda\f$.
253+
254+
- The computation supports both real and complex matrices. Regardless, due to symmetry the eigenvalues are returned as an array of `real` values.
255+
256+
The user can specify whether to use the upper or lower half of the matrix \f$A\f$ for the computation (default: lower half).
257+
258+
**Note:** The solution is based on LAPACK's [SYEV](@ref la_lapack::syev) and [HEEV](@ref la_lapack::heev) routines.
259+
260+
### Arguments
261+
262+
- `a`: A `real` or `complex` matrix of size \f$[n,n]\f$, representing the real symmetric or complex Hermitian matrix to be decomposed.
263+
- `upper_a` (optional): A logical flag indicating whether to use the upper half (`.true.`) or the lower half (`.false.`) of \f$A\f$ for the computation. The default is lower.
264+
- `err` (optional): A [type(la_state)](@ref la_state_type::la_state) variable to handle errors. If not provided, execution will stop on errors.
265+
266+
### Return value
267+
268+
- `lambda`: A `real` array containing the computed eigenvalues of the matrix \f$A\f$.
269+
270+
### Errors
271+
272+
- Raises [LINALG_VALUE_ERROR](@ref la_state_type::linalg_value_error) if the matrix has invalid size.
273+
- Raises [LINALG_ERROR](@ref la_state_type::linalg_error) if the eigendecomposition fails.
274+
- If `err` is not provided, execution will stop on errors.
275+
276+
### Notes
277+
278+
- The eigenvalues are returned in a `real` array, with the same kind as the input matrix `a`.
279+
- This routine is based on LAPACK's [SYEV](@ref la_lapack::syev) and [HEEV](@ref la_lapack::heev) routines.
280+
10281
## [solve](@ref la_solve::solve) - Solve a linear matrix equation or a linear system of equations.
11282

12283
### Syntax
@@ -471,40 +742,6 @@ The function returns a matrix of size \f$m \times n\f$ (or \f$m \times m\f$ if \
471742
- The `mold` scalar is used to provide a function return type.
472743
- If the `err` parameter is provided, the error state of the function will be returned.
473744

474-
475-
## `eigvals(A)`
476-
**Type**: Function
477-
**Description**: Eigenvalues of matrix $A$.
478-
**Optional arguments**:
479-
- `err`: State handler.
480-
481-
## `eig(A, lambda)`
482-
**Type**: Subroutine
483-
**Description**: Eigenproblem of matrix $A`.
484-
**Optional arguments**:
485-
- `left`: Output left eigenvector matrix.
486-
- `right`: Output right eigenvector matrix.
487-
- `overwrite_a`: Option to let A be destroyed.
488-
- `err`: Return state handler.
489-
490-
## `eigvalsh(A)`
491-
**Type**: Function
492-
**Description**: Eigenvalues of symmetric or Hermitian matrix $A$.
493-
**Optional arguments**:
494-
- `upper_a`: Choose to use upper or lower triangle.
495-
- `err`: State handler.
496-
497-
## `eigh(A, lambda)`
498-
**Type**: Subroutine
499-
**Description**: Eigenproblem of symmetric or Hermitian matrix $A`.
500-
**Optional arguments**:
501-
- `vector`: Output eigenvectors.
502-
- `upper_a`: Choose to use upper or lower triangle.
503-
- `overwrite_a`: Option to let A be destroyed.
504-
- `err`: Return state handler.
505-
506-
507-
508745
## [qr](@ref la_qr::qr) - QR factorization of a matrix.
509746

510747
### Syntax

0 commit comments

Comments
 (0)