deprecate/remove gradient from base, fix #16113 (#23816)

NEWS.md

@@ -479,6 +479,8 @@ Deprecated or removed
     `prompt_if_incorrect` argument are deprecated. Instead, prompting behavior is controlled using
     the `allow_prompt` keyword in the `LibGit2.CredentialPayload` constructor ([#23690]).
 
+  * `gradient` is deprecated and will be removed in the next release ([#23816]).
+
   * The timing functions `tic`, `toc`, and `toq` are deprecated in favor of `@time` and `@elapsed`
     ([#17046]).
 

base/deprecated.jl

@@ -1868,6 +1868,43 @@ function toc()
     return t
 end
 
+# PR #23816: deprecation of gradient
+export gradient
+@eval Base.LinAlg begin
+    export gradient
+
+    function gradient(args...)
+        Base.depwarn("gradient is deprecated and will be removed in the next release.", :gradient)
+        return _gradient(args...)
+    end
+
+    _gradient(F::BitVector) = _gradient(Array(F))
+    _gradient(F::BitVector, h::Real) = _gradient(Array(F), h)
+    _gradient(F::Vector, h::BitVector) = _gradient(F, Array(h))
+    _gradient(F::BitVector, h::Vector) = _gradient(Array(F), h)
+    _gradient(F::BitVector, h::BitVector) = _gradient(Array(F), Array(h))
+
+    function _gradient(F::AbstractVector, h::Vector)
+        n = length(F)
+        T = typeof(oneunit(eltype(F))/oneunit(eltype(h)))
+        g = similar(F, T)
+        if n == 1
+            g[1] = zero(T)
+        elseif n > 1
+            g[1] = (F[2] - F[1]) / (h[2] - h[1])
+            g[n] = (F[n] - F[n-1]) / (h[end] - h[end-1])
+            if n > 2
+                h = h[3:n] - h[1:n-2]
+                g[2:n-1] = (F[3:n] - F[1:n-2]) ./ h
+            end
+        end
+        g
+    end
+
+    _gradient(F::AbstractVector) = _gradient(F, [1:length(F);])
+    _gradient(F::AbstractVector, h::Real) = _gradient(F, [h*(1:length(F));])
+end
+
 @noinline function getaddrinfo(callback::Function, host::AbstractString)
     depwarn("getaddrinfo with a callback function is deprecated, wrap code in @async instead for deferred execution", :getaddrinfo)
     @async begin

base/exports.jl

@@ -458,7 +458,6 @@ export
     findnz,
     first,
     flipdim,
-    gradient,
     hcat,
     hvcat,
     ind2sub,

base/linalg/bitarray.jl

@@ -74,15 +74,6 @@ function tril(B::BitMatrix, k::Integer=0)
     A
 end
 
-## diff and gradient
-
-# TODO: this could be improved (is it worth it?)
-gradient(F::BitVector) = gradient(Array(F))
-gradient(F::BitVector, h::Real) = gradient(Array(F), h)
-gradient(F::Vector, h::BitVector) = gradient(F, Array(h))
-gradient(F::BitVector, h::Vector) = gradient(Array(F), h)
-gradient(F::BitVector, h::BitVector) = gradient(Array(F), Array(h))
-
 ## diag and related
 
 function diag(B::BitMatrix)

base/linalg/dense.jl

@@ -215,23 +215,6 @@ function tril!(M::AbstractMatrix, k::Integer)
 end
 tril(M::Matrix, k::Integer) = tril!(copy(M), k)
 
-function gradient(F::AbstractVector, h::Vector)
-    n = length(F)
-    T = typeof(oneunit(eltype(F))/oneunit(eltype(h)))
-    g = similar(F, T)
-    if n == 1
-        g[1] = zero(T)
-    elseif n > 1
-        g[1] = (F[2] - F[1]) / (h[2] - h[1])
-        g[n] = (F[n] - F[n-1]) / (h[end] - h[end-1])
-        if n > 2
-            h = h[3:n] - h[1:n-2]
-            g[2:n-1] = (F[3:n] - F[1:n-2]) ./ h
-        end
-    end
-    g
-end
-
 function diagind(m::Integer, n::Integer, k::Integer=0)
     if !(-m <= k <= n)
         throw(ArgumentError(string("requested diagonal, $k, must be at least $(-m) and ",

base/linalg/generic.jl

@@ -271,33 +271,8 @@ function diff(A::AbstractMatrix, dim::Integer=1)
     end
 end
 
-
-gradient(F::AbstractVector) = gradient(F, [1:length(F);])
-
-"""
-    gradient(F::AbstractVector, [h::Real])
-
-Compute differences along vector `F`, using `h` as the spacing between points. The default
-spacing is one.
-
-# Examples
-```jldoctest
-julia> a = [2,4,6,8];
-
-julia> gradient(a)
-4-element Array{Float64,1}:
- 2.0
- 2.0
- 2.0
- 2.0
-```
-"""
-gradient(F::AbstractVector, h::Real) = gradient(F, [h*(1:length(F));])
-
 diag(A::AbstractVector) = throw(ArgumentError("use diagm instead of diag to construct a diagonal matrix"))
 
-#diagm(v::AbstractVecOrMat{T}) where {T}
-
 ###########################################################################################
 # Inner products and norms
 

base/linalg/linalg.jl

@@ -84,7 +84,6 @@ export
     eye,
     factorize,
     givens,
-    gradient,
     hessfact,
     hessfact!,
     isdiag,

doc/src/stdlib/arrays.md

@@ -140,7 +140,6 @@ Base.cumsum!
 Base.cumsum_kbn
 Base.crc32c
 Base.LinAlg.diff
-Base.LinAlg.gradient
 Base.repeat(::AbstractArray)
 Base.rot180
 Base.rotl90

test/bitarray.jl

@@ -1401,10 +1401,6 @@ timesofar("cat")
     @check_bit_operation svd(b1)
     @check_bit_operation qr(b1)
 
-    b1 = bitrand(v1)
-    @check_bit_operation gradient(b1)
-    @check_bit_operation gradient(b1, 1.0)
-
     b1 = bitrand(v1)
     @check_bit_operation diagm(b1) BitMatrix
 

test/linalg/dense.jl

@@ -156,20 +156,6 @@ end # for eltya
     end
 end
 
-@testset "Test gradient for $elty" for elty in (Int32, Int64, Float32, Float64, Complex64, Complex128)
-    if elty <: Real
-        x = convert(Vector{elty}, [1:3;])
-        g = ones(elty, 3)
-    else
-        x = convert(Vector{elty}, complex.([1:3;], [1:3;]))
-        g = convert(Vector{elty}, complex.(ones(3), ones(3)))
-    end
-    xsub = view(x, 1:size(x, 1))
-    @test gradient(x) ≈ g
-    @test gradient(xsub) ≈ g # Test gradient on SubArray
-    @test gradient(ones(elty,1)) == zeros(elty,1)
-end
-
 @testset "Tests norms" begin
     nnorm = 10
     mmat = 10