From e18fa8e52b319884a3e3e72ede223cd196757c73 Mon Sep 17 00:00:00 2001 From: schillic Date: Mon, 23 Dec 2024 13:46:16 +0100 Subject: [PATCH 1/2] Line2D: revise docs entries, shorten docs --- docs/src/lib/sets/Line2D.md | 139 +++++++++++++++++++++++++--- src/Sets/Line2D/an_element.jl | 12 +-- src/Sets/Line2D/constraints_list.jl | 13 --- src/Sets/Line2D/dim.jl | 15 +-- src/Sets/Line2D/in.jl | 13 +-- src/Sets/Line2D/intersection.jl | 9 +- src/Sets/Line2D/isbounded.jl | 13 --- src/Sets/Line2D/isempty.jl | 15 +-- src/Sets/Line2D/isuniversal.jl | 14 +-- src/Sets/Line2D/rand.jl | 16 +--- src/Sets/Line2D/support_vector.jl | 15 --- src/Sets/Line2D/translate.jl | 15 +-- 12 files changed, 140 insertions(+), 149 deletions(-) diff --git a/docs/src/lib/sets/Line2D.md b/docs/src/lib/sets/Line2D.md index d11bf088f7..4eaa6d0c28 100644 --- a/docs/src/lib/sets/Line2D.md +++ b/docs/src/lib/sets/Line2D.md @@ -10,35 +10,148 @@ Line2D ## Operations +```@meta +CurrentModule = LazySets.API +``` +```@docs; canonical=false +an_element(::LazySet) +``` +```@meta +CurrentModule = LazySets.Line2DModule +``` ```@docs an_element(::Line2D) constrained_dimensions(::Line2D) -constraints_list(::Line2D) -dim(::Line2D) -isbounded(::Line2D) -isempty(::Line2D) +``` +```@meta +CurrentModule = LazySets.API +``` +```@docs; canonical=false +isuniversal(::LazySet, ::Bool=false) +``` +```@meta +CurrentModule = LazySets.Line2DModule +``` +```@docs isuniversal(::Line2D, ::Bool=false) +``` +```@meta +CurrentModule = LazySets.API +``` +```@docs; canonical=false +rand(::Type{LazySet}) +``` +```@meta +CurrentModule = LazySets.Line2DModule +``` +```@docs rand(::Type{Line2D}) +``` +```@meta +CurrentModule = LazySets.API +``` +```@docs; canonical=false +∈(::AbstractVector, ::LazySet) +``` +```@meta +CurrentModule = LazySets.Line2DModule +``` +```@docs ∈(::AbstractVector, ::Line2D) project(::AbstractVector, ::Line2D) -σ(::AbstractVector, ::Line2D) +``` +```@meta +CurrentModule = LazySets.API +``` +```@docs; canonical=false +translate(::LazySet, ::AbstractVector) +``` +```@meta +CurrentModule = LazySets.Line2DModule +``` +```@docs translate(::Line2D, ::AbstractVector) +``` +```@meta +CurrentModule = LazySets.API +``` +```@docs; canonical=false +intersection(::LazySet, ::LazySet) +``` +```@meta +CurrentModule = LazySets.Line2DModule +``` +```@docs intersection(::Line2D, ::Line2D) +isdisjoint(::Line2D, ::Line2D) ``` +```@meta +CurrentModule = LazySets.API +``` + +Undocumented implementations: +* [`constraints_list`](@ref constraints_list(::LazySet)) +* [`dim`](@ref dim(::LazySet)) +* [`isbounded`](@ref isbounded(::LazySet)) +* [`isempty`](@ref isempty(::LazySet)) +* [`isoperationtype`](@ref isoperationtype(::Type{LazySet})) +* [`project`](@ref project(::LazySet, ::AbstractVector{Int})) +* [`σ`](@ref σ(::AbstractVector, ::LazySet)) + ```@meta CurrentModule = LazySets ``` Inherited from [`LazySet`](@ref): -* [`diameter`](@ref diameter(::LazySet, ::Real)) -* [`high`](@ref high(::LazySet)) -* [`high`](@ref high(::LazySet, ::Int)) -* [`low`](@ref low(::LazySet)) -* [`low`](@ref low(::LazySet, ::Int)) -* [`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)) +* [`volume`](@ref volume(::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)) +* [`ρ`](@ref ρ(::AbstractVector, ::LazySet)) +* [`translate!`](@ref translate!(::LazySet, ::AbstractVector)) +* [`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)) +* [`⊆`](@ref ⊆(::LazySet, ::AbstractPolyhedron)) +* [`minkowski_sum`](@ref minkowski_sum(::AbstractPolyhedron, ::AbstractPolyhedron)) diff --git a/src/Sets/Line2D/an_element.jl b/src/Sets/Line2D/an_element.jl index 757e3c76b2..3b52545a60 100644 --- a/src/Sets/Line2D/an_element.jl +++ b/src/Sets/Line2D/an_element.jl @@ -1,15 +1,7 @@ """ - an_element(L::Line2D) - -Return some element of a 2D line. - -### Input +# Extended help -- `L` -- 2D line - -### Output - -An element on the line. + an_element(L::Line2D) ### Algorithm diff --git a/src/Sets/Line2D/constraints_list.jl b/src/Sets/Line2D/constraints_list.jl index 04a87b07e8..49fba74c59 100644 --- a/src/Sets/Line2D/constraints_list.jl +++ b/src/Sets/Line2D/constraints_list.jl @@ -1,16 +1,3 @@ -""" - constraints_list(L::Line2D) - -Return the list of constraints of a 2D line. - -### Input - -- `L` -- 2D line - -### Output - -A list containing two half-spaces. -""" function constraints_list(L::Line2D) return _constraints_list_hyperplane(L.a, L.b) end diff --git a/src/Sets/Line2D/dim.jl b/src/Sets/Line2D/dim.jl index 81470ec88e..d05e2c5740 100644 --- a/src/Sets/Line2D/dim.jl +++ b/src/Sets/Line2D/dim.jl @@ -1,16 +1,3 @@ -""" - dim(L::Line2D) - -Return the ambient dimension of a 2D line. - -### Input - -- `L` -- 2D line - -### Output - -The ambient dimension of the line, which is 2. -""" -function dim(L::Line2D) +function dim(::Line2D) return 2 end diff --git a/src/Sets/Line2D/in.jl b/src/Sets/Line2D/in.jl index 7f15461608..7f5b22d44a 100644 --- a/src/Sets/Line2D/in.jl +++ b/src/Sets/Line2D/in.jl @@ -1,16 +1,7 @@ """ - ∈(x::AbstractVector, L::Line2D) - -Check whether a given point is contained in a 2D line. - -### Input +# Extended help -- `x` -- point/vector -- `L` -- 2D line - -### Output - -`true` iff `x ∈ L`. + ∈(x::AbstractVector, L::Line2D) ### Algorithm diff --git a/src/Sets/Line2D/intersection.jl b/src/Sets/Line2D/intersection.jl index 3661416fde..79b30db7fb 100644 --- a/src/Sets/Line2D/intersection.jl +++ b/src/Sets/Line2D/intersection.jl @@ -1,12 +1,7 @@ """ - intersection(L1::Line2D, L2::Line2D) - -Compute the intersection of two two-dimensional lines. +# Extended help -### Input - -- `L1` -- line -- `L2` -- line + intersection(L1::Line2D, L2::Line2D) ### Output diff --git a/src/Sets/Line2D/isbounded.jl b/src/Sets/Line2D/isbounded.jl index e2eb89a02c..56cfc7af97 100644 --- a/src/Sets/Line2D/isbounded.jl +++ b/src/Sets/Line2D/isbounded.jl @@ -1,16 +1,3 @@ -""" - isbounded(L::Line2D) - -Check whether a 2D line is bounded. - -### Input - -- `L` -- 2D line - -### Output - -`false`. -""" function isbounded(::Line2D) return false end diff --git a/src/Sets/Line2D/isempty.jl b/src/Sets/Line2D/isempty.jl index 6aa4f7d076..7e37515b11 100644 --- a/src/Sets/Line2D/isempty.jl +++ b/src/Sets/Line2D/isempty.jl @@ -1,16 +1,3 @@ -""" - isempty(L::Line2D) - -Check whether a 2D line is empty. - -### Input - -- `L` -- 2D line - -### Output - -`false`. -""" -function isempty(L::Line2D) +function isempty(::Line2D) return false end diff --git a/src/Sets/Line2D/isuniversal.jl b/src/Sets/Line2D/isuniversal.jl index 85b7410894..5f81a5bf6c 100644 --- a/src/Sets/Line2D/isuniversal.jl +++ b/src/Sets/Line2D/isuniversal.jl @@ -1,17 +1,7 @@ """ - isuniversal(L::Line2D, [witness]::Bool=false) - -Check whether a 2D line is universal. - -### Input +# Extended help -- `L` -- 2D line -- `witness` -- (optional, default: `false`) compute a witness if activated - -### Output - -* If `witness` option is deactivated: `false` -* If `witness` option is activated: `(false, v)` where ``v ∉ L`` + isuniversal(L::Line2D, [witness]::Bool=false) ### Algorithm diff --git a/src/Sets/Line2D/rand.jl b/src/Sets/Line2D/rand.jl index 93921882ed..ae07c2ed7c 100644 --- a/src/Sets/Line2D/rand.jl +++ b/src/Sets/Line2D/rand.jl @@ -1,21 +1,9 @@ """ +# Extended help + rand(::Type{Line2D}; [N]::Type{<:Real}=Float64, [dim]::Int=2, [rng]::AbstractRNG=GLOBAL_RNG, [seed]::Union{Int, Nothing}=nothing) -Create a random line. - -### Input - -- `Line2D` -- 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 line. - ### Algorithm All numbers are normally distributed with mean 0 and standard deviation 1. diff --git a/src/Sets/Line2D/support_vector.jl b/src/Sets/Line2D/support_vector.jl index ff34ffb699..5dc2793b83 100644 --- a/src/Sets/Line2D/support_vector.jl +++ b/src/Sets/Line2D/support_vector.jl @@ -1,18 +1,3 @@ -""" - σ(d::AbstractVector, L::Line2D) - -Return the support vector of a 2D line in a given direction. - -### Input - -- `d` -- direction -- `L` -- 2D line - -### Output - -The support vector in the given direction, which is defined the same way as for -the more general `Hyperplane`. -""" function σ(d::AbstractVector, L::Line2D) v, unbounded = _σ_hyperplane_halfspace(d, L.a, L.b; error_unbounded=true, halfspace=false) diff --git a/src/Sets/Line2D/translate.jl b/src/Sets/Line2D/translate.jl index 220f85adc0..aa3de37eeb 100644 --- a/src/Sets/Line2D/translate.jl +++ b/src/Sets/Line2D/translate.jl @@ -1,18 +1,7 @@ """ - translate(L::Line2D, v::AbstractVector; [share]::Bool=false) - -Translate (i.e., shift) a 2D line by a given vector. - -### Input +# Extended help -- `L` -- 2D line -- `v` -- translation vector -- `share` -- (optional, default: `false`) flag for sharing unmodified parts of - the original set representation - -### Output - -A translated line. + translate(L::Line2D, v::AbstractVector; [share]::Bool=false) ### Notes From 1f6835887dbab22cf5a76f08f9d435966b580633 Mon Sep 17 00:00:00 2001 From: schillic Date: Mon, 23 Dec 2024 13:53:30 +0100 Subject: [PATCH 2/2] Line2D: move 'isdisjoint' method to module --- docs/src/lib/sets/Line2D.md | 2 +- src/ConcreteOperations/isdisjoint.jl | 34 ---------------------------- src/Sets/Line2D/Line2DModule.jl | 9 ++++---- src/Sets/Line2D/isdisjoint.jl | 14 ++++++++++++ 4 files changed, 20 insertions(+), 39 deletions(-) create mode 100644 src/Sets/Line2D/isdisjoint.jl diff --git a/docs/src/lib/sets/Line2D.md b/docs/src/lib/sets/Line2D.md index 4eaa6d0c28..97dfa7e5d7 100644 --- a/docs/src/lib/sets/Line2D.md +++ b/docs/src/lib/sets/Line2D.md @@ -83,7 +83,6 @@ CurrentModule = LazySets.Line2DModule ``` ```@docs intersection(::Line2D, ::Line2D) -isdisjoint(::Line2D, ::Line2D) ``` ```@meta @@ -98,6 +97,7 @@ Undocumented implementations: * [`isoperationtype`](@ref isoperationtype(::Type{LazySet})) * [`project`](@ref project(::LazySet, ::AbstractVector{Int})) * [`σ`](@ref σ(::AbstractVector, ::LazySet)) +* [`isdisjoint`](@ref isdisjoint(::LazySet, ::LazySet)) ```@meta CurrentModule = LazySets diff --git a/src/ConcreteOperations/isdisjoint.jl b/src/ConcreteOperations/isdisjoint.jl index d3ab1dd3e5..4a68c79e2b 100644 --- a/src/ConcreteOperations/isdisjoint.jl +++ b/src/ConcreteOperations/isdisjoint.jl @@ -966,40 +966,6 @@ for ST in [:AbstractPolyhedron, :AbstractSingleton, :HalfSpace, :Hyperplane, end end -""" - isdisjoint(L1::Line2D, L2::Line2D, [witness]::Bool=false) - -Check whether two two-dimensional lines do not intersect, and otherwise -optionally compute a witness. - -### Input - -- `L1` -- two-dimensional line -- `L2` -- two-dimensional line -- `witness` -- (optional, default: `false`) compute a witness if activated - -### Output - -* If `witness` option is deactivated: `true` iff ``L1 ∩ L2 = ∅`` -* If `witness` option is activated: - * `(true, [])` iff ``L1 ∩ L2 = ∅`` - * `(false, v)` iff ``L1 ∩ L2 ≠ ∅`` and ``v ∈ L1 ∩ L2`` -""" -function isdisjoint(L1::Line2D, L2::Line2D, witness::Bool=false) - disjoint = _isdisjoint(L1, L2) - if disjoint - return _witness_result_empty(witness, true, L1, L2) - end - return witness ? (false, an_element(intersection(L1, L2))) : false -end - -# the lines do not intersect <=> det is zero and they are not identical -function _isdisjoint(L1::Line2D, L2::Line2D) - det = right_turn(L1.a, L2.a) - disjoint = isapproxzero(det) && !isapprox(L1.b, L2.b) - return disjoint -end - for ST in [:AbstractZonotope, :AbstractSingleton] @eval @commutative function isdisjoint(C::CartesianProduct{N,<:LazySet,<:Universe}, Z::$(ST)) where {N} diff --git a/src/Sets/Line2D/Line2DModule.jl b/src/Sets/Line2D/Line2DModule.jl index f766df1309..8f3770232d 100644 --- a/src/Sets/Line2D/Line2DModule.jl +++ b/src/Sets/Line2D/Line2DModule.jl @@ -5,17 +5,17 @@ using Reexport, Requires using ..LazySets: AbstractPolyhedron, AbstractLinearMapAlgorithm, _constraints_list_hyperplane, _intersection_line2d, _linear_map_hrep, _non_element_halfspace, - _σ_hyperplane_halfspace + _σ_hyperplane_halfspace, _witness_result_empty using LinearAlgebra: dot using Random: AbstractRNG, GLOBAL_RNG -using ReachabilityBase.Arrays: nonzero_indices +using ReachabilityBase.Arrays: nonzero_indices, right_turn using ReachabilityBase.Distribution: reseed! -using ReachabilityBase.Comparison: _isapprox +using ReachabilityBase.Comparison: isapproxzero, _isapprox using ReachabilityBase.Require: require @reexport import ..API: an_element, constraints_list, dim, isbounded, isempty, isoperationtype, isuniversal, rand, ∈, project, σ, - translate, intersection + translate, intersection, isdisjoint @reexport import ..LazySets: constrained_dimensions import ..LazySets: _linear_map_hrep_helper @reexport using ..API @@ -38,6 +38,7 @@ include("project.jl") include("support_vector.jl") include("translate.jl") include("intersection.jl") +include("isdisjoint.jl") include("constrained_dimensions.jl") diff --git a/src/Sets/Line2D/isdisjoint.jl b/src/Sets/Line2D/isdisjoint.jl new file mode 100644 index 0000000000..029557c035 --- /dev/null +++ b/src/Sets/Line2D/isdisjoint.jl @@ -0,0 +1,14 @@ +function isdisjoint(L1::Line2D, L2::Line2D, witness::Bool=false) + disjoint = _isdisjoint(L1, L2) + if disjoint + return _witness_result_empty(witness, true, L1, L2) + end + return witness ? (false, an_element(intersection(L1, L2))) : false +end + +# the lines do not intersect <=> det is zero and they are not identical +function _isdisjoint(L1::Line2D, L2::Line2D) + det = right_turn(L1.a, L2.a) + disjoint = isapproxzero(det) && !isapprox(L1.b, L2.b) + return disjoint +end