Use verbosity system (#622)

* add SciMLLogging

* add verbosity types

* replace verbose::Bool with verbose::LinearVerbosity

* export symbols, include verbosity.jl

* add verbosity documentation

* add verbosity to IterativeSolversExt

* add verbosity to KrylovKitExt

* add verbose to PardisoExt

* add verbose to HYPREExt

* add verbose for iterative solvers

* bring in LinearVerbosity

* imports

* fix default

* add tests

* make verbose = Bool also valid for backwards compat

* allow bool verbose

* fix _init_cacheval

* fix verbose for HYPRE

* add compat for SciMLLogging

* get rid of stale import

* Update runtests.jl

* change bool to LinearVerbosity

* add messages for fallbacks

---------

Co-authored-by: Christopher Rackauckas <[email protected]>

Author: jClugstor

Project.toml

@@ -22,6 +22,7 @@ Preferences = "21216c6a-2e73-6563-6e65-726566657250"
 RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
+SciMLLogging = "a6db7da4-7206-11f0-1eab-35f2a5dbe1d1"
 SciMLOperators = "c0aeaf25-5076-4817-a8d5-81caf7dfa961"
 Setfield = "efcf1570-3423-57d1-acb7-fd33fddbac46"
 StaticArraysCore = "1e83bf80-4336-4d27-bf5d-d5a4f845583c"
@@ -122,6 +123,7 @@ Reexport = "1.2.2"
 SafeTestsets = "0.1"
 SciMLBase = "2.70"
 SciMLOperators = "1"
+SciMLLogging = "1"
 Setfield = "1.1.1"
 SparseArrays = "1.10"
 Sparspak = "0.3.9"

docs/src/advanced/developing.md

@@ -19,7 +19,7 @@ struct MyLUFactorization{P} <: LinearSolve.SciMLLinearSolveAlgorithm end
 
 function LinearSolve.init_cacheval(
         alg::MyLUFactorization, A, b, u, Pl, Pr, maxiters::Int, abstol, reltol,
-        verbose::Bool, assump::LinearSolve.OperatorAssumptions)
+        verbose::LinearVerbosity, assump::LinearSolve.OperatorAssumptions)
     lu!(convert(AbstractMatrix, A))
 end
 

docs/src/basics/common_solver_opts.md

@@ -26,3 +26,92 @@ solve completely. Error controls only apply to iterative solvers.
   - `maxiters`: The number of iterations allowed. Defaults to `length(prob.b)`
   - `Pl,Pr`: The left and right preconditioners, respectively. For more information,
     see [the Preconditioners page](@ref prec).
+
+## Verbosity Controls
+
+The verbosity system in LinearSolve.jl provides fine-grained control over the diagnostic messages, warnings, and errors that are displayed during the solution of linear systems.
+
+The verbosity system is organized hierarchically into three main categories:
+
+1. Error Control - Messages related to fallbacks and error handling
+2. Performance - Messages related to performance considerations
+3. Numerical - Messages related to numerical solvers and iterations
+
+Each category can be configured independently, and individual settings can be adjusted to suit your needs.
+
+### Verbosity Levels
+The following verbosity levels are available:
+
+#### Individual Settings
+These settings are meant for individual settings within a category. These can also be used to set all of the individual settings in a group to the same value.
+- Verbosity.None() - Suppress all messages
+- Verbosity.Info() - Show message as log message at info level
+- Verbosity.Warn() - Show warnings (default for most settings)
+- Verbosity.Error() - Throw errors instead of warnings
+- Verbosity.Level(n) - Show messages with a log level setting of n
+
+#### Group Settings
+These settings are meant for controlling a group of settings. 
+- Verbosity.Default() - Use the default settings
+- Verbosity.All() - Show all possible messages
+
+### Basic Usage 
+
+#### Global Verbosity Control
+
+```julia 
+using LinearSolve
+
+# Suppress all messages
+verbose = LinearVerbosity(Verbosity.None())
+prob = LinearProblem(A, b)
+sol = solve(prob; verbose=verbose)
+
+# Show all messages
+verbose = LinearVerbosity(Verbosity.All())
+sol = solve(prob; verbose=verbose)
+
+# Use default settings
+verbose = LinearVerbosity(Verbosity.Default())
+sol = solve(prob; verbose=verbose)
+```
+
+#### Group Level Control 
+
+```julia 
+# Customize by category
+verbose = LinearVerbosity(
+    error_control = Verbosity.Warn(),   # Show warnings for error control related issues
+    performance = Verbosity.None(),     # Suppress performance messages
+    numerical = Verbosity.Info()        # Show all numerical related log messages at info level
+)
+
+sol = solve(prob; verbose=verbose)
+```
+
+#### Fine-grained Control
+The constructor for `LinearVerbosity` allows you to set verbosity for each specific message toggle, giving you fine-grained control. 
+The verbosity settings for the toggles are automatically passed to the group objects. 
+```julia
+# Set specific message types
+verbose = LinearVerbosity(
+    default_lu_fallback = Verbosity.Info(),                     # Show info when LU fallback is used
+    KrylovJL_verbosity = Verbosity.Warn(),                      # Show warnings from KrylovJL
+    no_right_preconditioning = Verbosity.None(),                # Suppress right preconditioning messages
+    KrylovKit_verbosity = Verbosity.Level(KrylovKit.WARN_LEVEL) # Set KrylovKit verbosity level using KrylovKit's own verbosity levels
+)
+
+sol = solve(prob; verbose=verbose)
+
+```
+
+#### Verbosity Levels
+##### Error Control Settings
+- default_lu_fallback: Controls messages when falling back to LU factorization (default: Warn)
+##### Performance Settings
+- no_right_preconditioning: Controls messages when right preconditioning is not used (default: Warn)
+##### Numerical Settings
+- using_IterativeSolvers: Controls messages when using the IterativeSolvers.jl package (default: Warn)
+- IterativeSolvers_iterations: Controls messages about iteration counts from IterativeSolvers.jl (default: Warn)
+- KrylovKit_verbosity: Controls messages from the KrylovKit.jl package (default: Warn)
+- KrylovJL_verbosity: Controls verbosity of the KrylovJL.jl package (default: None)

ext/LinearSolveAMDGPUExt.jl

@@ -25,7 +25,7 @@ function SciMLBase.solve!(cache::LinearSolve.LinearCache, alg::AMDGPUOffloadLUFa
 end
 
 function LinearSolve.init_cacheval(alg::AMDGPUOffloadLUFactorization, A, b, u, Pl, Pr,
-        maxiters::Int, abstol, reltol, verbose::Bool,
+        maxiters::Int, abstol, reltol, verbose::LinearVerbosity,
         assumptions::OperatorAssumptions)
     AMDGPU.rocSOLVER.getrf!(AMDGPU.ROCArray(A))
 end
@@ -57,7 +57,7 @@ function SciMLBase.solve!(cache::LinearSolve.LinearCache, alg::AMDGPUOffloadQRFa
 end
 
 function LinearSolve.init_cacheval(alg::AMDGPUOffloadQRFactorization, A, b, u, Pl, Pr,
-        maxiters::Int, abstol, reltol, verbose::Bool,
+        maxiters::Int, abstol, reltol, verbose::LinearVerbosity,
         assumptions::OperatorAssumptions)
     A_gpu = AMDGPU.ROCArray(A)
     tau = AMDGPU.ROCVector{eltype(A_gpu)}(undef, min(size(A_gpu)...))

ext/LinearSolveBLISExt.jl

@@ -204,13 +204,13 @@ const PREALLOCATED_BLIS_LU = begin
 end
 
 function LinearSolve.init_cacheval(alg::BLISLUFactorization, A, b, u, Pl, Pr,
-    maxiters::Int, abstol, reltol, verbose::Bool,
+    maxiters::Int, abstol, reltol, verbose::LinearVerbosity,
     assumptions::OperatorAssumptions)
     PREALLOCATED_BLIS_LU
 end
 
 function LinearSolve.init_cacheval(alg::BLISLUFactorization, A::AbstractMatrix{<:Union{Float32,ComplexF32,ComplexF64}}, b, u, Pl, Pr,
-    maxiters::Int, abstol, reltol, verbose::Bool,
+    maxiters::Int, abstol, reltol, verbose::LinearVerbosity,
     assumptions::OperatorAssumptions)
     A = rand(eltype(A), 0, 0)
     ArrayInterface.lu_instance(A), Ref{BlasInt}()

ext/LinearSolveBandedMatricesExt.jl

@@ -41,14 +41,14 @@ for alg in (:SVDFactorization, :MKLLUFactorization, :DiagonalFactorization,
     :AppleAccelerateLUFactorization, :CholeskyFactorization)
     @eval begin
         function init_cacheval(::$(alg), ::BandedMatrix, b, u, Pl, Pr, maxiters::Int,
-                abstol, reltol, verbose::Bool, assumptions::OperatorAssumptions)
+                abstol, reltol, verbose::LinearVerbosity, assumptions::OperatorAssumptions)
             return nothing
         end
     end
 end
 
 function init_cacheval(::LUFactorization, A::BandedMatrix{T}, b, u, Pl, Pr, maxiters::Int,
-        abstol, reltol, verbose::Bool, assumptions::OperatorAssumptions) where {T}
+        abstol, reltol, verbose::LinearVerbosity, assumptions::OperatorAssumptions) where {T}
     (T <: BigFloat) && return qr(similar(A, 0, 0))
     return lu(similar(A, 0, 0))
 end
@@ -61,7 +61,7 @@ for alg in (:SVDFactorization, :MKLLUFactorization, :DiagonalFactorization,
     :AppleAccelerateLUFactorization, :QRFactorization, :LUFactorization)
     @eval begin
         function init_cacheval(::$(alg), ::Symmetric{<:Number, <:BandedMatrix}, b, u, Pl,
-                Pr, maxiters::Int, abstol, reltol, verbose::Bool,
+                Pr, maxiters::Int, abstol, reltol, verbose::LinearVerbosity,
                 assumptions::OperatorAssumptions)
             return nothing
         end

ext/LinearSolveCUDAExt.jl

@@ -50,7 +50,7 @@ function SciMLBase.solve!(cache::LinearSolve.LinearCache, alg::CudaOffloadLUFact
 end
 
 function LinearSolve.init_cacheval(alg::CudaOffloadLUFactorization, A, b, u, Pl, Pr,
-        maxiters::Int, abstol, reltol, verbose::Bool,
+        maxiters::Int, abstol, reltol, verbose::LinearVerbosity,
         assumptions::OperatorAssumptions)
     T = eltype(A)
     noUnitT = typeof(zero(T))
@@ -73,7 +73,7 @@ function SciMLBase.solve!(cache::LinearSolve.LinearCache, alg::CudaOffloadQRFact
 end
 
 function LinearSolve.init_cacheval(alg::CudaOffloadQRFactorization, A, b, u, Pl, Pr,
-        maxiters::Int, abstol, reltol, verbose::Bool,
+        maxiters::Int, abstol, reltol, verbose::LinearVerbosity,
         assumptions::OperatorAssumptions)
     qr(CUDA.CuArray(A))
 end
@@ -92,26 +92,26 @@ function SciMLBase.solve!(cache::LinearSolve.LinearCache, alg::CudaOffloadFactor
 end
 
 function LinearSolve.init_cacheval(alg::CudaOffloadFactorization, A, b, u, Pl, Pr,
-        maxiters::Int, abstol, reltol, verbose::Bool,
+        maxiters::Int, abstol, reltol, verbose::LinearVerbosity,
         assumptions::OperatorAssumptions)
     qr(CUDA.CuArray(A))
 end
 
 function LinearSolve.init_cacheval(
         ::SparspakFactorization, A::CUDA.CUSPARSE.CuSparseMatrixCSR, b, u,
-        Pl, Pr, maxiters::Int, abstol, reltol, verbose::Bool, assumptions::OperatorAssumptions)
+        Pl, Pr, maxiters::Int, abstol, reltol, verbose::LinearVerbosity, assumptions::OperatorAssumptions)
     nothing
 end
 
 function LinearSolve.init_cacheval(
         ::KLUFactorization, A::CUDA.CUSPARSE.CuSparseMatrixCSR, b, u,
-        Pl, Pr, maxiters::Int, abstol, reltol, verbose::Bool, assumptions::OperatorAssumptions)
+        Pl, Pr, maxiters::Int, abstol, reltol, verbose::LinearVerbosity, assumptions::OperatorAssumptions)
     nothing
 end
 
 function LinearSolve.init_cacheval(
         ::UMFPACKFactorization, A::CUDA.CUSPARSE.CuSparseMatrixCSR, b, u,
-        Pl, Pr, maxiters::Int, abstol, reltol, verbose::Bool, assumptions::OperatorAssumptions)
+        Pl, Pr, maxiters::Int, abstol, reltol, verbose::LinearVerbosity, assumptions::OperatorAssumptions)
     nothing
 end
 

ext/LinearSolveCUSOLVERRFExt.jl

@@ -10,15 +10,15 @@ using SciMLBase: SciMLBase, LinearProblem, ReturnCode
 function LinearSolve.init_cacheval(alg::LinearSolve.CUSOLVERRFFactorization,
         A, b, u, Pl, Pr,
         maxiters::Int, abstol, reltol,
-        verbose::Bool, assumptions::OperatorAssumptions)
+        verbose::LinearVerbosity, assumptions::OperatorAssumptions)
     nothing
 end
 
 function LinearSolve.init_cacheval(alg::LinearSolve.CUSOLVERRFFactorization,
         A::Union{CuSparseMatrixCSR{Float64, Int32}, SparseMatrixCSC{Float64, <:Integer}}, 
         b, u, Pl, Pr,
         maxiters::Int, abstol, reltol,
-        verbose::Bool, assumptions::OperatorAssumptions)
+        verbose::LinearVerbosity, assumptions::OperatorAssumptions)
     # Create initial factorization with appropriate options
     nrhs = b isa AbstractMatrix ? size(b, 2) : 1
     symbolic = alg.symbolic

ext/LinearSolveCliqueTreesExt.jl

@@ -22,7 +22,7 @@ end
 
 function LinearSolve.init_cacheval(
     alg::CliqueTreesFactorization, A::AbstractMatrix, b, u, Pl, Pr, maxiters::Int, abstol,
-    reltol, verbose::Bool, assumptions::OperatorAssumptions)
+    reltol, verbose::LinearVerbosity, assumptions::OperatorAssumptions)
     symbfact = _symbolic(A, alg)
     cholfact, cholwork = cholinit(A, symbfact)
     linwork = lininit(1, cholfact)

ext/LinearSolveFastAlmostBandedMatricesExt.jl

@@ -21,7 +21,7 @@ for alg in (:SVDFactorization, :MKLLUFactorization, :DiagonalFactorization,
     :AppleAccelerateLUFactorization, :CholeskyFactorization, :LUFactorization)
     @eval begin
         function init_cacheval(::$(alg), ::AlmostBandedMatrix, b, u, Pl, Pr, maxiters::Int,
-                abstol, reltol, verbose::Bool, assumptions::OperatorAssumptions)
+                abstol, reltol, verbose::LinearVerbosity, assumptions::OperatorAssumptions)
             return nothing
         end
     end