#63 - refactoring LazySet & an_element default implementation

docs/src/lib/interfaces.md

@@ -32,7 +32,7 @@ end
 
 ## LazySet
 
-Every convex set in this library implements the main `LazySet` interface.
+Every convex set in this library implements this interface.
 
 ```@docs
 LazySet

src/Approximations/box_approximations.jl

@@ -1,7 +1,3 @@
-import Base.LinAlg:norm
-import LazySets:radius,  # visible outside module Approximations
-                diameter
-
 # ===================================
 # Approximations in the infinity norm
 # ===================================
@@ -153,80 +149,3 @@ function ballinf_approximation(S::LazySet{N})::BallInf{N} where {N<:Real}
     end
     return BallInf(c, r)
 end
-
-# =======================================================
-# Metric properties of sets computed using Approximations
-# =======================================================
-
-"""
-    norm(S::LazySet, [p]::Real=Inf)
-
-Return the norm of a convex set.
-It is the norm of the enclosing ball (of the given ``p``-norm) of minimal volume
-that is centered in the origin.
-
-### Input
-
-- `S` -- convex set
-- `p` -- (optional, default: `Inf`) norm
-
-### Output
-
-A real number representing the norm.
-"""
-function norm(S::LazySet, p::Real=Inf)
-    if p == Inf
-        return norm(ballinf_approximation(S), p)
-    else
-        error("the norm for this value of p=$p is not implemented")
-    end
-end
-
-"""
-    radius(S::LazySet, [p]::Real=Inf)
-
-Return the radius of a convex set.
-It is the radius of the enclosing ball (of the given ``p``-norm) of minimal
-volume with the same center.
-
-### Input
-
-- `S` -- convex set
-- `p` -- (optional, default: `Inf`) norm
-
-### Output
-
-A real number representing the radius.
-"""
-function radius(S::LazySet, p::Real=Inf)
-    if p == Inf
-        return radius(ballinf_approximation(S)::BallInf, p)
-    else
-        error("the radius for this value of p=$p is not implemented")
-    end
-end
-
-"""
-    diameter(S::LazySet, [p]::Real=Inf)
-
-Return the diameter of a convex set.
-It is the maximum distance between any two elements of the set, or,
-equivalently, the diameter of the enclosing ball (of the given ``p``-norm) of
-minimal volume with the same center.
-
-### Input
-
-- `S` -- convex set
-- `p` -- (optional, default: `Inf`) norm
-
-### Output
-
-A real number representing the diameter.
-"""
-function diameter(S::LazySet, p::Real=Inf)
-    if p == Inf
-        return radius(S, p) * 2
-    else
-        error("the diameter for this value of p=$p is not implemented")
-    end
-end

src/LazySet.jl

@@ -0,0 +1,184 @@
+import Base.LinAlg:norm
+
+export LazySet,
+       ρ, support_function,
+       σ, support_vector,
+       dim,
+       norm,
+       radius,
+       diameter,
+       an_element
+
+"""
+    LazySet{N}
+
+Abstract type for convex sets, i.e., sets characterized by a (possibly infinite)
+intersection of halfspaces, or equivalently, sets ``S`` such that for any two
+elements ``x, y ∈ S`` and ``0 ≤ λ ≤ 1`` it holds that ``λ x + (1-λ) y ∈ S``.
+
+### Notes
+
+`LazySet` types should be parameterized with a type `N`, typically
+`N<:Real`, for using different numeric types.
+
+Every concrete `LazySet` must define the following functions:
+- `σ(d::AbstractVector{N}, S::LazySet)::AbstractVector{N}` -- the
+    support vector of `S` in a given direction `d`
+- `dim(S::LazySet)::Int` -- the ambient dimension of `S`
+
+```jldoctest
+julia> subtypes(LazySet)
+15-element Array{Union{DataType, UnionAll},1}:
+ LazySets.AbstractPointSymmetric  
+ LazySets.AbstractPolytope        
+ LazySets.CartesianProduct        
+ LazySets.CartesianProductArray   
+ LazySets.ConvexHull              
+ LazySets.ConvexHullArray         
+ LazySets.EmptySet                
+ LazySets.ExponentialMap          
+ LazySets.ExponentialProjectionMap
+ LazySets.HalfSpace               
+ LazySets.Hyperplane              
+ LazySets.Intersection            
+ LazySets.LinearMap               
+ LazySets.MinkowskiSum            
+ LazySets.MinkowskiSumArray
+```
+"""
+abstract type LazySet{N} end
+
+
+# --- common LazySet functions ---
+
+
+"""
+    ρ(d::AbstractVector{N}, S::LazySet{N})::N where {N<:Real}
+
+Evaluate the support function of a set in a given direction.
+
+### Input
+
+- `d` -- direction
+- `S` -- convex set
+
+### Output
+
+The support function of the set `S` for the direction `d`.
+"""
+function ρ(d::AbstractVector{N}, S::LazySet{N})::N where {N<:Real}
+    return dot(d, σ(d, S))
+end
+
+"""
+    support_function
+
+Alias for the support function ρ.
+"""
+const support_function = ρ
+
+"""
+    σ
+
+Function to compute the support vector σ.
+"""
+function σ end
+
+"""
+    support_vector
+
+Alias for the support vector σ.
+"""
+const support_vector = σ
+
+
+"""
+    norm(S::LazySet, [p]::Real=Inf)
+
+Return the norm of a convex set.
+It is the norm of the enclosing ball (of the given ``p``-norm) of minimal volume
+that is centered in the origin.
+
+### Input
+
+- `S` -- convex set
+- `p` -- (optional, default: `Inf`) norm
+
+### Output
+
+A real number representing the norm.
+"""
+function norm(S::LazySet, p::Real=Inf)
+    if p == Inf
+        return norm(Approximations.ballinf_approximation(S), p)
+    else
+        error("the norm for this value of p=$p is not implemented")
+    end
+end
+
+"""
+    radius(S::LazySet, [p]::Real=Inf)
+
+Return the radius of a convex set.
+It is the radius of the enclosing ball (of the given ``p``-norm) of minimal
+volume with the same center.
+
+### Input
+
+- `S` -- convex set
+- `p` -- (optional, default: `Inf`) norm
+
+### Output
+
+A real number representing the radius.
+"""
+function radius(S::LazySet, p::Real=Inf)
+    if p == Inf
+        return radius(Approximations.ballinf_approximation(S)::BallInf, p)
+    else
+        error("the radius for this value of p=$p is not implemented")
+    end
+end
+
+"""
+    diameter(S::LazySet, [p]::Real=Inf)
+
+Return the diameter of a convex set.
+It is the maximum distance between any two elements of the set, or,
+equivalently, the diameter of the enclosing ball (of the given ``p``-norm) of
+minimal volume with the same center.
+
+### Input
+
+- `S` -- convex set
+- `p` -- (optional, default: `Inf`) norm
+
+### Output
+
+A real number representing the diameter.
+"""
+function diameter(S::LazySet, p::Real=Inf)
+    if p == Inf
+        return radius(S, p) * 2
+    else
+        error("the diameter for this value of p=$p is not implemented")
+    end
+end
+
+
+"""
+    an_element(S::LazySet{N})::AbstractVector{N} where {N<:Real}
+
+Return some element of a convex set.
+
+### Input
+
+- `S` -- convex set
+
+### Output
+
+An element of a convex set.
+"""
+function an_element(S::LazySet{N})::AbstractVector{N} where {N<:Real}
+    return σ(sparsevec([1], [one(N)], dim(S)), S)
+end

src/LazySets.jl

@@ -7,89 +7,69 @@ module LazySets
 
 using RecipesBase, IterTools, Requires
 
-export LazySet,
-       ρ, support_function,
-       σ, support_vector,
-       dim,
-       norm,
-       radius,
-       diameter,
-       Approximations
-
-"""
-    LazySet{N}
-
-Abstract type for a lazy set.
-
-### Notes
-
-Every concrete `LazySet` must define the following functions:
-- `σ(d::AbstractVector{N}, S::LazySet)::AbstractVector{N}` -- the support vector
-    of `S` in a given direction `d`
-- `dim(S::LazySet)::Int` -- the ambient dimension of `S`
-
-`LazySet` types should be parameterized with a type `N`, typically `N<:Real`,
-for using different numeric types.
-"""
-abstract type LazySet{N} end
-
 # ============================
 # Auxiliary types or functions
 # ============================
 include("LinearConstraints.jl")
 include("helper_functions.jl")
 
-# ===============================
-# Types that inherit from LazySet
-# ===============================
-# abstract types
+# ==================
+# Abstract set types
+# ==================
+include("LazySet.jl")
 include("AbstractPolytope.jl")
 include("AbstractPointSymmetric.jl")
 include("AbstractPointSymmetricPolytope.jl")
 include("AbstractHyperrectangle.jl")
 include("AbstractPolygon.jl")
 include("AbstractHPolygon.jl")
 include("AbstractSingleton.jl")
-# concrete types
-include("EmptySet.jl")
-include("ZeroSet.jl")
-include("Singleton.jl")
+
+# =============================
+# Types representing basic sets
+# =============================
+include("Ball1.jl")
 include("Ball2.jl")
 include("BallInf.jl")
-include("Ball1.jl")
 include("Ballp.jl")
-include("Hyperrectangle.jl")
+include("Ellipsoid.jl")
+include("EmptySet.jl")
+include("HalfSpace.jl")
 include("HPolygon.jl")
 include("HPolygonOpt.jl")
 include("HPolytope.jl")
+include("Hyperplane.jl")
+include("Hyperrectangle.jl")
+include("Singleton.jl")
 include("VPolygon.jl")
+include("ZeroSet.jl")
 include("Zonotope.jl")
-include("Ellipsoid.jl")
-include("Hyperplane.jl")
-include("HalfSpace.jl")
 
 # =================================
 # Types representing set operations
 # =================================
-include("ConvexHull.jl")
 include("CartesianProduct.jl")
+include("ConvexHull.jl")
 include("ExponentialMap.jl")
+include("Intersection.jl")
 include("LinearMap.jl")
 include("MinkowskiSum.jl")
-include("Intersection.jl")
 include("SymmetricIntervalHull.jl")
 
 # =======================================
 # Algorithms for check operations on sets
 # =======================================
-include("is_subset.jl")
 include("is_intersection_empty.jl")
+include("is_subset.jl")
 
-# =================================================================
-# Algorithms for approximation of convex sets using support vectors
-# =================================================================
-include("support_function.jl")
+# =====================
+# Approximations module
+# =====================
 include("Approximations/Approximations.jl")
+
+# ============
+# Plot recipes
+# ============
 include("plot_recipes.jl")
 
 end # module