Add active filter to flattener

doc/OnlineDocs/advanced_topics/flattener/index.rst

@@ -0,0 +1,44 @@
+"Flattening" a Pyomo model
+==========================
+
+.. autosummary::
+
+   pyomo.dae.flatten
+
+.. toctree::
+   :maxdepth: 1
+
+   motivation.rst
+   reference.rst
+
+What does it mean to flatten a model?
+-------------------------------------
+When accessing components in a block-structured model, we use
+``component_objects`` or ``component_data_objects`` to access all objects
+of a specific ``Component`` or ``ComponentData`` type.
+The generated objects may be thought of as a "flattened" representation
+of the model, as they may be accessed without any knowledge of the model's
+block structure.
+These methods are very useful, but it is still challenging to use them
+to access specific components.
+Specifically, we often want to access "all components indexed by some set,"
+or "all component data at a particular index of this set."
+In addition, we often want to generate even the components in a block that
+is indexed by our particular set, as these components may be thought of as
+"implicitly indexed" by this set.
+The ``pyomo.dae.flatten`` module aims to address this use case by providing
+utilities to generate all components indexed, explicitly or implicitly, by
+user-provided sets.
+
+**When we say "flatten a model," we mean "generate all components in the model,
+preserving all user-specified indexing sets."**
+
+Data structures
+---------------
+The components returned are either ``ComponentData`` objects, for components
+not indexed by any of the provided sets, and references-to-slices, for
+components indexed, explicitly or implicitly, by the provided sets.
+Slices are necessary as they can encode "implicit indexing" -- where a
+component is contained in an indexed block. It is natural to return references
+to these slices, so they may be accessed and manipulated like any other
+component.

doc/OnlineDocs/advanced_topics/flattener/motivation.rst

@@ -0,0 +1,26 @@
+Motivation
+==========
+
+The ``pyomo.dae.flatten`` module was originally developed to assist with
+dynamic optimization. A very common operation in dynamic or multi-period
+optimization is to initialize all time-indexed variables to their values
+at a specific time point. However, for variables indexed by time and
+arbitrary other indexing sets, this is difficult to do in a way that does
+does not depend on the variable we are initializing. Things get worse
+when we consider that a time index can exist on a parent block rather
+than the component itself.
+
+By "reshaping" time-indexed variables in a model into references indexed
+only by time, the ``flatten_dae_components`` function allows us to perform
+operations that depend on knowledge of time indices without knowing
+anything about the variables that we are operating on.
+
+This "flattened representation" of a model turns out to be useful for
+dynamic optimization in a variety of other contexts. Examples include
+constructing a tracking objective function and plotting results.
+This representation is also useful in cases where we want to preserve
+indexing along more than one set, as in PDE-constrained optimization.
+The ``flatten_components_along_sets`` function allows partitioning
+components while preserving multiple indexing sets.
+In such a case, time and space-indexed data for a given variable is useful
+for purposes such as initialization, visualization, and stability analysis.

doc/OnlineDocs/advanced_topics/flattener/reference.rst

@@ -0,0 +1,14 @@
+API reference
+=============
+
+.. autosummary::
+
+   pyomo.dae.flatten.slice_component_along_sets
+   pyomo.dae.flatten.flatten_components_along_sets
+   pyomo.dae.flatten.flatten_dae_components
+
+.. autofunction:: pyomo.dae.flatten.slice_component_along_sets
+
+.. autofunction:: pyomo.dae.flatten.flatten_components_along_sets
+
+.. autofunction:: pyomo.dae.flatten.flatten_dae_components

doc/OnlineDocs/advanced_topics/index.rst

@@ -7,3 +7,4 @@ Advanced Topics
    persistent_solvers.rst
    units_container.rst
    linearexpression.rst
+   flattener/index.rst