Merge pull request #3693 from JuliaReach/schillic/hyperplane_revise

`Hyperplane`: revise docs entries, shorten docs, shorten signature, move `isdisjoint` method

docs/src/lib/sets/Hyperplane.md

@@ -8,38 +8,182 @@ CurrentModule = LazySets.HyperplaneModule
 Hyperplane
 ```
 
+## Conversion
+
+The following method requires the [`SymEngine`](https://github.com/symengine/SymEngine.jl) package.
+
+```@docs
+LazySets.convert(::Type{Hyperplane{N}}, ::Expr; vars::Vector{Basic}=Basic[]) where {N}
+```
+
 ## Operations
 
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+an_element(::LazySet)
+```
+```@meta
+CurrentModule = LazySets.HyperplaneModule
+```
 ```@docs
 an_element(::Hyperplane)
 constrained_dimensions(::Hyperplane)
-constraints_list(::Hyperplane)
-dim(::Hyperplane)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+isbounded(::LazySet)
+```
+```@meta
+CurrentModule = LazySets.HyperplaneModule
+```
+```@docs
 isbounded(::Hyperplane)
-isempty(::Hyperplane)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+isuniversal(::LazySet)
+```
+```@meta
+CurrentModule = LazySets.HyperplaneModule
+```
+```@docs
 isuniversal(::Hyperplane, ::Bool=false)
 normalize(::Hyperplane{N}, p::Real=N(2)) where {N}
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+rand(::Type{LazySet})
+```
+```@meta
+CurrentModule = LazySets.HyperplaneModule
+```
+```@docs
 rand(::Type{Hyperplane})
-distance(::AbstractVector, ::Hyperplane{N}) where {N}
+distance(::AbstractVector, ::Hyperplane)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+∈(::AbstractVector, ::LazySet)
+```
+```@meta
+CurrentModule = LazySets.HyperplaneModule
+```
+```@docs
 ∈(::AbstractVector, ::Hyperplane)
 project(::AbstractVector, ::Hyperplane)
 reflect(::AbstractVector, ::Hyperplane)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+ρ(::AbstractVector, ::LazySet)
+```
+```@meta
+CurrentModule = LazySets.HyperplaneModule
+```
+```@docs
 ρ(::AbstractVector, ::Hyperplane)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+σ(::AbstractVector, ::LazySet)
+```
+```@meta
+CurrentModule = LazySets.HyperplaneModule
+```
+```@docs
 σ(::AbstractVector, ::Hyperplane)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+translate(::LazySet, ::AbstractVector)
+```
+```@meta
+CurrentModule = LazySets.HyperplaneModule
+```
+```@docs
 translate(::Hyperplane, ::AbstractVector)
 ```
 
+```@meta
+CurrentModule = LazySets.API
+```
+
+Undocumented implementations:
+
+* [`constraints_list`](@ref constraints_list(::LazySet))
+* [`dim`](@ref dim(::LazySet))
+* [`isempty`](@ref isempty(::LazySet))
+* [`isoperationtype`](@ref isoperationtype(::Type{LazySet}))
+* [`project`](@ref project(::LazySet, ::AbstractVector{Int}))
+* [`isdisjoint`](@ref isdisjoint(::LazySet, ::LazySet))
+
 ```@meta
 CurrentModule = LazySets
 ```
 
 Inherited from [`LazySet`](@ref):
-* [`diameter`](@ref diameter(::LazySet, ::Real))
-* [`high`](@ref high(::LazySet))
-* [`low`](@ref low(::LazySet))
-* [`norm`](@ref norm(::LazySet, ::Real))
-* [`radius`](@ref radius(::LazySet, ::Real))
+* [`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))
+* [`isboundedtype`](@ref isboundedtype(::Type{LazySet}))
+* [`isoperation`](@ref isoperation(::LazySet))
+* [`norm`](@ref norm(::LazySet, ::Real=Inf))
+* [`radius`](@ref radius(::LazySet, ::Real=Inf))
+* [`rectify`](@ref rectify(::LazySet))
 * [`reflect`](@ref reflect(::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))
+* [`linear_map`](@ref linear_map(::AbstractMatrix, ::LazySet))
+* [`sample`](@ref sample(::LazySet, ::Int=1))
+* [`scale`](@ref scale(::Real, ::LazySet))
+* [`cartesian_product`](@ref cartesian_product(::LazySet, ::LazySet))
+* [`convex_hull`](@ref convex_hull(::LazySet, ::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):
-* [`linear_map`](@ref linear_map(::AbstractMatrix, ::AbstractPolyhedron))
+* [`extrema`](@ref extrema(::AbstractPolyhedron))
+* [`extrema`](@ref extrema(::AbstractPolyhedron, ::Int))
+* [`high`](@ref high(::AbstractPolyhedron))
+* [`high`](@ref high(::AbstractPolyhedron, ::Int))
+* [`isconvextype`](@ref isconvextype(::Type{AbstractPolyhedron}))
+* [`ispolyhedral`](@ref ispolyhedral(::AbstractPolyhedron))
+* [`low`](@ref low(::AbstractPolyhedron))
+* [`low`](@ref low(::AbstractPolyhedron, ::Int))
+* [`vertices_list`](@ref vertices_list(::AbstractPolyhedron))
+* [`intersection`](@ref intersection(::AbstractPolyhedron, ::AbstractPolyhedron))
+* [`⊆`](@ref ⊆(::LazySet, ::AbstractPolyhedron))
+* [`minkowski_sum`](@ref minkowski_sum(::AbstractPolyhedron, ::AbstractPolyhedron))

docs/src/lib/utils.md

@@ -64,7 +64,6 @@ LazySets._is_linear_combination
 LazySets._ishalfspace
 LazySets._ishyperplanar
 LazySets.convert(::Type{HalfSpace{N}}, ::Expr; vars::Vector{Basic}=Basic[]) where {N}
-LazySets.convert(::Type{Hyperplane{N}}, ::Expr; vars::Vector{Basic}=Basic[]) where {N}
 ```
 
 ## Functions for numbers
@@ -76,7 +75,6 @@ sign_cadlag
 ## Other functions
 
 ```@docs
-_an_element_helper_hyperplane
 binary_search_constraints
 get_constrained_lowdimset
 get_radius!

src/ConcreteOperations/isdisjoint.jl

@@ -491,35 +491,10 @@ for ST in [:AbstractPolyhedron]
     end
 end
 
-function isdisjoint(hp1::Hyperplane, hp2::Hyperplane, witness::Bool=false)
-    return _isdisjoint_hyperplane_hyperplane(hp1, hp2, witness)
-end
-
 @commutative function isdisjoint(hp::Hyperplane, L::Line2D, witness::Bool=false)
     return _isdisjoint_hyperplane_hyperplane(hp, L, witness)
 end
 
-function _isdisjoint_hyperplane_hyperplane(hp1::Union{Hyperplane,Line2D},
-                                           hp2::Union{Hyperplane,Line2D},
-                                           witness::Bool=false)
-    if isequivalent(hp1, hp2)
-        res = false
-        if witness
-            w = an_element(hp1)
-        end
-    else
-        cap = intersection(hp1, hp2)
-        res = cap isa EmptySet
-        if !res && witness
-            w = an_element(cap)
-        end
-    end
-    if res
-        return _witness_result_empty(witness, true, hp1, hp2)
-    end
-    return witness ? (false, w) : false
-end
-
 function _isdisjoint_halfspace(hs::HalfSpace, X::LazySet, witness::Bool=false)
     if !witness
         return !_leq(-ρ(-hs.a, X), hs.b)

src/LazySets.jl

@@ -148,6 +148,7 @@ include("Sets/Hyperplane/HyperplaneModule.jl")
 @reexport using ..HyperplaneModule: Hyperplane
 using ..HyperplaneModule: _an_element_helper_hyperplane,
                           _constraints_list_hyperplane,
+                          _isdisjoint_hyperplane_hyperplane,
                           _reflect_point_hyperplane,
                           _σ_hyperplane_halfspace
 

src/Sets/Hyperplane/HyperplaneModule.jl

@@ -14,9 +14,10 @@ using ReachabilityBase.Require: require
 
 @reexport import ..API: an_element, constraints_list, dim, isbounded, isempty,
                         isoperationtype, isuniversal, rand, reflect, distance,
-                        ∈, project, ρ, σ, translate
+                        ∈, project, ρ, σ, translate, isdisjoint
 @reexport import ..LazySets: constrained_dimensions, ishyperplanar, normalize
-import ..LazySets: _ishyperplanar, _linear_map_hrep_helper
+import ..LazySets: _ishyperplanar, _linear_map_hrep_helper,
+                   _witness_result_empty
 import ..Base: convert
 @reexport using ..API
 
@@ -40,6 +41,7 @@ include("project.jl")
 include("support_function.jl")
 include("support_vector.jl")
 include("translate.jl")
+include("isdisjoint.jl")
 
 include("constrained_dimensions.jl")
 include("ishyperplanar.jl")

src/Sets/Hyperplane/an_element.jl

@@ -1,44 +1,19 @@
 """
-    an_element(H::Hyperplane)
-
-Return some element of a hyperplane.
-
-### Input
+# Extended help
 
-- `H` -- hyperplane
+    an_element(H::Hyperplane)
 
-### Output
+### Algorithm
 
-An element on the hyperplane.
+We compute a point on the hyperplane ``a⋅x = b`` as follows:
+- We first find a nonzero entry of ``a`` in dimension, say, ``i``.
+- We set ``x[i] = b / a[i]``.
+- We set ``x[j] = 0`` for all ``j ≠ i``.
 """
 function an_element(H::Hyperplane)
     return _an_element_helper_hyperplane(H.a, H.b)
 end
 
-"""
-    _an_element_helper_hyperplane(a::AbstractVector{N}, b,
-                                  [nonzero_entry_a]::Int) where {N}
-
-Helper function that computes an element on a hyperplane ``a⋅x = b``.
-
-### Input
-
-- `a`               -- normal direction
-- `b`               -- constraint
-- `nonzero_entry_a` -- (optional, default: computes the first index) index `i`
-                       such that `a[i]` is different from 0
-
-### Output
-
-An element on a hyperplane.
-
-### Algorithm
-
-We compute the point on the hyperplane as follows:
-- We already found a nonzero entry of ``a`` in dimension, say, ``i``.
-- We set ``x[i] = b / a[i]``.
-- We set ``x[j] = 0`` for all ``j ≠ i``.
-"""
 @inline function _an_element_helper_hyperplane(a::AbstractVector{N}, b,
                                                nonzero_entry_a::Int=findfirst(!iszero, a)) where {N}
     x = zeros(N, length(a))

src/Sets/Hyperplane/constraints_list.jl

@@ -1,16 +1,3 @@
-"""
-    constraints_list(H::Hyperplane)
-
-Return the list of constraints of a hyperplane.
-
-### Input
-
-- `H` -- hyperplane
-
-### Output
-
-A list containing two half-spaces.
-"""
 function constraints_list(H::Hyperplane)
     return _constraints_list_hyperplane(H.a, H.b)
 end

src/Sets/Hyperplane/dim.jl

@@ -1,16 +1,3 @@
-"""
-    dim(H::Hyperplane)
-
-Return the dimension of a hyperplane.
-
-### Input
-
-- `H` -- hyperplane
-
-### Output
-
-The ambient dimension of the hyperplane.
-"""
 function dim(H::Hyperplane)
     return length(H.a)
 end

src/Sets/Hyperplane/distance.jl

@@ -1,5 +1,5 @@
 """
-    distance(x::AbstractVector, H::Hyperplane{N}) where {N}
+    distance(x::AbstractVector, H::Hyperplane)
 
 Compute the distance between point `x` and hyperplane `H` with respect to the
 Euclidean norm.
@@ -13,7 +13,8 @@ Euclidean norm.
 
 A scalar representing the distance between point `x` and hyperplane `H`.
 """
-@commutative function distance(x::AbstractVector, H::Hyperplane{N}) where {N}
+@commutative function distance(x::AbstractVector, H::Hyperplane)
+    N = promote_type(eltype(x), eltype(H))
     a, b = _normalize_halfspace(H, N(2))
     return abs(dot(x, a) - b)
 end

src/Sets/Hyperplane/in.jl

@@ -1,16 +1,7 @@
 """
-    ∈(x::AbstractVector, H::Hyperplane)
-
-Check whether a given point is contained in a hyperplane.
-
-### Input
+# Extended help
 
-- `x` -- point/vector
-- `H` -- hyperplane
-
-### Output
-
-`true` iff ``x ∈ H``.
+    ∈(x::AbstractVector, H::Hyperplane)
 
 ### Algorithm