add BLAS verbosity

jClugstor · jClugstor · commit ca0e50c5fa08 · 2025-09-23T13:49:37.000-04:00
diff --git a/docs/src/basics/common_solver_opts.md b/docs/src/basics/common_solver_opts.md
@@ -44,16 +44,16 @@ 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
+- SciMLLogging.None() - Suppress all messages
+- SciMLLogging.Info() - Show message as log message at info level
+- SciMLLogging.Warn() - Show warnings (default for most settings)
+- SciMLLogging.Error() - Throw errors instead of warnings
+- SciMLLogging.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
+- SciMLLogging.Default() - Use the default settings
+- SciMLLogging.All() - Show all possible messages
 
 ### Basic Usage 
 
@@ -63,16 +63,16 @@ These settings are meant for controlling a group of settings.
 using LinearSolve
 
 # Suppress all messages
-verbose = LinearVerbosity(Verbosity.None())
+verbose = LinearVerbosity(SciMLLogging.None())
 prob = LinearProblem(A, b)
 sol = solve(prob; verbose=verbose)
 
 # Show all messages
-verbose = LinearVerbosity(Verbosity.All())
+verbose = LinearVerbosity(SciMLLogging.All())
 sol = solve(prob; verbose=verbose)
 
 # Use default settings
-verbose = LinearVerbosity(Verbosity.Default())
+verbose = LinearVerbosity(SciMLLogging.Default())
 sol = solve(prob; verbose=verbose)
 ```
 
@@ -81,9 +81,9 @@ sol = solve(prob; verbose=verbose)
 ```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
+    error_control = SciMLLogging.Warn(),   # Show warnings for error control related issues
+    performance = SciMLLogging.None(),     # Suppress performance messages
+    numerical = SciMLLogging.Info()        # Show all numerical related log messages at info level
 )
 
 sol = solve(prob; verbose=verbose)
@@ -95,10 +95,10 @@ The verbosity settings for the toggles are automatically passed to the group obj
 ```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
+    default_lu_fallback = SciMLLogging.Info(),                     # Show info when LU fallback is used
+    KrylovJL_verbosity = SciMLLogging.Warn(),                      # Show warnings from KrylovJL
+    no_right_preconditioning = SciMLLogging.None(),                # Suppress right preconditioning messages
+    KrylovKit_verbosity = SciMLLogging.Level(KrylovKit.WARN_LEVEL) # Set KrylovKit verbosity level using KrylovKit's own verbosity levels
 )
 
 sol = solve(prob; verbose=verbose)
diff --git a/ext/LinearSolveBLISExt.jl b/ext/LinearSolveBLISExt.jl
@@ -9,7 +9,8 @@ using LinearSolve
 using LinearAlgebra: BlasInt, LU
 using LinearAlgebra.LAPACK: require_one_based_indexing, chkfinite, chkstride1, 
                             @blasfunc, chkargsok
-using LinearSolve: ArrayInterface, BLISLUFactorization, @get_cacheval, LinearCache, SciMLBase, LinearVerbosity
+using LinearSolve: ArrayInterface, BLISLUFactorization, @get_cacheval, LinearCache, SciMLBase, LinearVerbosity, get_blas_operation_info, blas_info_msg
+using SciMLLogging: SciMLLogging, @SciMLMessage
 using SciMLBase: ReturnCode
 
 const global libblis = blis_jll.blis
@@ -220,12 +221,45 @@ function SciMLBase.solve!(cache::LinearCache, alg::BLISLUFactorization;
     kwargs...)
     A = cache.A
     A = convert(AbstractMatrix, A)
+    verbose = cache.verbose
     if cache.isfresh
         cacheval = @get_cacheval(cache, :BLISLUFactorization)
         res = getrf!(A; ipiv = cacheval[1].ipiv, info = cacheval[2])
         fact = LU(res[1:3]...), res[4]
         cache.cacheval = fact
 
+        info_value = res[3]
+
+        if info_value != 0
+            if !isa(verbose.blas_info, SciMLLogging.Silent) || !isa(verbose.blas_errors, SciMLLogging.Silent) ||
+                !isa(verbose.blas_invalid_args, SciMLLogging.Silent) 
+                op_info = get_blas_operation_info(:dgetrf, A, cache.b, condition = !isa(verbose.condition_number, SciMLLogging.Silent))
+                @SciMLMessage(cache.verbose, :condition_number) do 
+                    if op_info[:condition_number] === nothing
+                        return "Matrix condition number calculation failed."
+                    else 
+                        return "Matrix condition number: $(round(op_info[:condition_number], sigdigits=4)) for $(size(A, 1))×$(size(A, 2)) matrix in dgetrf"
+                    end
+                end
+                verb_option, message = blas_info_msg(
+                    :dgetrf, info_value; extra_context = op_info)
+                @SciMLMessage(message, verbose, verb_option)
+            end
+        else
+            @SciMLMessage(cache.verbose, :blas_success) do 
+                op_info = get_blas_operation_info(:dgetrf, A, cache.b,
+                    condition = !isa(verbose.condition_number, SciMLLogging.Silent))
+                @SciMLMessage(cache.verbose, :condition_number) do
+                    if op_info[:condition_number] === nothing
+                        return "Matrix condition number calculation failed."
+                    else
+                        return "Matrix condition number: $(round(op_info[:condition_number], sigdigits=4)) for $(size(A, 1))×$(size(A, 2)) matrix in dgetrf"
+                    end
+                end
+                return "BLAS LU factorization (dgetrf) completed successfully for $(op_info[:matrix_size]) matrix"
+            end 
+        end
+
         if !LinearAlgebra.issuccess(fact[1])
             return SciMLBase.build_linear_solution(
                 alg, cache.u, nothing, cache; retcode = ReturnCode.Failure)
diff --git a/ext/LinearSolveForwardDiffExt.jl b/ext/LinearSolveForwardDiffExt.jl
@@ -137,7 +137,7 @@ function __dual_init(
         abstol = LinearSolve.default_tol(real(eltype(prob.b))),
         reltol = LinearSolve.default_tol(real(eltype(prob.b))),
         maxiters::Int = length(prob.b),
-        verbose = LinearVerbosity(Verbosity.None()),
+        verbose = LinearVerbosity(SciMLLogging.None()),
         Pl = nothing,
         Pr = nothing,
         assumptions = OperatorAssumptions(issquare(prob.A)),
diff --git a/ext/LinearSolveHYPREExt.jl b/ext/LinearSolveHYPREExt.jl
@@ -65,7 +65,7 @@ function SciMLBase.init(prob::LinearProblem, alg::HYPREAlgorithm,
                              eltype(prob.A)),
         # TODO: Implement length() for HYPREVector in HYPRE.jl?
         maxiters::Int = prob.b isa HYPREVector ? 1000 : length(prob.b),
-        verbose = LinearVerbosity(Verbosity.None()),
+        verbose = LinearVerbosity(SciMLLogging.None()),
         Pl = LinearAlgebra.I,
         Pr = LinearAlgebra.I,
         assumptions = OperatorAssumptions(),
@@ -118,9 +118,9 @@ function SciMLBase.init(prob::LinearProblem, alg::HYPREAlgorithm,
         if verbose
             verbose = LinearVerbosity()
         else
-            verbose = LinearVerbosity(Verbosity.None())
+            verbose = LinearVerbosity(SciMLLogging.None())
         end
-    elseif verbose isa Verbosity.Type
+    elseif verbose isa SciMLLogging.Type
         verbose = LinearVerbosity(verbose)
     end
 
diff --git a/src/LinearSolve.jl b/src/LinearSolve.jl
@@ -21,7 +21,7 @@ using SciMLBase: SciMLBase, LinearAliasSpecifier, AbstractSciMLOperator,
 using SciMLOperators: SciMLOperators, AbstractSciMLOperator, IdentityOperator,
                       MatrixOperator,
                       has_ldiv!, issquare
-using SciMLLogging: Verbosity, @SciMLMessage, verbosity_to_int, AbstractVerbositySpecifier
+using SciMLLogging: SciMLLogging, @SciMLMessage, verbosity_to_int, AbstractVerbositySpecifier, LogLevel, VerbosityPreset
 using Setfield: @set, @set!
 using UnPack: @unpack
 using DocStringExtensions: DocStringExtensions
@@ -363,6 +363,7 @@ const BLASELTYPES = Union{Float32, Float64, ComplexF32, ComplexF64}
 function defaultalg_symbol end
 
 include("verbosity.jl")
+include("blas_logging.jl")
 include("generic_lufact.jl")
 include("common.jl")
 include("extension_algs.jl")
diff --git a/src/blas_logging.jl b/src/blas_logging.jl
@@ -0,0 +1,173 @@
+
+"""
+    interpret_blas_code(func::Symbol, info::Integer)
+
+Interpret BLAS/LAPACK return codes (info parameter) to provide human-readable error messages.
+Returns a tuple of (category::Symbol, message::String, details::String)
+"""
+function interpret_blas_code(func::Symbol, info::Integer)
+    if info == 0
+        return (:success, "Operation completed successfully", "")
+    elseif info < 0
+        return (:invalid_argument,
+            "Invalid argument error",
+            "Argument $(-info) had an illegal value")
+    else
+        # info > 0 means different things for different functions
+        return interpret_positive_info(func, info)
+    end
+end
+
+function interpret_positive_info(func::Symbol, info::Integer)
+    func_str = string(func)
+
+    # LU factorization routines
+    if occursin("getrf", func_str)
+        return (:singular_matrix,
+            "Matrix is singular",
+            "U($info,$info) is exactly zero. The factorization has been completed, but U is singular and division by U will produce infinity.")
+
+        # Cholesky factorization routines
+    elseif occursin("potrf", func_str)
+        return (:not_positive_definite,
+            "Matrix is not positive definite",
+            "The leading minor of order $info is not positive definite, and the factorization could not be completed.")
+
+        # QR factorization routines
+    elseif occursin("geqrf", func_str) || occursin("geqrt", func_str)
+        return (:numerical_issue,
+            "Numerical issue in QR factorization",
+            "Householder reflector $info could not be formed properly.")
+
+        # SVD routines
+    elseif occursin("gesdd", func_str) || occursin("gesvd", func_str)
+        return (:convergence_failure,
+            "SVD did not converge",
+            "The algorithm failed to compute singular values. $info off-diagonal elements of an intermediate bidiagonal form did not converge to zero.")
+
+        # Symmetric/Hermitian eigenvalue routines
+    elseif occursin("syev", func_str) || occursin("heev", func_str)
+        return (:convergence_failure,
+            "Eigenvalue computation did not converge",
+            "$info off-diagonal elements of an intermediate tridiagonal form did not converge to zero.")
+
+        # Bunch-Kaufman factorization
+    elseif occursin("sytrf", func_str) || occursin("hetrf", func_str)
+        return (:singular_matrix,
+            "Matrix is singular",
+            "D($info,$info) is exactly zero. The factorization has been completed, but the block diagonal matrix D is singular.")
+
+        # Solve routines (should not have positive info)
+    elseif occursin("getrs", func_str) || occursin("potrs", func_str) ||
+           occursin("sytrs", func_str) || occursin("hetrs", func_str)
+        return (:unexpected_error,
+            "Unexpected positive return code from solve routine",
+            "Solve routine $func returned info=$info which should not happen.")
+
+        # General eigenvalue problem
+    elseif occursin("ggev", func_str) || occursin("gges", func_str)
+        if info <= size
+            return (:convergence_failure,
+                "QZ iteration failed",
+                "The QZ iteration failed to compute all eigenvalues. Elements 1:$(info-1) converged.")
+        else
+            return (:unexpected_error,
+                "Unexpected error in generalized eigenvalue problem",
+                "Info value $info is unexpected for $func.")
+        end
+
+        # LDLT factorization
+    elseif occursin("ldlt", func_str)
+        return (:singular_matrix,
+            "Matrix is singular",
+            "The $(info)-th pivot is zero. The factorization has been completed but division will produce infinity.")
+
+        # Default case
+    else
+        return (:unknown_error,
+            "Unknown positive return code",
+            "Function $func returned info=$info. Consult LAPACK documentation for details.")
+    end
+end
+
+
+
+"""
+    blas_info_msg(func::Symbol, info::Integer, verbose::LinearVerbosity;
+                  extra_context::Dict{Symbol,Any} = Dict())
+
+Log BLAS/LAPACK return code information with appropriate verbosity level.
+"""
+function blas_info_msg(func::Symbol, info::Integer;
+        extra_context::Dict{Symbol, Any} = Dict())
+    category, message, details = interpret_blas_code(func, info)
+
+    verbosity_field = if category in [:singular_matrix, :not_positive_definite, :convergence_failure]
+        :blas_errors
+    elseif category == :invalid_argument
+        :blas_invalid_args
+    else
+        :blas_info
+    end
+
+    # Build structured message components
+    msg_main = "BLAS/LAPACK $func: $message"
+    msg_details = !isempty(details) ? details : nothing
+    msg_info = info
+
+    # Build complete message with all details
+    full_msg = if !isempty(extra_context) || msg_details !== nothing
+        parts = String[msg_main]
+        if msg_details !== nothing
+            push!(parts, "Details: $msg_details")
+        end
+        push!(parts, "Return code (info): $msg_info")
+        if !isempty(extra_context)
+            for (key, value) in extra_context
+                push!(parts, "$key: $value")
+            end
+        end
+        join(parts, "\n  ")
+    else
+        "$msg_main (info=$msg_info)"
+    end
+
+    verbosity_field, full_msg
+end
+
+
+function get_blas_operation_info(func::Symbol, A, b; condition = false)
+    info = Dict{Symbol, Any}()
+
+    # Matrix properties
+    info[:matrix_size] = size(A)
+    info[:matrix_type] = typeof(A)
+    info[:element_type] = eltype(A)
+
+    # Condition number (based on verbosity setting)
+    if condition && size(A, 1) == size(A, 2)
+        try
+            cond_num = cond(A)
+            info[:condition_number] = cond_num
+
+            # Log the condition number if enabled  
+            cond_msg = "Matrix condition number: $(round(cond_num, sigdigits=4)) for $(size(A, 1))×$(size(A, 2)) matrix in $func"
+
+        catch
+            # Skip if condition number computation fails
+            info[:condition_number] = nothing
+        end
+    end
+
+    # RHS properties if provided
+    if b !== nothing
+        info[:rhs_size] = size(b)
+        info[:rhs_type] = typeof(b)
+    end
+
+    # Memory usage estimate
+    mem_bytes = prod(size(A)) * sizeof(eltype(A))
+    info[:memory_usage_MB] = round(mem_bytes / 1024^2, digits = 2)
+
+    return info
+end
diff --git a/src/common.jl b/src/common.jl
@@ -332,7 +332,7 @@ function __init(prob::LinearProblem, alg::SciMLLinearSolveAlgorithm,
         else
             verbose_spec = LinearVerbosity{false}()
         end
-    elseif verbose isa Verbosity.VerbosityPreset
+    elseif verbose isa SciMLLogging.VerbosityPreset
         verbose_spec = LinearVerbosity(verbose)
     else
         verbose_spec = verbose
diff --git a/src/verbosity.jl b/src/verbosity.jl
diff --git a/test/verbosity.jl b/test/verbosity.jl
