minimum(p) returns the minimal coefficient of p but minimum(p, itr) returns when p is applied onto itr

[singularitti]

This is a derivative of what we talked about in #454. However, when I just apply minimum to a polynomial, it returns some weird result:

julia> p = Polynomial([2, 6, 1])
Polynomial(2 + 6*x + x^2)

julia> findmin(p)
(-7.0, -3.0)

julia> minimum(p)
1

julia> minimum(p, -10:10)
-7

julia> minimum(p, Tuple(-10:10))
-7

Clearly, the minimum value of p returns the minimal coefficient in p, which is 1; but minimum(p, -10:10) returns the minimum of p.(-10:10), which is the lowest point on the graph: -7.
These definitions conflict with each other.

[singularitti]

Although, minimum(f, itr) "returns the smallest result of calling function f on each element of itr". So it is actually true. But minimum(p) "returns the smallest element in a collection", i.e., the coefficient, is a little bit unmatched. I guess this is because we treat a polynomial as an iterable.

[jverzani]

Yes, with the newer PR we would have:

cps = Polynomials.critical_points(p) # over the domain of p, includes endpoints
minimum(p, cps) == first(findmin(p, cps)) 
argmin(p, cps) == cps[last(findmin(p, cps))]
minimum(p) == minimum(coeffs(p))

[singularitti]

I have thought about the API, I will list the one that looks idiomatic to me:

minimum(p, list_of_points)
maximum(p, list_of_points)

returns the smallest/largest result of calling polynomial p on each element of list_of_points, which is the current implementation, good!

The only one thing I am not sure is that

minimum(p)
maximum(p)

returns the minimum coefficients and maximum coefficients of p. It does coincide with the definition in Base where minimum/maximum return the smallest/largest element in the collection p. To me, it is a little bit counterintuitive, so we probably need to warn the users in doc.

findmin(p, domain) -> (p(x), x)
findmax(p, domain) -> (p(x), x)

returns a pair of a value in the codomain (outputs of p) and the x in the domain (inputs to p) such that p(x) is minimised. If there are multiple minimal points, then the first one will be returned.

That is, findmin returns the minimum on the domain. The difference between this and minimum is that in minimum, we compute p on a finite number of points and find their minimum, this minimum may or may not be the local minimum on the range between two endpoints of the range. However, findmin only takes the maximum and minimum of the domain, regardless of the type of the domain. That is, once a domain is given, findmin will always return the local minima in the whole range.

argmin(p, domain)
argmax(p, domain)

Similar to findmin/findmax, return a value x in the domain of p for which p(x) is minimised.

extrema(p, list_of_points)

returns the results of (minimum(p, list_of_points), maximum(p, list_of_points)). extrema should be defined regardless of the findmin and findmax.

[jverzani]

The current PR has the following docstring:

"""
critical_points(p::AbstractPolynomial{<:Real}, I=domain(p); endpoints::Bool=true)

Return the critical points of p (real zeros of the derivative) within I in sorted order.

• p: a polynomial

• I: a specification of a closed or infinite domain, defaulting to Polynomials.domain(p). When specified, the values of extrema(I) are used with closed endpoints when finite.

• endpoints::Bool: if true, return the endpoints of I along with the critical points

Can be used in conjuction with findmax, findmin, argmax, argmin, extrema, etc.

Example

x = variable()
p = x^2 - 2
cps = Polynomials.critical_points(p)
findmin(p, cps)  # (-2.0, 2.0)
argmin(p, cps)   #  0.0
extrema(p, cps)  # (-2.0, Inf)
cps = Polynomials.critical_points(p, (0, 2))
extrema(p, cps)  # (-2.0, 2.0)

"""

If you want to suggest edits that would be great. It might be worth commenting how maximum(p) and maximum(p, critical_points(p)) will return different things, the latter in agreement with findmax(p, critical_points(p)) and the former in agreement with maximum(coeffs(p))

[ParadaCarleton]

I feel like someone calling minimum(p) will very rarely, if ever, be looking for the smallest coefficient. It's much more likely they'll be looking for the global minimum, and may think that's what they're getting.

[singularitti]

It's much more likely they'll be looking for the global minimum, and may think that's what they're getting.

Agree. That is what I was thinking.

[jverzani]

A math person might, but a julia person would expect, I believe, that minimum(p) treats p like a vector, unlike minimum(f, itr) which has a function in that first position. Since Polynomial (and other types) are basically just wrappers around a vector, the view that minimum(p) treats p like a vector seems appropriate. We may need some documentation here...