Add stopping conditions for CG

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.