Add enhanced BLAS/LAPACK return code interpretation and logging

This commit builds upon PR #622's verbosity system by adding:

1. Detailed BLAS/LAPACK return code interpretation
   - Human-readable explanations for all BLAS/LAPACK info codes
   - Categorized errors (singular_matrix, not_positive_definite, etc.)
   - Operation-specific interpretations for getrf, potrf, geqrf, etc.

2. Extended logging information for BLAS operations
   - Matrix properties (size, type, condition number)
   - Memory usage estimates
   - Performance timing metrics
   - Contextual information for debugging

3. New verbosity controls
   - blas_errors: Controls BLAS/LAPACK error messages (default: Warn)
   - blas_info: Controls informational messages (default: None)
   - blas_success: Controls success messages (default: None)
   - blas_invalid_args: Controls invalid argument errors (default: Error)
   - blas_timing: Controls performance timing (default: None)

4. Integration with BLISLUFactorization
   - Added detailed logging to the BLIS extension
   - Includes timing and error interpretation

5. Comprehensive documentation
   - Updated verbosity documentation with new BLAS options
   - Added section on BLAS/LAPACK return codes
   - Examples demonstrating enhanced logging capabilities

6. Tests
   - Added test suite for BLAS return code interpretation
   - Tests for different error categories
   - Verbosity integration tests

This enhancement makes debugging numerical issues much easier by providing
clear, actionable information when BLAS/LAPACK operations encounter problems.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: claude

docs/src/basics/common_solver_opts.md

@@ -108,10 +108,62 @@ sol = solve(prob; verbose=verbose)
 #### Verbosity Levels
 ##### Error Control Settings
 - default_lu_fallback: Controls messages when falling back to LU factorization (default: Warn)
+- blas_invalid_args: Controls messages when BLAS/LAPACK receives invalid arguments (default: Error)
 ##### Performance Settings
 - no_right_preconditioning: Controls messages when right preconditioning is not used (default: Warn)
+- blas_timing: Controls performance timing messages for BLAS/LAPACK operations (default: None)
 ##### 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)
+- KrylovJL_verbosity: Controls verbosity of the KrylovJL.jl package (default: None)
+- blas_errors: Controls messages for BLAS/LAPACK errors like singular matrices (default: Warn)
+- blas_info: Controls informational messages from BLAS/LAPACK operations (default: None)
+- blas_success: Controls success messages from BLAS/LAPACK operations (default: None)
+
+### BLAS/LAPACK Return Code Interpretation
+
+LinearSolve.jl now provides detailed interpretation of BLAS/LAPACK return codes (info parameter) to help diagnose numerical issues. When BLAS/LAPACK operations encounter problems, the logging system will provide human-readable explanations based on the specific return code and operation.
+
+#### Common BLAS/LAPACK Return Codes
+
+- **info = 0**: Operation completed successfully
+- **info < 0**: Argument -info had an illegal value (e.g., wrong dimensions, invalid parameters)
+- **info > 0**: Operation-specific issues:
+  - **LU factorization (getrf)**: U(info,info) is exactly zero, matrix is singular
+  - **Cholesky factorization (potrf)**: Leading minor of order info is not positive definite
+  - **QR factorization (geqrf)**: Numerical issues with Householder reflector info
+  - **SVD (gesdd/gesvd)**: Algorithm failed to converge, info off-diagonal elements did not converge
+  - **Eigenvalue computation (syev/heev)**: info off-diagonal elements did not converge to zero
+  - **Bunch-Kaufman (sytrf/hetrf)**: D(info,info) is exactly zero, matrix is singular
+
+#### Example Usage with Enhanced BLAS Logging
+
+```julia
+using LinearSolve
+
+# Enable detailed BLAS error logging
+verbose = LinearVerbosity(
+    blas_errors = Verbosity.Info(),  # Show detailed error interpretations
+    blas_timing = Verbosity.Info(),  # Show performance metrics
+    blas_info = Verbosity.Info()     # Show all BLAS operation details
+)
+
+# Solve a potentially singular system
+A = [1.0 2.0; 2.0 4.0]  # Singular matrix
+b = [1.0, 2.0]
+prob = LinearProblem(A, b)
+sol = solve(prob, LUFactorization(); verbose=verbose)
+
+# The logging will show:
+# - BLAS/LAPACK dgetrf: Matrix is singular
+# - Details: U(2,2) is exactly zero. The factorization has been completed, but U is singular
+# - Return code (info): 2
+# - Additional context: matrix size, condition number, memory usage
+```
+
+The enhanced logging also provides:
+- Matrix properties (size, type, condition number when feasible)
+- Memory usage estimates
+- Performance timing for BLAS operations (when blas_timing is enabled)
+- Detailed context for debugging numerical issues

ext/LinearSolveBLISExt.jl

@@ -9,8 +9,11 @@ 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
+using LinearSolve: ArrayInterface, BLISLUFactorization, @get_cacheval, LinearCache, SciMLBase,
+                   interpret_blas_code, log_blas_info, get_blas_operation_info, 
+                   time_blas_operation, check_and_log_lapack_result, LinearVerbosity
 using SciMLBase: ReturnCode
+using SciMLLogging: Verbosity
 
 const global libblis = blis_jll.blis
 const global liblapack = LAPACK_jll.liblapack
@@ -220,11 +223,29 @@ 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])
+        
+        # Get additional operation info for logging
+        op_info = get_blas_operation_info(:dgetrf, A, cache.b)
+        
+        # Time the BLAS operation if verbosity requires it
+        res = time_blas_operation(:dgetrf, verbose) do
+            getrf!(A; ipiv = cacheval[1].ipiv, info = cacheval[2])
+        end
+        
         fact = LU(res[1:3]...), res[4]
         cache.cacheval = fact
+        
+        # Log BLAS return code with detailed interpretation
+        info_value = res[3]
+        if info_value != 0
+            log_blas_info(:dgetrf, info_value, verbose; extra_context=op_info)
+        elseif isa(verbose.numerical.blas_success, Verbosity.Info)
+            @info "BLAS LU factorization (dgetrf) completed successfully" op_info
+        end
 
         if !LinearAlgebra.issuccess(fact[1])
             return SciMLBase.build_linear_solution(
@@ -236,13 +257,22 @@ function SciMLBase.solve!(cache::LinearCache, alg::BLISLUFactorization;
     A, info = @get_cacheval(cache, :BLISLUFactorization)
     require_one_based_indexing(cache.u, cache.b)
     m, n = size(A, 1), size(A, 2)
-    if m > n
-        Bc = copy(cache.b)
-        getrs!('N', A.factors, A.ipiv, Bc; info)
-        copyto!(cache.u, 1, Bc, 1, n)
-    else
-        copyto!(cache.u, cache.b)
-        getrs!('N', A.factors, A.ipiv, cache.u; info)
+    
+    # Time the solve operation
+    solve_result = time_blas_operation(:dgetrs, verbose) do
+        if m > n
+            Bc = copy(cache.b)
+            getrs!('N', A.factors, A.ipiv, Bc; info)
+            copyto!(cache.u, 1, Bc, 1, n)
+        else
+            copyto!(cache.u, cache.b)
+            getrs!('N', A.factors, A.ipiv, cache.u; info)
+        end
+    end
+    
+    # Log solve operation result if there was an error
+    if info[] != 0
+        log_blas_info(:dgetrs, info[], verbose)
     end
 
     SciMLBase.build_linear_solution(alg, cache.u, nothing, cache; retcode = ReturnCode.Success)

src/LinearSolve.jl

@@ -339,6 +339,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")