Merge pull request #3574 from JuliaReach/schillic/SSPZ

Update `AbstractPolynomialZonotope` interface functions; add `AbstractSparsePolynomialZonotope` interface

docs/make.jl

@@ -50,6 +50,7 @@ makedocs(; sitename="LazySets.jl",
                                                       "lib/interfaces/AbstractSingleton.md",
                                                       "lib/interfaces/AbstractAffineMap.md",
                                                       "lib/interfaces/AbstractPolynomialZonotope.md",
+                                                      "lib/interfaces/AbstractSparsePolynomialZonotope.md",
                                                       "lib/interfaces/AbstractBallp.md"
                                                       #
                                                       ],

docs/src/lib/interfaces/AbstractPolynomialZonotope.md

@@ -41,5 +41,3 @@ order(::AbstractPolynomialZonotope)
 ## Implementations
 
 * [Dense polynomial zonotope (DensePolynomialZonotope)](@ref def_DensePolynomialZonotope)
-* [Sparse polynomial zonotope (SparsePolynomialZonotope)](@ref def_SparsePolynomialZonotope)
-* [Simplified sparse polynomial zonotope (SimpleSparsePolynomialZonotope)](@ref def_SimpleSparsePolynomialZonotope)

docs/src/lib/interfaces/AbstractSparsePolynomialZonotope.md

@@ -0,0 +1,33 @@
+```@contents
+Pages = ["AbstractSparsePolynomialZonotope.md"]
+Depth = 3
+```
+
+```@meta
+CurrentModule = LazySets
+```
+
+# [Sparse polynomial zonotope sets (AbstractSparsePolynomialZonotope)](@id def_AbstractSparsePolynomialZonotope)
+
+```@docs
+AbstractSparsePolynomialZonotope
+```
+
+This interface requires to implement the following functions:
+
+```@docs
+expmat(::AbstractSparsePolynomialZonotope)
+genmat_dep(::AbstractSparsePolynomialZonotope)
+genmat_indep(::AbstractSparsePolynomialZonotope)
+```
+
+This interface defines the following functions:
+
+```@docs
+nparams(::AbstractSparsePolynomialZonotope)
+```
+
+## Implementations
+
+* [Sparse polynomial zonotope (SparsePolynomialZonotope)](@ref def_SparsePolynomialZonotope)
+* [Simplified sparse polynomial zonotope (SimpleSparsePolynomialZonotope)](@ref def_SimpleSparsePolynomialZonotope)

docs/src/lib/sets/SimpleSparsePolynomialZonotope.md

@@ -16,7 +16,6 @@ convex_hull(::SimpleSparsePolynomialZonotope)
 expmat(::SimpleSparsePolynomialZonotope)
 genmat(::SimpleSparsePolynomialZonotope)
 ngens(::SimpleSparsePolynomialZonotope)
-nparams(::SimpleSparsePolynomialZonotope)
 rand(::Type{SimpleSparsePolynomialZonotope})
 remove_redundant_generators(::SimpleSparsePolynomialZonotope)
 linear_map(::AbstractMatrix, ::SimpleSparsePolynomialZonotope)
@@ -36,4 +35,9 @@ PolynomialZonotope
 
 Inherited from [`AbstractPolynomialZonotope`](@ref):
 * [`dim`](@ref dim(::AbstractPolynomialZonotope))
-* [`order`](@ref dim(::AbstractPolynomialZonotope))
+* [`order`](@ref order(::AbstractPolynomialZonotope))
+
+Inherited from [`AbstractSparsePolynomialZonotope`](@ref):
+* [`ngens_dep`](@ref ngens_dep(::AbstractPolynomialZonotope))
+* [`ngens_indep`](@ref ngens_indep(::AbstractPolynomialZonotope))
+* [`nparams`](@ref nparams(::AbstractPolynomialZonotope))

docs/src/lib/sets/SparsePolynomialZonotope.md

@@ -11,9 +11,6 @@ expmat(::SparsePolynomialZonotope)
 genmat_dep(::SparsePolynomialZonotope)
 genmat_indep(::SparsePolynomialZonotope)
 indexvector(::SparsePolynomialZonotope)
-ngens_dep(::SparsePolynomialZonotope)
-ngens_indep(::SparsePolynomialZonotope)
-nparams(::SparsePolynomialZonotope)
 polynomial_order(::SparsePolynomialZonotope)
 rand(::Type{SparsePolynomialZonotope})
 remove_redundant_generators(::SparsePolynomialZonotope)
@@ -26,4 +23,10 @@ translate(::SparsePolynomialZonotope, ::AbstractVector)
 
 Inherited from [`AbstractPolynomialZonotope`](@ref):
 * [`dim`](@ref dim(::AbstractPolynomialZonotope))
-* [`order`](@ref dim(::AbstractPolynomialZonotope))
+* [`ngens`](@ref ngens(::AbstractPolynomialZonotope))
+* [`order`](@ref order(::AbstractPolynomialZonotope))
+
+Inherited from [`AbstractSparsePolynomialZonotope`](@ref):
+* [`ngens_dep`](@ref ngens_dep(::AbstractPolynomialZonotope))
+* [`ngens_indep`](@ref ngens_indep(::AbstractPolynomialZonotope))
+* [`nparams`](@ref nparams(::AbstractPolynomialZonotope))

src/Interfaces/AbstractPolynomialZonotope.jl

@@ -1,10 +1,8 @@
 export AbstractPolynomialZonotope,
        center,
-       polynomial_order,
+       ngens, ngens_dep, ngens_indep,
        order,
-       ngens,
-       ngens_dep,
-       ngens_indep
+       polynomial_order
 
 """
     AbstractPolynomialZonotope{N} <: LazySet{N}
@@ -19,20 +17,19 @@ Every concrete `AbstractPolynomialZonotope` must define the following functions:
 
 - `center(::AbstractPolynomialZonotope)` -- return the center
 
-- `order(::AbstractPolynomialZonotope)` -- return the order
-
 - `polynomial_order(::AbstractPolynomialZonotope)` -- return the polynomial order
 
 - `ngens_dep` -- return the number of dependent generators
 
 - `ngens_indep` -- return the number of independent generators
 
+The subtypes of `AbstractPolynomialZonotope` (including abstract interfaces):
+
 ```jldoctest; setup = :(using LazySets: subtypes)
 julia> subtypes(AbstractPolynomialZonotope)
-3-element Vector{Any}:
+2-element Vector{Any}:
+ AbstractSparsePolynomialZonotope
  DensePolynomialZonotope
- SimpleSparsePolynomialZonotope
- SparsePolynomialZonotope
 ```
 """
 abstract type AbstractPolynomialZonotope{N} <: LazySet{N} end

src/Interfaces/AbstractSparsePolynomialZonotope.jl

@@ -0,0 +1,133 @@
+export AbstractSparsePolynomialZonotope,
+       expmat,
+       genmat_dep, genmat_indep,
+       nparams
+
+"""
+    AbstractSparsePolynomialZonotope{N} <: AbstractPolynomialZonotope{N}
+
+Abstract type for sparse polynomial zonotope sets.
+
+### Notes
+
+Every concrete `AbstractSparsePolynomialZonotope` must define the following functions:
+
+- `expmat(::AbstractSparsePolynomialZonotope)` -- return the exponent matrix (sparse PZ only)
+
+- `genmat_dep(::AbstractSparsePolynomialZonotope)` -- return the matrix of dependent generators
+
+- `genmat_indep(::AbstractSparsePolynomialZonotope)` -- return the matrix of independent generators
+
+The subtypes of `AbstractSparsePolynomialZonotope` (including abstract interfaces):
+
+```jldoctest; setup = :(using LazySets: subtypes)
+julia> subtypes(AbstractSparsePolynomialZonotope)
+2-element Vector{Any}:
+ SimpleSparsePolynomialZonotope
+ SparsePolynomialZonotope
+```
+"""
+abstract type AbstractSparsePolynomialZonotope{N} <: AbstractPolynomialZonotope{N} end
+
+"""
+    expmat(P::AbstractSparsePolynomialZonotope)
+
+Return the matrix of exponents of a sparse polynomial zonotope.
+
+### Input
+
+- `P` -- sparse polynomial zonotope
+
+### Output
+
+The matrix of exponents, where each column is a multidegree.
+
+### Notes
+
+In the exponent matrix, each row corresponds to a parameter (``αₖ`` in the
+definition) and each column corresponds to a monomial.
+"""
+function expmat(::AbstractSparsePolynomialZonotope) end
+
+"""
+    genmat_dep(P::AbstractSparsePolynomialZonotope)
+
+Return the matrix of dependent generators of a sparse polynomial zonotope.
+
+### Input
+
+- `P` -- sparse polynomial zonotope
+
+### Output
+
+The matrix of dependent generators.
+"""
+function genmat_dep(::AbstractSparsePolynomialZonotope) end
+
+"""
+    genmat_indep(P::AbstractSparsePolynomialZonotope)
+
+Return the matrix of independent generators of a sparse polynomial zonotope.
+
+### Input
+
+- `P` -- sparse polynomial zonotope
+
+### Output
+
+The matrix of independent generators.
+"""
+function genmat_indep(::AbstractSparsePolynomialZonotope) end
+
+function ngens_dep(P::AbstractSparsePolynomialZonotope)
+    return size(genmat_dep(P), 2)
+end
+
+function ngens_indep(P::AbstractSparsePolynomialZonotope)
+    return size(genmat_indep(P), 2)
+end
+
+"""
+    nparams(P::AbstractSparsePolynomialZonotope)
+
+Return the number of dependent parameters in the polynomial representation of a
+sparse polynomial zonotope.
+
+### Input
+
+- `P` -- sparse polynomial zonotope
+
+### Output
+
+The number of dependent parameters in the polynomial representation.
+
+### Notes
+
+This number corresponds to the number of rows in the exponent matrix.
+"""
+function nparams(P::AbstractSparsePolynomialZonotope)
+    return size(expmat(P), 1)
+end
+
+function _remove_redundant_generators_polyzono(c, G, E)
+    Gnew = Matrix{eltype(G)}(undef, size(G, 1), 0)
+    Enew = Matrix{eltype(E)}(undef, size(E, 1), 0)
+    cnew = copy(c)
+
+    visited_exps = Dict{Vector{Int},Int}()
+    @inbounds for (gi, ei) in zip(eachcol(G), eachcol(E))
+        all(isapproxzero, gi) && continue
+        if iszero(ei)
+            cnew += gi
+        elseif haskey(visited_exps, ei) # repeated exponent
+            idx = visited_exps[ei]
+            Gnew[:, idx] += gi
+        else
+            Gnew = hcat(Gnew, gi)
+            Enew = hcat(Enew, ei)
+            visited_exps[ei] = size(Enew, 2)
+        end
+    end
+
+    return cnew, Gnew, Enew
+end

src/LazySets.jl

@@ -76,6 +76,7 @@ include("Interfaces/LazySet.jl")
 include("Interfaces/ConvexSet.jl")
 # include("Interfaces/AbstractStar.jl")
 include("Interfaces/AbstractPolynomialZonotope.jl")
+include("Interfaces/AbstractSparsePolynomialZonotope.jl")
 include("Interfaces/AbstractPolyhedron.jl")
 include("Sets/HalfSpace.jl")  # must come before AbstractPolyhedron_functions
 include("Interfaces/AbstractPolyhedron_functions.jl")
@@ -145,7 +146,6 @@ include("Sets/SimpleSparsePolynomialZonotope/SimpleSparsePolynomialZonotopeModul
 @reexport using ..SimpleSparsePolynomialZonotopeModule: SimpleSparsePolynomialZonotope,
                                                         SSPZ,
                                                         quadratic_map
-using ..SimpleSparsePolynomialZonotopeModule: _remove_redundant_generators_polyzono
 
 """
     PolynomialZonotope = SimpleSparsePolynomialZonotope

src/Sets/SimpleSparsePolynomialZonotope/SimpleSparsePolynomialZonotope.jl

@@ -2,7 +2,7 @@
     SimpleSparsePolynomialZonotope{N, VN<:AbstractVector{N},
                                    MN<:AbstractMatrix{N},
                                    ME<:AbstractMatrix{Int}}
-        <: AbstractPolynomialZonotope{N}
+        <: AbstractSparsePolynomialZonotope{N}
 
 Type that represents a sparse polynomial zonotope that is *simple* in the sense
 that there is no distinction between independent and dependent generators.
@@ -37,7 +37,7 @@ JuliaReach and JuliaIntervals Days 3, 2021.
 struct SimpleSparsePolynomialZonotope{N,VN<:AbstractVector{N},
                                       MN<:AbstractMatrix{N},
                                       ME<:AbstractMatrix{Int}} <:
-       AbstractPolynomialZonotope{N}
+       AbstractSparsePolynomialZonotope{N}
     c::VN
     G::MN
     E::ME

src/Sets/SimpleSparsePolynomialZonotope/SimpleSparsePolynomialZonotopeModule.jl

@@ -2,15 +2,16 @@ module SimpleSparsePolynomialZonotopeModule
 
 using Reexport
 
-using ..LazySets: AbstractPolynomialZonotope
+using ..LazySets: AbstractSparsePolynomialZonotope, ngens_dep, nparams,
+                  _remove_redundant_generators_polyzono
 using Random: AbstractRNG, GLOBAL_RNG
 using ReachabilityBase.Distribution: reseed!
 using ReachabilityBase.Comparison: isapproxzero
 using LinearAlgebra: dot
 
 @reexport import ..API: convex_hull, center, isoperationtype, rand, linear_map
-@reexport import ..LazySets: expmat, genmat, ngens, nparams, polynomial_order,
-                             remove_redundant_generators
+@reexport import ..LazySets: expmat, genmat, genmat_dep, genmat_indep, ngens,
+                             polynomial_order, remove_redundant_generators
 @reexport using ..API
 
 export SimpleSparsePolynomialZonotope,
@@ -26,11 +27,13 @@ include("center.jl")
 include("convex_hull.jl")
 include("genmat.jl")
 include("isoperationtype.jl")
+include("genmat_dep.jl")
+include("genmat_indep.jl")
 include("ngens.jl")
+include("ngens_indep.jl")
 include("polynomial_order.jl")
 include("remove_redundant_generators.jl")
 include("expmat.jl")
-include("nparams.jl")
 include("quadratic_map.jl")
 include("rand.jl")
 include("linear_map.jl")

src/Sets/SimpleSparsePolynomialZonotope/genmat_dep.jl

@@ -0,0 +1 @@
+genmat_dep(P::SSPZ) = P.G

src/Sets/SimpleSparsePolynomialZonotope/genmat_indep.jl

@@ -0,0 +1 @@
+genmat_indep(P::SSPZ{N}) where {N} = Matrix{N}(undef, dim(P), 0)

src/Sets/SimpleSparsePolynomialZonotope/ngens.jl

@@ -16,4 +16,4 @@ The number of generators of `P`.
 This number corresponds to the number of monomials in the polynomial
 representation of `P`.
 """
-ngens(P::SSPZ) = size(P.G, 2)
+ngens(P::SSPZ) = ngens_dep(P)

src/Sets/SimpleSparsePolynomialZonotope/ngens_indep.jl

@@ -0,0 +1 @@
+ngens_indep(::SSPZ) = 0

src/Sets/SimpleSparsePolynomialZonotope/remove_redundant_generators.jl

@@ -32,26 +32,3 @@ function remove_redundant_generators(S::SimpleSparsePolynomialZonotope)
 
     return SimpleSparsePolynomialZonotope(c, G, E)
 end
-
-function _remove_redundant_generators_polyzono(c, G, E)
-    Gnew = Matrix{eltype(G)}(undef, size(G, 1), 0)
-    Enew = Matrix{eltype(E)}(undef, size(E, 1), 0)
-    cnew = copy(c)
-
-    visited_exps = Dict{Vector{Int},Int}()
-    @inbounds for (gi, ei) in zip(eachcol(G), eachcol(E))
-        all(isapproxzero, gi) && continue
-        if iszero(ei)
-            cnew += gi
-        elseif haskey(visited_exps, ei) # repeated exponent
-            idx = visited_exps[ei]
-            Gnew[:, idx] += gi
-        else
-            Gnew = hcat(Gnew, gi)
-            Enew = hcat(Enew, ei)
-            visited_exps[ei] = size(Enew, 2)
-        end
-    end
-
-    return cnew, Gnew, Enew
-end