NFC: add/update comments

Author: jsiirola

pyomo/core/base/constraint.py

@@ -552,6 +552,13 @@ def template_expr(self):
         return self._expr
 
     def set_value(self, expr):
+        # Setting a value will convert this instance from a templatized
+        # type to the original Data type (and call the original set_value()).
+        #
+        # Note: We assume that the templatized type is created by
+        # inheriting (TemplateDataMixin, <original data class>), and
+        # that this instance doesn't have additional multiple
+        # inheritance that could re-order the MRO.
         self.__class__ = self.__class__.__mro__[
             self.__class__.__mro__.index(TemplateDataMixin) + 1
         ]

pyomo/core/base/objective.py

@@ -180,6 +180,13 @@ def template_expr(self):
         return self._args_
 
     def set_value(self, expr):
+        # Setting a value will convert this instance from a templatized
+        # type to the original Data type (and call the original set_value()).
+        #
+        # Note: We assume that the templatized type is created by
+        # inheriting (TemplateDataMixin, <original data class>), and
+        # that this instance doesn't have additional multiple
+        # inheritance that could re-order the MRO.
         self.__class__ = self.__class__.__mro__[
             self.__class__.__mro__.index(TemplateDataMixin) + 1
         ]

pyomo/repn/linear.py

@@ -181,7 +181,7 @@ def append(self, other):
         # change). Omitting the assertion for efficiency.
         # assert self.multiplier == 1
         _type, other = other
-        if _type <= _FIXED:
+        if _type <= _FIXED:  # Note: catching _FIXED and _CONSTANT
             self.constant += other
             return
 
@@ -234,7 +234,7 @@ def append(self, other):
 
 
 def to_expression(visitor, arg):
-    if arg[0] <= _VARIABLE:
+    if arg[0] <= _VARIABLE:  # Note: catching _VARIABLE, _FIXED, and _CONSTANT
         return arg[1]
     else:
         return arg[1].to_expression(visitor)
@@ -916,7 +916,7 @@ def finalizeResult(self, result):
         ans = result[1]
         if ans.__class__ is not self.Result:
             ans = self.Result()
-            assert result[0] <= _FIXED
+            assert result[0] <= _FIXED  # Note: allowing _FIXED or _CONSTANT
             ans.constant = result[1]
             return ans
 

pyomo/repn/util.py

@@ -67,6 +67,10 @@
 
 
 class ExprType(enums.IntEnum):
+    # Note that the ordering is meaningful, and we will compare
+    # instances using relational operators.  In particular, we assume
+    # that the Enum values increase in polynomial degree, starting at
+    # CONSTANT and endine at GENERAL (nonlinear).
     CONSTANT = 0
     FIXED = 3
     VARIABLE = 5