Use the suffix Workspace instead of Solver (#990)

Author: amontoison

docs/src/api.md

@@ -15,51 +15,51 @@ Krylov.LsmrStats
 ## Workspace of Krylov methods
 
 ```@docs
-KrylovSolver
-MinresSolver
-MinaresSolver
-CgSolver
-CrSolver
-CarSolver
-SymmlqSolver
-CgLanczosSolver
-CgLanczosShiftSolver
-MinresQlpSolver
-DiomSolver
-FomSolver
-DqgmresSolver
-GmresSolver
-UsymlqSolver
-UsymqrSolver
-TricgSolver
-TrimrSolver
-TrilqrSolver
-CgsSolver
-BicgstabSolver
-BilqSolver
-QmrSolver
-BilqrSolver
-CglsSolver
-CglsLanczosShiftSolver
-CrlsSolver
-CgneSolver
-CrmrSolver
-LslqSolver
-LsqrSolver
-LsmrSolver
-LnlqSolver
-CraigSolver
-CraigmrSolver
-GpmrSolver
-FgmresSolver
+KrylovWorkspace
+MinresWorkspace
+MinaresWorkspace
+CgWorkspace
+CrWorkspace
+CarWorkspace
+SymmlqWorkspace
+CgLanczosWorkspace
+CgLanczosShiftWorkspace
+MinresQlpWorkspace
+DiomWorkspace
+FomWorkspace
+DqgmresWorkspace
+GmresWorkspace
+UsymlqWorkspace
+UsymqrWorkspace
+TricgWorkspace
+TrimrWorkspace
+TrilqrWorkspace
+CgsWorkspace
+BicgstabWorkspace
+BilqWorkspace
+QmrWorkspace
+BilqrWorkspace
+CglsWorkspace
+CglsLanczosShiftWorkspace
+CrlsWorkspace
+CgneWorkspace
+CrmrWorkspace
+LslqWorkspace
+LsqrWorkspace
+LsmrWorkspace
+LnlqWorkspace
+CraigWorkspace
+CraigmrWorkspace
+GpmrWorkspace
+FgmresWorkspace
 ```
 
 ## Workspace of block-Krylov methods
 
 ```@docs
-BlockKrylovSolver
-BlockMinresSolver
-BlockGmresSolver
+BlockKrylovWorkspace
+BlockMinresWorkspace
+BlockGmresWorkspace
 ```
 
 ## Utilities

docs/src/callbacks.md

@@ -1,25 +1,25 @@
 # [Callbacks](@id callbacks)
 
-Each Krylov method is able to call a callback function as `callback(solver)` at each iteration.
+Each Krylov method is able to call a callback function as `callback(workspace)` at each iteration.
 The callback should return `true` if the main loop should terminate, and `false` otherwise.
 If the method terminated because of the callback, the output status will be `"user-requested exit"`.
-For example, if the user defines `minres_callback(solver::MinresSolver)`, it can be passed to the solver using
+For example, if the user defines `minres_callback(workspace::MinresWorkspace)`, it can be passed to the solver using
 
 ```julia
 (x, stats) = minres(A, b, callback = minres_callback)
 ```
 
-If you need to write a callback that uses variables that are not in a `KrylovSolver`, use a closure:
+If you need to write a callback that uses variables that are not in a `KrylovWorkspace`, use a closure:
 
 ```julia
-function custom_stopping_condition(solver::KrylovSolver, A, b, r, tol)
-  mul!(r, A, solver.x)
+function custom_stopping_condition(workspace::KrylovWorkspace, A, b, r, tol)
+  mul!(r, A, workspace.x)
   r .-= b               # r := b - Ax
   bool = norm(r) ≤ tol  # tolerance based on the 2-norm of the residual
   return bool
 end
 
-cg_callback(solver) = custom_stopping_condition(solver, A, b, r, tol)
+cg_callback(workspace) = custom_stopping_condition(workspace, A, b, r, tol)
 (x, stats) = cg(A, b, callback = cg_callback)
 ```
 
@@ -33,10 +33,10 @@ mutable struct CallbackWorkspace{T}
   tol::T
 end
 
-function (workspace::CallbackWorkspace)(solver::KrylovSolver)
-  mul!(workspace.r, workspace.A, solver.x)
-  workspace.r .-= workspace.b
-  bool = norm(workspace.r) ≤ workspace.tol
+function (callback::CallbackWorkspace)(workspace::KrylovWorkspace)
+  mul!(callback.r, callback.A, workspace.x)
+  callback.r .-= callback.b
+  bool = norm(callback.r) ≤ callback.tol
   return bool
 end
 
@@ -51,12 +51,12 @@ We now illustrate how to store all iterates $x_k$ of the GMRES method.
 S = Krylov.ktypeof(b)
 global X = S[]  # Storage for GMRES iterates
 
-function gmres_callback(solver)
-  z = solver.z
-  k = solver.inner_iter
+function gmres_callback(workspace)
+  z = workspace.z
+  k = workspace.inner_iter
   nr = sum(1:k)
-  V = solver.V
-  R = solver.R
+  V = workspace.V
+  R = workspace.R
   y = copy(z)
 
   # Solve Rk * yk = zk

docs/src/custom_workspaces.md

@@ -326,12 +326,12 @@ b = HaloVector(data)
 
 # Allocate the workspace
 kc = KrylovConstructor(b)
-solver = CgSolver(kc)
+workspace = CgWorkspace(kc)
 
 # Solve the system with CG
-Krylov.cg!(solver, A, b, atol=1e-12, rtol=0.0, verbose=1)
-u_sol = solution(solver)
-stats = statistics(solver)
+Krylov.cg!(workspace, A, b, atol=1e-12, rtol=0.0, verbose=1)
+u_sol = solution(workspace)
+stats = statistics(workspace)
 ```
 
 ```@example halo-regions
@@ -439,11 +439,11 @@ We now solve the system $Ax = b$ using `minres` with our preconditioner:
 using Krylov
 
 kc = KrylovConstructor(b)
-solver = MinresSolver(kc)
-minres!(solver, A, b; M=P)
+workspace = MinresWorkspace(kc)
+minres!(workspace, A, b; M=P)
 
-x = solution(solver)
-stats = statistics(solver)
+x = solution(workspace)
+stats = statistics(workspace)
 niter = stats.niter
 ```
 

docs/src/generic_interface.md

@@ -34,7 +34,7 @@ b = randn(n)
 
 # Out-of-place interface
 for method in (:cg, :cr, :car)
-    x, stats = krylov_solve(Val{method}(), A, b)
+    x, stats = krylov_solve(Val(method), A, b)
     r = b - A * x
     println("Residual norm for $(method): ", norm(r))
 end
@@ -51,23 +51,23 @@ b = rand(n)
 # In-place interface
 for method in (:bicgstab, :gmres)
     # Create a workspace for the Krylov method
-    solver = krylov_workspace(Val(method), A, b)
+    workspace = krylov_workspace(Val(method), A, b)
 
     # Solve the system in-place
-    krylov_solve!(solver, A, b)
+    krylov_solve!(workspace, A, b)
 
     # Get the statistics
-    stats = statistics(solver)
+    stats = statistics(workspace)
 
     # Retrieve the solution
-    x = solution(solver)
+    x = solution(workspace)
 
     # Check if the solver converged
-    solved = issolved(solver)
+    solved = issolved(workspace)
     println("Converged $method: ", solved)
 
     # Display the number of iterations
-    niter = niterations(solver)
+    niter = niterations(workspace)
     println("Number of iterations for $method: ", niter)
 end
 ```

docs/src/inplace.md

@@ -1,23 +1,23 @@
 ## [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 (`KrylovSolver`), 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`), 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.
 The section [storage requirements](@ref storage-requirements) specifies the memory needed for each Krylov method.
 
-Each `KrylovSolver` has three constructors with consistent argument patterns:
+Each `KrylovWorkspace` has three constructors with consistent argument patterns:
 
 ```@constructors
-XyzSolver(A, b)
-XyzSolver(m, n, S)
-XyzSolver(kc::KrylovConstructor)
+XyzWorkspace(A, b)
+XyzWorkspace(m, n, S)
+XyzWorkspace(kc::KrylovConstructor)
 ```
-The only exceptions are `CgLanczosShiftSolver` and `CglsLanczosShiftSolver`, which require an additional argument `nshifts`.
+The only exceptions are `CgLanczosShiftWorkspace` and `CglsLanczosShiftWorkspace`, which require an additional argument `nshifts`.
 Additionally, some constructors accept keyword arguments.
 
 `Xyz` represents the name of the Krylov method, written in lowercase except for its first letter (such as `Cg`, `Minres`, `Lsmr` or `Bicgstab`).
-If the name of the Krylov method contains an underscore (e.g., `minres_qlp` or `cgls_lanczos_shift`), the workspace constructor transforms it by capitalizing each word and removing underscores, resulting in names like `MinresQlpSolver` or `CglsLanczosShiftSolver`.
+If the name of the Krylov method contains an underscore (e.g., `minres_qlp` or `cgls_lanczos_shift`), the workspace constructor transforms it by capitalizing each word and removing underscores, resulting in names like `MinresQlpWorkspace` or `CglsLanczosShiftWorkspace`.
 
-Given an operator `A` and a right-hand side `b`, you can create a `KrylovSolver` based on the size of `A` and the type of `b`, or explicitly provide the dimensions `(m, n)` and the storage type `S`.
+Given an operator `A` and a right-hand side `b`, you can create a `KrylovWorkspace` based on the size of `A` and the type of `b`, or explicitly provide the dimensions `(m, n)` and the storage type `S`.
 
 We assume that `S(undef, 0)`, `S(undef, n)`, and `S(undef, m)` are well-defined for the storage type `S`.
 For more advanced vector types, workspaces can also be created with the help of a `KrylovConstructor`.
@@ -31,17 +31,17 @@ For example, use `S = Vector{Float64}` if you want to solve linear systems in do
 The workspace is always the first argument of the in-place methods:
 
 ```@solvers
-minres_solver = MinresSolver(m, n, Vector{Float64})
-minres!(minres_solver, A1, b1)
+minres_workspace = MinresWorkspace(m, n, Vector{Float64})
+minres!(minres_workspace, A1, b1)
 
-bicgstab_solver = BicgstabSolver(m, n, Vector{ComplexF64})
-bicgstab!(bicgstab_solver, A2, b2)
+bicgstab_workspace = BicgstabWorkspace(m, n, Vector{ComplexF64})
+bicgstab!(bicgstab_workspace, A2, b2)
 
-gmres_solver = GmresSolver(m, n, Vector{BigFloat})
-gmres!(gmres_solver, A3, b3)
+gmres_workspace = GmresWorkspace(m, n, Vector{BigFloat})
+gmres!(gmres_workspace, A3, b3)
 
-lsqr_solver = LsqrSolver(m, n, CuVector{Float32})
-lsqr!(lsqr_solver, A4, b4)
+lsqr_workspace = LsqrWorkspace(m, n, CuVector{Float32})
+lsqr!(lsqr_workspace, A4, b4)
 ```
 
 ## Examples
@@ -62,18 +62,18 @@ function newton(∇f, ∇²f, x₀; itmax = 200, tol = 1e-8)
     
     iter = 0
     S = typeof(x)
-    solver = CgSolver(n, n, S)
-    Δx = solver.x
+    workspace = CgWorkspace(n, n, S)
+    Δx = workspace.x
 
     solved = false
     tired = false
 
     while !(solved || tired)
  
-        Hx = ∇²f(x)           # Compute ∇²f(xₖ)
-        cg!(solver, Hx, -gx)  # Solve ∇²f(xₖ)Δx = -∇f(xₖ)
-        x = x + Δx            # Update xₖ₊₁ = xₖ + Δx
-        gx = ∇f(x)            # ∇f(xₖ₊₁)
+        Hx = ∇²f(x)              # Compute ∇²f(xₖ)
+        cg!(workspace, Hx, -gx)  # Solve ∇²f(xₖ)Δx = -∇f(xₖ)
+        x = x + Δx               # Update xₖ₊₁ = xₖ + Δx
+        gx = ∇f(x)               # ∇f(xₖ₊₁)
         
         iter += 1
         solved = norm(gx) ≤ tol
@@ -97,19 +97,19 @@ function gauss_newton(F, JF, x₀; itmax = 200, tol = 1e-8)
     
     iter = 0
     S = typeof(x)
-    solver = LsmrSolver(m, n, S)
-    Δx = solver.x
+    workspace = LsmrWorkspace(m, n, S)
+    Δx = workspace.x
 
     solved = false
     tired = false
 
     while !(solved || tired)
  
-        Jx = JF(x)              # Compute J(xₖ)
-        lsmr!(solver, Jx, -Fx)  # Minimize ‖J(xₖ)Δx + F(xₖ)‖
-        x = x + Δx              # Update xₖ₊₁ = xₖ + Δx
-        Fx_old = Fx             # F(xₖ)
-        Fx = F(x)               # F(xₖ₊₁)
+        Jx = JF(x)                 # Compute J(xₖ)
+        lsmr!(workspace, Jx, -Fx)  # Minimize ‖J(xₖ)Δx + F(xₖ)‖
+        x = x + Δx                 # Update xₖ₊₁ = xₖ + Δx
+        Fx_old = Fx                # F(xₖ)
+        Fx = F(x)                  # F(xₖ₊₁)
         
         iter += 1
         solved = norm(Fx - Fx_old) / norm(Fx) ≤ tol

docs/src/storage.md

@@ -105,8 +105,8 @@ Each table summarizes the storage requirements of Krylov methods recommended to
 
 ## Practical storage requirements
 
-Each method has its own `KrylovSolver` that contains all the storage needed by the method.
-In the REPL, the size in bytes of each attribute and the total amount of memory allocated by the solver are displayed when we show a `KrylovSolver`.
+Each method has its own `KrylovWorkspace` that contains all the storage needed by the method.
+In the REPL, the size in bytes of each attribute and the total amount of memory allocated by the solver are displayed when we show a `KrylovWorkspace`.
 
 ```@example storage
 using Krylov
@@ -115,14 +115,14 @@ m = 5000
 n = 12000
 A = rand(Float64, m, n)
 b = rand(Float64, m)
-solver = LsmrSolver(A, b)
-show(stdout, solver, show_stats=false)
+workspace = LsmrWorkspace(A, b)
+show(stdout, workspace, show_stats=false)
 ```
 
-If we want the total number of bytes used by the solver, we can call `nbytes = sizeof(solver)`.
+If we want the total number of bytes used by the workspace, we can call `nbytes = sizeof(workspace)`.
 
 ```@example storage
-nbytes = sizeof(solver)
+nbytes = sizeof(workspace)
 ```
 
 Thereafter, we can use `Base.format_bytes(nbytes)` to recover what is displayed in the REPL.
@@ -140,7 +140,7 @@ ncoefs_lsmr = 5*n + 2*m                 # number of coefficients
 nbytes_lsmr = sizeof(FC) * ncoefs_lsmr  # number of bytes
 ```
 
-Therefore, you can check that you have enough memory in RAM to allocate a `KrylovSolver`.
+Therefore, you can check that you have enough memory in RAM to allocate a `KrylovWorkspace`.
 
 ```@example storage
 free_nbytes = Sys.free_memory()