Merge pull request #3703 from JuliaReach/schillic/vpolytope

`VPolytope`: revise docs entries, shorten docs, shorten signatures

docs/src/lib/concrete_binary_operations/intersection.md

@@ -17,7 +17,7 @@ intersection(::Interval, ::Hyperplane)
 intersection(::Interval, ::LazySet)
 intersection(::AbstractHPolygon, ::AbstractHPolygon)
 intersection(::AbstractPolyhedron{N}, ::AbstractPolyhedron{N}) where {N}
-intersection(::Union{VPolytope, VPolygon}, ::Union{VPolytope, VPolygon})
+intersection(::Union{VPolygon,VPolytope}, ::Union{VPolygon,VPolytope})
 intersection(::UnionSet, ::LazySet)
 intersection(::UnionSetArray, ::LazySet)
 intersection(::Universe, ::LazySet)

docs/src/lib/sets/Polygon.md

@@ -68,13 +68,11 @@ Inherited from [`LazySet`](@ref):
 * [`cartesian_product`](@ref cartesian_product(::LazySet, ::LazySet))
 * [`convex_hull`](@ref convex_hull(::LazySet, ::LazySet))
 * [`exact_sum`](@ref exact_sum(::LazySet, ::LazySet))
-* [`intersection`](@ref intersection(::LazySet, ::LazySet))
 * [`≈`](@ref ≈(::LazySet, ::LazySet))
 * [`isdisjoint`](@ref isdisjoint(::LazySet, ::LazySet))
 * [`==`](@ref ==(::LazySet, ::LazySet))
 * [`isequivalent`](@ref isequivalent(::LazySet, ::LazySet))
 * [`⊂`](@ref ⊂(::LazySet, ::LazySet))
 * [`⊆`](@ref ⊆(::LazySet, ::LazySet))
-* [`linear_combination`](@ref linear_combination(::LazySet, ::LazySet))
 * [`minkowski_difference`](@ref minkowski_difference(::LazySet, ::LazySet))
 * [`minkowski_sum`](@ref minkowski_sum(::LazySet, ::LazySet))

docs/src/lib/sets/VPolytope.md

@@ -16,44 +16,181 @@ convert(::Type{VPolytope}, ::LazySet)
 
 ## Operations
 
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+constraints_list(::LazySet)
+```
+```@meta
+CurrentModule = LazySets.VPolytopeModule
+```
 ```@docs
 constraints_list(::VPolytope)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+dim(::LazySet)
+```
+```@meta
+CurrentModule = LazySets.VPolytopeModule
+```
+```@docs
 dim(::VPolytope)
 polyhedron(::VPolytope)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+rand(::Type{LazySet})
+```
+```@meta
+CurrentModule = LazySets.VPolytopeModule
+```
+```@docs
 rand(::Type{VPolytope})
-remove_redundant_vertices(::VPolytope{N}) where {N}
-reflect(::VPolytope)
-tohrep(::VPolytope{N}) where {N}
+remove_redundant_vertices(::VPolytope)
+tohrep(::VPolytope)
 tovrep(::VPolytope)
-vertices_list(::VPolytope)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+linear_map(::AbstractMatrix, ::LazySet)
+```
+```@meta
+CurrentModule = LazySets.VPolytopeModule
+```
+```@docs
 linear_map(::AbstractMatrix, ::VPolytope)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+∈(::AbstractVector, ::LazySet)
+```
+```@meta
+CurrentModule = LazySets.VPolytopeModule
+```
+```@docs
 ∈(::AbstractVector{N}, ::VPolytope{N}) where {N}
-ρ(::AbstractVector, ::VPolytope)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+σ(::AbstractVector, ::LazySet)
+```
+```@meta
+CurrentModule = LazySets.VPolytopeModule
+```
+```@docs
 σ(::AbstractVector, ::VPolytope)
-translate(::VPolytope, ::AbstractVector)
-translate!(::VPolytope, ::AbstractVector)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+cartesian_product(::LazySet, ::LazySet)
+```
+```@meta
+CurrentModule = LazySets.VPolytopeModule
+```
+```@docs
 cartesian_product(::VPolytope, ::VPolytope)
 convex_hull(::VPolytope, ::VPolytope)
+```
+```@meta
+CurrentModule = LazySets
+```
+```@docs; canonical=false
+intersection(::Union{VPolygon,VPolytope}, ::Union{VPolygon,VPolytope})
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+minkowski_sum(::LazySet, ::LazySet)
+```
+```@meta
+CurrentModule = LazySets.VPolytopeModule
+```
+```@docs
 minkowski_sum(::VPolytope, ::VPolytope)
 ```
 
 ```@meta
-CurrentModule = LazySets
+CurrentModule = LazySets.API
 ```
 
-Inherited from [`LazySet`](@ref):
-* [`diameter`](@ref diameter(::LazySet, ::Real))
+Undocumented implementations:
+* [`extrema`](@ref extrema(::LazySet))
+* [`extrema`](@ref extrema(::LazySet, ::Int))
 * [`high`](@ref high(::LazySet))
+* [`high`](@ref high(::LazySet, ::Int))
+* [`isoperationtype`](@ref isoperationtype(::Type{LazySet}))
 * [`low`](@ref low(::LazySet))
-* [`norm`](@ref norm(::LazySet, ::Real))
-* [`radius`](@ref radius(::LazySet, ::Real))
+* [`low`](@ref low(::LazySet, ::Int))
+* [`vertices_list`](@ref vertices_list(::LazySet))
+* [`permute`](@ref permute(::LazySet, ::AbstractVector{Int}))
+* [`project`](@ref project(::LazySet, ::AbstractVector{Int}))
+* [`reflect`](@ref reflect(::LazySet))
+* [`scale!`](@ref scale!(::Real, ::LazySet))
+* [`ρ`](@ref ρ(::AbstractVector, ::LazySet))
+* [`translate`](@ref translate(::LazySet, ::AbstractVector))
+* [`translate!`](@ref translate!(::LazySet, ::AbstractVector))
+
+```@meta
+CurrentModule = LazySets
+```
+
+Inherited from [`LazySet`](@ref):
+* [`area`](@ref area(::LazySet))
+* [`complement`](@ref complement(::LazySet))
+* [`concretize`](@ref concretize(::LazySet))
+* [`constraints`](@ref constraints(::LazySet))
+* [`convex_hull`](@ref convex_hull(::LazySet))
+* `copy(::Type{LazySet})`
+* [`diameter`](@ref diameter(::LazySet, ::Real=Inf))
+* [`eltype`](@ref eltype(::Type{<:LazySet}))
+* [`eltype`](@ref eltype(::LazySet))
+* [`isoperation`](@ref isoperation(::LazySet))
+* [`norm`](@ref norm(::LazySet, ::Real=Inf))
+* [`radius`](@ref radius(::LazySet, ::Real=Inf))
+* [`rectify`](@ref rectify(::LazySet))
 * [`singleton_list`](@ref singleton_list(::LazySet))
+* [`surface`](@ref surface(::LazySet))
+* [`vertices`](@ref vertices(::LazySet))
+* [`affine_map`](@ref affine_map(::AbstractMatrix, ::LazySet, ::AbstractVector))
+* [`exponential_map`](@ref exponential_map(::AbstractMatrix, ::LazySet))
+* [`is_interior_point`](@ref is_interior_point(::AbstractVector, ::LazySet))
+* [`sample`](@ref sample(::LazySet, ::Int=1))
+* [`scale`](@ref scale(::Real, ::LazySet))
+* [`exact_sum`](@ref exact_sum(::LazySet, ::LazySet))
+* [`≈`](@ref ≈(::LazySet, ::LazySet))
+* [`==`](@ref ==(::LazySet, ::LazySet))
+* [`isequivalent`](@ref isequivalent(::LazySet, ::LazySet))
+* [`⊂`](@ref ⊂(::LazySet, ::LazySet))
+* [`minkowski_difference`](@ref minkowski_difference(::LazySet, ::LazySet))
+
+Inherited from [`ConvexSet`](@ref):
+* [`linear_combination`](@ref linear_combination(::ConvexSet, ::ConvexSet))
 
 Inherited from [`AbstractPolyhedron`](@ref):
 * [`an_element`](@ref an_element(::AbstractPolyhedron))
+* [`ispolyhedral`](@ref ispolyhedral(::AbstractPolyhedron))
+* [`isdisjoint`](@ref isdisjoint(::AbstractPolyhedron, ::AbstractPolyhedron))
 
 Inherited from [`AbstractPolytope`](@ref):
 * [`isbounded`](@ref isbounded(::AbstractPolytope))
+* [`isboundedtype`](@ref isboundedtype(::Type{AbstractPolytope}))
+* [`isconvextype`](@ref isconvextype(::Type{AbstractPolytope}))
 * [`isempty`](@ref isempty(::AbstractPolytope))
 * [`isuniversal`](@ref isuniversal(::AbstractPolytope, ::Bool=false))
 * [`volume`](@ref volume(::AbstractPolytope))
+* [`⊆`](@ref ⊆(::AbstractPolytope, ::AbstractPolyhedron))

src/Sets/VPolytope/cartesian_product.jl

@@ -1,18 +1,12 @@
 """
-    cartesian_product(P1::VPolytope, P2::VPolytope; [backend]=nothing)
+# Extended help
 
-Compute the Cartesian product of two polytopes in vertex representation.
+    cartesian_product(P1::VPolytope, P2::VPolytope; [backend]=nothing)
 
 ### Input
 
-- `P1`      -- polytope in vertex representation
-- `P2`      -- polytope in vertex representation
 - `backend` -- (optional, default: `nothing`) backend for polyhedral computation
 
-### Output
-
-The `VPolytope` obtained by the concrete Cartesian product of `P1` and `P2`.
-
 ### Notes
 
 For further information on the supported backends see

src/Sets/VPolytope/constraints_list.jl

@@ -1,19 +1,12 @@
 """
     constraints_list(P::VPolytope)
 
-Return a list of constraints defining a polytope in vertex representation.
-
-### Input
-
-- `P` -- polytope in vertex representation
-
-### Output
-
-A list of constraints of the polytope.
-
 ### Algorithm
 
-We use `tohrep` to compute the constraint representation of `P`.
+For one- and two-dimensional sets, we respectively convert to an `Interval` or a
+`VPolytope` and call the corresponding `constraints_list` function.
+For higher-dimensional sets, we use `tohrep` to compute the constraint
+representation and call the corresponding `constraints_list` function.
 """
 function constraints_list(P::VPolytope)
     require(@__MODULE__, :LazySets; fun_name="constraints_list")

src/Sets/VPolytope/dim.jl

@@ -1,37 +1,9 @@
 """
     dim(P::VPolytope)
 
-Return the dimension of a polytope in vertex representation.
-
-### Input
-
-- `P` -- polytope in vertex representation
-
 ### Output
 
-The ambient dimension of the polytope in vertex representation.
 If `P` is empty, the result is ``-1``.
-
-### Examples
-
-```jldoctest
-julia> P = VPolytope();
-
-julia> isempty(P.vertices)
-true
-
-julia> dim(P)
--1
-
-julia> P = VPolytope([ones(3)]);
-
-julia> P.vertices
-1-element Vector{Vector{Float64}}:
- [1.0, 1.0, 1.0]
-
-julia> dim(P) == 3
-true
-```
 """
 function dim(P::VPolytope)
     return isempty(P.vertices) ? -1 : @inbounds length(P.vertices[1])

src/Sets/VPolytope/in.jl

@@ -1,20 +1,14 @@
 """
+# Extended help
+
     ∈(x::AbstractVector{N}, P::VPolytope{N};
       solver=default_lp_solver(N)) where {N}
 
-Check whether a given point is contained in a polytope in vertex representation.
-
 ### Input
 
-- `x`      -- point/vector
-- `P`      -- polytope in vertex representation
 - `solver` -- (optional, default: `default_lp_solver(N)`) the backend used to
               solve the linear program
 
-### Output
-
-`true` iff ``x ∈ P``.
-
 ### Algorithm
 
 We check, using linear programming, the definition of a convex polytope that a

src/Sets/VPolytope/linear_map.jl

@@ -1,19 +1,13 @@
 """
-    linear_map(M::AbstractMatrix, P::VPolytope; [apply_convex_hull]::Bool=false)
+# Extended help
 
-Concrete linear map of a polytope in vertex representation.
+    linear_map(M::AbstractMatrix, P::VPolytope; [apply_convex_hull]::Bool=false)
 
 ### Input
 
-- `M` -- matrix
-- `P` -- polytope in vertex representation
 - `apply_convex_hull` -- (optional, default: `false`) flag for applying a convex
                          hull to eliminate redundant vertices
 
-### Output
-
-A polytope in vertex representation.
-
 ### Algorithm
 
 The linear map ``M`` is applied to each vertex of the given set ``P``, obtaining

src/Sets/VPolytope/minkowski_sum.jl

@@ -1,15 +1,13 @@
 """
+# Extended help
+
     minkowski_sum(P1::VPolytope, P2::VPolytope;
                   [apply_convex_hull]=true,
                   [backend]=nothing,
                   [solver]=nothing)
 
-Compute the Minkowski sum of two polytopes in vertex representation.
-
 ### Input
 
-- `P1`                -- polytope
-- `P2`                -- polytope
 - `apply_convex_hull` -- (optional, default: `true`) if `true`, post-process the
                          pairwise sums using a convex-hull algorithm
 - `backend`           -- (optional, default: `nothing`) the backend for
@@ -19,10 +17,11 @@ Compute the Minkowski sum of two polytopes in vertex representation.
                          solve the linear program; see
                          `default_lp_solver_polyhedra(N)`
 
-### Output
+### Algorithm
 
-A new polytope in vertex representation whose vertices are the convex hull of
-the sum of all possible sums of vertices of `P1` and `P2`.
+The resulting polytope in vertex representation consists of the vertices
+corresponding to the convex hull of the sum of all possible sums of vertices of
+`P1` and `P2`.
 """
 function minkowski_sum(P1::VPolytope, P2::VPolytope;
                        apply_convex_hull::Bool=true, backend=nothing,