From bf371217d2262bcc424f112ea9ae8b5bffd4b66a Mon Sep 17 00:00:00 2001 From: Alexis Montoison Date: Tue, 4 Oct 2022 12:39:52 -0400 Subject: [PATCH] Add the size of each linear system in the docstring --- src/bicgstab.jl | 2 +- src/bilq.jl | 2 +- src/bilqr.jl | 4 ++-- src/cg.jl | 7 +++---- src/cg_lanczos.jl | 6 ++---- src/cg_lanczos_shift.jl | 10 +++++----- src/cgls.jl | 2 +- src/cgne.jl | 2 +- src/cgs.jl | 2 +- src/cr.jl | 10 +++++----- src/craig.jl | 2 +- src/craigmr.jl | 2 +- src/crls.jl | 4 ++-- src/crmr.jl | 2 +- src/diom.jl | 2 +- src/dqgmres.jl | 2 +- src/fgmres.jl | 2 +- src/fom.jl | 2 +- src/gmres.jl | 2 +- src/gpmr.jl | 2 +- src/lnlq.jl | 2 +- src/lslq.jl | 2 +- src/lsmr.jl | 2 +- src/lsqr.jl | 2 +- src/minres.jl | 8 ++++---- src/minres_qlp.jl | 4 ++-- src/qmr.jl | 2 +- src/symmlq.jl | 8 ++++---- src/tricg.jl | 2 +- src/trilqr.jl | 4 ++-- src/trimr.jl | 2 +- src/usymlq.jl | 2 +- src/usymqr.jl | 2 +- 33 files changed, 54 insertions(+), 57 deletions(-) diff --git a/src/bicgstab.jl b/src/bicgstab.jl index 2e6ae72b6..ed875827e 100644 --- a/src/bicgstab.jl +++ b/src/bicgstab.jl @@ -24,7 +24,7 @@ export bicgstab, bicgstab! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -Solve the square linear system Ax = b using BICGSTAB. +Solve the square linear system Ax = b of size n using BICGSTAB. BICGSTAB requires two initial vectors `b` and `c`. The relation `bᴴc ≠ 0` must be satisfied and by default `c = b`. diff --git a/src/bilq.jl b/src/bilq.jl index d2b88637c..304c7a67e 100644 --- a/src/bilq.jl +++ b/src/bilq.jl @@ -21,7 +21,7 @@ export bilq, bilq! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -Solve the square linear system Ax = b using BiLQ. +Solve the square linear system Ax = b of size n using BiLQ. BiLQ is based on the Lanczos biorthogonalization process and requires two initial vectors `b` and `c`. The relation `bᴴc ≠ 0` must be satisfied and by default `c = b`. diff --git a/src/bilqr.jl b/src/bilqr.jl index 070f8f253..7ce40ec2c 100644 --- a/src/bilqr.jl +++ b/src/bilqr.jl @@ -27,8 +27,8 @@ Combine BiLQ and QMR to solve adjoint systems. [Aᴴ 0] [x] [c] The relation `bᴴc ≠ 0` must be satisfied. -BiLQ is used for solving primal system `Ax = b`. -QMR is used for solving dual system `Aᴴy = c`. +BiLQ is used for solving primal system `Ax = b` of size n. +QMR is used for solving dual system `Aᴴy = c` of size n. An option gives the possibility of transferring from the BiLQ point to the BiCG point, when it exists. The transfer is based on the residual norm. diff --git a/src/cg.jl b/src/cg.jl index 3a07bc934..0bbe04535 100644 --- a/src/cg.jl +++ b/src/cg.jl @@ -26,16 +26,15 @@ export cg, cg! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -The conjugate gradient method to solve the symmetric linear system Ax = b. +The conjugate gradient method to solve the Hermitian linear system Ax = b of size n. The method does _not_ abort if A is not definite. A preconditioner M may be provided in the form of a linear operator and is -assumed to be symmetric and positive definite. +assumed to be Hermitian and positive definite. M also indicates the weighted norm in which residuals are measured. -If `itmax=0`, the default number of iterations is set to `2 * n`, -with `n = length(b)`. +If `itmax=0`, the default number of iterations is set to `2 * n`. CG can be warm-started from an initial guess `x0` with diff --git a/src/cg_lanczos.jl b/src/cg_lanczos.jl index cb232f4b1..fc8f273de 100644 --- a/src/cg_lanczos.jl +++ b/src/cg_lanczos.jl @@ -23,14 +23,12 @@ export cg_lanczos, cg_lanczos! `FC` is `T` or `Complex{T}`. The Lanczos version of the conjugate gradient method to solve the -symmetric linear system - - Ax = b +Hermitian linear system Ax = b of size n. The method does _not_ abort if A is not definite. A preconditioner M may be provided in the form of a linear operator and is -assumed to be hermitian and positive definite. +assumed to be Hermitian and positive definite. CG-LANCZOS can be warm-started from an initial guess `x0` with diff --git a/src/cg_lanczos_shift.jl b/src/cg_lanczos_shift.jl index 0559d1d5d..be51a8f31 100644 --- a/src/cg_lanczos_shift.jl +++ b/src/cg_lanczos_shift.jl @@ -27,12 +27,12 @@ export cg_lanczos_shift, cg_lanczos_shift! The Lanczos version of the conjugate gradient method to solve a family of shifted systems - (A + αI) x = b (α = α₁, ..., αₙ) + (A + αI) x = b (α = α₁, ..., αₚ) -The method does _not_ abort if A + αI is not definite. +of size n. The method does _not_ abort if A + αI is not definite. A preconditioner M may be provided in the form of a linear operator and is -assumed to be hermitian and positive definite. +assumed to be Hermitian and positive definite. The callback is called as `callback(solver)` and should return `true` if the main loop should terminate, and `false` otherwise. @@ -41,11 +41,11 @@ and `false` otherwise. * `A`: a linear operator that models a Hermitian matrix of dimension n; * `b`: a vector of length n; -* `shifts`: a vector of length nshifts. +* `shifts`: a vector of length p. #### Output arguments -* `x`: a vector of nshifts dense vectors, each one of length n; +* `x`: a vector of p dense vectors, each one of length n; * `stats`: statistics collected on the run in a [`LanczosShiftStats`](@ref) structure. #### References diff --git a/src/cgls.jl b/src/cgls.jl index 437e4cd11..b0c84c9a2 100644 --- a/src/cgls.jl +++ b/src/cgls.jl @@ -42,7 +42,7 @@ Solve the regularized linear least-squares problem minimize ‖b - Ax‖₂² + λ‖x‖₂² -using the Conjugate Gradient (CG) method, where λ ≥ 0 is a regularization +of size n × m using the Conjugate Gradient (CG) method, where λ ≥ 0 is a regularization parameter. This method is equivalent to applying CG to the normal equations (AᴴA + λI) x = Aᴴb diff --git a/src/cgne.jl b/src/cgne.jl index f09da2836..ca7a95565 100644 --- a/src/cgne.jl +++ b/src/cgne.jl @@ -42,7 +42,7 @@ Solve the consistent linear system Ax + √λs = b -using the Conjugate Gradient (CG) method, where λ ≥ 0 is a regularization +of size n × m using the Conjugate Gradient (CG) method, where λ ≥ 0 is a regularization parameter. This method is equivalent to applying CG to the normal equations of the second kind diff --git a/src/cgs.jl b/src/cgs.jl index f498cb37a..78c96831e 100644 --- a/src/cgs.jl +++ b/src/cgs.jl @@ -19,7 +19,7 @@ export cgs, cgs! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -Solve the consistent linear system Ax = b using conjugate gradient squared algorithm. +Solve the consistent linear system Ax = b of size n using CGS. CGS requires two initial vectors `b` and `c`. The relation `bᴴc ≠ 0` must be satisfied and by default `c = b`. diff --git a/src/cr.jl b/src/cr.jl index 5c0eb0b95..d8e43ae18 100644 --- a/src/cr.jl +++ b/src/cr.jl @@ -23,16 +23,16 @@ export cr, cr! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -A truncated version of Stiefel’s Conjugate Residual method to solve the symmetric linear system Ax = b or the least-squares problem min ‖b - Ax‖. -The matrix A must be positive semi-definite. +A truncated version of Stiefel’s Conjugate Residual method to solve the Hermitian linear system Ax = b +of size n or the least-squares problem min ‖b - Ax‖ if A is singular. +The matrix A must be Hermitian semi-definite. -A preconditioner M may be provided in the form of a linear operator and is assumed to be symmetric and positive definite. +A preconditioner M may be provided in the form of a linear operator and is assumed to be Hermitian and positive definite. M also indicates the weighted norm in which residuals are measured. In a linesearch context, 'linesearch' must be set to 'true'. -If `itmax=0`, the default number of iterations is set to `2 * n`, -with `n = length(b)`. +If `itmax=0`, the default number of iterations is set to `2 * n`. CR can be warm-started from an initial guess `x0` with diff --git a/src/craig.jl b/src/craig.jl index dcdaa28d8..02ae8f8c6 100644 --- a/src/craig.jl +++ b/src/craig.jl @@ -47,7 +47,7 @@ Find the least-norm solution of the consistent linear system Ax + λ²y = b -using the Golub-Kahan implementation of Craig's method, where λ ≥ 0 is a +of size n × m using the Golub-Kahan implementation of Craig's method, where λ ≥ 0 is a regularization parameter. This method is equivalent to CGNE but is more stable. diff --git a/src/craigmr.jl b/src/craigmr.jl index a0f5b7477..57a499350 100644 --- a/src/craigmr.jl +++ b/src/craigmr.jl @@ -40,7 +40,7 @@ Solve the consistent linear system Ax + λ²y = b -using the CRAIGMR method, where λ ≥ 0 is a regularization parameter. +of size n × m using the CRAIGMR method, where λ ≥ 0 is a regularization parameter. This method is equivalent to applying the Conjugate Residuals method to the normal equations of the second kind diff --git a/src/crls.jl b/src/crls.jl index 2bdaa7b4b..c57e6a503 100644 --- a/src/crls.jl +++ b/src/crls.jl @@ -34,8 +34,8 @@ Solve the linear least-squares problem minimize ‖b - Ax‖₂² + λ‖x‖₂² -using the Conjugate Residuals (CR) method. This method is equivalent to -applying MINRES to the normal equations +of size n × m using the Conjugate Residuals (CR) method. +This method is equivalent to applying MINRES to the normal equations (AᴴA + λI) x = Aᴴb. diff --git a/src/crmr.jl b/src/crmr.jl index cbd2fc696..b624b8a53 100644 --- a/src/crmr.jl +++ b/src/crmr.jl @@ -40,7 +40,7 @@ Solve the consistent linear system Ax + √λs = b -using the Conjugate Residual (CR) method, where λ ≥ 0 is a regularization +of size n × m using the Conjugate Residual (CR) method, where λ ≥ 0 is a regularization parameter. This method is equivalent to applying CR to the normal equations of the second kind diff --git a/src/diom.jl b/src/diom.jl index 5e4bb996b..9089fa05c 100644 --- a/src/diom.jl +++ b/src/diom.jl @@ -20,7 +20,7 @@ export diom, diom! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -Solve the consistent linear system Ax = b using DIOM. +Solve the consistent linear system Ax = b of size n using DIOM. DIOM only orthogonalizes the new vectors of the Krylov basis against the `memory` most recent vectors. If CG is well defined on `Ax = b` and `memory = 2`, DIOM is theoretically equivalent to CG. diff --git a/src/dqgmres.jl b/src/dqgmres.jl index ddc0c7123..6d08d7292 100644 --- a/src/dqgmres.jl +++ b/src/dqgmres.jl @@ -20,7 +20,7 @@ export dqgmres, dqgmres! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -Solve the consistent linear system Ax = b using DQGMRES. +Solve the consistent linear system Ax = b of size n using DQGMRES. DQGMRES algorithm is based on the incomplete Arnoldi orthogonalization process and computes a sequence of approximate solutions with the quasi-minimal residual property. diff --git a/src/fgmres.jl b/src/fgmres.jl index 0ddfcc87a..c4f3a9fc7 100644 --- a/src/fgmres.jl +++ b/src/fgmres.jl @@ -20,7 +20,7 @@ export fgmres, fgmres! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -Solve the linear system Ax = b using FGMRES. +Solve the linear system Ax = b of size n using FGMRES. FGMRES computes a sequence of approximate solutions with minimum residual. FGMRES is a variant of GMRES that allows changes in the right preconditioner at each iteration. diff --git a/src/fom.jl b/src/fom.jl index 069feb92d..9a102d456 100644 --- a/src/fom.jl +++ b/src/fom.jl @@ -20,7 +20,7 @@ export fom, fom! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -Solve the linear system Ax = b using FOM. +Solve the linear system Ax = b of size n using FOM. FOM algorithm is based on the Arnoldi process and a Galerkin condition. diff --git a/src/gmres.jl b/src/gmres.jl index b1fbe1f69..9c6a5fd08 100644 --- a/src/gmres.jl +++ b/src/gmres.jl @@ -20,7 +20,7 @@ export gmres, gmres! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -Solve the linear system Ax = b using GMRES. +Solve the linear system Ax = b of size n using GMRES. GMRES algorithm is based on the Arnoldi process and computes a sequence of approximate solutions with the minimum residual. diff --git a/src/gpmr.jl b/src/gpmr.jl index 850e385ef..a2990ab2a 100644 --- a/src/gpmr.jl +++ b/src/gpmr.jl @@ -27,7 +27,7 @@ GPMR solves the unsymmetric partitioned linear system [ λI A ] [ x ] = [ b ] [ B μI ] [ y ] [ c ], -where λ and μ are real or complex numbers. +of size (n+m) × (n+m) where λ and μ are real or complex numbers. `A` can have any shape and `B` has the shape of `Aᴴ`. `A`, `B`, `b` and `c` must be all nonzero. diff --git a/src/lnlq.jl b/src/lnlq.jl index 9c956f17e..8a5742b82 100644 --- a/src/lnlq.jl +++ b/src/lnlq.jl @@ -38,7 +38,7 @@ Find the least-norm solution of the consistent linear system Ax + λ²y = b -using the LNLQ method, where λ ≥ 0 is a regularization parameter. +of size n × m using the LNLQ method, where λ ≥ 0 is a regularization parameter. For a system in the form Ax = b, LNLQ method is equivalent to applying SYMMLQ to AAᴴy = b and recovering x = Aᴴy but is more stable. diff --git a/src/lslq.jl b/src/lslq.jl index 7d304a89b..a3aa6994e 100644 --- a/src/lslq.jl +++ b/src/lslq.jl @@ -38,7 +38,7 @@ Solve the regularized linear least-squares problem minimize ‖b - Ax‖₂² + λ²‖x‖₂² -using the LSLQ method, where λ ≥ 0 is a regularization parameter. +of size n × m using the LSLQ method, where λ ≥ 0 is a regularization parameter. LSLQ is formally equivalent to applying SYMMLQ to the normal equations (AᴴA + λ²I) x = Aᴴb diff --git a/src/lsmr.jl b/src/lsmr.jl index 17f8022b2..930443808 100644 --- a/src/lsmr.jl +++ b/src/lsmr.jl @@ -43,7 +43,7 @@ Solve the regularized linear least-squares problem minimize ‖b - Ax‖₂² + λ²‖x‖₂² -using the LSMR method, where λ ≥ 0 is a regularization parameter. +of size n × m using the LSMR method, where λ ≥ 0 is a regularization parameter. LSMR is formally equivalent to applying MINRES to the normal equations (AᴴA + λ²I) x = Aᴴb diff --git a/src/lsqr.jl b/src/lsqr.jl index b3164757a..80ca8003c 100644 --- a/src/lsqr.jl +++ b/src/lsqr.jl @@ -42,7 +42,7 @@ Solve the regularized linear least-squares problem minimize ‖b - Ax‖₂² + λ²‖x‖₂² -using the LSQR method, where λ ≥ 0 is a regularization parameter. +of size n × m using the LSQR method, where λ ≥ 0 is a regularization parameter. LSQR is formally equivalent to applying CG to the normal equations (AᴴA + λ²I) x = Aᴴb diff --git a/src/minres.jl b/src/minres.jl index 570a507de..1abe7160f 100644 --- a/src/minres.jl +++ b/src/minres.jl @@ -3,7 +3,7 @@ # # minimize ‖Ax - b‖₂ # -# where A is square and symmetric. +# where A is Hermitian. # # MINRES is formally equivalent to applying the conjugate residuals method # to Ax = b when A is positive definite, but is more general and also applies @@ -43,8 +43,8 @@ or the shifted linear system (A + λI) x = b -using the MINRES method, where λ ≥ 0 is a shift parameter, -where A is square and symmetric. +of size n using the MINRES method, where λ ≥ 0 is a shift parameter, +where A is Hermitian. MINRES is formally equivalent to applying CR to Ax=b when A is positive definite, but is typically more stable and also applies to the case where @@ -53,7 +53,7 @@ A is indefinite. MINRES produces monotonic residuals ‖r‖₂ and optimality residuals ‖Aᴴr‖₂. A preconditioner M may be provided in the form of a linear operator and is -assumed to be symmetric and positive definite. +assumed to be Hermitian and positive definite. MINRES can be warm-started from an initial guess `x0` with diff --git a/src/minres_qlp.jl b/src/minres_qlp.jl index bc11f4c1a..59ac6c77f 100644 --- a/src/minres_qlp.jl +++ b/src/minres_qlp.jl @@ -27,11 +27,11 @@ export minres_qlp, minres_qlp! `FC` is `T` or `Complex{T}`. MINRES-QLP is the only method based on the Lanczos process that returns the minimum-norm -solution on singular inconsistent systems (A + λI)x = b, where λ is a shift parameter. +solution on singular inconsistent systems (A + λI)x = b of size n, where λ is a shift parameter. It is significantly more complex but can be more reliable than MINRES when A is ill-conditioned. A preconditioner M may be provided in the form of a linear operator and is -assumed to be symmetric and positive definite. +assumed to be Hermitian and positive definite. M also indicates the weighted norm in which residuals are measured. MINRES-QLP can be warm-started from an initial guess `x0` with diff --git a/src/qmr.jl b/src/qmr.jl index a346d2546..c6eed1aa6 100644 --- a/src/qmr.jl +++ b/src/qmr.jl @@ -29,7 +29,7 @@ export qmr, qmr! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -Solve the square linear system Ax = b using QMR. +Solve the square linear system Ax = b of size n using QMR. QMR is based on the Lanczos biorthogonalization process and requires two initial vectors `b` and `c`. The relation `bᴴc ≠ 0` must be satisfied and by default `c = b`. diff --git a/src/symmlq.jl b/src/symmlq.jl index 74c4e8e59..a7b984b2b 100644 --- a/src/symmlq.jl +++ b/src/symmlq.jl @@ -1,5 +1,5 @@ # An implementation of SYMMLQ for the solution of the -# linear system Ax = b, where A is square and symmetric. +# linear system Ax = b, where A is Hermitian. # # This implementation follows the original implementation by # Michael Saunders described in @@ -27,13 +27,13 @@ Solve the shifted linear system (A + λI) x = b -using the SYMMLQ method, where λ is a shift parameter, -and A is square and symmetric. +of size n using the SYMMLQ method, where λ is a shift parameter, +and A is Hermitian. SYMMLQ produces monotonic errors ‖x* - x‖₂. A preconditioner M may be provided in the form of a linear operator and is -assumed to be symmetric and positive definite. +assumed to be Hermitian and positive definite. SYMMLQ can be warm-started from an initial guess `x0` with diff --git a/src/tricg.jl b/src/tricg.jl index d2645a5ed..6788a0026 100644 --- a/src/tricg.jl +++ b/src/tricg.jl @@ -27,7 +27,7 @@ TriCG solves the symmetric linear system [ τE A ] [ x ] = [ b ] [ Aᴴ νF ] [ y ] [ c ], -where τ and ν are real numbers, E = M⁻¹ ≻ 0 and F = N⁻¹ ≻ 0. +of size (n+m) × (n+m) where τ and ν are real numbers, E = M⁻¹ ≻ 0 and F = N⁻¹ ≻ 0. `b` and `c` must both be nonzero. TriCG could breakdown if `τ = 0` or `ν = 0`. It's recommended to use TriMR in these cases. diff --git a/src/trilqr.jl b/src/trilqr.jl index f0ff3a1b7..bb279e947 100644 --- a/src/trilqr.jl +++ b/src/trilqr.jl @@ -26,8 +26,8 @@ Combine USYMLQ and USYMQR to solve adjoint systems. [0 A] [y] = [b] [Aᴴ 0] [x] [c] -USYMLQ is used for solving primal system `Ax = b`. -USYMQR is used for solving dual system `Aᴴy = c`. +USYMLQ is used for solving primal system `Ax = b` of size n. +USYMQR is used for solving dual system `Aᴴy = c` of size m. An option gives the possibility of transferring from the USYMLQ point to the USYMCG point, when it exists. The transfer is based on the residual norm. diff --git a/src/trimr.jl b/src/trimr.jl index 1c693639c..90ee54387 100644 --- a/src/trimr.jl +++ b/src/trimr.jl @@ -27,7 +27,7 @@ TriMR solves the symmetric linear system [ τE A ] [ x ] = [ b ] [ Aᴴ νF ] [ y ] [ c ], -where τ and ν are real numbers, E = M⁻¹ ≻ 0, F = N⁻¹ ≻ 0. +of size (n+m) × (n+m) where τ and ν are real numbers, E = M⁻¹ ≻ 0, F = N⁻¹ ≻ 0. `b` and `c` must both be nonzero. TriMR handles saddle-point systems (`τ = 0` or `ν = 0`) and adjoint systems (`τ = 0` and `ν = 0`) without any risk of breakdown. diff --git a/src/usymlq.jl b/src/usymlq.jl index 2d83aeb83..e89a400c2 100644 --- a/src/usymlq.jl +++ b/src/usymlq.jl @@ -28,7 +28,7 @@ export usymlq, usymlq! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -Solve the linear system Ax = b using the USYMLQ method. +Solve the linear system Ax = b of size n × m using the USYMLQ method. USYMLQ is based on the orthogonal tridiagonalization process and requires two initial nonzero vectors `b` and `c`. The vector `c` is only used to initialize the process and a default value can be `b` or `Aᴴb` depending on the shape of `A`. diff --git a/src/usymqr.jl b/src/usymqr.jl index f30aa3261..6dfef55fb 100644 --- a/src/usymqr.jl +++ b/src/usymqr.jl @@ -28,7 +28,7 @@ export usymqr, usymqr! `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`. `FC` is `T` or `Complex{T}`. -Solve the linear system Ax = b using USYMQR. +Solve the linear system Ax = b of size n × m using USYMQR. USYMQR is based on the orthogonal tridiagonalization process and requires two initial nonzero vectors `b` and `c`. The vector `c` is only used to initialize the process and a default value can be `b` or `Aᴴb` depending on the shape of `A`.