Update the API for workspace accessors (#998)

Author: amontoison

docs/src/custom_workspaces.md

@@ -298,6 +298,7 @@ Note that `Krylov.kref!` is only required for the function `minres_qlp`.
 
 ```@example halo-regions
 using Krylov, OffsetArrays
+import Krylov: solution, statistics
 
 # Parameters
 L = 1.0            # Length of the square domain
@@ -437,14 +438,14 @@ We now solve the system $Ax = b$ using `minres` with our preconditioner:
 
 ```@example block-arrays
 using Krylov
+import Krylov: solution, niterations
 
 kc = KrylovConstructor(b)
 workspace = MinresWorkspace(kc)
 minres!(workspace, A, b; M=P)
 
 x = solution(workspace)
-stats = statistics(workspace)
-niter = stats.niter
+niter = niterations(workspace)
 ```
 
 This example demonstrates how `BlockArrays.jl` and `Krylov.jl` can be effectively combined to solve structured saddle point systems.

docs/src/generic_interface.md

@@ -10,18 +10,6 @@ krylov_solve!
 krylov_solve
 ```
 
-In-place solvers update the workspace, from which solutions and statistics can be retrieved.
-The following functions are available for post-solve analysis:
-
-```@docs
-Krylov.results
-Krylov.solution
-Krylov.statistics
-Krylov.nsolution
-Krylov.issolved
-krylov_elapsed_time
-```
-
 ## Examples
 
 ```julia
@@ -58,21 +46,21 @@ for method in (:bicgstab, :gmres)
     krylov_solve!(workspace, A, b)
 
     # Get the statistics
-    stats = statistics(workspace)
+    stats = Krylov.statistics(workspace)
 
     # Retrieve the solution
-    x = solution(workspace)
+    x = Krylov.solution(workspace)
 
     # Check if the solver converged
-    solved = issolved(workspace)
+    solved = Krylov.issolved(workspace)
     println("Convergence of $method: ", solved)
 
     # Display the number of iterations
-    niter = niterations(workspace)
+    niter = Krylov.niterations(workspace)
     println("Number of iterations for $method: ", niter)
 
     # Display the elapsed timer
-    timer = krylov_elapsed_time(workspace)
+    timer = Krylov.elapsed_time(workspace)
     println("Elapsed time for $method: ", timer, " seconds")
 
     println()

docs/src/inplace.md

@@ -1,7 +1,8 @@
 ## [In-place methods](@id in-place)
 
 All solvers in Krylov.jl have an in-place variant implemented in a method whose name ends with `!`.
-A workspace (`KrylovWorkspace`), which contains the storage needed by a Krylov method, can be used to solve multiple linear systems with the same dimensions and the same floating-point precision.
+A workspace (`KrylovWorkspace` or `BlockKrylovWorkspace`), which contains the storage needed by a Krylov method, can be used to solve multiple linear systems with the same dimensions and the same floating-point precision.
+It should also be the same number of right-hand sides in block Krylov methods.
 The section [storage requirements](@ref storage-requirements) specifies the memory needed for each Krylov method.
 
 Each `KrylovWorkspace` has three constructors with consistent argument patterns:
@@ -44,6 +45,26 @@ lsqr_workspace = LsqrWorkspace(m, n, CuVector{Float32})
 lsqr!(lsqr_workspace, A4, b4)
 ```
 
+## Workspace accessors
+
+In-place solvers update the workspace, from which solutions and statistics can be retrieved.
+The following functions are available for post-solve analysis.
+
+These functions are not exported and must be accessed using the prefix `Krylov.`, e.g. `Krylov.solution(workspace)`.
+
+```@docs
+Krylov.results
+Krylov.solution
+Krylov.nsolution
+Krylov.statistics
+Krylov.elapsed_time
+Krylov.niterations
+Krylov.issolved
+Krylov.Aprod
+Krylov.Atprod
+Krylov.Bprod
+```
+
 ## Examples
 
 We illustrate the use of in-place Krylov solvers with two well-known optimization methods.
@@ -53,6 +74,7 @@ The details of the optimization methods are described in the section about [Fact
 
 ```@newton
 using Krylov
+import Krylov: solution
 
 function newton(∇f, ∇²f, x₀; itmax = 200, tol = 1e-8)
 
@@ -63,7 +85,6 @@ function newton(∇f, ∇²f, x₀; itmax = 200, tol = 1e-8)
     iter = 0
     S = typeof(x)
     workspace = CgWorkspace(n, n, S)
-    Δx = workspace.x
 
     solved = false
     tired = false
@@ -72,6 +93,7 @@ function newton(∇f, ∇²f, x₀; itmax = 200, tol = 1e-8)
  
         Hx = ∇²f(x)              # Compute ∇²f(xₖ)
         cg!(workspace, Hx, -gx)  # Solve ∇²f(xₖ)Δx = -∇f(xₖ)
+        Δx = solution(workspace) # Recover Δx from the workspace
         x = x + Δx               # Update xₖ₊₁ = xₖ + Δx
         gx = ∇f(x)               # ∇f(xₖ₊₁)
         
@@ -87,6 +109,7 @@ end
 
 ```@gauss_newton
 using Krylov
+import Krylov: solution
 
 function gauss_newton(F, JF, x₀; itmax = 200, tol = 1e-8)
 
@@ -98,7 +121,6 @@ function gauss_newton(F, JF, x₀; itmax = 200, tol = 1e-8)
     iter = 0
     S = typeof(x)
     workspace = LsmrWorkspace(m, n, S)
-    Δx = workspace.x
 
     solved = false
     tired = false
@@ -107,6 +129,7 @@ function gauss_newton(F, JF, x₀; itmax = 200, tol = 1e-8)
  
         Jx = JF(x)                 # Compute J(xₖ)
         lsmr!(workspace, Jx, -Fx)  # Minimize ‖J(xₖ)Δx + F(xₖ)‖
+        Δx = solution(workspace)   # Recover Δx from the workspace
         x = x + Δx                 # Update xₖ₊₁ = xₖ + Δx
         Fx_old = Fx                # F(xₖ)
         Fx = F(x)                  # F(xₖ₊₁)

docs/src/reference.md

@@ -5,11 +5,11 @@
 ```@index
 ```
 
+## Internals
+
 ```@docs
 Krylov.FloatOrComplex
-Krylov.niterations
-Krylov.Aprod
-Krylov.Atprod
+Krylov.warm_start!
 Krylov.kstdout
 Krylov.extract_parameters
 Base.show

docs/src/warm-start.md

@@ -1,7 +1,6 @@
 # [Warm-start](@id warm-start)
 
-Most Krylov methods in this module accept a starting point as argument.
-The starting point is used as initial approximation to a solution.
+Most Krylov methods accept a user-provided initial guess instead of starting from zero.
 
 ```julia
 workspace = CgWorkspace(A, b)
@@ -18,14 +17,6 @@ If the user has an initial guess `x0`, it can be provided directly.
 cg(A, b, x0)
 ```
 
-It is also possible to use the function `warm_start!` to feed the starting point into the workspace.
-
-```julia
-warm_start!(workspace, x0)
-cg!(workspace, A, b)
-# the previous two lines are equivalent to cg!(workspace, A, b, x0)
-```
-
 If a Krylov method doesn't have the option to warm start, it can still be done explicitly.
 We provide an example with `cg_lanczos!`.
 

src/Krylov.jl

@@ -5,12 +5,14 @@ using LinearAlgebra, SparseArrays, Printf
 include("krylov_stats.jl")
 
 include("krylov_utils.jl")
-include("krylov_processes.jl")
-include("krylov_workspaces.jl")
-
 include("block_krylov_utils.jl")
+
+include("krylov_processes.jl")
 include("block_krylov_processes.jl")
+
+include("krylov_workspaces.jl")
 include("block_krylov_workspaces.jl")
+include("workspace_accessors.jl")
 
 include("krylov_show.jl")