More documentation for singleton set membership

[mforets]

See #1281, this PR adds a better error message and a comment in the convex hull docs.

[schillic]

I would say that this is not specific to VPolygon, but I do not know where to put it instead.

[mforets]

Just checked building the docs locally and it doesn't behave as i expected: the error message is not displayed in the generated docs (although it is shown in the docs build). I'll not run the command in the example block.

[schillic]

Maybe use a jldoctest block instead of an example block?

[kmundnic]

@mforets the comments you're proposing for the docs look good to me! I would include a section or comment for explicitly stating that you can check whether a point is in a convex hull. If you Google for this in Julia, there's mostly a very old comment (circa 2015) using JuMP, since you can pose the problem as a LP. However, in many cases (and in lower dimensions), this solution seems cleaner to me than posing the problem as a feasibility problem using an optimization package (JuMP, Convex.jl).

[mforets]

Ok, i see your use case. Indeed, in 2D it's much more efficient to exploit that the points in the plane can be ordered (cf. the implementation in this function, in particular it doesn't allocate, see below).

The feasibility test is still good in higher dims and is the fallback implementation for a general VPolytope (cf. this function).

We can compare both:

julia> points = N -> [randn(2) for i in 1:N];
julia> p = points(100);
julia> hull = convex_hull(p);
julia> V_polygon = VPolygon(hull, apply_convex_hull=false);
julia> V_polytope = convert(VPolytope, V_polygon);
julia> x = sum(hull)/length(hull);

julia> @btime x ∈ $V_polygon
  47.688 ns (0 allocations: 0 bytes)
true

julia> @btime $x ∈ $V_polytope
  33.998 μs (106 allocations: 7.56 KiB)
true