Merge branch 'main' into cuid-from-cuid

Author: blnicho

doc/OnlineDocs/explanation/solvers/pyros.rst

@@ -329,23 +329,30 @@ The deterministic Pyomo model for *hydro* is shown below.
 
 .. note::
     Primitive data (Python literals) that have been hard-coded within a
-    deterministic model cannot be later considered uncertain,
-    unless they are first converted to ``Param`` objects within
-    the ``ConcreteModel`` object.
-    Furthermore, any ``Param`` object that is to be later considered
-    uncertain must have the property ``mutable=True``.
+    deterministic model (:class:`~pyomo.core.base.PyomoModel.ConcreteModel`)
+    cannot be later considered uncertain,
+    unless they are first converted to Pyomo
+    :class:`~pyomo.core.base.param.Param` instances declared on the
+    :class:`~pyomo.core.base.PyomoModel.ConcreteModel` object.
+    Furthermore, any :class:`~pyomo.core.base.param.Param`
+    object that is to be later considered uncertain must be instantiated
+    with the argument ``mutable=True``.
 
 .. note::
-    In case modifying the ``mutable`` property inside the deterministic
-    model object itself is not straightforward in your context,
-    you may consider adding the following statement **after**
+    If specifying/modifying the ``mutable`` argument in the
+    :class:`~pyomo.core.base.param.Param` declarations
+    of your deterministic model source code
+    is not straightforward in your context, then
+    you may consider adding **after** the line
     ``import pyomo.environ as pyo`` but **before** defining the model
-    object: ``pyo.Param.DefaultMutable = True``.
-    For all ``Param`` objects declared after this statement,
-    the attribute ``mutable`` is set to ``True`` by default.
-    Hence, non-mutable ``Param`` objects are now declared by
-    explicitly passing the argument ``mutable=False`` to the
-    ``Param`` constructor.
+    object the statement: ``pyo.Param.DefaultMutable = True``.
+    For all :class:`~pyomo.core.base.param.Param`
+    objects declared after this statement,
+    the attribute ``mutable`` is set to True by default.
+    Hence, non-mutable :class:`~pyomo.core.base.param.Param`
+    objects are now declared by explicitly passing the argument
+    ``mutable=False`` to the :class:`~pyomo.core.base.param.Param`
+    constructor.
 
 .. doctest::
 
@@ -428,22 +435,37 @@ The deterministic Pyomo model for *hydro* is shown below.
 Step 2: Define the Uncertainty
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-First, we need to collect into a list those ``Param`` objects of our model
-that represent potentially uncertain parameters.
-For the purposes of our example, we shall assume uncertainty in the model
-parameters ``[m.p[0], m.p[1], m.p[2], m.p[3]]``, for which we can
-conveniently utilize the object ``m.p`` (itself an indexed ``Param`` object).
+We first collect the components of our model that represent the
+uncertain parameters.
+In this example, we assume uncertainty in
+the parameter objects ``m.p[0]``, ``m.p[1]``, ``m.p[2]``, and ``m.p[3]``.
+Since these objects comprise the mutable :class:`~pyomo.core.base.param.Param`
+object ``m.p``, we can conveniently specify:
 
 .. doctest::
 
-  >>> # === Specify which parameters are uncertain ===
-  >>> # We can pass IndexedParams this way to PyROS,
-  >>> #   or as an expanded list per index
-  >>> uncertain_parameters = [m.p]
+  >>> uncertain_params = m.p
+
+Equivalently, we may instead set ``uncertain_params`` to
+either ``[m.p]``, ``[m.p[0], m.p[1], m.p[2], m.p[3]]``,
+or ``list(m.p.values())``.
+
+.. note::
+    Any :class:`~pyomo.core.base.param.Param` object that is
+    to be considered uncertain by PyROS must have the property
+    ``mutable=True``.
 
 .. note::
-    Any ``Param`` object that is to be considered uncertain by PyROS
-    must have the property ``mutable=True``.
+    PyROS also allows uncertain parameters to be implemented as
+    :class:`~pyomo.core.base.var.Var` objects declared on the
+    deterministic model.
+    This may be convenient for users transitioning to PyROS from
+    parameter estimation and/or uncertainty quantification workflows,
+    in which the uncertain parameters are
+    often represented by :class:`~pyomo.core.base.var.Var` objects.
+    Prior to invoking PyROS,
+    all such :class:`~pyomo.core.base.var.Var` objects should be fixed.
+
 
 PyROS will seek to identify solutions that remain feasible for any
 realization of these parameters included in an uncertainty set.
@@ -555,7 +577,7 @@ correspond to first-stage degrees of freedom.
   ...     model=m,
   ...     first_stage_variables=first_stage_variables,
   ...     second_stage_variables=second_stage_variables,
-  ...     uncertain_params=uncertain_parameters,
+  ...     uncertain_params=uncertain_params,
   ...     uncertainty_set=box_uncertainty_set,
   ...     local_solver=local_solver,
   ...     global_solver=global_solver,
@@ -648,7 +670,7 @@ In this example, we select affine decision rules by setting
   ...     model=m,
   ...     first_stage_variables=first_stage_variables,
   ...     second_stage_variables=second_stage_variables,
-  ...     uncertain_params=uncertain_parameters,
+  ...     uncertain_params=uncertain_params,
   ...     uncertainty_set=box_uncertainty_set,
   ...     local_solver=local_solver,
   ...     global_solver=global_solver,
@@ -702,7 +724,7 @@ could have been equivalently written as:
   ...     model=m,
   ...     first_stage_variables=first_stage_variables,
   ...     second_stage_variables=second_stage_variables,
-  ...     uncertain_params=uncertain_parameters,
+  ...     uncertain_params=uncertain_params,
   ...     uncertainty_set=box_uncertainty_set,
   ...     local_solver=local_solver,
   ...     global_solver=global_solver,
@@ -768,7 +790,7 @@ instance and invoking the PyROS solver:
   ...         model=m,
   ...         first_stage_variables=first_stage_variables,
   ...         second_stage_variables=second_stage_variables,
-  ...         uncertain_params=uncertain_parameters,
+  ...         uncertain_params=uncertain_params,
   ...         uncertainty_set= box_uncertainty_set,
   ...         local_solver=local_solver,
   ...         global_solver=global_solver,
@@ -860,7 +882,8 @@ for a basic tutorial, see the :doc:`logging HOWTO <python:howto/logging>`.
        * Iteration log table
        * Termination details: message, timing breakdown, summary of statistics
    * - :py:obj:`logging.DEBUG`
-     - * Termination outcomes and summary of statistics for
+     - * Progress through the various preprocessing subroutines
+       * Termination outcomes and summary of statistics for
          every master feasility, master, and DR polishing problem
        * Progress updates for the separation procedure
        * Separation subproblem initial point infeasibilities
@@ -935,7 +958,7 @@ Observe that the log contains the following information:
    :linenos:
 
    ==============================================================================
-   PyROS: The Pyomo Robust Optimization Solver, v1.3.1.
+   PyROS: The Pyomo Robust Optimization Solver, v1.3.2.
           Pyomo version: 6.9.0
           Commit hash: unknown
           Invoked at UTC 2024-11-01T00:00:00.000000