diff --git a/src/cg.jl b/src/cg.jl index 8197beaa8..e71b5ca5c 100644 --- a/src/cg.jl +++ b/src/cg.jl @@ -55,10 +55,10 @@ For an in-place variant that reuses memory across solves, see [`cg!`](@ref). * `M`: linear operator that models a Hermitian positive-definite matrix of size `n` used for centered preconditioning; * `ldiv`: define whether the preconditioner uses `ldiv!` or `mul!`; * `radius`: add the trust-region constraint ‖x‖ ≤ `radius` if `radius > 0`. Useful to compute a step in a trust-region method for optimization. - - If `radius > 0`, and nonpositive curvature is detected along the current search direction, we take the step to the trust-region boundary, the search direction is stored in `stats.npc_dir`, and `stats.npcCount` is set to 1. + - If `radius > 0`, and nonpositive curvature is detected along the current search direction, we take the step to the trust-region boundary, the search direction is stored in `workspace.npc_dir` and `stats.npcCount` is set to 1. * `linesearch`: when `true`, assume that CG is used within an inexact Newton method with line search. - If nonpositive curvature occurs at k = 0, the solver instead takes the right-hand side (i.e., the preconditioned negative gradient) as the current solution. The same search direction is returned in `workspace.npc_dir`, and `stats.npcCount` is set to 1.; - - If nonpositive curvature is detected at iteration k > 0, the method rolls back to the solution from iteration k – 1. The search direction computed at iteration k is stored in `stats.npc_dir`, and `stats.npcCount` is set to 1. + - If nonpositive curvature is detected at iteration k > 0, the method rolls back to the solution from iteration k - 1. The search direction computed at iteration k is stored in `workspace.npc_dir`, and `stats.npcCount` is set to 1. * `atol`: absolute stopping tolerance based on the residual norm; * `rtol`: relative stopping tolerance based on the residual norm; * `itmax`: the maximum number of iterations. If `itmax=0`, the default number of iterations is set to `2n`; @@ -73,6 +73,32 @@ For an in-place variant that reuses memory across solves, see [`cg!`](@ref). * `x`: a dense vector of length `n`; * `stats`: statistics collected on the run in a [`SimpleStats`](@ref) structure. + +### Stopping conditions + +* **convergence**: the (preconditioned) residual norm satisfies + ``` + ‖r_k‖ ≤ atol + rtol * ‖r_0‖ + ``` + or when further decrease is limited by machine precision. + The residual norm is measured in the norm induced by the preconditioner `M`. + +* **trust-region boundary**: if `radius > 0` and the computed step would leave the trust region, + the iterate is moved to the boundary `‖x‖ = radius` and the method terminates. + +* **nonpositive curvature**: if nonpositive or near-zero curvature is detected along the current search direction: + * with `linesearch = false`, the method stops and reports an indefinite or inconsistent system; + * with `linesearch = true`, the method returns a suitable descent direction and terminates. + In the in-place variant [`cg!`](@ref), the corresponding direction is stored in `workspace.npc_dir`. + +* **maximum iterations**: the iteration count reaches `itmax` (or the default value `2n` when `itmax = 0`). + +* **time limit**: the elapsed wall-clock time exceeds `timemax` seconds. + +* **user callback**: the user-provided `callback` returns `true`. + +A descriptive termination message is stored in `stats.status`, and additional flags in `stats` further characterize the outcome. + #### Reference * M. R. Hestenes and E. Stiefel, [*Methods of conjugate gradients for solving linear systems*](https://doi.org/10.6028/jres.049.044), Journal of Research of the National Bureau of Standards, 49(6), pp. 409--436, 1952.