Merge branch 'main' into fix-nested-everywhere

.github/workflows/release_wheel_creation.yml

@@ -22,14 +22,27 @@ jobs:
     name: Build wheels (${{ matrix.wheel-version }}) on ${{ matrix.os }} for native and cross-compiled architecture
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: true
       matrix:
         os: [ubuntu-22.04, windows-latest, macos-latest]
         arch: [all]
         wheel-version: ['cp38*', 'cp39*', 'cp310*', 'cp311*', 'cp312*']
+
+        include:
+        - wheel-version: 'cp38*'
+          TARGET: 'py38'
+        - wheel-version: 'cp39*'
+          TARGET: 'py39'
+        - wheel-version: 'cp310*'
+          TARGET: 'py310'
+        - wheel-version: 'cp311*'
+          TARGET: 'py311'
+        - wheel-version: 'cp312*'
+          TARGET: 'py312'
     steps:
       - uses: actions/checkout@v4
       - name: Build wheels
-        uses: pypa/[email protected].2
+        uses: pypa/[email protected].5
         with:
           output-dir: dist
         env:
@@ -43,8 +56,9 @@ jobs:
             CIBW_CONFIG_SETTINGS: '--global-option="--with-cython --with-distributable-extensions"'
       - uses: actions/upload-artifact@v4
         with:
-          name: native_wheels
+          name: native_wheels-${{ matrix.os }}-${{ matrix.TARGET }}
           path: dist/*.whl
+          overwrite: true
 
   alternative_wheels:
     name: Build wheels (${{ matrix.wheel-version }}) on ${{ matrix.os }} for aarch64
@@ -54,6 +68,18 @@ jobs:
         os: [ubuntu-22.04]
         arch: [all]
         wheel-version: ['cp38*', 'cp39*', 'cp310*', 'cp311*', 'cp312*']
+
+        include:
+        - wheel-version: 'cp38*'
+          TARGET: 'py38'
+        - wheel-version: 'cp39*'
+          TARGET: 'py39'
+        - wheel-version: 'cp310*'
+          TARGET: 'py310'
+        - wheel-version: 'cp311*'
+          TARGET: 'py311'
+        - wheel-version: 'cp312*'
+          TARGET: 'py312'
     steps:
       - uses: actions/checkout@v4
       - name: Set up QEMU
@@ -62,7 +88,7 @@ jobs:
         with:
           platforms: all
       - name: Build wheels
-        uses: pypa/[email protected].2
+        uses: pypa/[email protected].5
         with:
           output-dir: dist
         env:
@@ -74,8 +100,9 @@ jobs:
             CIBW_CONFIG_SETTINGS: '--global-option="--with-cython --with-distributable-extensions"'
       - uses: actions/upload-artifact@v4
         with:
-          name: alt_wheels
+          name: alt_wheels-${{ matrix.os }}-${{ matrix.TARGET }}
           path: dist/*.whl
+          overwrite: true
 
   generictarball:
     name: ${{ matrix.TARGET }}
@@ -106,4 +133,5 @@ jobs:
       with:
         name: generictarball
         path: dist
+        overwrite: true
 

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:

doc/OnlineDocs/contributed_packages/pyros.rst

@@ -142,6 +142,7 @@ PyROS Solver Interface
 
     Otherwise, the solution returned is certified to only be robust feasible.
 
+
 PyROS Uncertainty Sets
 -----------------------------
 Uncertainty sets are represented by subclasses of
@@ -518,7 +519,7 @@ correspond to first-stage degrees of freedom.
 
   >>> # === Designate which variables correspond to first-stage
   >>> #     and second-stage degrees of freedom ===
-  >>> first_stage_variables =[
+  >>> first_stage_variables = [
   ...     m.x1, m.x2, m.x3, m.x4, m.x5, m.x6,
   ...     m.x19, m.x20, m.x21, m.x22, m.x23, m.x24, m.x31,
   ... ]
@@ -657,6 +658,54 @@ For this example, we notice a ~25% decrease in the final objective
 value when switching from a static decision rule (no second-stage recourse)
 to an affine decision rule.
 
+
+Specifying Arguments Indirectly Through ``options``
+"""""""""""""""""""""""""""""""""""""""""""""""""""
+Like other Pyomo solver interface methods,
+:meth:`~pyomo.contrib.pyros.PyROS.solve`
+provides support for specifying options indirectly by passing
+a keyword argument ``options``, whose value must be a :class:`dict`
+mapping names of arguments to :meth:`~pyomo.contrib.pyros.PyROS.solve`
+to their desired values.
+For example, the ``solve()`` statement in the
+:ref:`two-stage problem snippet <example-two-stg>`
+could have been equivalently written as:
+
+.. doctest::
+  :skipif: not (baron.available() and baron.license_is_valid())
+
+  >>> results_2 = pyros_solver.solve(
+  ...     model=m,
+  ...     first_stage_variables=first_stage_variables,
+  ...     second_stage_variables=second_stage_variables,
+  ...     uncertain_params=uncertain_parameters,
+  ...     uncertainty_set=box_uncertainty_set,
+  ...     local_solver=local_solver,
+  ...     global_solver=global_solver,
+  ...     options={
+  ...         "objective_focus": pyros.ObjectiveType.worst_case,
+  ...         "solve_master_globally": True,
+  ...         "decision_rule_order": 1,
+  ...     },
+  ... )
+  ==============================================================================
+  PyROS: The Pyomo Robust Optimization Solver.
+  ...
+  ------------------------------------------------------------------------------
+  Robust optimal solution identified.
+  ------------------------------------------------------------------------------
+  ...
+  ------------------------------------------------------------------------------
+  All done. Exiting PyROS.
+  ==============================================================================
+
+In the event an argument is passed directly
+by position or keyword, *and* indirectly through ``options``,
+an appropriate warning is issued,
+and the value passed directly takes precedence over the value
+passed through ``options``.
+
+
 The Price of Robustness
 """"""""""""""""""""""""
 In conjunction with standard Python control flow tools,

doc/OnlineDocs/library_reference/common/config.rst

@@ -36,6 +36,7 @@ Domain validators
    NonPositiveFloat
    NonNegativeFloat
    In
+   IsInstance
    InEnum
    ListOf
    Module
@@ -75,6 +76,7 @@ Domain validators
 .. autofunction:: NonPositiveFloat
 .. autofunction:: NonNegativeFloat
 .. autoclass:: In
+.. autoclass:: IsInstance
 .. autoclass:: InEnum
 .. autoclass:: ListOf
 .. autoclass:: Module

pyomo/common/_command.py

@@ -13,8 +13,6 @@
 Management of Pyomo commands
 """
 
-__all__ = ['pyomo_command', 'get_pyomo_commands']
-
 import logging
 
 logger = logging.getLogger('pyomo.common')

pyomo/common/autoslots.py

@@ -29,7 +29,7 @@ def _deepcopy_tuple(obj, memo, _id):
             unchanged = False
     if unchanged:
         # Python does not duplicate "unchanged" tuples (i.e. allows the
-        # original objecct to be returned from deepcopy()).  We will
+        # original object to be returned from deepcopy()).  We will
         # preserve that behavior here.
         #
         # It also appears to be faster *not* to cache the fact that this

pyomo/common/collections/__init__.py

@@ -14,6 +14,6 @@
 from collections import UserDict
 
 from .orderedset import OrderedDict, OrderedSet
-from .component_map import ComponentMap
+from .component_map import ComponentMap, DefaultComponentMap
 from .component_set import ComponentSet
 from .bunch import Bunch