From 62639c8e134fcdd45913f81164f04e5db28fd1a5 Mon Sep 17 00:00:00 2001 From: schillic Date: Sun, 22 Dec 2024 10:59:54 +0100 Subject: [PATCH] HParallelotope: revise docs entries, shorten docs, shorten signature --- docs/src/lib/sets/HParallelotope.md | 129 ++++++++++++++++++-- src/Sets/HParallelotope/center.jl | 12 +- src/Sets/HParallelotope/constraints_list.jl | 15 +-- src/Sets/HParallelotope/convert.jl | 5 +- src/Sets/HParallelotope/dim.jl | 13 -- src/Sets/HParallelotope/generators.jl | 14 --- src/Sets/HParallelotope/genmat.jl | 12 +- src/Sets/HParallelotope/rand.jl | 20 +-- src/Sets/HParallelotope/volume.jl | 12 +- 9 files changed, 130 insertions(+), 102 deletions(-) diff --git a/docs/src/lib/sets/HParallelotope.md b/docs/src/lib/sets/HParallelotope.md index bcf8e86a4d..fdd5f8c35d 100644 --- a/docs/src/lib/sets/HParallelotope.md +++ b/docs/src/lib/sets/HParallelotope.md @@ -11,54 +11,159 @@ HParallelotope ## Conversion ```@docs -convert(::Type{HParallelotope}, Z::AbstractZonotope{N}) where {N} +convert(::Type{HParallelotope}, Z::AbstractZonotope) ``` ## Operations ```@docs base_vertex(::HParallelotope) +``` +```@meta +CurrentModule = LazySets.API +``` +```@docs; canonical=false +center(::LazySet) +``` +```@meta +CurrentModule = LazySets.HParallelotopeModule +``` +```@docs center(::HParallelotope) -constraints_list(::HParallelotope) -dim(::HParallelotope) directions(::HParallelotope) extremal_vertices(::HParallelotope{N, VN}) where {N, VN} -generators(::HParallelotope) +``` +```@meta +CurrentModule = LazySets +``` +```@docs; canonical=false +genmat(::AbstractZonotope) +``` +```@meta +CurrentModule = LazySets.HParallelotopeModule +``` +```@docs genmat(::HParallelotope) offset(::HParallelotope) +``` +```@meta +CurrentModule = LazySets.API +``` +```@docs; canonical=false +rand(::Type{LazySet}) +``` +```@meta +CurrentModule = LazySets.HParallelotopeModule +``` +```@docs rand(::Type{HParallelotope}) +``` +```@meta +CurrentModule = LazySets.API +``` +```@docs; canonical=false +volume(::LazySet) +``` +```@meta +CurrentModule = LazySets.HParallelotopeModule +``` +```@docs volume(::HParallelotope) ``` +```@meta +CurrentModule = LazySets.API +``` + +Undocumented implementations: +* [`constraints_list`](@ref constraints_list(::LazySet)) +* [`dim`](@ref dim(::LazySet)) +```@meta +CurrentModule = LazySets +``` +* [`generators`](@ref generators(::AbstractZonotope)) +```@meta +CurrentModule = LazySets.API +``` +* [`isoperationtype`](@ref isoperationtype(::Type{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)) +* [`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)) +* [`scale!`](@ref scale!(::Real, ::LazySet)) +* [`translate`](@ref translate(::LazySet, ::AbstractVector)) +* [`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 [`AbstractPolyhedron`](@ref): +* [`linear_combination`](@ref linear_combination(::AbstractPolyhedron, ::AbstractPolyhedron)) + +Inherited from [`AbstractPolyhedron`](@ref): +* [`high`](@ref high(::AbstractPolyhedron)) +* [`high`](@ref high(::AbstractPolyhedron, ::Int)) +* [`ispolyhedral`](@ref ispolyhedral(::AbstractPolyhedron)) +* [`low`](@ref low(::AbstractPolyhedron)) +* [`low`](@ref low(::AbstractPolyhedron, ::Int)) +* [`intersection`](@ref intersection(::AbstractPolyhedron, ::AbstractPolyhedron)) Inherited from [`AbstractPolytope`](@ref): * [`isbounded`](@ref isbounded(::AbstractPolytope)) +* [`isboundedtype`](@ref isboundedtype(::Type{AbstractPolytope})) +* [`isconvextype`](@ref isconvextype(::Type{AbstractPolytope})) Inherited from [`AbstractCentrallySymmetricPolytope`](@ref): * [`an_element`](@ref an_element(::AbstractCentrallySymmetricPolytope)) +* [`center`](@ref center(::AbstractCentrallySymmetricPolytope, ::Int)) * [`extrema`](@ref extrema(::AbstractCentrallySymmetricPolytope)) * [`extrema`](@ref extrema(::AbstractCentrallySymmetricPolytope, ::Int)) -* [`isuniversal`](@ref isuniversal(::AbstractPolytope, ::Bool=false)) +* [`isempty`](@ref isempty(::AbstractCentrallySymmetricPolytope)) +* [`isuniversal`](@ref isuniversal(::AbstractCentrallySymmetricPolytope, ::Bool=false)) Inherited from [`AbstractZonotope`](@ref): -* [`isempty`](@ref isempty(::AbstractZonotope)) +* [`ngens`](@ref ngens(::AbstractZonotope)) * [`order`](@ref order(::AbstractZonotope)) * [`reflect`](@ref reflect(::AbstractZonotope)) +* [`remove_redundant_generators`](@ref remove_redundant_generators(::AbstractZonotope)) +* [`togrep`](@ref togrep(::AbstractZonotope)) * [`vertices_list`](@ref vertices_list(::AbstractZonotope)) * [`linear_map`](@ref linear_map(::AbstractMatrix, ::AbstractZonotope)) * [`∈`](@ref ∈(::AbstractVector, ::AbstractZonotope)) +* [`project`](@ref project(::AbstractZonotope, ::AbstractVector{Int})) +* [`reduce_order`](@ref reduce_order(::AbstractZonotope, ::Real, ::AbstractReductionMethod=GIR05())) +* [`split`](@ref split(::AbstractZonotope, ::Int)) +* [`split`](@ref split(::AbstractZonotope, ::AbstractVector{Int}, ::AbstractVector{Int})) * [`ρ`](@ref ρ(::AbstractVector, ::AbstractZonotope)) * [`σ`](@ref σ(::AbstractVector, ::AbstractZonotope)) -* [`translate`](@ref translate(::AbstractZonotope, ::AbstractVector)) +* [`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)) diff --git a/src/Sets/HParallelotope/center.jl b/src/Sets/HParallelotope/center.jl index 84422cef68..a779316a49 100644 --- a/src/Sets/HParallelotope/center.jl +++ b/src/Sets/HParallelotope/center.jl @@ -1,15 +1,7 @@ """ - center(P::HParallelotope) - -Return the center of a parallelotope in constraint representation. - -### Input +# Extended help -- `P` -- parallelotope in constraint representation - -### Output - -The center of the parallelotope. + center(P::HParallelotope) ### Algorithm diff --git a/src/Sets/HParallelotope/constraints_list.jl b/src/Sets/HParallelotope/constraints_list.jl index 853eb4578c..a266bfafad 100644 --- a/src/Sets/HParallelotope/constraints_list.jl +++ b/src/Sets/HParallelotope/constraints_list.jl @@ -1,16 +1,3 @@ -""" - constraints_list(P::HParallelotope) - -Return the list of constraints of a parallelotope in constraint representation. - -### Input - -- `P` -- parallelotope in constraint representation - -### Output - -The list of constraints of `P`. -""" function constraints_list(P::HParallelotope) D, c = P.directions, P.offset N, VN = _parameters(P) @@ -18,7 +5,7 @@ function constraints_list(P::HParallelotope) end # reason: `Documenter` cannot annotate `constraints_list` with type parameters -function _parameters(P::HParallelotope{N,VN}) where {N,VN} +function _parameters(::HParallelotope{N,VN}) where {N,VN} return (N, VN) end diff --git a/src/Sets/HParallelotope/convert.jl b/src/Sets/HParallelotope/convert.jl index 96e663ff3b..7032a71779 100644 --- a/src/Sets/HParallelotope/convert.jl +++ b/src/Sets/HParallelotope/convert.jl @@ -1,5 +1,5 @@ """ - convert(::Type{HParallelotope}, Z::AbstractZonotope{N}) where {N} + convert(::Type{HParallelotope}, Z::AbstractZonotope) Convert a zonotopic set of order one to a parallelotope in constraint representation. @@ -19,10 +19,11 @@ This function requires that the list of constraints of `Z` are obtained in the particular order returned from the `constraints_list` function of a `Zonotope`. Hence it first converts `Z` to a `Zonotope`. """ -function convert(::Type{HParallelotope}, Z::AbstractZonotope{N}) where {N} +function convert(::Type{HParallelotope}, Z::AbstractZonotope) @assert order(Z) == 1 "cannot convert a zonotope that is not of order 1 " * "to a parallelotope" n = dim(Z) + N = eltype(Z) constraints = _constraints_list_zonotope(Z) diff --git a/src/Sets/HParallelotope/dim.jl b/src/Sets/HParallelotope/dim.jl index 71a9b83770..e95907ef52 100644 --- a/src/Sets/HParallelotope/dim.jl +++ b/src/Sets/HParallelotope/dim.jl @@ -1,16 +1,3 @@ -""" - dim(P::HParallelotope) - -Return the dimension of a parallelotope in constraint representation. - -### Input - -- `P` -- parallelotope in constraint representation - -### Output - -The ambient dimension of the parallelotope. -""" function dim(P::HParallelotope) return size(P.directions, 1) end diff --git a/src/Sets/HParallelotope/generators.jl b/src/Sets/HParallelotope/generators.jl index 300452744e..240ae9cf3a 100644 --- a/src/Sets/HParallelotope/generators.jl +++ b/src/Sets/HParallelotope/generators.jl @@ -1,17 +1,3 @@ -""" - generators(P::HParallelotope) - -Return an iterator over the generators of a parallelotope in constraint -representation. - -### Input - -- `P` -- parallelotope in constraint representation - -### Output - -An iterator over the generators of `P`. -""" function generators(P::HParallelotope) return generators_fallback(P) end diff --git a/src/Sets/HParallelotope/genmat.jl b/src/Sets/HParallelotope/genmat.jl index 53c6d9d71c..ca45d45c2e 100644 --- a/src/Sets/HParallelotope/genmat.jl +++ b/src/Sets/HParallelotope/genmat.jl @@ -1,15 +1,7 @@ """ - genmat(P::HParallelotope) - -Return the generator matrix of a parallelotope in constraint representation. - -### Input +# Extended help -- `P` -- parallelotope in constraint representation - -### Output - -A matrix where each column represents one generator of the parallelotope `P`. + genmat(P::HParallelotope) ### Algorithm diff --git a/src/Sets/HParallelotope/rand.jl b/src/Sets/HParallelotope/rand.jl index 1a5759df05..1e54206d60 100644 --- a/src/Sets/HParallelotope/rand.jl +++ b/src/Sets/HParallelotope/rand.jl @@ -1,27 +1,13 @@ """ +# Extended help + rand(::Type{HParallelotope}; [N]::Type{<:Real}=Float64, [dim]::Int=2, [rng]::AbstractRNG=GLOBAL_RNG, [seed]::Union{Int, Nothing}=nothing) -Create a random parallelotope in constraint representation. - -### Input - -- `HParallelotope` -- 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 - -### Output - -A random parallelotope. - -### Notes +### Algorithm All numbers are normally distributed with mean 0 and standard deviation 1. -### Algorithm - The directions matrix and offset vector are created randomly. On average there is a good chance that this resulting set is empty. We then modify the offset to ensure non-emptiness. diff --git a/src/Sets/HParallelotope/volume.jl b/src/Sets/HParallelotope/volume.jl index 0523ce62bf..3062705492 100644 --- a/src/Sets/HParallelotope/volume.jl +++ b/src/Sets/HParallelotope/volume.jl @@ -1,15 +1,7 @@ """ - volume(P::HParallelotope) - -Return the volume of a parallelotope in constraint representation. - -### Input +# Extended help -- `P` -- parallelotope in constraint representation - -### Output - -The volume. + volume(P::HParallelotope) ### Algorithm