From a641b6b7b9c418654696bc8ce5e1a0240750a654 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beno=C3=AEt=20Legat?= Date: Tue, 8 Dec 2020 18:30:06 +0100 Subject: [PATCH] Document certificates (#179) --- docs/src/constraints.md | 19 +++++- src/Certificate/Certificate.jl | 73 +++++++++++++++++++++ src/Certificate/sparse/monomial_sparsity.jl | 24 ++++--- src/Certificate/sparse/sign.jl | 10 +++ src/Certificate/sparse/sparse_putinar.jl | 20 ++++++ src/Certificate/sparse/variable_sparsity.jl | 7 ++ 6 files changed, 143 insertions(+), 10 deletions(-) diff --git a/docs/src/constraints.md b/docs/src/constraints.md index 36b9cc285..6a60a9cba 100644 --- a/docs/src/constraints.md +++ b/docs/src/constraints.md @@ -285,9 +285,26 @@ Approximations of the cone of copositive matrices: SumOfSquares.CopositiveInner ``` -Sparsity certificates: +Types of sparsity ```@docs +SumOfSquares.Certificate.VariableSparsity SumOfSquares.Certificate.MonomialSparsity +SumOfSquares.Certificate.SignSymmetry +``` + +Ideal certificates: +```@docs +SumOfSquares.Certificate.MaxDegree +SumOfSquares.Certificate.FixedBasis +SumOfSquares.Certificate.Newton +SumOfSquares.Certificate.Remainder +SumOfSquares.Certificate.SparseIdeal +``` + +Preorder certificates: +```@docs +SumOfSquares.Certificate.Putinar +SumOfSquares.Certificate.SparsePreorder ``` Attributes diff --git a/src/Certificate/Certificate.jl b/src/Certificate/Certificate.jl index f5b255f92..06afec8ed 100644 --- a/src/Certificate/Certificate.jl +++ b/src/Certificate/Certificate.jl @@ -56,6 +56,21 @@ abstract type AbstractCertificate end abstract type AbstractPreorderCertificate <: AbstractCertificate end abstract type AbstractIdealCertificate <: AbstractCertificate end +""" + struct Putinar{IC <: AbstractIdealCertificate, CT <: SumOfSquares.SOSLikeCone, BT <: MB.AbstractPolynomialBasis} <: AbstractPreorderCertificate + ideal_certificate::IC + cone::CT + basis::Type{BT} + maxdegree::Int + end + +The `Putinar` certificate ensures the nonnegativity of `p(x)` for all `x` such that +`g_i(x) >= 0` and `h_i(x) = 0` by exhibiting Sum-of-Squares polynomials `σ_i(x)` +such that `p(x) - ∑ σ_i(x) g_i(x)` is guaranteed to be nonnegativity for all `x` +such that `h_i(x) = 0`. +The polynomials `σ_i(x)` are search over `cone` with a basis of type `basis` such that +the degree of `σ_i(x) g_i(x)` does not exceed `maxdegree`. +""" struct Putinar{IC <: AbstractIdealCertificate, CT <: SumOfSquares.SOSLikeCone, BT <: MB.AbstractPolynomialBasis} <: AbstractPreorderCertificate ideal_certificate::IC cone::CT @@ -119,6 +134,20 @@ SumOfSquares.matrix_cone_type(::Type{<:SimpleIdealCertificate{CT}}) where {CT} = zero_basis(certificate::SimpleIdealCertificate) = MB.MonomialBasis zero_basis_type(::Type{<:SimpleIdealCertificate{CT, BT}}) where {CT, BT} = MB.MonomialBasis +""" + struct MaxDegree{CT <: SumOfSquares.SOSLikeCone, BT <: MB.AbstractPolynomialBasis} <: SimpleIdealCertificate{CT, BT} + cone::CT + basis::Type{BT} + maxdegree::Int + end + +The `MaxDegree` certificate ensures the nonnegativity of `p(x)` for all `x` such that +`h_i(x) = 0` by exhibiting a Sum-of-Squares polynomials `σ(x)` +such that `p(x) - σ(x)` is guaranteed to be zero for all `x` +such that `h_i(x) = 0`. +The polynomial `σ(x)` is search over `cone` with a basis of type `basis` such that +the degree of `σ(x)` does not exceed `maxdegree`. +""" struct MaxDegree{CT <: SumOfSquares.SOSLikeCone, BT <: MB.AbstractPolynomialBasis} <: SimpleIdealCertificate{CT, BT} cone::CT basis::Type{BT} @@ -131,6 +160,18 @@ function get(::Type{MaxDegree{CT, BT}}, ::GramBasisType) where {CT, BT} return BT end +""" + struct FixedBasis{CT <: SumOfSquares.SOSLikeCone, BT <: MB.AbstractPolynomialBasis} <: SimpleIdealCertificate{CT, BT} + cone::CT + basis::BT + end + +The `FixedBasis` certificate ensures the nonnegativity of `p(x)` for all `x` such that +`h_i(x) = 0` by exhibiting a Sum-of-Squares polynomials `σ(x)` +such that `p(x) - σ(x)` is guaranteed to be zero for all `x` +such that `h_i(x) = 0`. +The polynomial `σ(x)` is search over `cone` with basis `basis`. +""" struct FixedBasis{CT <: SumOfSquares.SOSLikeCone, BT <: MB.AbstractPolynomialBasis} <: SimpleIdealCertificate{CT, BT} cone::CT basis::BT @@ -142,6 +183,22 @@ function get(::Type{FixedBasis{CT, BT}}, ::GramBasisType) where {CT, BT} return BT end +""" + struct Newton{CT <: SumOfSquares.SOSLikeCone, BT <: MB.AbstractPolynomialBasis, NPT <: Tuple} <: SimpleIdealCertificate{CT, BT} + cone::CT + basis::Type{BT} + variable_groups::NPT + end + +The `Newton` certificate ensures the nonnegativity of `p(x)` for all `x` such that +`h_i(x) = 0` by exhibiting a Sum-of-Squares polynomials `σ(x)` +such that `p(x) - σ(x)` is guaranteed to be zero for all `x` +such that `h_i(x) = 0`. +The polynomial `σ(x)` is search over `cone` with a basis of type `basis` +chosen using the multipartite Newton polytope with parts `variable_groups`. +If `variable_groups = tuple()` then it falls back to the classical Newton polytope +with all variables in the same part. +""" struct Newton{CT <: SumOfSquares.SOSLikeCone, BT <: MB.AbstractPolynomialBasis, NPT <: Tuple} <: SimpleIdealCertificate{CT, BT} cone::CT basis::Type{BT} @@ -154,6 +211,22 @@ function get(::Type{<:Newton{CT, BT}}, ::GramBasisType) where {CT, BT} return BT end +""" + struct Remainder{GCT<:AbstractIdealCertificate} <: AbstractIdealCertificate + gram_certificate::GCT + end + +The `Remainder` certificate ensures the nonnegativity of `p(x)` for all `x` such that +`h_i(x) = 0` by guaranteeing the remainder of `p(x)` modulo the ideal generated by +`⟨h_i⟩` to be nonnegative for all `x` such that `h_i(x) = 0` using the certificate +`gram_certificate`. +For instance, if `gram_certificate` is [`SumOfSquares.Certificate.Newton`](@ref), +then the certificate `Remainder(gram_certificate)` will take the remainder before +computing the Newton polytope hence might generate a much smaller Newton polytope +hence a smaller basis and smaller semidefinite program. +However, this then corresponds to a lower degree of the hierarchy which might +be insufficient to find a certificate. +""" struct Remainder{GCT<:AbstractIdealCertificate} <: AbstractIdealCertificate gram_certificate::GCT end diff --git a/src/Certificate/sparse/monomial_sparsity.jl b/src/Certificate/sparse/monomial_sparsity.jl index 6d7458520..d0f7ccef5 100644 --- a/src/Certificate/sparse/monomial_sparsity.jl +++ b/src/Certificate/sparse/monomial_sparsity.jl @@ -2,20 +2,26 @@ const CEG = SumOfSquares.Certificate.ChordalExtensionGraph """ struct MonomialSparsity{C<:CEG.AbstractCompletion} <: Sparsity - k::Int completion::C + k::Int use_all_monomials::Bool end -Monomial or term sparsity as developed in []. +Monomial or term sparsity as developed in [WML20a, WML20b]. +The `completion` field should be `ClusterCompletion()` [default] for the block-closure or cluster completion [WML20a], +and `ChordalCompletion()` for chordal completion [WML20b]. +The integer `k` [default=0] corresponds to `Σ_k` defined in [(3.2), WML20a] +and `k = 0` corresponds to `Σ_*` defined in [(3.3), WML20a]. +If `use_all_monomials` is `false` then some monomials of the basis +might be dropped from the basis if not needed. + +[WML20a] Wang, Jie, Victor Magron, and Jean-Bernard Lasserre. +*TSSOS: A Moment-SOS hierarchy that exploits term sparsity*. +arXiv preprint arXiv:1912.08899 (2020). -# [WML20a] Wang, Jie, Victor Magron, and Jean-Bernard Lasserre. -# *TSSOS: A Moment-SOS hierarchy that exploits term sparsity*. -# arXiv preprint arXiv:1912.08899 (2020). -# -# [WML20b] Wang, Jie, Victor Magron, and Jean-Bernard Lasserre. -# *Chordal-TSSOS: a moment-SOS hierarchy that exploits term sparsity with chordal extension*. -# arXiv preprint arXiv:2003.03210 (2020). +[WML20b] Wang, Jie, Victor Magron, and Jean-Bernard Lasserre. +*Chordal-TSSOS: a moment-SOS hierarchy that exploits term sparsity with chordal extension*. +arXiv preprint arXiv:2003.03210 (2020). """ struct MonomialSparsity{C<:CEG.AbstractCompletion} <: Sparsity completion::C diff --git a/src/Certificate/sparse/sign.jl b/src/Certificate/sparse/sign.jl index ca3a6fdaa..423fa5173 100644 --- a/src/Certificate/sparse/sign.jl +++ b/src/Certificate/sparse/sign.jl @@ -1,4 +1,14 @@ +""" + struct SignSymmetry <: Sparsity end + +Sign symmetry as developed in [Section III.C, L09]. + +[L09] Lofberg, Johan. +*Pre-and post-processing sum-of-squares programs in practice*. +IEEE transactions on automatic control 54, no. 5 (2009): 1007-1011. +""" struct SignSymmetry <: Sparsity end + function binary_exponent(exponents, ::Type{T}) where T cur = zero(T) for exponent in exponents diff --git a/src/Certificate/sparse/sparse_putinar.jl b/src/Certificate/sparse/sparse_putinar.jl index 1be710ed2..c303dd857 100644 --- a/src/Certificate/sparse/sparse_putinar.jl +++ b/src/Certificate/sparse/sparse_putinar.jl @@ -7,6 +7,16 @@ include("sign.jl") include("variable_sparsity.jl") include("monomial_sparsity.jl") +""" + struct SparsePreorder{S <: Sparsity, C <: AbstractPreorderCertificate} <: AbstractPreorderCertificate + sparsity::S + certificate::C + end + +Same certificate as `C` except that the Sum-of-Squares polynomials `σ_i` +are modelled as a sum of Sum-of-Squares polynomials with smaller basis +using the sparsity reduction `sparsity`. +""" struct SparsePreorder{S <: Sparsity, C <: AbstractPreorderCertificate} <: AbstractPreorderCertificate sparsity::S certificate::C @@ -45,6 +55,16 @@ get(::Type{<:SparsePreorder{S, C}}, attr::IdealCertificate) where {S, C} = Spars SumOfSquares.matrix_cone_type(::Type{SparsePreorder{S, C}}) where {S, C} = SumOfSquares.matrix_cone_type(C) +""" + struct SparseIdeal{S <: Sparsity, C <: AbstractIdealCertificate} <: AbstractIdealCertificate + sparsity::S + certificate::C + end + +Same certificate as `C` except that the Sum-of-Squares polynomial `σ` +is modelled as a sum of Sum-of-Squares polynomials with smaller basis +using the sparsity reduction `sparsity`. +""" struct SparseIdeal{S <: Sparsity, C <: AbstractIdealCertificate} <: AbstractIdealCertificate sparsity::S certificate::C diff --git a/src/Certificate/sparse/variable_sparsity.jl b/src/Certificate/sparse/variable_sparsity.jl index 7ebd4d216..a0dfc7892 100644 --- a/src/Certificate/sparse/variable_sparsity.jl +++ b/src/Certificate/sparse/variable_sparsity.jl @@ -1,3 +1,10 @@ +""" + struct VariableSparsity <: Sparsity end + +Variable or correlative sparsity as developed in [WSMM06]. + +[WSMM06] Waki, Hayato, Sunyoung Kim, Masakazu Kojima, and Masakazu Muramatsu. "Sums of squares and semidefinite program relaxations for polynomial optimization problems with structured sparsity." SIAM Journal on Optimization 17, no. 1 (2006): 218-242. +""" struct VariableSparsity <: Sparsity end const CEG = ChordalExtensionGraph