Rename indmin and indmax to argmin and argmax (#25654)

argmin and argmax match the mathematical names as well as those used by Numpy.
On the contrary, there does not appear to be any precedent for indmin and indmax,
and they do not follow any pattern in Julia either.

Author: nalimilan

NEWS.md

@@ -308,7 +308,9 @@ This section lists changes that do not have deprecation warnings.
     This avoids stack overflows in the common case of definitions like
     `f(x, y) = f(promote(x, y)...)` ([#22801]).
 
-  * `findmin`, `findmax`, `indmin`, and `indmax` used to always return linear indices.
+  * `indmin` and `indmax` have been renamed to `argmin` and `argmax`, respectively ([#25654]).
+
+  * `findmin`, `findmax`, `argmin`, and `argmax` used to always return linear indices.
     They now return `CartesianIndex`es for all but 1-d arrays, and in general return
     the `keys` of indexed collections (e.g. dictionaries) ([#22907]).
 
@@ -1238,3 +1240,4 @@ Command-line option changes
 [#25545]: https://github.com/JuliaLang/julia/issues/25545
 [#25616]: https://github.com/JuliaLang/julia/issues/25616
 [#25634]: https://github.com/JuliaLang/julia/issues/25634
+[#25654]: https://github.com/JuliaLang/julia/issues/25654

base/array.jl

@@ -2077,7 +2077,7 @@ function findmin(a)
 end
 
 """
-    indmax(itr) -> Integer
+    argmax(itr) -> Integer
 
 Return the index of the maximum element in a collection. If there are multiple maximal
 elements, then the first one will be returned.
@@ -2086,20 +2086,20 @@ The collection must not be empty.
 
 # Examples
 ```jldoctest
-julia> indmax([8,0.1,-9,pi])
+julia> argmax([8,0.1,-9,pi])
 1
 
-julia> indmax([1,7,7,6])
+julia> argmax([1,7,7,6])
 2
 
-julia> indmax([1,7,7,NaN])
+julia> argmax([1,7,7,NaN])
 4
 ```
 """
-indmax(a) = findmax(a)[2]
+argmax(a) = findmax(a)[2]
 
 """
-    indmin(itr) -> Integer
+    argmin(itr) -> Integer
 
 Return the index of the minimum element in a collection. If there are multiple minimal
 elements, then the first one will be returned.
@@ -2108,17 +2108,17 @@ The collection must not be empty.
 
 # Examples
 ```jldoctest
-julia> indmin([8,0.1,-9,pi])
+julia> argmin([8,0.1,-9,pi])
 3
 
-julia> indmin([7,1,1,6])
+julia> argmin([7,1,1,6])
 2
 
-julia> indmin([7,1,1,NaN])
+julia> argmin([7,1,1,NaN])
 4
 ```
 """
-indmin(a) = findmin(a)[2]
+argmin(a) = findmin(a)[2]
 
 # similar to Matlab's ismember
 """

base/deprecated.jl

@@ -691,8 +691,8 @@ import .Iterators.enumerate
     return p
 end
 
-# ease transition for return type change of e.g. indmax due to PR #22907 when used in the
-# common pattern `ind2sub(size(a), indmax(a))`
+# ease transition for return type change of e.g. argmax due to PR #22907 when used in the
+# common pattern `ind2sub(size(a), argmax(a))`
 @deprecate(ind2sub(dims::NTuple{N,Integer}, idx::CartesianIndex{N}) where N, Tuple(idx))
 
 @deprecate contains(eq::Function, itr, x) any(y->eq(y,x), itr)
@@ -1627,6 +1627,10 @@ export readandwrite
 # PR #25196
 @deprecate_binding ObjectIdDict IdDict{Any,Any}
 
+# PR #25654
+@deprecate indmin argmin
+@deprecate indmax argmax
+
 # END 0.7 deprecations
 
 # BEGIN 1.0 deprecations

base/exports.jl

@@ -393,8 +393,8 @@ export
     hcat,
     hvcat,
     indexin,
-    indmax,
-    indmin,
+    argmax,
+    argmin,
     invperm,
     invpermute!,
     isassigned,

base/pkg/resolve/fieldvalue.jl

@@ -93,9 +93,9 @@ end
 # some hard constraint is being violated
 validmax(a::FieldValue) = a.l0 >= 0
 
-# like usual indmax, but favors the highest indices
+# like usual argmax, but favors the highest indices
 # in case of a tie
-function Base.indmax(f::Field)
+function Base.argmax(f::Field)
     m = typemin(FieldValue)
     mi = 0
     for j = length(f):-1:1

base/pkg/resolve/maxsum.jl

@@ -244,7 +244,7 @@ function getsolution(msgs::Messages)
     sol = Vector{Int}(uninitialized, np)
     for p0 = 1:np
         fld0 = fld[p0]
-        s0 = indmax(fld0)
+        s0 = argmax(fld0)
         if !validmax(fld0[s0])
             throw(UnsatError(p0))
         end
@@ -387,12 +387,12 @@ function decimate1(p0::Int, graph::Graph, msgs::Messages)
 
     @assert !decimated[p0]
     fld0 = fld[p0]
-    s0 = indmax(fld0)
+    s0 = argmax(fld0)
     # only do the decimation if it is consistent with
     # the previously decimated nodes
     for p1 in findall(decimated)
         haskey(adjdict[p0], p1) || continue
-        s1 = indmax(fld[p1])
+        s1 = argmax(fld[p1])
         j1 = adjdict[p0][p1]
         gmsk[p1][j1][s0,s1] || return false
     end

doc/src/base/collections.md

@@ -94,8 +94,8 @@ Base.minimum(::Any, ::Any)
 Base.minimum!
 Base.extrema(::Any)
 Base.extrema(::AbstractArray, ::Any)
-Base.indmax
-Base.indmin
+Base.argmax
+Base.argmin
 Base.findmax(::Any)
 Base.findmax(::AbstractArray, ::Any)
 Base.findmin(::Any)

stdlib/IterativeEigensolvers/test/runtests.jl

@@ -43,16 +43,16 @@ using Test, LinearAlgebra, SparseArrays, Random
         # @test a*v[:,2] ≈ d[2]*b*v[:,2] atol=testtol
         # @test norm(v) > testtol # eigenvectors cannot be null vectors
         if elty <: LinearAlgebra.BlasComplex
-            sr_ind = indmin(real.(a_evs))
+            sr_ind = argmin(real.(a_evs))
             (d, v) = eigs(a, nev=1, which=:SR)
             @test d[1] ≈ a_evs[sr_ind]
-            si_ind = indmin(imag.(a_evs))
+            si_ind = argmin(imag.(a_evs))
             (d, v) = eigs(a, nev=1, which=:SI)
             @test d[1] ≈ a_evs[si_ind]
-            lr_ind = indmax(real.(a_evs))
+            lr_ind = argmax(real.(a_evs))
             (d, v) = eigs(a, nev=1, which=:LR)
             @test d[1] ≈ a_evs[lr_ind]
-            li_ind = indmax(imag.(a_evs))
+            li_ind = argmax(imag.(a_evs))
             (d, v) = eigs(a, nev=1, which=:LI)
             @test d[1] ≈ a_evs[li_ind]
         end

stdlib/LinearAlgebra/test/blas.jl

@@ -71,10 +71,10 @@ srand(100)
         @testset "iamax" begin
             if elty <: Real
                 x = convert(Vector{elty}, randn(n))
-                @test BLAS.iamax(x) == indmax(abs.(x))
+                @test BLAS.iamax(x) == argmax(abs.(x))
             else
                 z = convert(Vector{elty}, complex.(randn(n),randn(n)))
-                @test BLAS.iamax(z) == indmax(map(x -> abs(real(x)) + abs(imag(x)), z))
+                @test BLAS.iamax(z) == argmax(map(x -> abs(real(x)) + abs(imag(x)), z))
             end
         end
         @testset "axp(b)y" begin
@@ -109,10 +109,10 @@ srand(100)
             @test BLAS.nrm2(b) ≈ norm(b)
             if elty <: Real
                 @test BLAS.asum(b) ≈ sum(abs.(b))
-                @test BLAS.iamax(b) ≈ indmax(abs.(b))
+                @test BLAS.iamax(b) ≈ argmax(abs.(b))
             else
                 @test BLAS.asum(b) ≈ sum(abs.(real(b))) + sum(abs.(imag(b)))
-                @test BLAS.iamax(b) == indmax(map(x -> abs(real(x)) + abs(imag(x)), b))
+                @test BLAS.iamax(b) == argmax(map(x -> abs(real(x)) + abs(imag(x)), b))
             end
         end
         # scal

stdlib/SparseArrays/src/SparseArrays.jl

@@ -19,13 +19,13 @@ import LinearAlgebra: mul!, ldiv!, rdiv!, chol, adjoint!, diag, diff, dot, eig,
 import Base: @get!, acos, acosd, acot, acotd, acsch, asech, asin, asind, asinh,
     atan, atand, atanh, broadcast!, conj!, cos, cosc, cosd, cosh, cospi, cot,
     cotd, coth, count, csc, cscd, csch, done,
-    exp10, exp2, findprev, findnext, floor, hash, indmin, inv,
+    exp10, exp2, findprev, findnext, floor, hash, argmin, inv,
     log10, log2, next, sec, secd, sech, show,
     sin, sinc, sind, sinh, sinpi, squeeze, start, sum, summary, tan,
     tand, tanh, trunc, abs, abs2,
     broadcast, ceil, complex, conj, convert, copy, copyto!, adjoint,
     exp, expm1, findall, findmax, findmin, float, getindex,
-    vcat, hcat, hvcat, cat, imag, indmax, kron, length, log, log1p, max, min,
+    vcat, hcat, hvcat, cat, imag, argmax, kron, length, log, log1p, max, min,
     maximum, minimum, one, promote_eltype, real, reshape, rot180,
     rotl90, rotr90, round, setindex!, similar, size, transpose,
     vec, permute!, map, map!, Array