Deprecate speye.

NEWS.md

@@ -509,6 +509,9 @@ Deprecated or removed
     particularly, consider instead `triu!(copy(parent(A)))`. On `LowerTriangular` matrices
     `A` particularly, consider instead `tril!(copy(parent(A)))` ([#24250]).
 
+  * `speye` has been deprecated in favor of `I`, `sparse`, and `SparseMatrixCSC`
+    constructor methods ([#24356]).
+
   * Calling `union` with no arguments is deprecated; construct an empty set with an appropriate
     element type using `Set{T}()` instead ([#23144]).
 

base/deprecated.jl

@@ -2070,6 +2070,55 @@ end
 # deprecate bits to bitstring (#24263, #24281)
 @deprecate bits bitstring
 
+# deprecate speye
+export speye
+function speye(n::Integer)
+    depwarn(string("`speye(n::Integer)` has been deprecated in favor of `I`, `sparse`, and ",
+                    "`SparseMatrixCSC` constructor methods. For a direct replacement, consider ",
+                    "`sparse(1.0I, n, n)`, `SparseMatrixCSC(1.0I, n, n)`, or `SparseMatrixCSC{Float64}(I, n, n)`. ",
+                    "If `Float64` element type is not necessary, consider the shorter `sparse(I, n, n)` ",
+                    "or `SparseMatrixCSC(I, n, n)` (with default `eltype(I)` of `Bool`)."), :speye)
+    return sparse(1.0I, n, n)
+end
+function speye(m::Integer, n::Integer)
+    depwarn(string("`speye(m::Integer, n::Integer)` has been deprecated in favor of `I`, ",
+                    "`sparse`, and `SparseMatrixCSC` constructor methods. For a direct ",
+                    "replacement, consider `sparse(1.0I, m, n)`, `SparseMatrixCSC(1.0I, m, n)`, ",
+                    "or `SparseMatrixCSC{Float64}(I, m, n)`. If `Float64` element type is not ",
+                    " necessary, consider the shorter `sparse(I, m, n)` or `SparseMatrixCSC(I, m, n)` ",
+                    "(with default `eltype(I)` of `Bool`)."), :speye)
+    return sparse(1.0I, m, n)
+end
+function speye(::Type{T}, n::Integer) where T
+    depwarn(string("`speye(T, n::Integer)` has been deprecated in favor of `I`, `sparse`, and ",
+                    "`SparseMatrixCSC` constructor methods. For a direct replacement, consider ",
+                    "`sparse(T(1)I, n, n)` if `T` is concrete or `SparseMatrixCSC{T}(I, n, n)` ",
+                    "if `T` is either concrete or abstract. If element type `T` is not necessary, ",
+                    "consider the shorter `sparse(I, n, n)` or `SparseMatrixCSC(I, n, n)` ",
+                    "(with default `eltype(I)` of `Bool`)."), :speye)
+    return SparseMatrixCSC{T}(I, n)
+end
+function speye(::Type{T}, m::Integer, n::Integer) where T
+    depwarn(string("`speye(T, m::Integer, n::Integer)` has been deprecated in favor of `I`, ",
+                    "`sparse`, and `SparseMatrixCSC` constructor methods. For a direct ",
+                    "replacement, consider `sparse(T(1)I, m, n)` if `T` is concrete or ",
+                    "`SparseMatrixCSC{T}(I, m, n)` if `T` is either concrete or abstract. ",
+                    "If element type `T` is not necessary, consider the shorter ",
+                    "`sparse(I, m, n)` or `SparseMatrixCSC(I, m, n)` (with default `eltype(I)` ",
+                    "of `Bool`)."), :speye)
+    return SparseMatrixCSC{T}(I, m, n)
+end
+function speye(S::SparseMatrixCSC{T}) where T
+    depwarn(string("`speye(S::SparseMatrixCSC{T})` has been deprecated in favor of `I`, ",
+                    "`sparse`, and `SparseMatrixCSC` constructor methods. For a direct ",
+                    "replacement, consider `sparse(T(1)I, size(S)...)` if `T` is concrete or ",
+                    "`SparseMatrixCSC{eltype(S)}(I, size(S))` if `T` is either concrete or abstract. ",
+                    "If preserving element type `T` is not necessary, consider the shorter ",
+                    "`sparse(I, size(S)...)` or `SparseMatrixCSC(I, size(S))` (with default ",
+                    "`eltype(I)` of `Bool`)."), :speye)
+    return SparseMatrixCSC{T}(I, m, n)
+end
+
 # issue #24167
 @deprecate EnvHash EnvDict
 

base/essentials.jl

@@ -119,7 +119,7 @@ true
 Similarly, if `T` is a composite type and `x` a related instance, the result of
 `convert(T, x)` may alias part or all of `x`.
 ```jldoctest
-julia> x = speye(5);
+julia> x = sparse(1.0I, 5, 5);
 
 julia> typeof(x)
 SparseMatrixCSC{Float64,Int64}

base/exports.jl

@@ -1256,7 +1256,6 @@ export
     sparse,
     sparsevec,
     spdiagm,
-    speye,
     spones,
     sprand,
     sprandn,

base/linalg/arnoldi.jl

@@ -145,7 +145,7 @@ final residual vector `resid`.
 
 # Examples
 ```jldoctest
-julia> A = speye(4, 4); B = Diagonal(1:4);
+julia> A = sparse(1.0I, 4, 4); B = Diagonal(1:4);
 
 julia> λ, ϕ = eigs(A, B, nev = 2);
 

base/sparse/cholmod.jl

@@ -16,7 +16,7 @@ export
     Factor,
     Sparse
 
-import ..SparseArrays: AbstractSparseMatrix, SparseMatrixCSC, increment, indtype, sparse, speye,
+import ..SparseArrays: AbstractSparseMatrix, SparseMatrixCSC, increment, indtype, sparse,
     spzeros, nnz
 
 #########

base/sparse/sparse.jl

@@ -31,7 +31,7 @@ import Base: @get!, acos, acosd, acot, acotd, acsch, asech, asin, asind, asinh,
 
 export AbstractSparseArray, AbstractSparseMatrix, AbstractSparseVector,
     SparseMatrixCSC, SparseVector, blkdiag, droptol!, dropzeros!, dropzeros,
-    issparse, nonzeros, nzrange, rowvals, sparse, sparsevec, spdiagm, speye, spones,
+    issparse, nonzeros, nzrange, rowvals, sparse, sparsevec, spdiagm, spones,
     sprand, sprandn, spzeros, nnz, permute
 
 include("abstractsparse.jl")

base/sparse/sparsematrix.jl

@@ -59,11 +59,11 @@ Returns the number of stored (filled) elements in a sparse array.
 
 # Examples
 ```jldoctest
-julia> A = speye(3)
-3×3 SparseMatrixCSC{Float64,Int64} with 3 stored entries:
-  [1, 1]  =  1.0
-  [2, 2]  =  1.0
-  [3, 3]  =  1.0
+julia> A = sparse(2I, 3, 3)
+3×3 SparseMatrixCSC{Int64,Int64} with 3 stored entries:
+  [1, 1]  =  2
+  [2, 2]  =  2
+  [3, 3]  =  2
 
 julia> nnz(A)
 3
@@ -83,17 +83,17 @@ modifications to the returned vector will mutate `A` as well. See
 
 # Examples
 ```jldoctest
-julia> A = speye(3)
-3×3 SparseMatrixCSC{Float64,Int64} with 3 stored entries:
-  [1, 1]  =  1.0
-  [2, 2]  =  1.0
-  [3, 3]  =  1.0
+julia> A = sparse(2I, 3, 3)
+3×3 SparseMatrixCSC{Int64,Int64} with 3 stored entries:
+  [1, 1]  =  2
+  [2, 2]  =  2
+  [3, 3]  =  2
 
 julia> nonzeros(A)
-3-element Array{Float64,1}:
- 1.0
- 1.0
- 1.0
+3-element Array{Int64,1}:
+ 2
+ 2
+ 2
 ```
 """
 nonzeros(S::SparseMatrixCSC) = S.nzval
@@ -108,11 +108,11 @@ nonzero values. See also [`nonzeros`](@ref) and [`nzrange`](@ref).
 
 # Examples
 ```jldoctest
-julia> A = speye(3)
-3×3 SparseMatrixCSC{Float64,Int64} with 3 stored entries:
-  [1, 1]  =  1.0
-  [2, 2]  =  1.0
-  [3, 3]  =  1.0
+julia> A = sparse(2I, 3, 3)
+3×3 SparseMatrixCSC{Int64,Int64} with 3 stored entries:
+  [1, 1]  =  2
+  [2, 2]  =  2
+  [3, 3]  =  2
 
 julia> rowvals(A)
 3-element Array{Int64,1}:
@@ -1453,8 +1453,6 @@ julia> spones(A)
   [3, 3]  =  1.0
   [2, 4]  =  1.0
 ```
-
-Note the difference from [`speye`](@ref).
 """
 spones(S::SparseMatrixCSC{T}) where {T} =
      SparseMatrixCSC(S.m, S.n, copy(S.colptr), copy(S.rowval), ones(T, S.colptr[end]-1))
@@ -1487,55 +1485,11 @@ function spzeros(::Type{Tv}, ::Type{Ti}, sz::Tuple{Integer,Integer}) where {Tv,
     spzeros(Tv, Ti, sz[1], sz[2])
 end
 
-speye(n::Integer) = speye(Float64, n)
-speye(::Type{T}, n::Integer) where {T} = speye(T, n, n)
-speye(m::Integer, n::Integer) = speye(Float64, m, n)
-
-"""
-    speye(S)
-
-Create a sparse identity matrix with the same size as `S`.
-
-# Examples
-```jldoctest
-julia> A = sparse([1,2,3,4],[2,4,3,1],[5.,4.,3.,2.])
-4×4 SparseMatrixCSC{Float64,Int64} with 4 stored entries:
-  [4, 1]  =  2.0
-  [1, 2]  =  5.0
-  [3, 3]  =  3.0
-  [2, 4]  =  4.0
-
-julia> speye(A)
-4×4 SparseMatrixCSC{Float64,Int64} with 4 stored entries:
-  [1, 1]  =  1.0
-  [2, 2]  =  1.0
-  [3, 3]  =  1.0
-  [4, 4]  =  1.0
-```
-
-Note the difference from [`spones`](@ref).
-"""
-speye(S::SparseMatrixCSC{T}) where {T} = speye(T, size(S, 1), size(S, 2))
-eye(S::SparseMatrixCSC) = speye(S)
-
-"""
-    speye([type,]m[,n])
-
-Create a sparse identity matrix of size `m x m`. When `n` is supplied,
-create a sparse identity matrix of size `m x n`. The type defaults to [`Float64`](@ref)
-if not specified.
-
-`sparse(I, m, n)` is equivalent to `speye(Int, m, n)`, and
-`sparse(α*I, m, n)` can be used to efficiently create a sparse
-multiple `α` of the identity matrix.
-"""
-speye(::Type{T}, m::Integer, n::Integer) where {T} = SparseMatrixCSC{T}(UniformScaling(one(T)), Dims((m, n)))
-sparse(s::UniformScaling, m::Integer, n::Integer=m) = SparseMatrixCSC(s, Dims((m, n)))
+eye(S::SparseMatrixCSC{T}) where {T} = SparseMatrixCSC{T}(I, size(S))
 
 function one(S::SparseMatrixCSC{T}) where T
-    m,n = size(S)
-    if m != n; throw(DimensionMismatch("multiplicative identity only defined for square matrices")); end
-    speye(T, m)
+    S.m == S.n || throw(DimensionMismatch("multiplicative identity only defined for square matrices"))
+    return SparseMatrixCSC{T}(I, S.m, S.n)
 end
 
 ## SparseMatrixCSC construction from UniformScaling
@@ -1573,6 +1527,7 @@ function Base.isone(A::SparseMatrixCSC)
     return true
 end
 
+sparse(s::UniformScaling, m::Integer, n::Integer=m) = SparseMatrixCSC(s, m, n)
 
 # TODO: More appropriate location?
 conj!(A::SparseMatrixCSC) = (@inbounds broadcast!(conj, A.nzval, A.nzval); A)
@@ -3141,13 +3096,13 @@ Concatenate matrices block-diagonally. Currently only implemented for sparse mat
 
 # Examples
 ```jldoctest
-julia> blkdiag(speye(3), 2*speye(2))
-5×5 SparseMatrixCSC{Float64,Int64} with 5 stored entries:
-  [1, 1]  =  1.0
-  [2, 2]  =  1.0
-  [3, 3]  =  1.0
-  [4, 4]  =  2.0
-  [5, 5]  =  2.0
+julia> blkdiag(sparse(2I, 3, 3), sparse(4I, 2, 2))
+5×5 SparseMatrixCSC{Int64,Int64} with 5 stored entries:
+  [1, 1]  =  2
+  [2, 2]  =  2
+  [3, 3]  =  2
+  [4, 4]  =  4
+  [5, 5]  =  4
 ```
 """
 function blkdiag(X::SparseMatrixCSC...)
@@ -3599,6 +3554,6 @@ end
 
 ## Uniform matrix arithmetic
 
-(+)(A::SparseMatrixCSC, J::UniformScaling) = A + J.λ * speye(A)
-(-)(A::SparseMatrixCSC, J::UniformScaling) = A - J.λ * speye(A)
-(-)(J::UniformScaling, A::SparseMatrixCSC) = J.λ * speye(A) - A
+(+)(A::SparseMatrixCSC, J::UniformScaling) = A + sparse(J, size(A)...)
+(-)(A::SparseMatrixCSC, J::UniformScaling) = A - sparse(J, size(A)...)
+(-)(J::UniformScaling, A::SparseMatrixCSC) = sparse(J, size(A)...) - A

doc/src/manual/arrays.md

@@ -781,19 +781,13 @@ stored zeros. (See [Sparse Matrix Storage](@ref man-csc).).
 
 ### Sparse Vector and Matrix Constructors
 
-The simplest way to create sparse arrays is to use functions equivalent to the [`zeros`](@ref)
-and [`eye`](@ref) functions that Julia provides for working with dense arrays. To produce
-sparse arrays instead, you can use the same names with an `sp` prefix:
+The simplest way to create a sparse array is to use a function equivalent to the [`zeros`](@ref)
+function that Julia provides for working with dense arrays. To produce a
+sparse array instead, you can use the same name with an `sp` prefix:
 
 ```jldoctest
 julia> spzeros(3)
 3-element SparseVector{Float64,Int64} with 0 stored entries
-
-julia> speye(3,5)
-3×5 SparseMatrixCSC{Float64,Int64} with 3 stored entries:
-  [1, 1]  =  1.0
-  [2, 2]  =  1.0
-  [3, 3]  =  1.0
 ```
 
 The [`sparse`](@ref) function is often a handy way to construct sparse arrays. For
@@ -867,7 +861,7 @@ You can go in the other direction using the [`Array`](@ref) constructor. The [`i
 function can be used to query if a matrix is sparse.
 
 ```jldoctest
-julia> issparse(speye(5))
+julia> issparse(spzeros(5))
 true
 ```
 
@@ -895,7 +889,7 @@ section of the standard library reference.
 |:-------------------------- |:---------------------- |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`spzeros(m,n)`](@ref)     | [`zeros(m,n)`](@ref)   | Creates a *m*-by-*n* matrix of zeros. ([`spzeros(m,n)`](@ref) is empty.)                                                                                              |
 | [`spones(S)`](@ref)        | [`ones(m,n)`](@ref)    | Creates a matrix filled with ones. Unlike the dense version, [`spones`](@ref) has the same sparsity pattern as *S*.                                                 |
-| [`speye(n)`](@ref)         | [`eye(n)`](@ref)       | Creates a *n*-by-*n* identity matrix.                                                                                                                                 |
+| [`sparse(I, n, n)`](@ref)  | [`eye(n)`](@ref)       | Creates a *n*-by-*n* identity matrix.                                                                                                                                 |
 | [`Array(S)`](@ref)         | [`sparse(A)`](@ref)    | Interconverts between dense and sparse formats.                                                                                                                       |
 | [`sprand(m,n,d)`](@ref)    | [`rand(m,n)`](@ref)    | Creates a *m*-by-*n* random matrix (of density *d*) with iid non-zero elements distributed uniformly on the half-open interval ``[0, 1)``.                            |
 | [`sprandn(m,n,d)`](@ref)   | [`randn(m,n)`](@ref)   | Creates a *m*-by-*n* random matrix (of density *d*) with iid non-zero elements distributed according to the standard normal (Gaussian) distribution.                  |

doc/src/stdlib/arrays.md

@@ -188,8 +188,6 @@ Base.SparseArrays.issparse
 Base.SparseArrays.nnz
 Base.SparseArrays.spzeros
 Base.SparseArrays.spones
-Base.SparseArrays.speye(::Type, ::Integer, ::Integer)
-Base.SparseArrays.speye(::SparseMatrixCSC)
 Base.SparseArrays.spdiagm
 Base.SparseArrays.sprand
 Base.SparseArrays.sprandn

test/arrayops.jl

@@ -1008,7 +1008,7 @@ end
     @test m[1,2] == ([2,4],)
 
     # issue #21123
-    @test mapslices(nnz, speye(3), 1) == [1 1 1]
+    @test mapslices(nnz, sparse(1.0I, 3, 3), 1) == [1 1 1]
 end
 
 @testset "single multidimensional index" begin

test/hashing.jl

@@ -73,7 +73,7 @@ vals = Any[
     Dict(x => x for x in 1:10),
     Dict(7=>7,9=>9,4=>4,10=>10,2=>2,3=>3,8=>8,5=>5,6=>6,1=>1),
     [], [1], [2], [1, 1], [1, 2], [1, 3], [2, 2], [1, 2, 2], [1, 3, 3],
-    zeros(2, 2), spzeros(2, 2), eye(2, 2), speye(2, 2),
+    zeros(2, 2), spzeros(2, 2), eye(2, 2), sparse(1.0I, 2, 2),
     sparse(ones(2, 2)), ones(2, 2), sparse([0 0; 1 0]), [0 0; 1 0],
     [-0. 0; -0. 0.], SparseMatrixCSC(2, 2, [1, 3, 3], [1, 2], [-0., -0.])
 ]

test/linalg/arnoldi.jl

@@ -178,7 +178,7 @@ let
     # Adjust the tolerance a bit since matrices with repeated eigenvalues
     # can be very stressful to ARPACK and this may therefore fail with
     # info = 3 if the tolerance is too small
-    @test eigs(speye(50), nev=10, tol = 5e-16)[1] ≈ ones(10) #Issue 4246
+    @test eigs(sparse(1.0I, 50, 50), nev=10, tol = 5e-16)[1] ≈ ones(10) #Issue 4246
 end
 
 @testset "real svds" begin

test/linalg/special.jl

@@ -178,7 +178,7 @@ end
     annotations = testfull ? (triannotations..., symannotations...) : (LowerTriangular, Symmetric)
     # Concatenations involving these types, un/annotated, should yield sparse arrays
     spvec = spzeros(N)
-    spmat = speye(N)
+    spmat = sparse(1.0I, N, N)
     diagmat = Diagonal(ones(N))
     bidiagmat = Bidiagonal(ones(N), ones(N-1), :U)
     tridiagmat = Tridiagonal(ones(N-1), ones(N), ones(N-1))

test/linalg/uniformscaling.jl

@@ -82,7 +82,7 @@ let
         @test B + I == B + eye(B)
         @test I + B == B + eye(B)
         AA = randn(2, 2)
-        for SS in (sprandn(3,3, 0.5), speye(Int, 3))
+        for SS in (sprandn(3,3, 0.5), sparse(Int(1)I, 3, 3))
             for (A, S) in ((AA, SS), (view(AA, 1:2, 1:2), view(SS, 1:3, 1:3)))
                 @test @inferred(A + I) == A + eye(A)
                 @test @inferred(I + A) == A + eye(A)

test/perf/kernel/getdivgrad.jl

@@ -5,9 +5,9 @@
 #----------------- Get the A matrix
 function getDivGrad(n1,n2,n3)
     # the Divergence
-    D1 = kron(speye(n3),kron(speye(n2),ddx(n1)))
-    D2 = kron(speye(n3),kron(ddx(n2),speye(n1)))
-    D3 = kron(ddx(n3),kron(speye(n2),speye(n1)))
+    D1 = kron(sparse(1.0I, n3, n3), kron(sparse(1.0I, n2), ddx(n1)))
+    D2 = kron(sparse(1.0I, n3, n3), kron(ddx(n2), sparse(1.0I, n1, n1)))
+    D3 = kron(ddx(n3), kron(sparse(1.0I, n2, n2), sparse(1.0I, n1, n1)))
     # DIV from faces to cell-centers
     Div = [D1 D2 D3]
 

test/perf/sparse/fem.jl

@@ -7,7 +7,7 @@ function fdlaplacian(N)
     # create a 1D laplacian and a sparse identity
     fdl1 = spdiagm(-1 => ones(N-1), 0 => -2*ones(N), 1 => ones(N-1))
     # laplace operator on the full grid
-    return kron(speye(N), fdl1) + kron(fdl1, speye(N))
+    return kron(sparse(1.0I, N, N), fdl1) + kron(fdl1, sparse(1.0I, N, N))
 end
 
 # get the list of boundary dof-indices