Display sparse matrices by showing their structure with braille patterns (#33821)

* Display sparse matrices by showing their structure with braille patterns

* Adopt test which involves showing of sparse matrix

* Adopt docstrings

* Call `rowvals(S)` only once

* Extend code documentation

* Simplify calculation of `scaleHeight` and `scaleWidth`

* Make `brailleBlocks` a `const`

* Initialize `brailleGrid` with `UInt16(10240)`

* Let the compiler do the conversion of `\n`

* Improve printing to `io`

* Unwrap the helper functions directly into the loop

* Show small sparse matrix in traditional manner

* Add tests for `isstored`

* Adapt tests for `show`

* Adapt doctests

* Use `m` and `n` instead of `size` calls

* Initialize `scaleHeight` and `scaleWidth` in `else` clause

* Reenable commented test

* Declare type of `maxHeight` and `maxWidth`

* Do not print leading newline in `_show_with_braille_patterns`

* Reenable test for issue 30589

* Shorten type declarations of `maxHeight` and `maxWidth`

* Add `isstored` to Base

* Add `isstored` for sparse vectors

* Make use of Base function `isstored`

* Add `boundscheck` macro

* Clarify news

* Call `issorted` by `Base.issored`

* Use `Base.isstored` in tests

* Set cutoff value to print sparse matrices with braille to 16

Co-authored-by: Steven G. Johnson <stevenj@alum.mit.edu>

Author: goggle

NEWS.md

@@ -60,6 +60,7 @@ Standard library changes
 
 #### SparseArrays
 
+* Display large sparse matrices with a Unicode "spy" plot of their nonzero patterns, and display small sparse matrices by an `Matrix`-like 2d layout of their contents.
 
 #### Dates
 

base/abstractarray.jl

@@ -412,6 +412,11 @@ function isassigned(a::AbstractArray, i::Integer...)
     end
 end
 
+function isstored(A::AbstractArray{<:Any,N}, I::Vararg{Integer,N}) where {N}
+    @boundscheck checkbounds(A, I...)
+    return true
+end
+
 # used to compute "end" for last index
 function trailingsize(A, n)
     s = 1

stdlib/LinearAlgebra/src/svd.jl

@@ -303,12 +303,12 @@ Q factor:
  0.0  1.0
 D1 factor:
 2×2 SparseArrays.SparseMatrixCSC{Float64,Int64} with 2 stored entries:
-  [1, 1]  =  0.707107
-  [2, 2]  =  0.707107
+ 0.707107   ⋅
+  ⋅        0.707107
 D2 factor:
 2×2 SparseArrays.SparseMatrixCSC{Float64,Int64} with 2 stored entries:
-  [1, 1]  =  0.707107
-  [2, 2]  =  0.707107
+ 0.707107   ⋅
+  ⋅        0.707107
 R0 factor:
 2×2 Array{Float64,2}:
  1.41421   0.0

stdlib/SparseArrays/docs/src/index.md

@@ -52,15 +52,15 @@ remove stored zeros from the sparse matrix.
 ```jldoctest
 julia> A = sparse([1, 1, 2, 3], [1, 3, 2, 3], [0, 1, 2, 0])
 3×3 SparseMatrixCSC{Int64,Int64} with 4 stored entries:
-  [1, 1]  =  0
-  [2, 2]  =  2
-  [1, 3]  =  1
-  [3, 3]  =  0
+ 0  ⋅  1
+ ⋅  2  ⋅
+ ⋅  ⋅  0
 
 julia> dropzeros(A)
 3×3 SparseMatrixCSC{Int64,Int64} with 2 stored entries:
-  [2, 2]  =  2
-  [1, 3]  =  1
+ ⋅  ⋅  1
+ ⋅  2  ⋅
+ ⋅  ⋅  ⋅
 ```
 
 ## Sparse Vector Storage
@@ -106,10 +106,8 @@ julia> I = [1, 4, 3, 5]; J = [4, 7, 18, 9]; V = [1, 2, -5, 3];
 
 julia> S = sparse(I,J,V)
 5×18 SparseMatrixCSC{Int64,Int64} with 4 stored entries:
-  [1,  4]  =  1
-  [4,  7]  =  2
-  [5,  9]  =  3
-  [3, 18]  =  -5
+⠀⠈⠀⡀⠀⠀⠀⠀⠠
+⠀⠀⠀⠀⠁⠀⠀⠀⠀
 
 julia> R = sparsevec(I,V)
 5-element SparseVector{Int64,Int64} with 4 stored entries:
@@ -152,11 +150,11 @@ the [`sparse`](@ref) function:
 ```jldoctest
 julia> sparse(Matrix(1.0I, 5, 5))
 5×5 SparseMatrixCSC{Float64,Int64} with 5 stored entries:
-  [1, 1]  =  1.0
-  [2, 2]  =  1.0
-  [3, 3]  =  1.0
-  [4, 4]  =  1.0
-  [5, 5]  =  1.0
+ 1.0   ⋅    ⋅    ⋅    ⋅
+  ⋅   1.0   ⋅    ⋅    ⋅
+  ⋅    ⋅   1.0   ⋅    ⋅
+  ⋅    ⋅    ⋅   1.0   ⋅
+  ⋅    ⋅    ⋅    ⋅   1.0
 
 julia> sparse([1.0, 0.0, 1.0])
 3-element SparseVector{Float64,Int64} with 2 stored entries:

stdlib/SparseArrays/src/abstractsparse.jl

@@ -112,10 +112,9 @@ Return a tuple `(I, J, V)` where `I` and `J` are the row and column indices of t
 ```jldoctest
 julia> A = sparse([1 2 0; 0 0 3; 0 4 0])
 3×3 SparseMatrixCSC{Int64,Int64} with 4 stored entries:
-  [1, 1]  =  1
-  [1, 2]  =  2
-  [3, 2]  =  4
-  [2, 3]  =  3
+ 1  2  ⋅
+ ⋅  ⋅  3
+ ⋅  4  ⋅
 
 julia> findnz(A)
 ([1, 1, 3, 2], [1, 2, 2, 3], [1, 2, 4, 3])