API Reference

Defining Optimization Variables

sosopt.polymat.from_.define_variable

Defines a decision variable for the SOS Problem.

Parameters:

Name	Type	Description	Default
name	DecisionVariableSymbol | str	The name assigned to the variable. This name needs to be unique.	required
size	int | MatrixExpression | None	The size of the decision variables. This is either given by an integer or derived from the shape of a polynomial expression.	None

Returns:

Type	Description
VariableVectorSymbolExpression	A polynomial variable expression

Example

like = polymat.from_(np.ones((3, 2)))

# creates a variable of size 6
x = sosopt.define_variable('x', size=like)

Source code in sosopt\polymat\from_.py

def define_variable(
    name: DecisionVariableSymbol | str,
    size: int | MatrixExpression | None = None,
):
    """
    Defines a decision variable for the SOS Problem.

    Args:
        name: The name assigned to the variable. This name needs to be unique.
        size: The size of the decision variables. This is either given by an integer or derived
            from the shape of a polynomial expression.

    Returns:
        (VariableVectorSymbolExpression): A polynomial variable expression

    Example:
        ``` python
        like = polymat.from_(np.ones((3, 2)))

        # creates a variable of size 6
        x = sosopt.define_variable('x', size=like)
        ```
    """

    if not isinstance(name, DecisionVariableSymbol):
        symbol = DecisionVariableSymbol(name)
    else:
        symbol = name

    return polymat.define_variable(name=symbol, size=size)

sosopt.polymat.from_.define_polynomial

Defines of a fully parametrized polynomial -- involving the specification of a decision variable for each coefficient of the polynomial.

Parameters:

Name	Type	Description	Default
name	str	The name assigned to the parametrized polynomial. This defines the name of the decision variable for each coefficient of the polynomial.	required
monomials	MonomialVectorExpression | None	Optional monomial vector that determines the structure of the polynomial matrix. If None, monomials are assumed to be a single element 1.	None
n_rows	int | None	The number of rows of the resulting polynomial matrix.	None
n_cols	int | None	The number of columns of the resulting polynomial matrix.	None
like	MatrixExpression | None	Copy the number of rows and columns from the given polynomial expression.	None

Returns:

Type	Description
StateMonad[MatrixExpression]	A polynomial expression where the coefficients are decision variables.

Example

x = polymat.define_variable('x')

# Define a parametrized polynomial specified by a monomial vector
state, r = sosopt.define_polynomial(
    name='r',
    monomials=x.combinations((0, 1, 2)),
).apply(state)

# returns a polymat vector [r_0, r_1, r_2] containing the coefficients
r.coefficient

Source code in sosopt\polymat\from_.py

def define_polynomial(
    name: str,
    monomials: MonomialVectorExpression | None = None,
    n_rows: int | None = None,
    n_cols: int | None = None,
    like: MatrixExpression | None = None,
):
    """
    Defines of a fully parametrized polynomial -- involving the specification of a decision variable
    for each coefficient of the polynomial.

    Args:
        name: The name assigned to the parametrized polynomial. This defines the name of the
            decision variable for each coefficient of the polynomial.
        monomials: Optional monomial vector that determines the structure of the polynomial matrix. If None,
            monomials are assumed to be a single element 1.
        n_rows: The number of rows of the resulting polynomial matrix.
        n_cols: The number of columns of the resulting polynomial matrix.
        like: Copy the number of rows and columns from the given polynomial expression.

    Returns:
        (StateMonad[MatrixExpression]): A polynomial expression where the coefficients are decision variables.

    Example:
        ``` python
        x = polymat.define_variable('x')

        # Define a parametrized polynomial specified by a monomial vector
        state, r = sosopt.define_polynomial(
            name='r',
            monomials=x.combinations((0, 1, 2)),
        ).apply(state)

        # returns a polymat vector [r_0, r_1, r_2] containing the coefficients
        r.coefficient
        ```
    """

    if monomials is None:
        monomials = polymat.from_(1).to_monomial_vector()

    def _define_polynomial(state):
        match (n_rows, n_cols, like):
            case None, None, None:
                shape = 1, 1
            case None, None, MatrixExpression():
                state, shape = polymat.to_shape(like).apply(state)
            case None, int() as nc, None:
                shape = (1, nc)
            case int() as nr, None, None:
                shape = (nr, 1)
            case int() as nr, int() as nc, _:
                shape = (nr, nc)
            case _:
                ValueError("Invalid shape specification")

        match shape:
            case (1, 1):
                get_name = lambda r, c: name  # noqa: E731
            case (1, _):
                get_name = lambda r, c: f"{name}_{c + 1}"  # noqa: E731
            case (_, 1):
                get_name = lambda r, c: f"{name}_{r + 1}"  # noqa: E731
            case _:
                get_name = lambda r, c: f"{name}_{r + 1}_{c + 1}"  # noqa: E731

        def gen_rows():
            for row in range(shape[0]):

                def gen_cols():
                    for col in range(shape[1]):
                        param = define_variable(
                            name=get_name(row, col),
                            size=monomials,
                        )

                        yield param, param.T @ monomials

                params, polynomials = tuple(zip(*gen_cols()))

                if 1 < len(polynomials):
                    expr = polymat.h_stack(polynomials)
                else:
                    expr = polynomials[0]

                yield params, expr

        coefficients, row_vectors = tuple(zip(*gen_rows()))

        if 1 < len(row_vectors):
            expr = polymat.v_stack(row_vectors)
        else:
            expr = row_vectors[0]

        expr = init_polynomial_variable(
            name=name,
            monomials=monomials,
            coefficients=coefficients,
            child=expr.child,
            shape=shape,
        )

        return state, expr

    return statemonad.get_map_put(_define_polynomial)

sosopt.polymat.from_.define_symmetric_matrix

Defines of a symmetric n x n matrix.

Parameters:

Name	Type	Description	Default
name	str	The name assigned to the parametrized polynomial. This defines the name of the decision variable for each coefficient of the polynomial.	required
monomials	MonomialVectorExpression | None	Optional monomial vector that determines the structure of the polynomial matrix. If None, monomials are assumed to be a single element 1.	None
size	int | None	The number of rows of the resulting polynomial matrix.	None

Returns:

Type	Description
StateMonad[MatrixExpression]	A polynomial expression where the coefficients are decision variables.

Source code in sosopt\polymat\from_.py

def define_symmetric_matrix(
    name: str,
    size: int | None = None,
    monomials: MonomialVectorExpression | None = None,
    like: MatrixExpression | None = None,
):
    """
    Defines of a symmetric n x n matrix.

    Args:
        name: The name assigned to the parametrized polynomial. This defines the name of the
            decision variable for each coefficient of the polynomial.
        monomials: Optional monomial vector that determines the structure of the polynomial matrix. If None,
            monomials are assumed to be a single element 1.
        size: The number of rows of the resulting polynomial matrix.

    Returns:
        (StateMonad[MatrixExpression]): A polynomial expression where the coefficients are decision variables.
    """

    if monomials is None:
        monomials = polymat.from_(1).to_monomial_vector()

    def _define_symmetric_matrix(state, monomials=monomials):
        match (size, like):
            case None, MatrixExpression():
                state, (size_, _) = polymat.to_shape(like).apply(state)
            case size_, _:
                pass

        entries = {}

        def gen_rows():
            for row in range(size_):

                def gen_cols():
                    for col in range(size_):
                        if row <= col:
                            param = define_variable(
                                name=f"{name}_{row + 1}_{col + 1}",
                                size=monomials,
                            )
                            entry = param, param.T @ monomials

                            entries[row, col] = entry

                            yield entry
                        else:
                            yield entries[col, row]

                params, polynomials = tuple(zip(*gen_cols()))
                yield params, polymat.h_stack(polynomials)

        params, row_vectors = tuple(zip(*gen_rows()))

        expr = polymat.v_stack(row_vectors)

        return state, init_polynomial_variable(
            name=name,
            monomials=monomials,
            coefficients=params,
            child=expr.child,
            shape=(size_, size_),
        )

    return statemonad.get_map_put(_define_symmetric_matrix)

sosopt.polymat.from_.define_multiplier

Defines a polynomial multiplier intended to be multiplied with a given polynomial (the multiplicand), ensuring that the resulting product does not exceed a specified degree.

Parameters:

Name	Type	Description	Default
name	str	The name assigned to the multiplier polynomial variable. This defines the name of the decision variable for each coefficient of the multiplier.	required
degree	int | MatrixExpression	The maximum allowed degree for the product of the multiplicand and multiplier.	required
multiplicand	MatrixExpression | None	The polynomial to be multiplied with the multiplier.	None
variables	VariableVectorExpression | tuple[int, ...]	The polynomial variables used to determine the degree of the resulting polynomial.	required

Returns:

Type	Description
StateMonad[ScalarPolynomialExpression]	A polynomial expression parameterized as a decision variable, representing the multiplier constrained by the specified degree.

Example

Q = polymat.from_([
    [x**2 - 2*x + 2, x],
    [x, x**2],
])

state, m = sosopt.define_multiplier(
    name='m',           # name of the polynomial variable
    degree=4,           # maximum degree of the product P*m
    multiplicand=Q,
    variables=x,        # polynomial variables determining the degree
).apply(state)

Source code in sosopt\polymat\from_.py

def define_multiplier(
    name: str,
    degree: int | MatrixExpression,
    variables: VariableVectorExpression | tuple[int, ...],
    multiplicand: MatrixExpression | None = None,
):
    """
    Defines a polynomial multiplier intended to be multiplied with a given polynomial
    (the multiplicand), ensuring that the resulting product does not exceed a specified degree.

    Args:
        name: The name assigned to the multiplier polynomial variable. This defines the name of the
            decision variable for each coefficient of the multiplier.
        degree: The maximum allowed degree for the product of the multiplicand and multiplier.
        multiplicand: The polynomial to be multiplied with the multiplier.
        variables: The polynomial variables used to determine the degree of the resulting polynomial.

    Returns:
        (StateMonad[ScalarPolynomialExpression]): A polynomial expression parameterized as a decision variable,
            representing the multiplier constrained by the specified degree.

    Example:
        ```python
        Q = polymat.from_([
            [x**2 - 2*x + 2, x],
            [x, x**2],
        ])

        state, m = sosopt.define_multiplier(
            name='m',           # name of the polynomial variable
            degree=4,           # maximum degree of the product P*m
            multiplicand=Q,
            variables=x,        # polynomial variables determining the degree
        ).apply(state)
        ```
    """

    def _define_multiplier(state, degree=degree):
        if isinstance(degree, MatrixExpression):
            # Compute the degree of the denominator s(x)
            state, max_degree_multiplier = polymat.to_degree(degree, variables=variables).apply(state)
            degree = max(max(max_degree_multiplier))

        else:
            assert isinstance(degree, int), f"Degree {degree} must be of type Int."

        def round_up_to_even(n):
            if n % 2 == 0:
                return n
            else:
                return n + 1

        max_degree = round_up_to_even(degree)

        if multiplicand is None:
            max_degree_multiplicand = 0

        else:
            state, multiplicand_degrees = polymat.to_degree(
                multiplicand, variables=variables
            ).apply(state)
            max_degree_multiplicand = max(max(multiplicand_degrees))

        max_degree_multiplier = max(max_degree - max_degree_multiplicand, 0)
        degree_range_multiplier = tuple(range(int(max_degree_multiplier) + 1))

        match variables:
            case MatrixExpression():
                variable = variables
            case _:
                variable = polymat.from_variable_indices(variables)

        state, expr = define_polynomial(
            name=name,
            monomials=variable.combinations(degree_range_multiplier).cache(),
        ).apply(state)

        return state, expr

    return statemonad.get_map_put(_define_multiplier)

Operations on Polynomial Expressions

sosopt.polymat.from_.sos_monomial_basis

Defines an SOS monomial basis \(Z(x)\) used for SOS decomposition.

Parameters:

Name	Type	Description	Default
expression	MatrixExpression[State]	Defines the expression \(p(x)\) that can be written as \(p(x) = Z(x)^T Q Z(x)\) for some a monomial vector \(Z(x)\).	required
variables	VariableVectorExpression[State]	Defines the polynomial variables.	required
sparse_smr	bool | None	If True, no SOS decomposition variables are defined	None

Source code in sosopt\polymat\from_.py

def sos_monomial_basis(
    expression: MatrixExpression,
    variables: MatrixExpression,
    sparse_smr: bool | None = None,
):
    """
    Defines an SOS monomial basis $Z(x)$ used for SOS decomposition.

    Args:
        expression: Defines the expression $p(x)$ that can be written
            as $p(x) = Z(x)^T Q Z(x)$ for some a monomial vector $Z(x)$.
        variables: Defines the polynomial variables.
        sparse_smr: If True, no SOS decomposition variables are defined
    """

    if sparse_smr is None:
        sparse_smr = True

    if sparse_smr:
        node = init_sos_monomial_basis_sparse(
            child=expression,
            variables=variables,
        )
    else:
        node = init_sos_monomial_basis(
            child=expression,
            variables=variables,
        )

    return polymat.from_(node)

sosopt.polymat.from_.gram_matrix

Performs an SOS decomposition to retrieve the SMR from a polynomial expression.

Parameters:

Name	Type	Description	Default
expression	ScalarPolynomialExpression[State]	Defines the expression \(p(x)\) that can be written as \(p(x) = Z(x)^T Q Z(x)\) for some a monomial vector \(Z(x)\).	required
variables	VariableVectorExpression[State]	Defines the polynomial variables.	required
monomials	MonomialVectorExpression[State] | None	Defines the monomial vector \(Z(x)\).	None
sparse_smr	bool | None	If True, no SOS decomposition variables are defined.	None

Source code in sosopt\polymat\from_.py

def gram_matrix(
    expression: MatrixExpression,
    variables: MatrixExpression,
    monomials: MatrixExpression | None = None,
    auxilliary_variable_symbol: AuxiliaryVariableSymbol | None = None,
    sparse_smr: bool | None = None,
):
    """
    Performs an SOS decomposition to retrieve the SMR from a polynomial expression.

    Args:
        expression: Defines the expression $p(x)$ that can be written
            as $p(x) = Z(x)^T Q Z(x)$ for some a monomial vector $Z(x)$.
        variables: Defines the polynomial variables.
        monomials: Defines the monomial vector $Z(x)$.
        sparse_smr: If True, no SOS decomposition variables are defined.
    """

    if sparse_smr is None:
        sparse_smr = True

    if sparse_smr:
        node = init_gram_matrix_sparse(
            child=expression,
            variables=variables,
            monomials=monomials,
        )
    else:
        node = init_gram_matrix(
            child=expression,
            variables=variables,
            monomials=monomials,
            auxilliary_variable_symbol=auxilliary_variable_symbol,
        )

    return polymat.from_(node).symmetric()

Defining Sets

sosopt.semialgebraicset.set_

Define a semialgebraic set from a collection scalar polynomial expressions.

Parameters:

Name	Type	Description	Default
equal_zero	dict[str, VectorExpression]	A dictionary of polynomial expressions which evaluate to zero on the set.	{}
greater_than_zero	dict[str, VectorExpression]	A dictionary of polynomial expressions which evaluate to a positive number on the set.	{}
smaller_than_zero	dict[str, VectorExpression]	A dictionary of polynomial expressions which evaluate to a negative number on the set.	{}

Returns:

Type	Description
SemialgebraicSet	A semi-algebraic set

Example

sosopt.set_(
    smaller_than_zero={'w': w},
    equal_zero={'V': V},
)

Source code in sosopt\semialgebraicset.py

def set_(
    equal_zero: dict[str, VectorExpression] = {},
    greater_than_zero: dict[str, VectorExpression] = {},
    smaller_than_zero: dict[str, VectorExpression] = {},
):
    """
    Define a semialgebraic set from a collection scalar polynomial expressions.

    Args:
        equal_zero: A dictionary of polynomial expressions which evaluate to zero 
            on the set.
        greater_than_zero: A dictionary of polynomial expressions which evaluate
            to a positive number on the set.
        smaller_than_zero: A dictionary of polynomial expressions which evaluate
            to a negative number on the set.

    Returns:
        (SemialgebraicSet): A semi-algebraic set

    Example:
        ``` python
        sosopt.set_(
            smaller_than_zero={'w': w},
            equal_zero={'V': V},
        )
        ```
    """

    inequalities = greater_than_zero | {n: -p for n, p in smaller_than_zero.items()}

    return SemialgebraicSet(
        inequalities=inequalities,
        equalities=equal_zero,
    )

Defining Polynomial Constraints

sosopt.polynomialconstraints.from_.zero_polynomial_constraint

This polynomial constraint ensures that a polynomial expression is zero as a polynomial: All coefficients of the polynomials must be zero.

Parameters:

Name	Type	Description	Default
name	str | None	The name of the constraint.	None
equal_to_zero	MatrixExpression	The polynomial expression whose coefficients must be zero.	required

Returns:

Type	Description
StateMonad[ZeroPolynomialConstraint]	A polynomial constraint

Example

state, r_zero_constraint = sosopt.zero_polynomial_constraint(
    name='r_zero',
    equal_to_zero=r,
).apply(state)

Source code in sosopt\polynomialconstraints\from_.py

def zero_polynomial_constraint(
    equal_to_zero: MatrixExpression,
    name: str | None = None,
):
    """
    This polynomial constraint ensures that a polynomial expression is zero 
    as a polynomial: All coefficients of the polynomials must be zero.

    Args:
        name: The name of the constraint. 
        equal_to_zero: The polynomial expression whose coefficients must be zero.

    Returns:
        (StateMonad[ZeroPolynomialConstraint]): A polynomial constraint

    Example:
        ``` python
        state, r_zero_constraint = sosopt.zero_polynomial_constraint(
            name='r_zero',
            equal_to_zero=r,
        ).apply(state)
        ```
    """

    return init_zero_polynomial_constraint(
        name=name,
        zero_matrix=equal_to_zero,
    )

sosopt.polynomialconstraints.from_.sos_constraint

This polynomial constraint ensures that a scalar polynomial expression belongs to the SOS Cone.

Parameters:

Name	Type	Description	Default
name	str	The name of the constraint.	required
greater_than_zero	MatrixExpression | None	The polynomial expression that must be SOS.	None
smaller_than_zero	MatrixExpression | None	The polynomial expression whose negative must be SOS. This argument is ignore if greater_than_zero is not None.	None

Returns:

Type	Description
StateMonad[SumOfSqauresConstraint]	A polynomial constraint

Example

state, r_sos_constraint = sosopt.sos_constraint(
    name='r_sos',
    greater_than_zero=r,
).apply(state)

Source code in sosopt\polynomialconstraints\from_.py

def sos_constraint(
    name: str,
    greater_than_zero: MatrixExpression | None = None,
    smaller_than_zero: MatrixExpression | None = None,
):
    """
    This polynomial constraint ensures that a scalar polynomial expression belongs 
    to the SOS Cone.

    Args:
        name: The name of the constraint. 
        greater_than_zero: The polynomial expression that must be SOS.
        smaller_than_zero: The polynomial expression whose negative must be SOS.
            This argument is ignore if greater_than_zero is not None.

    Returns:
        (StateMonad[SumOfSqauresConstraint]): A polynomial constraint

    Example:
        ``` python
        state, r_sos_constraint = sosopt.sos_constraint(
            name='r_sos',
            greater_than_zero=r,
        ).apply(state)
        ```
    """

    if greater_than_zero is not None:
        positive_matrix = greater_than_zero
    elif smaller_than_zero is not None:
        positive_matrix = -smaller_than_zero
    else:
        raise Exception("SOS constraint requires condition.")

    return init_sum_of_squares_constraint(
        name=name,
        positive_matrix=positive_matrix,
    )

sosopt.polynomialconstraints.from_.sos_matrix_constraint

This polynomial constraint ensures a polynomial matrix expression belongs to the SOS Matrix Cone.

Parameters:

Name	Type	Description	Default
name	str	The name of the constraint.	required
greater_than_zero	SymmetricMatrixExpression | None	The polynomial expression Q that must be SOS Matrix. This means that v^T Q v is SOS for an additional polynomial variable v.	None
smaller_than_zero	SymmetricMatrixExpression | None	The polynomial expression whose negative must be SOS Matrix. This argument is ignore if greater_than_zero is not None.	None

Returns:

Type	Description
StateMonad[SumOfSqauresConstraint]	A polynomial constraint

Example

state, q_sos_constraint = sosopt.sos_matrix_constraint(
    name='q_sos',
    greater_than_zero=q,
).apply(state)

Source code in sosopt\polynomialconstraints\from_.py

def sos_matrix_constraint(
    name: str,
    greater_than_zero: SymmetricMatrixExpression | None = None,
    smaller_than_zero: SymmetricMatrixExpression | None = None,
):
    """
    This polynomial constraint ensures a polynomial matrix expression belongs 
    to the SOS Matrix Cone.

    Args:
        name: The name of the constraint. 
        greater_than_zero: The polynomial expression Q that must be SOS Matrix.
            This means that v^T Q v is SOS for an additional polynomial variable v.
        smaller_than_zero: The polynomial expression whose negative must be SOS Matrix.
            This argument is ignore if greater_than_zero is not None.

    Returns:
        (StateMonad[SumOfSqauresConstraint]): A polynomial constraint

    Example:
        ``` python
        state, q_sos_constraint = sosopt.sos_matrix_constraint(
            name='q_sos',
            greater_than_zero=q,
        ).apply(state)
        ```
    """

    if greater_than_zero is not None:
        condition = greater_than_zero
    elif smaller_than_zero is not None:
        condition = -smaller_than_zero
    else:
        raise Exception("SOS constraint requires condition.")

    def _sos_matrix_constraint(state):

        state, shape = polymat.to_shape(condition).apply(state)

        x = polymat.define_variable(f"{name}_x", size=shape[0])

        constraint = sos_constraint(
            name=name,
            greater_than_zero=x.T @ condition @ x,
        )

        return state, constraint

    return statemonad.get_map_put(_sos_matrix_constraint)

sosopt.polynomialconstraints.from_.quadratic_module_constraint

This polynomial constraint defines a non-negativity condition on a subset of the states space (called the domain) using a quadratic module construction following Putinar's Positivstellensatz.

Parameters:

Name	Type	Description	Default
name	str	The name of the constraint.	required
domain	SemialgebraicSet | None	Defined by a algebraic set.	None
greater_than_zero	MatrixExpression | None	The polynomial expression that must be non-negative on the domain.	None
smaller_than_zero	MatrixExpression | None	The polynomial expression that must be non-positive on the domain. This argument is ignore if greater_than_zero is not None.	None

Returns:

Type	Description
StateMonad[QuadraticModuleConstraint]	A polynomial constraint

Example

state, r_qm_constraint = sosopt.quadratic_module_constraint(
    name='r_qm',
    greater_than_zero=r,
    domain=sosopt.set_(
        smaller_than_zero={'w': w},
    )
).apply(state)

Source code in sosopt\polynomialconstraints\from_.py

def quadratic_module_constraint(
    name: str,
    domain: SemialgebraicSet | None = None,
    greater_than_zero: MatrixExpression | None = None,
    smaller_than_zero: MatrixExpression | None = None,
):
    """
    This polynomial constraint defines a non-negativity condition on a subset of the 
    states space (called the domain) using a quadratic module construction following Putinar's 
    Positivstellensatz.

    Args:
        name: The name of the constraint.
        domain: Defined by a algebraic set.
        greater_than_zero: The polynomial expression that must be non-negative on the domain.
        smaller_than_zero: The polynomial expression that must be non-positive on the domain.
            This argument is ignore if greater_than_zero is not None.

    Returns:
        (StateMonad[QuadraticModuleConstraint]): A polynomial constraint

    Example:
        ``` python
        state, r_qm_constraint = sosopt.quadratic_module_constraint(
            name='r_qm',
            greater_than_zero=r,
            domain=sosopt.set_(
                smaller_than_zero={'w': w},
            )
        ).apply(state)
        ```
    """

    if greater_than_zero is not None:
        positive_matrix = greater_than_zero
    elif smaller_than_zero is not None:
        positive_matrix = -smaller_than_zero
    else:
        raise Exception("SOS constraint requires condition.")

    return init_quadratic_module_constraint(
        name,
        expression=positive_matrix,
        domain=domain,
    )

Defining SDP constraints

sosopt.coneconstraints.from_.semi_definite_constraint

This constraint ensures that a symmetric matrix belongs to the positive semidefinite Cone.

Parameters:

Name	Type	Description	Default
name	str	The name of the constraint.	required
greater_than_zero	SymmetricMatrixExpression	The symmetric matrix that must be positive semi-definite.	required

Returns:

Type	Description
StateMonad[SemiDefiniteConstraint]	A polynomial constraint

Example

state, q_psd_constraint = sosopt.semidefinite_constraint(
    name='q_psd',
    greater_than_zero=q,
).apply(state)

Source code in sosopt\coneconstraints\from_.py

def semi_definite_constraint(
    name: str,
    greater_than_zero: SymmetricMatrixExpression,
):
    """
    This constraint ensures that a symmetric matrix belongs to the positive semidefinite Cone.

    Args:
        name: The name of the constraint. 
        greater_than_zero: The symmetric matrix that must be positive semi-definite.

    Returns:
        (StateMonad[SemiDefiniteConstraint]): A polynomial constraint

    Example:
        ``` python
        state, q_psd_constraint = sosopt.semidefinite_constraint(
            name='q_psd',
            greater_than_zero=q,
        ).apply(state)
        ```
    """

    return init_semi_definite_constraint(
        name=name,
        expression=greater_than_zero,
    )

sosopt.coneconstraints.from_.equality_constraint

This constraint ensures that all entries of the polynomial expression are zero.

Parameters:

Name	Type	Description	Default
name	str	The name of the constraint.	required
equal_to_zero	VectorExpression	The polynomial expression that must be zero.	required

Returns:

Type	Description
StateMonad[EqualityConstraint]	A polynomial constraint

Example

state, eq_constraint = sosopt.equality_constraint(
    name='eq',
    greater_than_zero=eq,
).apply(state)

Source code in sosopt\coneconstraints\from_.py

def equality_constraint(
    name: str,
    equal_to_zero: VectorExpression,
):
    """
    This constraint ensures that all entries of the polynomial expression are zero.

    Args:
        name: The name of the constraint. 
        equal_to_zero: The polynomial expression that must be zero.

    Returns:
        (StateMonad[EqualityConstraint]): A polynomial constraint

    Example:
        ``` python
        state, eq_constraint = sosopt.equality_constraint(
            name='eq',
            greater_than_zero=eq,
        ).apply(state)
        ```
    """

    return init_equality_constraint(
        name=name,
        expression=equal_to_zero,
    )

Defining the SOS Optimization Problem

sosopt.sosproblem.init_sos_problem

Defines an SOS problem.

Parameters:

Name	Type	Description	Default
lin_cost	ScalarPolynomialExpression | None	Scalar expression \(c( heta)\) defining the linear cost.	None
constraints	tuple[PolynomialConstraint | ConeConstraint, ...]	SOS and equality constraints	required
solver	SolverMixin	SDP solver selection (CVXOPT or MOSEK)	required
quad_cost	VectorExpression | None	Vector expression \(q( heta)\) defining the quadratic cost \(q( heta)^ op q( heta)\).	None

Returns:

Type	Description
SOS Problem	A Sum-of-Squares (SOS) Problem

Example

problem = sosopt.sos_problem(
    lin_cost=Q.trace(),
    quad_cost=Q.diag(),
    constraints=(r_sos_constraint,),
    solver=polymat.cvxopt_solver,
)

# solve SOS problem
state, result = problem.solve().apply(state)

Source code in sosopt\sosproblem.py

def init_sos_problem(
    constraints: tuple[PolynomialConstraint | ConeConstraint, ...],
    solver: SolverMixin,
    lin_cost: ScalarPolynomialExpression | None = None,
    quad_cost: VectorExpression | None = None,
):
    """
    Defines an SOS problem.

    Args:
        lin_cost: Scalar expression $c(\theta)$ defining the linear cost.
        constraints: SOS and equality constraints
        solver: SDP solver selection (*CVXOPT* or *MOSEK*)
        quad_cost: Vector expression $q(\theta)$ defining the quadratic cost $q(\theta)^\top q(\theta)$.

    Returns:
        (SOS Problem): A Sum-of-Squares (SOS) Problem

    Example:
        ``` python
        problem = sosopt.sos_problem(
            lin_cost=Q.trace(),
            quad_cost=Q.diag(),
            constraints=(r_sos_constraint,),
            solver=polymat.cvxopt_solver,
        )

        # solve SOS problem
        state, result = problem.solve().apply(state)
        ```
    """

    return SOSProblem(
        lin_cost=lin_cost,
        quad_cost=quad_cost,
        constraints=constraints,
        solver=solver,
    )