JuliaLang · Sacha0 · Nov 19, 2017 · Oct 26, 2017 · fredrikekre · Oct 31, 2017
diff --git a/NEWS.md b/NEWS.md
@@ -528,6 +528,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]).
 

diff --git a/base/deprecated.jl b/base/deprecated.jl
@@ -2076,6 +2076,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
 

diff --git a/base/essentials.jl b/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}

diff --git a/base/exports.jl b/base/exports.jl
@@ -1255,7 +1255,6 @@ export
  sparse,
  sparsevec,
  spdiagm,
- speye,
  spones,
  sprand,
  sprandn,

diff --git a/base/linalg/arnoldi.jl b/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);
 

diff --git a/base/sparse/cholmod.jl b/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
 
 #########

diff --git a/base/sparse/sparse.jl b/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")

diff --git a/base/sparse/sparsematrix.jl b/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) = 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
@@ -1568,6 +1522,7 @@ function Base.isone(A::SparseMatrixCSC)
  return true
 end
 
+sparse(s::UniformScaling, m::Integer, n::Integer) = SparseMatrixCSC(s, Dims((m, n)))
 
 # TODO: More appropriate location?
 conj!(A::SparseMatrixCSC) = (@inbounds broadcast!(conj, A.nzval, A.nzval); A)
@@ -3136,13 +3091,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...)
@@ -3594,6 +3549,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
diff --git a/doc/src/manual/arrays.md b/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. |

diff --git a/doc/src/stdlib/arrays.md b/doc/src/stdlib/arrays.md
@@ -187,8 +187,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

diff --git a/test/arrayops.jl b/test/arrayops.jl
@@ -1017,7 +1017,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

diff --git a/test/hashing.jl b/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.])
 ]

diff --git a/test/linalg/arnoldi.jl b/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

diff --git a/test/linalg/special.jl b/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))

diff --git a/test/linalg/uniformscaling.jl b/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)

diff --git a/test/perf/kernel/getdivgrad.jl b/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]
 

diff --git a/test/perf/sparse/fem.jl b/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