Add comments and docstring

1 files changed, 12 insertions, 3 deletions

diff --git a/sumofsquares/problems.py b/sumofsquares/problems.py
index 4256642..4482c1e 100644
--- a/sumofsquares/problems.py
+++ b/sumofsquares/problems.py
@@ -174,7 +174,15 @@ class SOSProblem(Problem):
         return internal_prob.solve(verbose)
 
     def apply(self, state: ExpressionState) -> tuple[ExpressionState, InternalSOSProblem]:
-        """ Convert to internal SOS problem by applying state to the expressions. """
+        """
+        Convert to internal SOS problem by applying state to the expressions.
+
+        **Technical Note:** The internal SOS problem may only constraints that
+        are linear in the optimization variables, hence, conversion of
+        polynomial equality / non-negativity constraints are done here.
+        Likewise the cost function must also be reduced to quadratic expression
+        here.
+        """
 
         constraints: list[Constraint[PolyMatrixMixin]] = []
         state, cost = self.cost.apply(state)
@@ -213,6 +221,7 @@ class SOSProblem(Problem):
 
             elif isinstance(c, NonNegative):
                 if c.domain:
+                    # See also class canon.PutinarPSatz
                     raise ValueError(f"Cannot convert non-negativity constraint nr. {i} "
                                      "to conic constraint. Domain restricted non-negativity "
                                      "must be preprocessed by using a Positivstellensatz!")
@@ -270,8 +279,6 @@ class InternalSOSProblem(Problem):
     def to_conic_problem(self) -> ConicProblem:
         """
         Conver the SOS problem into a Conic program. 
-
-        TODO: docstring
         """
         cost = poly.to_affine(self.cost)
         if cost.degree > 2:
@@ -327,6 +334,8 @@ class InternalSOSProblem(Problem):
             nrows, ncols = constr.shape
 
             if constr.degree > 1:
+                # If this error occurs an it is not the user's fault, there is a bug in
+                # SOSProblem.apply
                 raise ValueError("To convert to conic constraints must be linear or affine "
                                 f"but {str(c.expression)} has degree {constr.degree}.")