Merge branch 'main' into highs_log

Author: mrmundt

Diff for: doc/OnlineDocs/explanation/experimental/solvers.rst

@@ -40,17 +40,20 @@ with existing interfaces).
    :header-rows: 1
 
    * - Solver
-     - Name registered in the |br| ``pyomo.contrib.solver.factory.SolverFactory``
+     - Name registered in the |br| ``pyomo.contrib.solver.common.factory.SolverFactory``
      - Name registered in the |br| ``pyomo.opt.base.solvers.LegacySolverFactory``
    * - Ipopt
      - ``ipopt``
      - ``ipopt_v2``
    * - Gurobi (persistent)
-     - ``gurobi``
-     - ``gurobi_v2``
+     - ``gurobi_persistent``
+     - ``gurobi_persistent_v2``
    * - Gurobi (direct)
      - ``gurobi_direct``
      - ``gurobi_direct_v2``
+   * - HiGHS
+     - ``highs``
+     - ``highs``
 
 Using the new interfaces through the legacy interface
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -64,7 +67,6 @@ be used with other Pyomo tools / capabilities.
    :skipif: not ipopt_available
 
    import pyomo.environ as pyo
-   from pyomo.contrib.solver.util import assert_optimal_termination
 
    model = pyo.ConcreteModel()
    model.x = pyo.Var(initialize=1.5)
@@ -76,13 +78,14 @@ be used with other Pyomo tools / capabilities.
    model.obj = pyo.Objective(rule=rosenbrock, sense=pyo.minimize)
 
    status = pyo.SolverFactory('ipopt_v2').solve(model)
-   assert_optimal_termination(status)
+   pyo.assert_optimal_termination(status)
    model.pprint()
 
 .. testoutput::
    :skipif: not ipopt_available
    :hide:
 
+   ...
    2 Var Declarations
    ...
    3 Declarations: x y obj
@@ -114,6 +117,7 @@ future methods of specifying solver options are supported:
    :skipif: not ipopt_available
    :hide:
 
+   ...
    2 Var Declarations
    ...
    3 Declarations: x y obj
@@ -128,8 +132,7 @@ Here we use the new interface by importing it directly:
 
    # Direct import
    import pyomo.environ as pyo
-   from pyomo.contrib.solver.util import assert_optimal_termination
-   from pyomo.contrib.solver.ipopt import Ipopt
+   from pyomo.contrib.solver.solvers.ipopt import Ipopt
 
    model = pyo.ConcreteModel()
    model.x = pyo.Var(initialize=1.5)
@@ -142,7 +145,7 @@ Here we use the new interface by importing it directly:
 
    opt = Ipopt()
    status = opt.solve(model)
-   assert_optimal_termination(status)
+   pyo.assert_optimal_termination(status)
    # Displays important results information; only available through the new interfaces
    status.display()
    model.pprint()
@@ -165,8 +168,7 @@ Here we use the new interface by retrieving it from the new ``SolverFactory``:
 
    # Import through new SolverFactory
    import pyomo.environ as pyo
-   from pyomo.contrib.solver.util import assert_optimal_termination
-   from pyomo.contrib.solver.factory import SolverFactory
+   from pyomo.contrib.solver.common.factory import SolverFactory
 
    model = pyo.ConcreteModel()
    model.x = pyo.Var(initialize=1.5)
@@ -179,7 +181,7 @@ Here we use the new interface by retrieving it from the new ``SolverFactory``:
 
    opt = SolverFactory('ipopt')
    status = opt.solve(model)
-   assert_optimal_termination(status)
+   pyo.assert_optimal_termination(status)
    # Displays important results information; only available through the new interfaces
    status.display()
    model.pprint()
@@ -204,7 +206,6 @@ replace the existing (legacy) SolverFactory and utilities with the new
 
    # Change default SolverFactory version
    import pyomo.environ as pyo
-   from pyomo.contrib.solver.util import assert_optimal_termination
    from pyomo.__future__ import solver_factory_v3
 
    model = pyo.ConcreteModel()
@@ -217,7 +218,7 @@ replace the existing (legacy) SolverFactory and utilities with the new
    model.obj = pyo.Objective(rule=rosenbrock, sense=pyo.minimize)
 
    status = pyo.SolverFactory('ipopt').solve(model)
-   assert_optimal_termination(status)
+   pyo.assert_optimal_termination(status)
    # Displays important results information; only available through the new interfaces
    status.display()
    model.pprint()
@@ -245,13 +246,13 @@ recently incorporated into the redesigned NL writer.  For example, you
 can control the NL writer in the new ``ipopt`` interface through the
 solver's ``writer_config`` configuration option:
 
-.. autoclass:: pyomo.contrib.solver.ipopt.Ipopt
+.. autoclass:: pyomo.contrib.solver.solvers.ipopt.Ipopt
    :noindex:
    :members: solve
 
 .. testcode::
 
-   from pyomo.contrib.solver.ipopt import Ipopt
+   from pyomo.contrib.solver.solvers.ipopt import Ipopt
    opt = Ipopt()
    opt.config.writer_config.display()
 
@@ -281,18 +282,18 @@ Interface Implementation
 ------------------------
 
 All new interfaces should be built upon one of two classes (currently):
-:class:`SolverBase<pyomo.contrib.solver.base.SolverBase>` or
-:class:`PersistentSolverBase<pyomo.contrib.solver.base.PersistentSolverBase>`.
+:class:`SolverBase<pyomo.contrib.solver.common.base.SolverBase>` or
+:class:`PersistentSolverBase<pyomo.contrib.solver.common.base.PersistentSolverBase>`.
 
 All solvers should have the following:
 
-.. autoclass:: pyomo.contrib.solver.base.SolverBase
+.. autoclass:: pyomo.contrib.solver.common.base.SolverBase
    :noindex:
    :members:
 
 Persistent solvers include additional members as well as other configuration options:
 
-.. autoclass:: pyomo.contrib.solver.base.PersistentSolverBase
+.. autoclass:: pyomo.contrib.solver.common.base.PersistentSolverBase
    :noindex:
    :show-inheritance:
    :members:
@@ -301,12 +302,12 @@ Results
 -------
 
 Every solver, at the end of a
-:meth:`solve<pyomo.contrib.solver.base.SolverBase.solve>` call, will
-return a :class:`Results<pyomo.contrib.solver.results.Results>`
+:meth:`solve<pyomo.contrib.solver.common.base.SolverBase.solve>` call, will
+return a :class:`Results<pyomo.contrib.solver.common.results.Results>`
 object.  This object is a :py:class:`pyomo.common.config.ConfigDict`,
 which can be manipulated similar to a standard ``dict`` in Python.
 
-.. autoclass:: pyomo.contrib.solver.results.Results
+.. autoclass:: pyomo.contrib.solver.common.results.Results
    :noindex:
    :show-inheritance:
    :members:
@@ -318,12 +319,12 @@ Termination Conditions
 
 Pyomo offers a standard set of termination conditions to map to solver
 returns. The intent of
-:class:`TerminationCondition<pyomo.contrib.solver.results.TerminationCondition>`
+:class:`TerminationCondition<pyomo.contrib.solver.common.results.TerminationCondition>`
 is to notify the user of why the solver exited. The user is expected
-to inspect the :class:`Results<pyomo.contrib.solver.results.Results>`
+to inspect the :class:`Results<pyomo.contrib.solver.common.results.Results>`
 object or any returned solver messages or logs for more information.
 
-.. autoclass:: pyomo.contrib.solver.results.TerminationCondition
+.. autoclass:: pyomo.contrib.solver.common.results.TerminationCondition
    :noindex:
    :show-inheritance:
 
@@ -333,13 +334,13 @@ Solution Status
 
 Pyomo offers a standard set of solution statuses to map to solver
 output. The intent of
-:class:`SolutionStatus<pyomo.contrib.solver.results.SolutionStatus>`
+:class:`SolutionStatus<pyomo.contrib.solver.common.results.SolutionStatus>`
 is to notify the user of what the solver returned at a high level. The
 user is expected to inspect the
-:class:`Results<pyomo.contrib.solver.results.Results>` object or any
+:class:`Results<pyomo.contrib.solver.common.results.Results>` object or any
 returned solver messages or logs for more information.
 
-.. autoclass:: pyomo.contrib.solver.results.SolutionStatus
+.. autoclass:: pyomo.contrib.solver.common.results.SolutionStatus
    :noindex:
    :show-inheritance:
 
@@ -351,7 +352,7 @@ Solutions can be loaded back into a model using a ``SolutionLoader``. A specific
 loader should be written for each unique case. Several have already been
 implemented. For example, for ``ipopt``:
 
-.. autoclass:: pyomo.contrib.solver.ipopt.IpoptSolutionLoader
+.. autoclass:: pyomo.contrib.solver.solvers.ipopt.IpoptSolutionLoader
    :noindex:
    :members:
    :show-inheritance:

Diff for: doc/OnlineDocs/explanation/solvers/pyros.rst

@@ -924,6 +924,9 @@ Observe that the log contains the following information:
   are included in parentheses, next to the total numbers
   of second-stage variables and state variables, respectively;
   note that "adjustable" has been abbreviated as "adj."
+  The number of truly uncertain parameters detected during preprocessing
+  is also noted in parentheses
+  (in which "eff." is an abbreviation for "effective").
 * **Iteration log table** (lines 59--69).
   Summary information on the problem iterates and subproblem outcomes.
   The constituent columns are defined in detail in
@@ -961,21 +964,21 @@ Observe that the log contains the following information:
    :linenos:
 
    ==============================================================================
-   PyROS: The Pyomo Robust Optimization Solver, v1.3.4.
-          Pyomo version: 6.9.0
-          Commit hash: unknown
-          Invoked at UTC 2025-02-13T00:00:00.000000
+   PyROS: The Pyomo Robust Optimization Solver, v1.3.6.
+          Pyomo version: 6.9.2.dev0 (devel {pyros-effective-uncertain-params})
+          Commit hash: 41cd797e0
+          Invoked at UTC 2025-03-13T16:20:31.105320+00:00
 
    Developed by: Natalie M. Isenberg (1), Jason A. F. Sherman (1),
                  John D. Siirola (2), Chrysanthos E. Gounaris (1)
    (1) Carnegie Mellon University, Department of Chemical Engineering
    (2) Sandia National Laboratories, Center for Computing Research
-
+   
    The developers gratefully acknowledge support from the U.S. Department
    of Energy's Institute for the Design of Advanced Energy Systems (IDAES).
    ==============================================================================
    ================================= DISCLAIMER =================================
-   PyROS is still under development.
+   PyROS is still under development. 
    Please provide feedback and/or report any issues by creating a ticket at
    https://github.com/Pyomo/pyomo/issues/new/choose
    ==============================================================================
@@ -1001,7 +1004,7 @@ Observe that the log contains the following information:
     p_robustness={}
    ------------------------------------------------------------------------------
    Preprocessing...
-   Done preprocessing; required wall time of 0.009s.
+   Done preprocessing; required wall time of 0.013s.
    ------------------------------------------------------------------------------
    Model Statistics:
      Number of variables : 62
@@ -1010,7 +1013,7 @@ Observe that the log contains the following information:
        Second-stage variables : 6 (6 adj.)
        State variables : 18 (7 adj.)
        Decision rule variables : 30
-     Number of uncertain parameters : 4
+     Number of uncertain parameters : 4 (4 eff.)
      Number of constraints : 52
        Equality constraints : 24
          Coefficient matching constraints : 0
@@ -1023,33 +1026,34 @@ 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.412
-   1     3.5838e+07  1.2289e-09   1.5886e-12   5       2.8919e+02   0.992
-   2     3.6269e+07  3.1647e-01   1.0432e-01   4       2.9020e+02   1.865
-   3     3.6285e+07  7.6526e-01   2.2258e-01   0       2.3874e-12g  3.508
+   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        
    ------------------------------------------------------------------------------
    Robust optimal solution identified.
    ------------------------------------------------------------------------------
    Timing breakdown:
-
+   
    Identifier                ncalls   cumtime   percall      %
    -----------------------------------------------------------
-   main                           1     3.509     3.509  100.0
+   main                           1     6.291     6.291  100.0
         ------------------------------------------------------
-        dr_polishing              3     0.209     0.070    6.0
-        global_separation        27     0.590     0.022   16.8
-        local_separation        108     1.569     0.015   44.7
-        master                    4     0.654     0.163   18.6
-        master_feasibility        3     0.083     0.028    2.4
-        preprocessing             1     0.009     0.009    0.3
-        other                   n/a     0.394       n/a   11.2
+        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
         ======================================================
    ===========================================================
-
+   
    ------------------------------------------------------------------------------
    Termination stats:
-    Iterations            : 4
-    Solve time (wall s)   : 3.509
+    Iterations            : 5
+    Solve time (wall s)   : 6.291
     Final objective value : 3.6285e+07
     Termination condition : pyrosTerminationCondition.robust_optimal
    ------------------------------------------------------------------------------

Diff for: doc/OnlineDocs/reference/topical/appsi/appsi.rst

@@ -24,17 +24,17 @@ example of using an APPSI solver interface.
 
 .. code-block:: python
 
-    >>> import pyomo.environ as pe
+    >>> import pyomo.environ as pyo
     >>> from pyomo.contrib import appsi
     >>> import numpy as np
     >>> from pyomo.common.timing import HierarchicalTimer
-    >>> m = pe.ConcreteModel()
-    >>> m.x = pe.Var()
-    >>> m.y = pe.Var()
-    >>> m.p = pe.Param(mutable=True)
-    >>> m.obj = pe.Objective(expr=m.x**2 + m.y**2)
-    >>> m.c1 = pe.Constraint(expr=m.y >= pe.exp(m.x))
-    >>> m.c2 = pe.Constraint(expr=m.y >= (m.x - m.p)**2)
+    >>> m = pyo.ConcreteModel()
+    >>> m.x = pyo.Var()
+    >>> m.y = pyo.Var()
+    >>> m.p = pyo.Param(mutable=True)
+    >>> m.obj = pyo.Objective(expr=m.x**2 + m.y**2)
+    >>> m.c1 = pyo.Constraint(expr=m.y >= pyo.exp(m.x))
+    >>> m.c2 = pyo.Constraint(expr=m.y >= (m.x - m.p)**2)
     >>> opt = appsi.solvers.Ipopt()
     >>> timer = HierarchicalTimer()
     >>> for p_val in np.linspace(1, 10, 100):
@@ -44,6 +44,15 @@ example of using an APPSI solver interface.
     >>>     print(res.best_feasible_objective)
     >>> print(timer)
 
+Alternatively, you can access the APPSI solvers through the classic
+``SolverFactory`` using the pattern ``appsi_solvername``.
+
+.. code-block:: python
+
+    >>> import pyomo.environ as pyo
+    >>> opt_ipopt = pyo.SolverFactory('appsi_ipopt')
+    >>> opt_highs = pyo.SolverFactory('appsi_highs')
+
 Extra performance improvements can be made if you know exactly what
 changes will be made in your model. In the example above, only
 parameter values are changed, so we can setup the