From a4d109425a4e7f1f271aeddf0fd536c909f6c9fc Mon Sep 17 00:00:00 2001 From: John Siirola Date: Wed, 21 Feb 2024 09:36:46 -0700 Subject: [PATCH 1/5] Clarify some solver documentation --- .../developer_reference/solvers.rst | 113 +++++++++++++----- 1 file changed, 83 insertions(+), 30 deletions(-) diff --git a/doc/OnlineDocs/developer_reference/solvers.rst b/doc/OnlineDocs/developer_reference/solvers.rst index 45945c18b12..9f18119e373 100644 --- a/doc/OnlineDocs/developer_reference/solvers.rst +++ b/doc/OnlineDocs/developer_reference/solvers.rst @@ -1,10 +1,11 @@ Future Solver Interface Changes =============================== -Pyomo offers interfaces into multiple solvers, both commercial and open source. -To support better capabilities for solver interfaces, the Pyomo team is actively -redesigning the existing interfaces to make them more maintainable and intuitive -for use. Redesigned interfaces can be found in ``pyomo.contrib.solver``. +Pyomo offers interfaces into multiple solvers, both commercial and open +source. To support better capabilities for solver interfaces, the Pyomo +team is actively redesigning the existing interfaces to make them more +maintainable and intuitive for use. A preview of the redesigned +interfaces can be found in ``pyomo.contrib.solver``. .. currentmodule:: pyomo.contrib.solver @@ -12,27 +13,39 @@ for use. Redesigned interfaces can be found in ``pyomo.contrib.solver``. New Interface Usage ------------------- -The new interfaces have two modes: backwards compatible and future capability. -The future capability mode can be accessed directly or by switching the default -``SolverFactory`` version (see :doc:`future`). Currently, the new versions -available are: +The new interfaces are not completely backwards compatible with the +existing Pyomo solver interfaces. However, to aid in testing and +evaluation, we are distributing versions of the new solver interfaces +that are compatible with the existing ("legacy") solver interface. +These "legacy" interfaces are registered with the current +``SolverFactory`` using slightly different names (to avoid conflicts +with existing interfaces). -.. list-table:: Available Redesigned Solvers - :widths: 25 25 25 +.. |br| raw:: html + +
+ +.. list-table:: Available Redesigned Solvers and Names Registered + in the SolverFactories :header-rows: 1 * - Solver - - ``SolverFactory`` (v1) Name - - ``SolverFactory`` (v3) Name - * - ipopt - - ``ipopt_v2`` + - Name registered in the |br| ``pyomo.contrib.solver.factory.SolverFactory`` + - Name registered in the |br| ``pyomo.opt.base.solvers.LegacySolverFactory`` + * - Ipopt - ``ipopt`` + - ``ipopt_v2`` * - Gurobi - - ``gurobi_v2`` - ``gurobi`` + - ``gurobi_v2`` -Backwards Compatible Mode -^^^^^^^^^^^^^^^^^^^^^^^^^ +Using the new interfaces through the legacy interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Here we use the new interface as exposed through the existing (legacy) +solver factory and solver interface wrapper. This provides an API that +is compatible with the existing (legacy) Pyomo solver interface and can +be used with other Pyomo tools / capabilities. .. testcode:: :skipif: not ipopt_available @@ -61,11 +74,10 @@ Backwards Compatible Mode ... 3 Declarations: x y obj -Future Capability Mode -^^^^^^^^^^^^^^^^^^^^^^ +Using the new interfaces directly +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -There are multiple ways to utilize the future capability mode: direct import -or changed ``SolverFactory`` version. +Here we use the new interface by importing it directly: .. testcode:: :skipif: not ipopt_available @@ -87,7 +99,7 @@ or changed ``SolverFactory`` version. opt = Ipopt() status = opt.solve(model) assert_optimal_termination(status) - # Displays important results information; only available in future capability mode + # Displays important results information; only available through the new interfaces status.display() model.pprint() @@ -99,7 +111,49 @@ or changed ``SolverFactory`` version. ... 3 Declarations: x y obj -Changing the ``SolverFactory`` version: +Using the new interfaces through the "new" SolverFactory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Here we use the new interface by retrieving it from the new ``SolverFactory``: + +.. testcode:: + :skipif: not ipopt_available + + # Direct import + import pyomo.environ as pyo + from pyomo.contrib.solver.util import assert_optimal_termination + from pyomo.contrib.solver.factory import SolverFactory + + model = pyo.ConcreteModel() + model.x = pyo.Var(initialize=1.5) + model.y = pyo.Var(initialize=1.5) + + def rosenbrock(model): + return (1.0 - model.x) ** 2 + 100.0 * (model.y - model.x**2) ** 2 + + model.obj = pyo.Objective(rule=rosenbrock, sense=pyo.minimize) + + opt = SolverFactory('ipopt') + status = opt.solve(model) + assert_optimal_termination(status) + # Displays important results information; only available through the new interfaces + status.display() + model.pprint() + +.. testoutput:: + :skipif: not ipopt_available + :hide: + + solution_loader: ... + ... + 3 Declarations: x y obj + +Switching all of Pyomo to use the new interfaces +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We also provide a mechansim to get a "preview" of the future where we +replace the existing (legacy) SolverFactory and utilities with the new +(development) version: .. testcode:: :skipif: not ipopt_available @@ -120,7 +174,7 @@ Changing the ``SolverFactory`` version: status = pyo.SolverFactory('ipopt').solve(model) assert_optimal_termination(status) - # Displays important results information; only available in future capability mode + # Displays important results information; only available through the new interfaces status.display() model.pprint() @@ -141,16 +195,15 @@ Changing the ``SolverFactory`` version: Linear Presolve and Scaling ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The new interface will allow for direct manipulation of linear presolve and scaling -options for certain solvers. Currently, these options are only available for -``ipopt``. +The new interface allows access to new capabilities in the various +problem writers, including the linear presolve and scaling options +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 :members: solve -The ``writer_config`` configuration option can be used to manipulate presolve -and scaling options: - .. testcode:: from pyomo.contrib.solver.ipopt import Ipopt From 286e99de1e076c19f74df6705d1b8493cfb82992 Mon Sep 17 00:00:00 2001 From: John Siirola Date: Wed, 21 Feb 2024 09:42:55 -0700 Subject: [PATCH 2/5] Fix typos --- doc/OnlineDocs/developer_reference/solvers.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/OnlineDocs/developer_reference/solvers.rst b/doc/OnlineDocs/developer_reference/solvers.rst index 9f18119e373..cdf36b74397 100644 --- a/doc/OnlineDocs/developer_reference/solvers.rst +++ b/doc/OnlineDocs/developer_reference/solvers.rst @@ -82,7 +82,7 @@ Here we use the new interface by importing it directly: .. testcode:: :skipif: not ipopt_available - # Direct import + # Direct import import pyomo.environ as pyo from pyomo.contrib.solver.util import assert_optimal_termination from pyomo.contrib.solver.ipopt import Ipopt @@ -119,7 +119,7 @@ Here we use the new interface by retrieving it from the new ``SolverFactory``: .. testcode:: :skipif: not ipopt_available - # Direct import + # 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 @@ -151,14 +151,14 @@ Here we use the new interface by retrieving it from the new ``SolverFactory``: Switching all of Pyomo to use the new interfaces ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -We also provide a mechansim to get a "preview" of the future where we +We also provide a mechanism to get a "preview" of the future where we replace the existing (legacy) SolverFactory and utilities with the new (development) version: .. testcode:: :skipif: not ipopt_available - # Change SolverFactory version + # 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 From 93fff175609a32262728a33a16e27866398b5f62 Mon Sep 17 00:00:00 2001 From: John Siirola Date: Wed, 21 Feb 2024 09:45:34 -0700 Subject: [PATCH 3/5] Restore link to future docs --- doc/OnlineDocs/developer_reference/solvers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/OnlineDocs/developer_reference/solvers.rst b/doc/OnlineDocs/developer_reference/solvers.rst index cdf36b74397..7b17c4b40f0 100644 --- a/doc/OnlineDocs/developer_reference/solvers.rst +++ b/doc/OnlineDocs/developer_reference/solvers.rst @@ -153,7 +153,7 @@ Switching all of Pyomo to use the new interfaces We also provide a mechanism to get a "preview" of the future where we replace the existing (legacy) SolverFactory and utilities with the new -(development) version: +(development) version (see :doc:`future`): .. testcode:: :skipif: not ipopt_available From a906f9fb760d64bf96d60aa0093ddafacefd14d7 Mon Sep 17 00:00:00 2001 From: Miranda Mundt <55767766+mrmundt@users.noreply.github.com> Date: Wed, 21 Feb 2024 09:52:29 -0700 Subject: [PATCH 4/5] Fix incorrect docstring --- pyomo/contrib/solver/results.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/pyomo/contrib/solver/results.py b/pyomo/contrib/solver/results.py index 699137d2fc9..cbc04681235 100644 --- a/pyomo/contrib/solver/results.py +++ b/pyomo/contrib/solver/results.py @@ -164,10 +164,12 @@ class Results(ConfigDict): iteration_count: int The total number of iterations. timing_info: ConfigDict - A ConfigDict containing two pieces of information: - start_timestamp: UTC timestamp of when run was initiated - wall_time: elapsed wall clock time for entire process - timer: a HierarchicalTimer object containing timing data about the solve + A ConfigDict containing three pieces of information: + - ``start_timestamp``: UTC timestamp of when run was initiated + - ``wall_time``: elapsed wall clock time for entire process + - ``timer``: a HierarchicalTimer object containing timing data about the solve + + Specific solvers may add other relevant timing information, as appropriate. extra_info: ConfigDict A ConfigDict to store extra information such as solver messages. solver_configuration: ConfigDict From cf5dc9c954700d106152ff6afc47a766a4062001 Mon Sep 17 00:00:00 2001 From: John Siirola Date: Wed, 21 Feb 2024 09:55:39 -0700 Subject: [PATCH 5/5] Add warning / link to #1030 --- doc/OnlineDocs/developer_reference/solvers.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/OnlineDocs/developer_reference/solvers.rst b/doc/OnlineDocs/developer_reference/solvers.rst index 7b17c4b40f0..6168da3480e 100644 --- a/doc/OnlineDocs/developer_reference/solvers.rst +++ b/doc/OnlineDocs/developer_reference/solvers.rst @@ -1,6 +1,16 @@ Future Solver Interface Changes =============================== +.. note:: + + The new solver interfaces are still under active development. They + are included in the releases as development previews. Please be + aware that APIs and functionality may change with no notice. + + We welcome any feedback and ideas as we develop this capability. + Please post feedback on + `Issue 1030 `_. + Pyomo offers interfaces into multiple solvers, both commercial and open source. To support better capabilities for solver interfaces, the Pyomo team is actively redesigning the existing interfaces to make them more