From 62635a2f60d65b771999f22afec80f04ca4ffc57 Mon Sep 17 00:00:00 2001 From: schillic Date: Sat, 4 Jan 2025 14:51:09 +0100 Subject: [PATCH 1/6] document convenience in-place functions for lazy binary operations --- docs/src/lib/lazy_operations/CartesianProduct.md | 1 + docs/src/lib/lazy_operations/ConvexHull.md | 1 + docs/src/lib/lazy_operations/Intersection.md | 1 + docs/src/lib/lazy_operations/MinkowskiSum.md | 1 + docs/src/lib/lazy_operations/UnionSet.md | 1 + src/LazyOperations/CartesianProductArray.jl | 8 ++++++++ src/LazyOperations/ConvexHullArray.jl | 8 ++++++++ src/LazyOperations/IntersectionArray.jl | 8 ++++++++ src/LazyOperations/MinkowskiSumArray.jl | 8 ++++++++ src/LazyOperations/UnionSetArray.jl | 8 ++++++++ 10 files changed, 45 insertions(+) diff --git a/docs/src/lib/lazy_operations/CartesianProduct.md b/docs/src/lib/lazy_operations/CartesianProduct.md index 519a873cf9..9f47ac7d80 100644 --- a/docs/src/lib/lazy_operations/CartesianProduct.md +++ b/docs/src/lib/lazy_operations/CartesianProduct.md @@ -38,6 +38,7 @@ Inherited from [`LazySet`](@ref): ```@docs CartesianProductArray +CartesianProduct! ×(::LazySet, ::LazySet...) *(::LazySet, ::LazySet...) dim(::CartesianProductArray) diff --git a/docs/src/lib/lazy_operations/ConvexHull.md b/docs/src/lib/lazy_operations/ConvexHull.md index d0e74a6257..4d098573f5 100644 --- a/docs/src/lib/lazy_operations/ConvexHull.md +++ b/docs/src/lib/lazy_operations/ConvexHull.md @@ -30,6 +30,7 @@ Inherited from [`LazySet`](@ref): ```@docs ConvexHullArray CHArray +ConvexHull! dim(::ConvexHullArray) ρ(::AbstractVector, ::ConvexHullArray) σ(::AbstractVector, ::ConvexHullArray) diff --git a/docs/src/lib/lazy_operations/Intersection.md b/docs/src/lib/lazy_operations/Intersection.md index d77fa336fd..80bff757d4 100644 --- a/docs/src/lib/lazy_operations/Intersection.md +++ b/docs/src/lib/lazy_operations/Intersection.md @@ -49,6 +49,7 @@ IntersectionCache ```@docs IntersectionArray +Intersection! ∩(::LazySet, ::LazySet...) dim(::IntersectionArray) σ(::AbstractVector, ::IntersectionArray) diff --git a/docs/src/lib/lazy_operations/MinkowskiSum.md b/docs/src/lib/lazy_operations/MinkowskiSum.md index 4ffa2da8fa..61581b4a3d 100644 --- a/docs/src/lib/lazy_operations/MinkowskiSum.md +++ b/docs/src/lib/lazy_operations/MinkowskiSum.md @@ -33,6 +33,7 @@ Inherited from [`LazySet`](@ref): ```@docs MinkowskiSumArray +MinkowskiSum! ⊕(::LazySet, ::LazySet...) +(::LazySet, ::LazySet...) dim(::MinkowskiSumArray) diff --git a/docs/src/lib/lazy_operations/UnionSet.md b/docs/src/lib/lazy_operations/UnionSet.md index fd2b13799b..d01fe0360a 100644 --- a/docs/src/lib/lazy_operations/UnionSet.md +++ b/docs/src/lib/lazy_operations/UnionSet.md @@ -24,6 +24,7 @@ vertices_list(::UnionSet) ```@docs UnionSetArray +UnionSet! dim(::UnionSetArray) array(::UnionSetArray) σ(::AbstractVector, ::UnionSetArray; algorithm="support_vector") diff --git a/src/LazyOperations/CartesianProductArray.jl b/src/LazyOperations/CartesianProductArray.jl index 62bb4cd4f4..e1a25153d1 100644 --- a/src/LazyOperations/CartesianProductArray.jl +++ b/src/LazyOperations/CartesianProductArray.jl @@ -29,6 +29,14 @@ function CartesianProductArray(n::Int=0, N::Type=Float64) return CartesianProductArray(arr) end +""" + CartesianProduct!(X, Y) + +Convenience function to compute the lazy Cartesian product and modify +`CartesianProductArray`s in-place. +""" +function CartesianProduct! end + """ ``` *(X::LazySet, Xs::LazySet...) diff --git a/src/LazyOperations/ConvexHullArray.jl b/src/LazyOperations/ConvexHullArray.jl index b859ece9ad..9009e82d2c 100644 --- a/src/LazyOperations/ConvexHullArray.jl +++ b/src/LazyOperations/ConvexHullArray.jl @@ -30,6 +30,14 @@ struct ConvexHullArray{N,S<:LazySet{N}} <: ConvexSet{N} array::Vector{S} end +""" + ConvexHull!(X, Y) + +Convenience function to compute the lazy convex hull and modify +`ConvexHullArray`s in-place. +""" +function ConvexHull! end + isoperationtype(::Type{<:ConvexHullArray}) = true # constructor for an empty hull with optional size hint and numeric type diff --git a/src/LazyOperations/IntersectionArray.jl b/src/LazyOperations/IntersectionArray.jl index e94df512ae..9a267dc415 100644 --- a/src/LazyOperations/IntersectionArray.jl +++ b/src/LazyOperations/IntersectionArray.jl @@ -23,6 +23,14 @@ struct IntersectionArray{N,S<:LazySet{N}} <: LazySet{N} array::Vector{S} end +""" + Intersection!(X, Y) + +Convenience function to compute the lazy intersection and modify +`IntersectionArray`s in-place. +""" +function Intersection! end + """ ∩(X::LazySet, Xs::LazySet...) ∩(Xs::Vector{<:LazySet}) diff --git a/src/LazyOperations/MinkowskiSumArray.jl b/src/LazyOperations/MinkowskiSumArray.jl index 2c91ba9209..2233535d11 100644 --- a/src/LazyOperations/MinkowskiSumArray.jl +++ b/src/LazyOperations/MinkowskiSumArray.jl @@ -24,6 +24,14 @@ struct MinkowskiSumArray{N,S<:LazySet{N}} <: LazySet{N} array::Vector{S} end +""" + MinkowskiSum!(X, Y) + +Convenience function to compute the lazy Minkowski sum and modify +`MinkowskiSumArray`s in-place. +""" +function MinkowskiSum! end + """ +(X::LazySet, Xs::LazySet...) +(Xs::Vector{<:LazySet}) diff --git a/src/LazyOperations/UnionSetArray.jl b/src/LazyOperations/UnionSetArray.jl index 0b7902909b..72becfeba2 100644 --- a/src/LazyOperations/UnionSetArray.jl +++ b/src/LazyOperations/UnionSetArray.jl @@ -18,6 +18,14 @@ struct UnionSetArray{N,S<:LazySet{N}} <: LazySet{N} array::Vector{S} end +""" + UnionSet!(X, Y) + +Convenience function to compute the lazy union and modify `UnionSetArray`s +in-place. +""" +function UnionSet! end + isoperationtype(::Type{<:UnionSetArray}) = true isconvextype(::Type{<:UnionSetArray}) = false From 7dbfb3c6e9700c54575784aa846a18405a02c8b3 Mon Sep 17 00:00:00 2001 From: schillic Date: Sat, 4 Jan 2025 14:52:58 +0100 Subject: [PATCH 2/6] document LazySets module --- docs/src/lib/interfaces/overview.md | 8 ++++++++ src/LazySets.jl | 5 +++++ 2 files changed, 13 insertions(+) diff --git a/docs/src/lib/interfaces/overview.md b/docs/src/lib/interfaces/overview.md index 65ea74e1a7..b6449fa523 100644 --- a/docs/src/lib/interfaces/overview.md +++ b/docs/src/lib/interfaces/overview.md @@ -1,5 +1,13 @@ # Overview +```@meta +CurrentModule = LazySets +``` + +```@docs +LazySets +``` + This section of the manual describes the interfaces for different set types. Every set that fits the description of an interface should also implement it. This helps in several ways: diff --git a/src/LazySets.jl b/src/LazySets.jl index 1224303c2c..01650bb3c9 100644 --- a/src/LazySets.jl +++ b/src/LazySets.jl @@ -1,3 +1,8 @@ +""" + LazySets + +Scalable symbolic-numeric set computations in Julia. +""" module LazySets using Reexport From acf399ccd3249c79580231e1f80c26e33ab5ab5e Mon Sep 17 00:00:00 2001 From: schillic Date: Sat, 4 Jan 2025 15:08:18 +0100 Subject: [PATCH 3/6] document 'neutral' and 'absorbing' --- docs/src/lib/utils.md | 9 ++++++++- src/Utils/macros.jl | 14 ++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/src/lib/utils.md b/docs/src/lib/utils.md index 8fadbf444a..0530b4c2e4 100644 --- a/docs/src/lib/utils.md +++ b/docs/src/lib/utils.md @@ -4,7 +4,14 @@ CurrentModule = LazySets # Utilities -## Macros +## Array set types + +```@docs +neutral +absorbing +``` + +### Internal helper macros ```@docs @neutral diff --git a/src/Utils/macros.jl b/src/Utils/macros.jl index 631141676d..bc150ff9f7 100644 --- a/src/Utils/macros.jl +++ b/src/Utils/macros.jl @@ -1,3 +1,10 @@ +""" + neutral(T::Type{<:LazySet}) + +Get the neutral set type for a lazy binary operation, if any. +""" +function neutral end + """ @neutral(SET, NEUT) @@ -68,6 +75,13 @@ macro neutral(SET, NEUT) return nothing end +""" + absorbing(T::Type{<:LazySet}) + +Get the absorbing set type for a lazy binary operation, if any. +""" +function absorbing end + """ @absorbing(SET, ABS) From 496bbbd9a8cdb60d32c813978e810667780d33a1 Mon Sep 17 00:00:00 2001 From: schillic Date: Sat, 4 Jan 2025 15:08:26 +0100 Subject: [PATCH 4/6] document 'flatten' --- docs/src/lib/utils.md | 1 + src/Interfaces/AbstractArraySet.jl | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+) diff --git a/docs/src/lib/utils.md b/docs/src/lib/utils.md index 0530b4c2e4..cfefb7de73 100644 --- a/docs/src/lib/utils.md +++ b/docs/src/lib/utils.md @@ -7,6 +7,7 @@ CurrentModule = LazySets ## Array set types ```@docs +flatten neutral absorbing ``` diff --git a/src/Interfaces/AbstractArraySet.jl b/src/Interfaces/AbstractArraySet.jl index 06ed8f01e0..85ab3a2600 100644 --- a/src/Interfaces/AbstractArraySet.jl +++ b/src/Interfaces/AbstractArraySet.jl @@ -24,6 +24,25 @@ function Base.iterate(X::AbstractArraySet, state=1) return iterate(array(X), state) end +""" + flatten(X::LazySets.AbstractArraySet) + +Flatten an array set, i.e., resolve potential nestings. + +### Examples + +```jldoctest +julia> E1 = EmptySet(1); E2 = EmptySet(2); E3 = EmptySet(3); + +julia> X = MinkowskiSumArray([E1, MinkowskiSumArray([E2, E2])]) +MinkowskiSumArray{Float64, LazySet{Float64}}(LazySet{Float64}[∅(1), MinkowskiSumArray{Float64, ∅}(∅[∅(2), ∅(2)])]) + +julia> flatten(X) +MinkowskiSumArray{Float64, ∅}(∅[∅(1), ∅(2), ∅(2)]) +``` +""" +function flatten end + function flatten!(arr, X, bin_op) if X isa bin_op flatten!(arr, first(X), bin_op) From f1ae6e60dbdf38e6a65819b9125812d049907b99 Mon Sep 17 00:00:00 2001 From: schillic Date: Sat, 4 Jan 2025 15:19:08 +0100 Subject: [PATCH 5/6] document in-place 'convex_hull' --- .../concrete_binary_operations/convex_hull.md | 3 +- src/ConcreteOperations/convex_hull.jl | 34 +++++++++++++++---- 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/docs/src/lib/concrete_binary_operations/convex_hull.md b/docs/src/lib/concrete_binary_operations/convex_hull.md index 3b43287112..78707448a1 100644 --- a/docs/src/lib/concrete_binary_operations/convex_hull.md +++ b/docs/src/lib/concrete_binary_operations/convex_hull.md @@ -10,6 +10,7 @@ CurrentModule = LazySets # Convex Hull ```@docs -convex_hull(::Vector{VN}) where {N, VN<:AbstractVector{N}} +convex_hull(::Vector{<:AbstractVector}) +convex_hull!(::Vector{<:AbstractVector}) monotone_chain! ``` diff --git a/src/ConcreteOperations/convex_hull.jl b/src/ConcreteOperations/convex_hull.jl index f908553261..5c02fa7516 100644 --- a/src/ConcreteOperations/convex_hull.jl +++ b/src/ConcreteOperations/convex_hull.jl @@ -66,8 +66,8 @@ function _convex_hull_set(vlist; n::Int=(isempty(vlist) ? -1 : length(vlist[1])) end """ - convex_hull(points::Vector{VN}; [algorithm]=nothing, [backend]=nothing, - [solver]=nothing) where {N, VN<:AbstractVector{N}} + convex_hull(points::Vector{<:AbstractVector}; [algorithm]=nothing, + [backend]=nothing, [solver]=nothing) Compute the convex hull of a list of points. @@ -111,7 +111,7 @@ The higher-dimensional case is treated using the concrete polyhedra library ### Notes -For the in-place version use `convex_hull!` instead of `convex_hull`. +For the in-place version use [`convex_hull!(::Vector{<:AbstractVector})`](@ref). ### Examples @@ -126,14 +126,34 @@ julia> typeof(hull) Vector{Vector{Float64}} (alias for Array{Array{Float64, 1}, 1}) ``` """ -function convex_hull(points::Vector{VN}; algorithm=nothing, backend=nothing, - solver=nothing) where {N,VN<:AbstractVector{N}} +function convex_hull(points::Vector{<:AbstractVector}; algorithm=nothing, + backend=nothing, solver=nothing) return convex_hull!(copy(points); algorithm=algorithm, backend=backend, solver=solver) end -function convex_hull!(points::Vector{VN}; algorithm=nothing, backend=nothing, - solver=nothing) where {N,VN<:AbstractVector{N}} +""" + convex_hull!(points::Vector{<:AbstractVector}; [algorithm]=nothing, + [backend]=nothing, [solver]=nothing) + +Compute the convex hull of a list of points in-place. + +### Input + +- `points` -- list of points (modified in-place) +- `algorithm` -- (optional, default: `nothing`) the convex-hull algorithm; see + below for valid options +- `backend` -- (optional, default: `nothing`) polyhedral computation backend + for higher-dimensional point sets +- `solver` -- (optional, default: `nothing`) the linear-programming solver + used in the backend + +### Notes + +See [`convex_hull(::Vector{<:AbstractVector})`](@ref) for more details. +""" +function convex_hull!(points::Vector{<:AbstractVector}; algorithm=nothing, + backend=nothing, solver=nothing) m = length(points) # zero or one point From 2181285fd9761f8c70db6456decb5d094f174adf Mon Sep 17 00:00:00 2001 From: schillic Date: Sat, 4 Jan 2025 15:34:08 +0100 Subject: [PATCH 6/6] document 'get_rows','get_column','get_columns' --- .../src/lib/lazy_operations/ExponentialMap.md | 3 ++ src/LazyOperations/ExponentialMap.jl | 53 ++++++++++++++++++- 2 files changed, 55 insertions(+), 1 deletion(-) diff --git a/docs/src/lib/lazy_operations/ExponentialMap.md b/docs/src/lib/lazy_operations/ExponentialMap.md index cba1707c41..ee6889fd10 100644 --- a/docs/src/lib/lazy_operations/ExponentialMap.md +++ b/docs/src/lib/lazy_operations/ExponentialMap.md @@ -34,6 +34,9 @@ Inherited from [`AbstractAffineMap`](@ref): SparseMatrixExp *(::SparseMatrixExp, ::LazySet) get_row(::SparseMatrixExp, ::Int) +get_rows(::SparseMatrixExp, ::AbstractArray{Int}) +get_column(::SparseMatrixExp, ::Int) +get_columns(::SparseMatrixExp, ::AbstractArray{Int}) ``` ## [Exponential projection map (ExponentialProjectionMap)](@id def_ExponentialProjectionMap) diff --git a/src/LazyOperations/ExponentialMap.jl b/src/LazyOperations/ExponentialMap.jl index a8399dd81a..87a1be0605 100644 --- a/src/LazyOperations/ExponentialMap.jl +++ b/src/LazyOperations/ExponentialMap.jl @@ -86,6 +86,23 @@ function size(spmexp::SparseMatrixExp, ax::Int) return size(spmexp.M, ax) end +""" + get_column(spmexp::SparseMatrixExp{N}, j::Int; + [backend]=get_exponential_backend()) where {N} + +Compute a single column of a sparse matrix exponential. + +### Input + +- `spmexp` -- sparse matrix exponential +- `j` -- column index +- `backend` -- (optional; default: `get_exponential_backend()`) exponentiation + backend + +### Output + +A column vector corresponding to the `j`th column of the matrix exponential. +""" function get_column(spmexp::SparseMatrixExp{N}, j::Int; backend=get_exponential_backend()) where {N} n = size(spmexp, 1) @@ -94,6 +111,23 @@ function get_column(spmexp::SparseMatrixExp{N}, j::Int; return _expmv(backend, one(N), spmexp.M, aux) end +""" + get_columns(spmexp::SparseMatrixExp{N}, J::AbstractArray; + [backend]=get_exponential_backend()) where {N} + +Compute multiple columns of a sparse matrix exponential. + +### Input + +- `spmexp` -- sparse matrix exponential +- `J` -- list of column indices +- `backend` -- (optional; default: `get_exponential_backend()`) exponentiation + backend + +### Output + +A matrix with one column vector for each entry in `J`. +""" function get_columns(spmexp::SparseMatrixExp{N}, J::AbstractArray; backend=get_exponential_backend()) where {N} n = size(spmexp, 1) @@ -111,7 +145,7 @@ end get_row(spmexp::SparseMatrixExp{N}, i::Int; [backend]=get_exponential_backend()) where {N} -Return a single row of a sparse matrix exponential. +Compute a single row of a sparse matrix exponential. ### Input @@ -138,6 +172,23 @@ function get_row(spmexp::SparseMatrixExp{N}, i::Int; return transpose(_expmv(backend, one(N), transpose(spmexp.M), aux)) end +""" + get_rows(spmexp::SparseMatrixExp{N}, I::AbstractArray; + [backend]=get_exponential_backend()) where {N} + +Compute multiple rows of a sparse matrix exponential. + +### Input + +- `spmexp` -- sparse matrix exponential +- `I` -- list of row indices +- `backend` -- (optional; default: `get_exponential_backend()`) exponentiation + backend + +### Output + +A transposed matrix with one (transposed) column vector for each entry in `I`. +""" function get_rows(spmexp::SparseMatrixExp{N}, I::AbstractArray{Int}; backend=get_exponential_backend()) where {N} n = size(spmexp, 1)