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

stdlib/SparseArrays/src/sparsematrix.jl

@@ -1761,7 +1761,7 @@ function _mapreducecols!(f, op::typeof(+), R::AbstractArray, A::SparseMatrixCSC{
     R
 end
 
-# findmax/min and indmax/min methods
+# findmax/min and argmax/min methods
 # find first zero value in sparse matrix - return linear index in full matrix
 # non-structural zeros are identified by x == 0 in line with the sparse constructors.
 function _findz(A::SparseMatrixCSC{Tv,Ti}, rows=1:A.m, cols=1:A.n) where {Tv,Ti}
@@ -1868,8 +1868,8 @@ findmax(A::SparseMatrixCSC{Tv,Ti}, region) where {Tv,Ti} = _findr(_isgreater_fm,
 findmin(A::SparseMatrixCSC) = (r=findmin(A,(1,2)); (r[1][1], r[2][1]))
 findmax(A::SparseMatrixCSC) = (r=findmax(A,(1,2)); (r[1][1], r[2][1]))
 
-indmin(A::SparseMatrixCSC) = findmin(A)[2]
-indmax(A::SparseMatrixCSC) = findmax(A)[2]
+argmin(A::SparseMatrixCSC) = findmin(A)[2]
+argmax(A::SparseMatrixCSC) = findmax(A)[2]
 
 ## getindex
 function rangesearch(haystack::AbstractRange, needle)

stdlib/SparseArrays/test/sparse.jl

@@ -1023,11 +1023,11 @@ end
     @test_throws ArgumentError sparse([3], [5], 1.0, 3, 3)
 end
 
-@testset "indmax, indmin, findmax, findmin" begin
+@testset "argmax, argmin, findmax, findmin" begin
     S = sprand(100,80, 0.5)
     A = Array(S)
-    @test indmax(S) == indmax(A)
-    @test indmin(S) == indmin(A)
+    @test argmax(S) == argmax(A)
+    @test argmin(S) == argmin(A)
     @test findmin(S) == findmin(A)
     @test findmax(S) == findmax(A)
     for region in [(1,), (2,), (1,2)], m in [findmax, findmin]
@@ -1036,16 +1036,16 @@ end
 
     S = spzeros(10,8)
     A = Array(S)
-    @test indmax(S) == indmax(A) == CartesianIndex(1,1)
-    @test indmin(S) == indmin(A) == CartesianIndex(1,1)
+    @test argmax(S) == argmax(A) == CartesianIndex(1,1)
+    @test argmin(S) == argmin(A) == CartesianIndex(1,1)
 
     A = Matrix{Int}(I, 0, 0)
     S = sparse(A)
-    iA = try indmax(A) end
-    iS = try indmax(S) end
+    iA = try argmax(A) end
+    iS = try argmax(S) end
     @test iA === iS === nothing
-    iA = try indmin(A) end
-    iS = try indmin(S) end
+    iA = try argmin(A) end
+    iS = try argmin(S) end
     @test iA === iS === nothing
 end
 

test/arrayops.jl

@@ -505,9 +505,9 @@ end
     @test findlast(equalto(2), g3) === nothing
 end
 
-@testset "findmin findmax indmin indmax" begin
-    @test indmax([10,12,9,11]) == 2
-    @test indmin([10,12,9,11]) == 3
+@testset "findmin findmax argmin argmax" begin
+    @test argmax([10,12,9,11]) == 2
+    @test argmin([10,12,9,11]) == 3
     @test findmin([NaN,3.2,1.8]) === (NaN,1)
     @test findmax([NaN,3.2,1.8]) === (NaN,1)
     @test findmin([NaN,3.2,1.8,NaN]) === (NaN,1)
@@ -517,13 +517,13 @@ end
 
     #14085
     @test findmax(4:9) == (9,6)
-    @test indmax(4:9) == 6
+    @test argmax(4:9) == 6
     @test findmin(4:9) == (4,1)
-    @test indmin(4:9) == 1
+    @test argmin(4:9) == 1
     @test findmax(5:-2:1) == (5,1)
-    @test indmax(5:-2:1) == 1
+    @test argmax(5:-2:1) == 1
     @test findmin(5:-2:1) == (1,3)
-    @test indmin(5:-2:1) == 3
+    @test argmin(5:-2:1) == 3
 
     #23094
     @test_throws MethodError findmax(Set(["abc"]))

test/euler.jl

@@ -227,7 +227,7 @@ function euler14(m)
             d -= 1
         end
     end
-    indmax(c)
+    argmax(c)
 end
 @test euler14(999999) == 837799
 

test/perf/perfcomp.jl

@@ -35,8 +35,8 @@ function main()
     end
     println()
 
-    minname = names[indmin(change)]
-    maxname = names[indmax(change)]
+    minname = names[argmin(change)]
+    maxname = names[argmax(change)]
 
     minstd = baseline[minname][4]/baseline[minname][3]
     maxstd = baseline[maxname][4]/baseline[maxname][3]