Merge pull request #3148 from Robbybp/mpc-doc

MPC documentation and citation

doc/OnlineDocs/advanced_topics/flattener/index.rst

@@ -30,8 +30,9 @@ 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."**
+**When we say "flatten a model," we mean "recursively generate all components in
+the model," where a component can be indexed only by user-specified indexing
+sets (or is not indexed at all)**.
 
 Data structures
 ---------------
@@ -42,3 +43,23 @@ 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.
+
+Citation
+--------
+If you use the ``pyomo.dae.flatten`` module in your research, we would appreciate
+you citing the following paper, which gives more detail about the motivation for
+and examples of using this functinoality.
+
+.. code-block:: bibtex
+
+    @article{parker2023mpc,
+    title = {Model predictive control simulations with block-hierarchical differential-algebraic process models},
+    journal = {Journal of Process Control},
+    volume = {132},
+    pages = {103113},
+    year = {2023},
+    issn = {0959-1524},
+    doi = {https://doi.org/10.1016/j.jprocont.2023.103113},
+    url = {https://www.sciencedirect.com/science/article/pii/S0959152423002007},
+    author = {Robert B. Parker and Bethany L. Nicholson and John D. Siirola and Lorenz T. Biegler},
+    }

doc/OnlineDocs/contributed_packages/mpc/api.rst

@@ -0,0 +1,10 @@
+.. _mpc_api:
+
+API Reference
+=============
+
+.. toctree::
+   data.rst
+   conversion.rst
+   interface.rst
+   modeling.rst

doc/OnlineDocs/contributed_packages/mpc/conversion.rst

@@ -0,0 +1,5 @@
+Data Conversion
+===============
+
+.. automodule:: pyomo.contrib.mpc.data.convert
+   :members:

doc/OnlineDocs/contributed_packages/mpc/data.rst

@@ -0,0 +1,17 @@
+Data Structures
+===============
+
+.. automodule:: pyomo.contrib.mpc.data.get_cuid
+   :members:
+
+.. automodule:: pyomo.contrib.mpc.data.dynamic_data_base
+   :members:
+
+.. automodule:: pyomo.contrib.mpc.data.scalar_data
+   :members:
+
+.. automodule:: pyomo.contrib.mpc.data.series_data
+   :members:
+
+.. automodule:: pyomo.contrib.mpc.data.interval_data
+   :members:

doc/OnlineDocs/contributed_packages/mpc/index.rst

@@ -1,7 +1,7 @@
 MPC
 ===
 
-This package contains data structures and utilities for dynamic optimization
+Pyomo MPC contains data structures and utilities for dynamic optimization
 and rolling horizon applications, e.g. model predictive control.
 
 .. toctree::
@@ -10,3 +10,23 @@ and rolling horizon applications, e.g. model predictive control.
    overview.rst
    examples.rst
    faq.rst
+   api.rst
+
+Citation
+--------
+
+If you use Pyomo MPC in your research, please cite the following paper:
+
+.. code-block:: bibtex
+
+    @article{parker2023mpc,
+    title = {Model predictive control simulations with block-hierarchical differential-algebraic process models},
+    journal = {Journal of Process Control},
+    volume = {132},
+    pages = {103113},
+    year = {2023},
+    issn = {0959-1524},
+    doi = {https://doi.org/10.1016/j.jprocont.2023.103113},
+    url = {https://www.sciencedirect.com/science/article/pii/S0959152423002007},
+    author = {Robert B. Parker and Bethany L. Nicholson and John D. Siirola and Lorenz T. Biegler},
+    }

doc/OnlineDocs/contributed_packages/mpc/interface.rst

@@ -0,0 +1,8 @@
+Interfaces
+==========
+
+.. automodule:: pyomo.contrib.mpc.interfaces.model_interface
+   :members:
+
+.. automodule:: pyomo.contrib.mpc.interfaces.var_linker
+   :members:

doc/OnlineDocs/contributed_packages/mpc/modeling.rst

@@ -0,0 +1,11 @@
+Modeling Components
+===================
+
+.. automodule:: pyomo.contrib.mpc.modeling.constraints
+   :members:
+
+.. automodule:: pyomo.contrib.mpc.modeling.cost_expressions
+   :members:
+
+.. automodule:: pyomo.contrib.mpc.modeling.terminal
+   :members:

pyomo/contrib/mpc/README.md

@@ -0,0 +1,34 @@
+# Pyomo MPC
+
+Pyomo MPC is an extension for developing model predictive control simulations
+using Pyomo models. Please see the
+[documentation](https://pyomo.readthedocs.io/en/stable/contributed_packages/mpc/index.html)
+for more detailed information.
+
+Pyomo MPC helps with, among other things, the following use cases:
+- Transferring values between different points in time in a dynamic model
+(e.g. to initialize a dynamic model to its initial conditions)
+- Extracting or loading disturbances and inputs from or to models, and storing
+these in model-agnostic, easily JSON-serializable data structures
+- Constructing common modeling components, such as weighted-least-squares
+tracking objective functions, piecewise-constant input constraints, or
+terminal region constraints.
+
+## Citation
+
+If you use Pyomo MPC in your research, please cite the following paper, which
+discusses the motivation for the Pyomo MPC data structures and the underlying
+Pyomo features that make them possible.
+```bibtex
+@article{parker2023mpc,
+title = {Model predictive control simulations with block-hierarchical differential-algebraic process models},
+journal = {Journal of Process Control},
+volume = {132},
+pages = {103113},
+year = {2023},
+issn = {0959-1524},
+doi = {https://doi.org/10.1016/j.jprocont.2023.103113},
+url = {https://www.sciencedirect.com/science/article/pii/S0959152423002007},
+author = {Robert B. Parker and Bethany L. Nicholson and John D. Siirola and Lorenz T. Biegler},
+}
+```

pyomo/contrib/mpc/data/get_cuid.py

@@ -16,14 +16,13 @@
 
 
 def get_indexed_cuid(var, sets=None, dereference=None, context=None):
-    """
-    Attempts to convert the provided "var" object into a CUID with
-    with wildcards.
+    """Attempt to convert the provided "var" object into a CUID with wildcards
 
     Arguments
     ---------
     var:
-        Object to process
+        Object to process. May be a VarData, IndexedVar (reference or otherwise),
+        ComponentUID, slice, or string.
     sets: Tuple of sets
         Sets to use if slicing a vardata object
     dereference: None or int
@@ -32,6 +31,11 @@ def get_indexed_cuid(var, sets=None, dereference=None, context=None):
     context: Block
         Block with respect to which slices and CUIDs will be generated
 
+    Returns
+    -------
+    ``ComponentUID``
+        ComponentUID corresponding to the provided ``var`` and sets
+
     """
     # TODO: Does this function have a good name?
     # Should this function be generalized beyond a single indexing set?