Merge branch 'Pyomo:main' into Example-seed-issue

Author: sscini

.github/workflows/test_branches.yml

@@ -76,13 +76,13 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python: [3.13]
+        python: ['3.13.3']  # FIXME: Remove specific 3.13 version once logging tests are fixed
         other: [""]
         category: [""]
 
         include:
         - os: ubuntu-latest
-          python: 3.13
+          python: '3.13.3'  # FIXME: Remove specific 3.13 version once logging tests are fixed
           test_docs: 1
           TARGET: linux
           PYENV: pip
@@ -348,7 +348,7 @@ jobs:
         if test "${{matrix.TARGET}}" == linux; then
             EXCLUDE="casadi numdifftools $EXCLUDE"
         fi
-        if [[ "${{matrix.TARGET}}" == win && "${{matrix.python}}" == "3.13" ]]; then
+        if [[ "${{matrix.TARGET}}" == win && "${{matrix.python}}" == 3.13* ]]; then
             # As of Nov 7, 2024, qtconsole is not compatible with python 3.13 on win
             EXCLUDE="qtconsole $EXCLUDE"
         fi
@@ -373,7 +373,7 @@ jobs:
         fi
         # Note: this will fail the build if any installation fails (or
         # possibly if it outputs messages to stderr)
-        conda install --update-deps -q -y $CONDA_DEPENDENCIES
+        conda install --update-deps -q -y python="${{matrix.python}}" $CONDA_DEPENDENCIES
         if test -z "${{matrix.slim}}"; then
             # xpress.init() (xpress 9.5.1 from conda) hangs indefinitely
             # on GHA/Windows under Python 3.10 and 3.11.  Exclude that

.github/workflows/test_pr_and_main.yml

@@ -88,7 +88,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python: [ 3.9, '3.10', 3.11, 3.12, 3.13 ]
+        python: [ 3.9, '3.10', 3.11, 3.12, '3.13.3' ]  # FIXME: Remove specific 3.13 version once logging tests are fixed
         other: [""]
         category: [""]
 
@@ -400,7 +400,7 @@ jobs:
         if test "${{matrix.TARGET}}" == linux; then
             EXCLUDE="casadi numdifftools $EXCLUDE"
         fi
-        if [[ "${{matrix.TARGET}}" == win && "${{matrix.python}}" == "3.13" ]]; then
+        if [[ "${{matrix.TARGET}}" == win && "${{matrix.python}}" == 3.13* ]]; then
             # As of Nov 7, 2024, qtconsole is not compatible with python 3.13 on win
             EXCLUDE="qtconsole $EXCLUDE"
         fi
@@ -425,7 +425,7 @@ jobs:
         fi
         # Note: this will fail the build if any installation fails (or
         # possibly if it outputs messages to stderr)
-        conda install --update-deps -q -y $CONDA_DEPENDENCIES
+        conda install --update-deps -q -y python="${{matrix.python}}" $CONDA_DEPENDENCIES
         if test -z "${{matrix.slim}}"; then
             # xpress.init() (xpress 9.5.1 from conda) hangs indefinitely
             # on GHA/Windows under Python 3.10 and 3.11.  Exclude that

doc/OnlineDocs/_templates/recursive-base.rst

@@ -7,6 +7,11 @@
    # import everything from the module containing this class so that
    # doctests for the class docstrings see the correct environment
    from {{ module }} import *
+   try:
+       from {{ module }} import _autosummary_doctest_setup
+       _autosummary_doctest_setup()
+   except ImportError:
+       pass
 
 .. currentmodule:: {{ module }}
 

doc/OnlineDocs/_templates/recursive-class.rst

@@ -7,6 +7,11 @@
    # import everything from the module containing this class so that
    # doctests for the class docstrings see the correct environment
    from {{ module }} import *
+   try:
+       from {{ module }} import _autosummary_doctest_setup
+       _autosummary_doctest_setup()
+   except ImportError:
+       pass
 
 .. currentmodule:: {{ module }}
 

doc/OnlineDocs/_templates/recursive-enum.rst

@@ -7,6 +7,11 @@
    # import everything from the module containing this class so that
    # doctests for the class docstrings see the correct environment
    from {{ module }} import *
+   try:
+       from {{ module }} import _autosummary_doctest_setup
+       _autosummary_doctest_setup()
+   except ImportError:
+       pass
 
 .. currentmodule:: {{ module }}
 

doc/OnlineDocs/_templates/recursive-module.rst

@@ -5,6 +5,19 @@ Library Reference
 {{ name | escape | underline}}
 {% endif %}
 
+.. testsetup:: *
+
+   # import everything from the module containing this class so that
+   # doctests for the class docstrings see the correct environment
+   from {{ module }} import *
+   try:
+       from {{ module }} import _autosummary_doctest_setup
+       _autosummary_doctest_setup()
+   except ImportError:
+       pass
+
+.. currentmodule:: {{ module }}
+
 .. automodule:: {{ fullname }}
    :undoc-members:
 

doc/OnlineDocs/errors.rst

@@ -8,10 +8,13 @@ Common Warnings/Errors
    for backwards compatibility, DO NOT recycle old ID (no longer used)
    numbers.
 
-.. doctest::
-   :hide:
+.. testsetup::
 
-   >>> import pyomo.environ as pyo
+   import pyomo.environ as pyo
+   # Ensure that all logged messages are sent to stdout
+   # (so they show up in the doctest output and can be tested)
+   import pyomo.common.log as _log
+   _log.pyomo_handler.__class__ = _log.StdoutHandler
 
 .. py:currentmodule:: pyomo.environ
 

doc/OnlineDocs/explanation/developer_utils/deprecation.rst

@@ -9,40 +9,29 @@ Deprecation
 -----------
 
 We offer a set of tools to help with deprecation in
-``pyomo.common.deprecation``.
+:py:mod:`pyomo.common.deprecation`.
 
 By policy, when deprecating or moving an existing capability, one of the
 following utilities should be leveraged.  Each has a required
 ``version`` argument that should be set to current development version (e.g.,
 ``"6.6.2.dev0"``).  This version will be updated to the next actual
 release as part of the Pyomo release process.  The current development version
-can be found by running ``pyomo --version`` on your local fork/branch.
+can be found by running
+
+   ``pyomo --version``
+
+on your local fork/branch.
 
 .. currentmodule:: pyomo.common.deprecation
 
 .. autosummary::
 
    deprecated
    deprecation_warning
-   relocated_module
+   moved_module
    relocated_module_attribute
    RenamedClass
 
-.. autodecorator:: pyomo.common.deprecation.deprecated
-   :noindex:
-
-.. autofunction:: pyomo.common.deprecation.deprecation_warning
-   :noindex:
-
-.. autofunction:: pyomo.common.deprecation.relocated_module
-   :noindex:
-
-.. autofunction:: pyomo.common.deprecation.relocated_module_attribute
-   :noindex:
-
-.. autoclass:: pyomo.common.deprecation.RenamedClass
-   :noindex:
-
 
 Removal
 -------
@@ -52,10 +41,8 @@ warning, pending extenuating circumstances. The functionality should
 be deprecated, following the information above.
 
 If the functionality is documented in the most recent
-edition of [`Pyomo - Optimization Modeling in Python`_], it may not be removed
-until the next major version release.
-
-.. _Pyomo - Optimization Modeling in Python: https://doi.org/10.1007/978-3-030-68928-5
+edition of :ref:`Pyomo - Optimization Modeling in Python <pyomobookiii>`,
+it may not be removed until the next major version release.
 
 For other functionality, it is preferred that ample time is given
 before removing the functionality. At minimum, significant functionality

doc/OnlineDocs/explanation/solvers/pynumero/tutorial.linear_solver_interfaces.rst

@@ -42,7 +42,7 @@ Interface to MA27
    >>> status = solver.do_numeric_factorization(A)
    >>> x, status = solver.do_back_solve(rhs)
    >>> np.max(np.abs(A*x - rhs)) <= 1e-15
-   True
+   np.True_
 
 
 Interface to MUMPS

doc/OnlineDocs/explanation/solvers/pyros.rst

@@ -963,10 +963,10 @@ Observe that the log contains the following information:
    :linenos:
 
    ==============================================================================
-   PyROS: The Pyomo Robust Optimization Solver, v1.3.6.
-          Pyomo version: 6.9.2
-          Commit hash: 41cd797e0
-          Invoked at UTC 2025-03-13T16:20:31.105320+00:00
+   PyROS: The Pyomo Robust Optimization Solver, v1.3.8.
+          Pyomo version: 6.9.3dev0
+          Commit hash: unknown
+          Invoked at UTC 2025-05-05T00:00:00.000000+00:00
 
    Developed by: Natalie M. Isenberg (1), Jason A. F. Sherman (1),
                  John D. Siirola (2), Chrysanthos E. Gounaris (1)
@@ -1025,34 +1025,33 @@ Observe that the log contains the following information:
    ------------------------------------------------------------------------------
    Itn  Objective    1-Stg Shift  2-Stg Shift  #CViol  Max Viol     Wall Time (s)
    ------------------------------------------------------------------------------
-   0     3.5838e+07  -            -            5       1.8832e+04   0.693        
-   1     3.5838e+07  1.2289e-09   1.5876e-12   5       3.7762e+04   1.514        
-   2     3.6129e+07  2.7244e-01   3.6878e-01   3       1.1093e+02   2.486        
-   3     3.6269e+07  3.7352e-01   4.3227e-01   1       2.7711e+01   3.667        
-   4     3.6285e+07  7.6526e-01   2.8426e-11   0       4.3364e-05g  6.291        
+   0     3.5838e+07  -            -            5       1.8832e+04   0.759
+   1     3.5838e+07  2.9329e-09   5.0030e-10   5       2.1295e+04   1.573
+   2     3.6285e+07  7.6526e-01   2.0398e-01   2       2.2457e+02   2.272
+   3     3.6285e+07  7.7212e-13   1.2525e-10   0       7.2940e-08g  5.280
    ------------------------------------------------------------------------------
    Robust optimal solution identified.
    ------------------------------------------------------------------------------
    Timing breakdown:
    
    Identifier                ncalls   cumtime   percall      %
    -----------------------------------------------------------
-   main                           1     6.291     6.291  100.0
+   main                           1     5.281     5.281  100.0
         ------------------------------------------------------
-        dr_polishing              4     0.334     0.083    5.3
-        global_separation        27     0.954     0.035   15.2
-        local_separation        135     3.046     0.023   48.4
-        master                    5     1.027     0.205   16.3
-        master_feasibility        4     0.133     0.033    2.1
-        preprocessing             1     0.013     0.013    0.2
-        other                   n/a     0.785       n/a   12.5
+        dr_polishing              3     0.155     0.052    2.9
+        global_separation        27     1.280     0.047   24.2
+        local_separation        108     2.200     0.020   41.7
+        master                    4     0.727     0.182   13.8
+        master_feasibility        3     0.103     0.034    1.9
+        preprocessing             1     0.021     0.021    0.4
+        other                   n/a     0.794       n/a   15.0
         ======================================================
    ===========================================================
    
    ------------------------------------------------------------------------------
    Termination stats:
-    Iterations            : 5
-    Solve time (wall s)   : 6.291
+    Iterations            : 4
+    Solve time (wall s)   : 5.281
     Final objective value : 3.6285e+07
     Termination condition : pyrosTerminationCondition.robust_optimal
    ------------------------------------------------------------------------------
@@ -1133,6 +1132,58 @@ The constituent columns are defined in the
        current iteration.
 
 
+Separation Priority Ordering 
+----------------------------
+The PyROS solver supports custom prioritization of
+the separation subproblems (and, thus, the constraints)
+that are automatically derived from
+a given model for robust optimization.
+Users may specify separation priorities through:
+
+- (Recommended) :class:`~pyomo.core.base.suffix.Suffix` components
+  with local name ``pyros_separation_priority``,
+  declared on the model or any of its sub-blocks.
+  Each entry of every such
+  :class:`~pyomo.core.base.suffix.Suffix`
+  should map a
+  :class:`~pyomo.core.base.var.Var`
+  or :class:`~pyomo.core.base.constraint.Constraint`
+  component to a value that specifies the separation
+  priority of all constraints derived from that component
+- The optional argument ``separation_priority_order``
+  to the PyROS :py:meth:`~pyomo.contrib.pyros.pyros.PyROS.solve`
+  method. The argument should be castable to a :py:obj:`dict`,
+  of which each entry maps the full name of a
+  :class:`~pyomo.core.base.var.Var`
+  or :class:`~pyomo.core.base.constraint.Constraint`
+  component to a value that specifies the
+  separation priority of all constraints
+  derived from that component
+
+Specification via :class:`~pyomo.core.base.suffix.Suffix` components
+takes precedence over specification via the solver argument
+``separation_priority_order``.
+Moreover, the precedence ordering among
+:class:`~pyomo.core.base.suffix.Suffix`
+components is handled by the Pyomo
+:class:`~pyomo.core.base.suffix.SuffixFinder` utility.
+
+A separation priority can be either
+a (real) number (i.e., of type :py:class:`int`, :py:class:`float`, etc.)
+or :py:obj:`None`.
+A higher number indicates a higher priority.
+The default priority for all constraints is 0.
+Therefore a constraint can be prioritized [or deprioritized]
+over the default by mapping the constraint to a positive [or negative] number.
+In practice, critical or dominant constraints are often
+prioritized over algorithmic or implied constraints.
+
+Constraints that have been assigned a priority of :py:obj:`None`
+are enforced subject to only the nominal uncertain parameter realization
+provided by the user. Therefore, these constraints are not imposed robustly
+and, in particular, are excluded from the separation problems.
+
+
 Feedback and Reporting Issues
 -------------------------------
 Please provide feedback and/or report any problems by opening an issue on