Merge pull request #3684 from JuliaReach/schillic/zonotope

`Zonotope`: revise docs entries, shorten docs, shorten signature

docs/src/lib/sets/Zonotope.md

@@ -10,50 +10,146 @@ Zonotope
 
 ## Conversion
 
-```@docs
+```julia
 convert(::Type{Zonotope}, ::AbstractZonotope)
 ```
 
 ## Operations
 
 ```@docs
-center(::Zonotope)
 generators(::Zonotope)
 genmat(::Zonotope)
-high(::Zonotope, ::Int)
-low(::Zonotope, ::Int)
-ngens(::Zonotope)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+rand(::Type{LazySet})
+```
+```@meta
+CurrentModule = LazySets.ZonotopeModule
+```
+```@docs
 rand(::Type{Zonotope})
-remove_redundant_generators(Z::Zonotope{N}) where {N}
+```
+```@meta
+CurrentModule = LazySets
+```
+```@docs; canonical=false
+remove_redundant_generators(::AbstractZonotope)
+```
+```@meta
+CurrentModule = LazySets.ZonotopeModule
+```
+```@docs
+remove_redundant_generators(::Zonotope)
 remove_zero_generators(::Zonotope)
-togrep(::Zonotope)
 linear_map!(::Zonotope, ::AbstractMatrix, ::Zonotope)
-scale!(::Real, Z::Zonotope)
-translate!(::Zonotope, ::AbstractVector)
+```
+```@meta
+CurrentModule = LazySets.API
+```
+```@docs; canonical=false
+scale!(::Real, ::LazySet)
+```
+```@meta
+CurrentModule = LazySets.ZonotopeModule
+```
+```@docs
+scale!(::Real, ::Zonotope)
+```
+
+```@meta
+CurrentModule = LazySets.API
 ```
 
+Undocumented implementations:
+
+* [`center`](@ref center(::LazySet))
+* [`high`](@ref high(::LazySet, ::Int))
+* [`low`](@ref low(::LazySet, ::Int))
+```@meta
+CurrentModule = LazySets
+```
+* [`ngens`](@ref ngens(::AbstractZonotope))
+```@meta
+CurrentModule = LazySets.API
+```
+* [`isoperationtype`](@ref isoperationtype(::Type{LazySet}))
+```@meta
+CurrentModule = LazySets
+```
+* [`togrep`](@ref togrep(::AbstractZonotope))
+```@meta
+CurrentModule = LazySets.API
+```
+* [`permute`](@ref permute(::LazySet, ::AbstractVector))
+```@meta
+CurrentModule = LazySets
+```
+* [`reduce_order`](@ref reduce_order(::AbstractZonotope, ::Real, ::AbstractReductionMethod=GIR05()))
+* [`split`](@ref split(::AbstractZonotope, ::Int))
+* [`split`](@ref split(::AbstractZonotope, ::AbstractVector{Int}, ::AbstractVector{Int}))
+```@meta
+CurrentModule = LazySets.API
+```
+* [`translate!`](@ref translate!(::LazySet, ::AbstractVector))
+
 ```@meta
 CurrentModule = LazySets
 ```
 
 Inherited from [`LazySet`](@ref):
+* [`area`](@ref area(::LazySet))
+* [`concretize`](@ref concretize(::LazySet))
+* [`convex_hull`](@ref convex_hull(::LazySet))
+* `copy(::Type{LazySet})`
 * [`diameter`](@ref diameter(::LazySet, ::Real))
-* [`high`](@ref high(::LazySet))
-* [`low`](@ref low(::LazySet))
+* [`eltype`](@ref eltype(::Type{<:LazySet}))
+* [`eltype`](@ref eltype(::LazySet))
+* [`isoperation`](@ref isoperation(::LazySet))
 * [`norm`](@ref norm(::LazySet, ::Real))
 * [`radius`](@ref radius(::LazySet, ::Real))
+* [`rectify`](@ref rectify(::LazySet))
+* [`sample`](@ref sample(::LazySet, ::Int=1))
 * [`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))
+* [`scale`](@ref scale(::Real, ::LazySet))
 * [`translate`](@ref translate(::LazySet, ::AbstractVector))
+* [`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))
+
+Inherited from [`ConvexSet`](@ref):
+* [`linear_combination`](@ref linear_combination(::ConvexSet, ::ConvexSet))
+
+Inherited from [`AbstractPolyhedron`](@ref):
+* [`high`](@ref high(::AbstractPolyhedron))
+* [`ispolyhedral`](@ref ispolyhedral(::AbstractPolyhedron))
+* [`low`](@ref low(::AbstractPolyhedron))
+* [`intersection`](@ref intersection(::AbstractPolyhedron, ::LazySet))
 
 Inherited from [`AbstractPolytope`](@ref):
 * [`isbounded`](@ref isbounded(::AbstractPolytope))
-* [`isuniversal`](@ref isuniversal(::AbstractPolytope, ::Bool=false))
 * [`volume`](@ref volume(::AbstractPolytope))
+* [`isboundedtype`](@ref isboundedtype(::Type{AbstractPolytope}))
+* [`isconvextype`](@ref isconvextype(::Type{AbstractPolytope}))
 
 Inherited from [`AbstractCentrallySymmetricPolytope`](@ref):
 * [`an_element`](@ref an_element(::AbstractCentrallySymmetricPolytope))
+* [`center`](@ref center(::AbstractCentrallySymmetric, ::Int))
 * [`dim`](@ref dim(::AbstractCentrallySymmetricPolytope))
+* [`extrema`](@ref extrema(::AbstractCentrallySymmetricPolytope))
+* [`extrema`](@ref extrema(::AbstractCentrallySymmetricPolytope, ::Int))
 * [`isempty`](@ref isempty(::AbstractCentrallySymmetricPolytope))
+* [`isuniversal`](@ref isuniversal(::AbstractCentrallySymmetricPolytope))
 
 Inherited from [`AbstractZonotope`](@ref):
 * [`constraints_list`](@ref constraints_list(::AbstractZonotope))
@@ -63,8 +159,11 @@ Inherited from [`AbstractZonotope`](@ref):
 * [`vertices_list`](@ref vertices_list(::AbstractZonotope))
 * [`∈`](@ref ∈(::AbstractVector, ::AbstractZonotope))
 * [`linear_map`](@ref linear_map(::AbstractMatrix, ::AbstractZonotope))
-* [`reduce_order`](@ref reduce_order(::AbstractZonotope, ::Real, ::AbstractReductionMethod=GIR05()))
-* [`split`](@ref split(::AbstractZonotope, ::Int))
-* [`split`](@ref split(::AbstractZonotope, ::AbstractVector{Int}, ::AbstractVector{Int}))
+* [`project`](@ref project(::AbstractZonotope, ::AbstractVector))
 * [`ρ`](@ref ρ(::AbstractVector, ::AbstractZonotope))
 * [`σ`](@ref σ(::AbstractVector, ::AbstractZonotope))
+* [`cartesian_product`](@ref cartesian_product(::AbstractZonotope, ::AbstractZonotope))
+* [`isdisjoint`](@ref isdisjoint(::AbstractZonotope, ::AbstractZonotope))
+* [`⊆`](@ref ⊆(::AbstractZonotope, ::AbstractZonotope))
+* [`minkowski_difference`](@ref minkowski_difference(::AbstractZonotope, ::AbstractZonotope))
+* [`minkowski_sum`](@ref minkowski_sum(::AbstractZonotope, ::AbstractZonotope))

src/Sets/Zonotope/center.jl

@@ -1,16 +1,3 @@
-"""
-    center(Z::Zonotope)
-
-Return the center of a zonotope.
-
-### Input
-
-- `Z` -- zonotope
-
-### Output
-
-The center of the zonotope.
-"""
 function center(Z::Zonotope)
     return Z.center
 end

src/Sets/Zonotope/convert.jl

@@ -1,17 +1,3 @@
-"""
-    convert(::Type{Zonotope}, Z::AbstractZonotope)
-
-Convert a zonotopic set to a zonotope.
-
-### Input
-
-- `Zonotope` -- target type
-- `H`        -- zonotopic set
-
-### Output
-
-A zonotope.
-"""
 function convert(::Type{Zonotope}, Z::AbstractZonotope)
     return Zonotope(center(Z), genmat(Z))
 end

src/Sets/Zonotope/high.jl

@@ -1,17 +1,3 @@
-"""
-    high(Z::Zonotope, i::Int)
-
-Return the higher coordinate of a zonotope in a given dimension.
-
-### Input
-
-- `Z` -- zonotope
-- `i` -- dimension of interest
-
-### Output
-
-The higher coordinate of the zonotope in the given dimension.
-"""
 function high(Z::Zonotope, i::Int)
     G = genmat(Z)
     v = center(Z, i)

src/Sets/Zonotope/low.jl

@@ -1,17 +1,3 @@
-"""
-    low(Z::Zonotope, i::Int)
-
-Return the lower coordinate of a zonotope in a given dimension.
-
-### Input
-
-- `Z` -- zonotope
-- `i` -- dimension of interest
-
-### Output
-
-The lower coordinate of the zonotope in the given dimension.
-"""
 function low(Z::Zonotope, i::Int)
     G = genmat(Z)
     v = center(Z, i)

src/Sets/Zonotope/ngens.jl

@@ -1,14 +1 @@
-"""
-    ngens(Z::Zonotope)
-
-Return the number of generators of a zonotope.
-
-### Input
-
-- `Z` -- zonotope
-
-### Output
-
-An integer representing the number of generators.
-"""
 ngens(Z::Zonotope) = size(Z.generators, 2)

src/Sets/Zonotope/rand.jl

@@ -1,23 +1,9 @@
 """
+# Extended help
+
     rand(::Type{Zonotope}; [N]::Type{<:Real}=Float64, [dim]::Int=2,
          [rng]::AbstractRNG=GLOBAL_RNG, [seed]::Union{Int, Nothing}=nothing)
 
-Create a random zonotope.
-
-### Input
-
-- `Zonotope`       -- type for dispatch
-- `N`              -- (optional, default: `Float64`) numeric type
-- `dim`            -- (optional, default: 2) dimension
-- `rng`            -- (optional, default: `GLOBAL_RNG`) random number generator
-- `seed`           -- (optional, default: `nothing`) seed for reseeding
-- `num_generators` -- (optional, default: `-1`) number of generators of the
-                      zonotope (see the comment below)
-
-### Output
-
-A random zonotope.
-
 ### Algorithm
 
 All numbers are normally distributed with mean 0 and standard deviation 1.

src/Sets/Zonotope/remove_redundant_generators.jl

@@ -1,16 +1,7 @@
 """
-    remove_redundant_generators(Z::Zonotope{N}) where {N}
+# Extended help
 
-Remove all redundant (pairwise linearly dependent) generators of a zonotope.
-
-### Input
-
-- `Z` -- zonotope
-
-### Output
-
-A new zonotope with fewer generators, or the same zonotope if no generator could
-be removed.
+    remove_redundant_generators(Z::Zonotope)
 
 ### Algorithm
 
@@ -21,11 +12,12 @@ Then we combine those generators into a single generator.
 For one-dimensional zonotopes we use a more efficient implementation where we
 just take the absolute sum of all generators.
 """
-function remove_redundant_generators(Z::Zonotope{N}) where {N}
+function remove_redundant_generators(Z::Zonotope)
     if dim(Z) == 1  # more efficient implementation in 1D
         return _remove_redundant_generators_1d(Z)
     end
 
+    N = eltype(Z)
     G = genmat(Z)
     G = remove_zero_columns(G)
     p = size(G, 2)

src/Sets/Zonotope/scale.jl

@@ -1,17 +1,12 @@
 """
-    scale!(α::Real, Z::Zonotope)
-
-Concrete scaling of a zonotope modifying `Z` in-place.
+# Extended help
 
-### Input
-
-- `α` -- scalar
-- `Z` -- zonotope
+    scale!(α::Real, Z::Zonotope)
 
-### Output
+### Algorithm
 
-The zonotope obtained by applying the numerical scale to the center and
-generators of ``Z``.
+The result is obtained by applying the numerical scale to the center and
+generators.
 """
 function scale!(α::Real, Z::Zonotope)
     Z.center .*= α

src/Sets/Zonotope/togrep.jl

@@ -1,16 +1,3 @@
-"""
-    togrep(Z::Zonotope)
-
-Return a generator representation of a zonotope.
-
-### Input
-
-- `Z` -- zonotope
-
-### Output
-
-The same set `Z`.
-"""
 function togrep(Z::Zonotope)
     return Z
 end

src/Sets/Zonotope/translate.jl

@@ -1,26 +1,3 @@
-"""
-    translate!(Z::Zonotope, v::AbstractVector)
-
-Translate (i.e., shift) a zonotope by a given vector in-place.
-
-### Input
-
-- `Z` -- zonotope
-- `v` -- translation vector
-
-### Output
-
-A translated zonotope.
-
-### Notes
-
-See also [`LazySets.API.translate(Z::LazySet, v::AbstractVector)`](@ref) for the
-out-of-place version.
-
-### Algorithm
-
-We add the translation vector to the center of the zonotope.
-"""
 function translate!(Z::Zonotope, v::AbstractVector)
     @assert length(v) == dim(Z) "cannot translate a $(dim(Z))-dimensional " *
                                 "set by a $(length(v))-dimensional vector"