Merge pull request #2619 from andrewlee94/scaling_transform

Adding support for local suffixes in scaling transformation

Author: blnicho

doc/OnlineDocs/index.rst

@@ -18,6 +18,7 @@ with a diverse set of optimization capabilities.
    solving_pyomo_models.rst
    working_models.rst
    working_abstractmodels/index.rst
+   model_transformations/index.rst
    modeling_extensions/index.rst
    tutorial_examples.rst
    model_debugging/index.rst

doc/OnlineDocs/model_transformations/index.rst

@@ -0,0 +1,7 @@
+Model Transformations
+=====================
+
+.. toctree::
+   :maxdepth: 1
+
+   scaling.rst

doc/OnlineDocs/model_transformations/scaling.rst

@@ -0,0 +1,41 @@
+Model Scaling Transformation
+============================
+
+Good scaling of models can greatly improve the numerical properties of a problem and thus increase reliability and convergence. The ``core.scale_model`` transformation allows users to separate scaling of a model from the declaration of the model variables and constraints which allows for models to be written in more natural forms and to be scaled and rescaled as required without having to rewrite the model code.
+
+.. autoclass:: pyomo.core.plugins.transform.scaling.ScaleModel
+    :members:
+
+Setting Scaling Factors
+-----------------------
+
+Scaling factors for components in a model are declared using :ref:`Suffixes`, as shown in the example above. In order to define a scaling factor for a component, a ``Suffix`` named ``scaling_factor`` must first be created to hold the scaling factor(s). Scaling factor suffixes can be declared at any level of the model hierarchy, but scaling factors declared on the higher-level ``models`` or ``Blocks`` take precedence over those declared at lower levels.
+
+Scaling suffixes are dict-like where each key is a Pyomo component and the value is the scaling factor to be applied to that component.
+
+In the case of indexed components, scaling factors can either be declared for an individual index or for the indexed component as a whole (with scaling factors for individual indices taking precedence over overall scaling factors).
+
+.. note::
+
+   In the case that a scaling factor is declared for a component on at multiple levels of the hierarchy, the highest level scaling factor will be applied.
+
+.. note::
+
+   It is also possible (but not encouraged) to define a "default" scaling factor to be applied to any component for which a specific scaling factor has not been declared by setting a entry in a Suffix with a key of ``None``. In this case, the default value declared closest to the component to be scaled will be used (i.e., the first default value found when walking up the model hierarchy).
+
+Applying Model Scaling
+----------------------
+
+The ``core.scale_model`` transformation provides two approaches for creating a scaled model.
+
+In-Place Scaling
+****************
+
+The ``apply_to(model)`` method can be used to apply scaling directly to an existing model. When using this method, all the variables, constraints and objectives within the target model are replaced with new scaled components and the appropriate scaling factors applied. The model can then be sent to a solver as usual, however the results will be in terms of the scaled components and must be un-scaled by the user.
+
+Creating a New Scaled Model
+***************************
+
+Alternatively, the ``create_using(model)`` method can be used to create a new, scaled version of the model which can be solved. In this case, a clone of the original model is generated with the variables, constraints and objectives replaced by scaled equivalents. Users can then send the scaled model to a solver after which the ``propagate_solution`` method can be used to map the scaled solution back onto the original model for further analysis.
+
+The advantage of this approach is that the original model is maintained separately from the scaled model, which facilitates rescaling and other manipulation of the original model after a solution has been found. The disadvantage of this approach is that cloning the model may result in memory issues when dealing with larger models.

pyomo/core/plugins/transform/scaling.py

@@ -10,7 +10,10 @@
 #  ___________________________________________________________________________
 
 from pyomo.common.collections import ComponentMap
-from pyomo.core.base import Var, Constraint, Objective, _ConstraintData, _ObjectiveData, Suffix, value
+from pyomo.core.base import (
+    Block, Var, Constraint, Objective, _ConstraintData, _ObjectiveData,
+    Suffix, value,
+)
 from pyomo.core.plugins.transform.hierarchy import Transformation
 from pyomo.core.base import TransformationFactory
 from pyomo.core.expr.current import replace_expressions
@@ -81,16 +84,91 @@ def _create_using(self, original_model, **kwds):
         self._apply_to(scaled_model, **kwds)
         return scaled_model
 
+    def _suffix_finder(self, component_data, suffix_name, root=None):
+        """Find suffix value for a given component data object in model tree
+
+        Suffixes are searched by traversing the model hierarchy in three passes:
+
+        1. Search for a Suffix matching the specific component_data,
+           starting at the `root` and descending down the tree to
+           the component_data.  Return the first match found.
+        2. Search for a Suffix matching the component_data's container,
+           starting at the `root` and descending down the tree to
+           the component_data.  Return the first match found.
+        3. Search for a Suffix with key `None`, starting from the
+           component_data and working up the tree to the `root`.
+           Return the first match found.
+        4. Return None
+
+        Parameters
+        ----------
+        component_data: ComponentDataBase
+
+            Component or component data object to find suffix value for.
+
+        suffix_name: str
+
+            Name of Suffix to search for.
+
+        root: BlockData
+
+            When searching up the block hierarchy, stop at this
+            BlockData instead of traversing all the way to the
+            `component_data.model()` Block.  If the `component_data` is
+            not in the subtree defined by `root`, then the search will
+            proceed up to `component_data.model()`.
+
+        Returns
+        -------
+        The value for Suffix associated with component data if found, else None.
+
+        """
+        # Prototype for Suffix finder
+
+        # We want to *include* the root (if it is not None), so if
+        # it is not None, we want to stop as soon as we get to its
+        # parent.
+        if root is not None:
+            if root.ctype is not Block and not issubclass(root.ctype, Block):
+                raise ValueError("_find_suffix: root must be a BlockData "
+                                 f"(found {root.ctype.__name__}: {root})")
+            if root.is_indexed():
+                raise ValueError(
+                    "_find_suffix: root must be a BlockData "
+                    f"(found {type(root).__name__}: {root})")
+            root = root.parent_block()
+        # Walk parent tree and search for suffixes
+        parent = component_data.parent_block()
+        suffixes = []
+        while parent is not root:
+            s = parent.component(suffix_name)
+            if s is not None and s.ctype is Suffix:
+                suffixes.append(s)
+            parent = parent.parent_block()
+        # Pass 1: look for the component_data, working root to leaf
+        for s in reversed(suffixes):
+            if component_data in s:
+                return s[component_data]
+        # Pass 2: look for the component container, working root to leaf
+        parent_comp = component_data.parent_component()
+        if parent_comp is not component_data:
+            for s in reversed(suffixes):
+                if parent_comp in s:
+                    return s[parent_comp]
+        # Pass 3: look for None, working leaf to root
+        for s in suffixes:
+            if None in s:
+                return s[None]
+        return None
+
     def _get_float_scaling_factor(self, instance, component_data):
-        scaling_factor = None
-        if component_data in instance.scaling_factor:
-            scaling_factor = instance.scaling_factor[component_data]
-        elif component_data.parent_component() in instance.scaling_factor:
-            scaling_factor = instance.scaling_factor[component_data.parent_component()]
+        scaling_factor = self._suffix_finder(component_data, "scaling_factor")
 
+        # If still no scaling factor, return 1.0
         if scaling_factor is None:
             return 1.0
 
+        # Make sure scaling factor is a float
         try:
             scaling_factor = float(scaling_factor)
         except ValueError: