Document certificates (#179)

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

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

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

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

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

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