Merge pull request #3497 from JuliaReach/schillic/api_docs

Outsource documentation to API module

docs/make.jl

@@ -5,7 +5,7 @@ import Polyhedra, Optim, ExponentialUtilities, TaylorModels, Distributions,
 include("init.jl")
 
 makedocs(; sitename="LazySets.jl",
-         modules=[LazySets, Approximations, LazySets.Parallel],
+         modules=[LazySets, LazySets.API, Approximations, LazySets.Parallel],
          format=Documenter.HTML(; prettyurls=get(ENV, "CI", nothing) == "true",
                                 assets=["assets/aligned.css"],
                                 size_threshold_warn=150 * 2^10),
@@ -33,6 +33,7 @@ makedocs(; sitename="LazySets.jl",
                                 "Lazy Intersections" => "man/lazy_intersections.md"
                                 #
                                 ],
+                "API" => "lib/API.md",
                 "Library" => Any["Set Interfaces" => [
                                                       #
                                                       "lib/interfaces/overview.md",

docs/src/lib/API.md

@@ -0,0 +1,100 @@
+```@contents
+Pages = ["API.md"]
+Depth = 3
+```
+
+```@meta
+CurrentModule = LazySets.API
+```
+
+```@docs
+API
+```
+
+# Set interface
+
+```@docs
+LazySet
+```
+
+# Unary set functions
+
+```@docs
+an_element(::LazySet)
+area(::LazySet)
+complement(::LazySet)
+concretize(::LazySet)
+constraints_list(::LazySet)
+constraints(::LazySet)
+convex_hull(::LazySet)
+diameter(::LazySet, ::Real=Inf)
+dim(::LazySet)
+eltype(::Type{<:LazySet})
+eltype(::LazySet)
+extrema(::LazySet, ::Int)
+extrema(::LazySet)
+high(::LazySet, ::Int)
+high(::LazySet)
+is_polyhedral(::LazySet)
+isbounded(::LazySet)
+isboundedtype(::Type{<:LazySet})
+isconvextype(::Type{<:LazySet})
+isempty(::LazySet, ::Bool=false)
+isoperation(::LazySet)
+isoperationtype(::Type{<:LazySet})
+isuniversal(::LazySet, ::Bool=false)
+low(::LazySet, ::Int)
+low(::LazySet)
+norm(::LazySet, ::Real=Inf)
+radius(::LazySet, ::Real=Inf)
+rand(::Type{<:LazySet})
+rectify(::LazySet)
+reflect(::LazySet)
+surface(::LazySet)
+vertices_list(::LazySet)
+vertices(::LazySet)
+volume(::LazySet)
+```
+
+# Mixed set functions
+
+```@docs
+affine_map(::AbstractMatrix, ::LazySet, ::AbstractVector)
+exponential_map(::AbstractMatrix, ::LazySet)
+∈(::AbstractVector, ::LazySet)
+is_interior_point(::AbstractVector{N}, ::LazySet; p=Inf, ε=_rtol(N)) where {N<:Real}
+linear_map(::AbstractMatrix, ::LazySet)
+permute(::LazySet, ::AbstractVector{Int})
+project(::LazySet, ::AbstractVector{Int})
+sample(::LazySet, ::Int)
+scale(::Real, ::LazySet)
+scale!(::Real, ::LazySet)
+ρ(::AbstractVector, ::LazySet)
+support_function
+σ(::AbstractVector, ::LazySet)
+support_vector
+translate(::LazySet, ::AbstractVector)
+translate!(::LazySet, ::AbstractVector)
+```
+
+# Binary set functions
+
+```@docs
+cartesian_product(::LazySet, ::LazySet)
+difference(::LazySet, ::LazySet)
+distance(::LazySet, ::LazySet)
+exact_sum(::LazySet, ::LazySet)
+⊞
+intersection(::LazySet, ::LazySet)
+≈(::LazySet, ::LazySet)
+isdisjoint(::LazySet, ::LazySet)
+is_intersection_empty
+==(::LazySet, ::LazySet)
+isequivalent(::LazySet, ::LazySet)
+⊂(::LazySet, ::LazySet)
+⊆(::LazySet, ::LazySet)
+linear_combination(::LazySet, ::LazySet)
+minkowski_difference(::LazySet, ::LazySet)
+pontryagin_difference
+minkowski_sum(::LazySet, ::LazySet)
+```

docs/src/lib/concrete_binary_operations/difference.md

@@ -12,5 +12,5 @@ CurrentModule = LazySets
 ```@docs
 \(::LazySet, ::LazySet)
 difference(::Interval{N}, ::Interval) where {N}
-difference(::AbstractHyperrectangle{N}, ::AbstractHyperrectangle) where {N}
+difference(::AbstractHyperrectangle, ::AbstractHyperrectangle)
 ```

docs/src/lib/concrete_binary_operations/exact_sum.md

@@ -10,6 +10,5 @@ CurrentModule = LazySets
 # Exact Sum
 
 ```@docs
-⊞
 exact_sum(::SparsePolynomialZonotope, ::SparsePolynomialZonotope)
 ```

docs/src/lib/concrete_binary_operations/isdisjoint.md

@@ -12,9 +12,6 @@ CurrentModule = LazySets
 The function `isdisjoint` checks whether the intersection of two sets is empty.
 It can optionally produce a witness if the intersection is nonempty.
 
-!!! note
-    `is_intersection_empty` can be used as an alternative name to `isdisjoint`.
-
 ## Examples
 
 We use the following four sets for illustration.

docs/src/lib/concrete_binary_operations/issubset.md

@@ -98,7 +98,6 @@ plot1
 ## Methods
 
 ```@docs
-issubset
 ⊆(::LazySet, ::LazySet, ::Bool=false)
 ⊆(::LazySet, ::AbstractHyperrectangle, ::Bool=false)
 ⊆(::AbstractPolytope, ::LazySet, ::Bool=false)

docs/src/lib/concrete_binary_operations/minkowski_difference.md

@@ -10,7 +10,6 @@ CurrentModule = LazySets
 # Minkowski Difference
 
 ```@docs
-pontryagin_difference
 minkowski_difference(::LazySet, ::LazySet)
 minkowski_difference(::AbstractZonotope, ::AbstractZonotope)
 minkowski_difference(::AbstractHyperrectangle, ::AbstractHyperrectangle)

docs/src/lib/interfaces/LazySet.md

@@ -67,7 +67,6 @@ an_element(::LazySet)
 tosimplehrep(::LazySet)
 reflect(::LazySet)
 is_interior_point(::AbstractVector{N}, ::LazySet{N}; p=Inf, ε=_rtol(N)) where {N<:Real}
-isoperationtype(::Type{<:LazySet})
 isoperation(::LazySet)
 isequivalent(::LazySet, ::LazySet)
 surface(::LazySet)
@@ -108,18 +107,14 @@ definition based on `σ` is used.
 
 ```@docs
 σ
-support_vector
 ρ(::AbstractVector, ::LazySet)
-support_function
 ```
 
 ## Set functions that override Base functions
 
 ```@docs
 ==(::LazySet, ::LazySet)
 ≈(::LazySet, ::LazySet)
-copy(::LazySet)
-eltype
 ```
 
 ## Aliases for set types

src/API/API.jl

@@ -0,0 +1,96 @@
+"""
+    API
+
+This module contains an API (application programming interface) for set
+libraries. The module only defines and documents the general functions and does
+not provide implementations.
+"""
+module API
+
+import Base: eltype, extrema, isdisjoint, isempty, ∈, ≈, ==, ⊆
+import Random: rand
+import LinearAlgebra: norm
+import SparseArrays: permute
+import ReachabilityBase.Arrays: distance, rectify
+
+export
+# unary set operations
+       an_element, area, complement, concretize, constraints_list, constraints,
+       convex_hull, diameter, dim, high, is_polyhedral, isbounded,
+       isboundedtype, isconvextype, isempty, isoperation, isoperationtype,
+       isuniversal, low, norm, radius, rectify, reflect, sample,
+       support_function, ρ, support_vector, σ, surface, vertices_list, vertices,
+       volume,
+# mixed set operations (typically with vectors or matrices)
+       affine_map, exponential_map, is_interior_point, linear_map, project,
+       scale!, scale, support_function, ρ, support_vector, σ, translate!,
+       translate,
+# binary set operations
+       cartesian_product, difference, distance, exact_sum, ⊞, intersection,
+       is_intersection_empty, isequivalent, ⊂, linear_combination,
+       minkowski_difference, pontryagin_difference, minkowski_sum
+
+include("LazySet.jl")
+
+include("Unary/an_element.jl")
+include("Unary/area.jl")
+include("Unary/complement.jl")
+include("Unary/concretize.jl")
+include("Unary/constraints_list.jl")
+include("Unary/constraints.jl")
+include("Unary/convex_hull.jl")
+include("Unary/diameter.jl")
+include("Unary/dim.jl")
+include("Unary/eltype.jl")
+include("Unary/extrema.jl")
+include("Unary/high.jl")
+include("Unary/is_polyhedral.jl")
+include("Unary/isbounded.jl")
+include("Unary/isboundedtype.jl")
+include("Unary/isconvextype.jl")
+include("Unary/isempty.jl")
+include("Unary/isoperation.jl")
+include("Unary/isoperationtype.jl")
+include("Unary/isuniversal.jl")
+include("Unary/low.jl")
+include("Unary/norm.jl")
+include("Unary/radius.jl")
+include("Unary/rand.jl")
+include("Unary/rectify.jl")
+include("Unary/reflect.jl")
+include("Unary/surface.jl")
+include("Unary/vertices_list.jl")
+include("Unary/vertices.jl")
+include("Unary/volume.jl")
+
+include("Mixed/affine_map.jl")
+include("Mixed/exponential_map.jl")
+include("Mixed/in.jl")
+include("Mixed/is_interior_point.jl")
+include("Mixed/linear_map.jl")
+include("Mixed/permute.jl")
+include("Mixed/project.jl")
+include("Mixed/sample.jl")
+include("Mixed/scale!.jl")
+include("Mixed/scale.jl")
+include("Mixed/support_function.jl")
+include("Mixed/support_vector.jl")
+include("Mixed/translate!.jl")
+include("Mixed/translate.jl")
+
+include("Binary/cartesian_product.jl")
+include("Binary/difference.jl")
+include("Binary/distance.jl")
+include("Binary/exact_sum.jl")
+include("Binary/intersection.jl")
+include("Binary/isapprox.jl")
+include("Binary/isdisjoint.jl")
+include("Binary/isequal.jl")
+include("Binary/isequivalent.jl")
+include("Binary/isstrictsubset.jl")
+include("Binary/issubset.jl")
+include("Binary/linear_combination.jl")
+include("Binary/minkowski_difference.jl")
+include("Binary/minkowski_sum.jl")
+
+end  # module

src/API/Binary/cartesian_product.jl

@@ -0,0 +1,23 @@
+"""
+    cartesian_product(X::LazySet, Y::LazySet)
+
+Compute the Cartesian product of two sets.
+
+### Input
+
+- `X` -- set
+- `Y` -- set
+
+### Output
+
+A set representing the Cartesian product ``X × Y``.
+
+### Notes
+
+The Cartesian product of two sets ``X`` and ``Y`` is defined as
+
+```math
+    X × Y = \\{[x, y] \\mid x ∈ X, y ∈ Y\\}.
+```
+"""
+function cartesian_product(::LazySet, ::LazySet) end

src/API/Binary/difference.jl

@@ -0,0 +1,23 @@
+"""
+    difference(X::LazySet, Y::LazySet)
+
+Compute the set difference of two sets.
+
+### Input
+
+- `X` -- set
+- `Y` -- set
+
+### Output
+
+A set representing the difference ``X ∖ Y``.
+
+### Notes
+
+The set difference is defined as:
+
+```math
+    X ∖ Y = \\{x \\mid x ∈ X \\text{ and } x ∉ Y \\}
+```
+"""
+function difference(::LazySet, ::LazySet) end

src/API/Binary/distance.jl

@@ -0,0 +1,25 @@
+"""
+    distance(X::LazySet, Y::LazySet; [p]::Real=2)
+
+Compute the standard distance (induced by the ``p``-norm) between two sets.
+
+### Input
+
+- `X` -- set
+- `Y` -- set
+- `p` -- (optional; default: `2`) value of the ``p``-norm
+
+### Output
+
+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,
+
+```math
+    \\inf_{x ∈ H_1, y ∈ H_2} \\{ d(x, y) \\}.
+```
+"""
+function distance(::LazySet, ::LazySet; p::Real=2) end

src/API/Binary/exact_sum.jl

@@ -0,0 +1,31 @@
+"""
+    exact_sum(X::LazySet, Y::LazySet)
+
+Compute the exact sum of two parametric sets.
+
+### Input
+
+- `X` -- parametric set
+- `Y` -- parametric set
+
+### Output
+
+A set representing the exact sum ``X ⊞ Y``.
+
+### Notes
+
+The convenience alias `⊞` is also available, which can be typed by
+`\\boxplus<tab>`.
+"""
+function exact_sum(::LazySet, ::LazySet) end
+
+"""
+    ⊞(X::LazySet, Y::LazySet)
+
+Convenience alias for the (concrete) `exact_sum` function.
+
+### Notes
+
+"`⊞`" can be typed by `\\boxplus<tab>`.
+"""
+const ⊞ = exact_sum