Merge pull request #3126 from shermanjasonaf/update-kwarg-parsing-val…

…idation

Update PyROS Solver Argument Resolution and Validation Routines

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,

pyomo/contrib/pyros/CHANGELOG.txt

@@ -2,6 +2,13 @@
 PyROS CHANGELOG
 ===============
 
+-------------------------------------------------------------------------------
+PyROS 1.2.10    07 Feb 2024
+-------------------------------------------------------------------------------
+- Update argument resolution and validation routines of `PyROS.solve()`
+- Use methods of `common.config` for docstring of `PyROS.solve()`
+
+
 -------------------------------------------------------------------------------
 PyROS 1.2.9    15 Dec 2023
 -------------------------------------------------------------------------------
@@ -14,6 +21,7 @@ PyROS 1.2.9    15 Dec 2023
 - Refactor DR polishing routine; initialize auxiliary variables
   to values they are meant to represent
 
+
 -------------------------------------------------------------------------------
 PyROS 1.2.8    12 Oct 2023
 -------------------------------------------------------------------------------