add 'distance' between vector and set to API

docs/src/lib/API.md

@@ -62,6 +62,7 @@ volume(::LazySet)
 
 ```@docs
 affine_map(::AbstractMatrix, ::LazySet, ::AbstractVector)
+distance(::AbstractVector, ::LazySet)
 exponential_map(::AbstractMatrix, ::LazySet)
 ∈(::AbstractVector, ::LazySet)
 is_interior_point(::AbstractVector, ::LazySet)

src/API/API.jl

@@ -21,11 +21,11 @@ export
       low, norm, radius, rectify, reflect, surface, vertices_list, vertices,
       volume,
 # mixed set operations (typically with vectors or matrices)
-      affine_map, exponential_map, is_interior_point, linear_map, permute,
-      project, sample, scale!, scale, support_function, ρ, support_vector, σ,
-      translate!, translate,
+      affine_map, distance, exponential_map, is_interior_point, linear_map,
+      permute, project, sample, scale!, scale, support_function, ρ,
+      support_vector, σ, translate!, translate,
 # binary set operations
-      cartesian_product, difference, distance, exact_sum, intersection,
+      cartesian_product, difference, exact_sum, intersection,
       is_intersection_empty, isequivalent, ⊂, linear_combination,
       minkowski_difference, pontryagin_difference, minkowski_sum
 
@@ -64,6 +64,7 @@ include("Unary/vertices.jl")
 include("Unary/volume.jl")
 
 include("Mixed/affine_map.jl")
+include("Mixed/distance.jl")
 include("Mixed/exponential_map.jl")
 include("Mixed/in.jl")
 include("Mixed/is_interior_point.jl")

src/API/Binary/distance.jl

@@ -15,11 +15,11 @@ A real number representing the distance between `X` and `Y`.
 
 ### Notes
 
-The standard distance is zero if the sets intersect and otherwise the ``p``-norm
-of the shortest line segment between any pair of points. Formally,
+The standard distance is zero if the sets intersect, and infinite if one of the sets is empty.
+Otherwise, it is the ``p``-norm of the shortest line segment between any pair of points. Formally,
 
 ```math
-    \\inf_{x ∈ H_1, y ∈ H_2} \\{ d(x, y) \\}.
+    \\inf_{x ∈ X, y ∈ Y} \\{ d(x, y) \\}.
 ```
 """
 function distance(::LazySet, ::LazySet; p::Real=2) end

src/API/Mixed/distance.jl

@@ -0,0 +1,27 @@
+"""
+    distance(x::AbstractVector, X::LazySet; [p]::Real=2)
+    distance(X::LazySet, x::AbstractVector; [p]::Real=2)
+
+Compute the standard distance (induced by the ``p``-norm) between a point and a set.
+
+### Input
+
+- `x` -- point/vector
+- `X` -- set
+- `p` -- (optional; default: `2`) value of the ``p``-norm
+
+### Output
+
+A real number representing the distance between `x` and `X`.
+
+### Notes
+
+The standard distance is zero if the point lies inside the set, and infinite if the set is empty.
+Otherwise, it is the ``p``-norm of the shortest line segment between the point and any other point
+in the set. Formally,
+
+```math
+    \\inf_{y ∈ X} \\{ d(x, y) \\}.
+```
+"""
+function distance(::AbstractVector, ::LazySet; p::Real=2) end

test/API.jl

@@ -40,10 +40,10 @@ end
         @test isnothing(f(X, n))
     end
     v = [1]
-    for f in (permute, project, translate!, translate)
+    for f in (distance, permute, project, translate!, translate)
         @test isnothing(f(X, v))
     end
-    for f in (is_interior_point, ∈, support_function, ρ, support_vector, σ)
+    for f in (distance, is_interior_point, ∈, support_function, ρ, support_vector, σ)
         @test isnothing(f(v, X))
     end
     M = hcat(1)