Merge pull request #2406 from emma58/gdpopt-rewrite

GDPopt rewrite!

Author: emma58

doc/OnlineDocs/contributed_packages/gdpopt.rst

@@ -29,27 +29,35 @@ Credit for prototyping and development can be found in the ``GDPopt`` class docu
 .. _Lee & Grossmann, 2000: https://doi.org/10.1016/S0098-1354(00)00581-0
 .. _Chen et al., 2018: https://doi.org/10.1016/B978-0-444-64241-7.50143-9
 
-Usage of GDPopt to solve a Pyomo.GDP concrete model involves:
+GDPopt can be used to solve a Pyomo.GDP concrete model in two ways.
+The simplest is to instantiate the generic GDPopt solver and specify the desired algorithm as an argument to the ``solve`` method:
 
 .. code::
 
-  >>> SolverFactory('gdpopt').solve(model)
+  >>> SolverFactory('gdpopt').solve(model, algorithm='LOA')
+
+The alternative is to instantiate an algorithm-specific GDPopt solver:
+
+.. code::
+
+  >>> SolverFactory('gdpopt.loa').solve(model)
+
+In the above examples, GDPopt uses the GDPopt-LOA algorithm.
+Other algorithms may be used by specifying them in the ``algorithm`` argument when using the generic solver or by instantiating the algorithm-specific GDPopt solvers. All GDPopt options are listed below.
 
 .. note::
 
-  By default, GDPopt uses the GDPopt-LOA strategy.
-  Other strategies may be used by specifying the ``strategy`` argument during ``solve()``.
-  All GDPopt options are listed below.
+  The generic GDPopt solver allows minimal configuration outside of the arguments to the ``solve`` method. To avoid repeatedly specifying the same configuration options to the ``solve`` method, use the algorithm-specific solvers.
 
-Logic-based Outer Approximation
--------------------------------
+Logic-based Outer Approximation (LOA)
+-------------------------------------
 
 `Chen et al., 2018`_ contains the following flowchart, taken from the preprint version:
 
 .. image:: gdpopt_flowchart.png
     :scale: 70%
 
-An example which includes the modeling approach may be found below.
+An example that includes the modeling approach may be found below.
 
 .. doctest::
   :skipif: not glpk_available
@@ -75,8 +83,8 @@ An example which includes the modeling approach may be found below.
   >>> model.objective = Objective(expr=model.x + 0.1*model.y, sense=minimize)
 
   Solve the model using GDPopt
-  >>> results = SolverFactory('gdpopt').solve(
-  ...     model, strategy='LOA', mip_solver='glpk') # doctest: +IGNORE_RESULT
+  >>> results = SolverFactory('gdpopt.loa').solve(
+  ...     model, mip_solver='glpk') # doctest: +IGNORE_RESULT
 
   Display the final solution
   >>> model.display()
@@ -107,10 +115,38 @@ An example which includes the modeling approach may be found below.
 
 .. code::
 
-  >>> SolverFactory('gdpopt').solve(model, tee=True)
+  >>> SolverFactory('gdpopt.loa').solve(model, tee=True)
+
+Global Logic-based Outer Approximation (GLOA)
+---------------------------------------------
 
-Logic-based Branch-and-Bound
-----------------------------
+The same algorithm can be used to solve GDPs involving nonconvex nonlinear constraints by solving the subproblems globally:
+
+.. code::
+
+  >>> SolverFactory('gdpopt.gloa').solve(model)
+
+.. warning::
+
+  The ``nlp_solver`` option must be set to a global solver for the solution returned by GDPopt to also be globally optimal.
+
+Relaxation with Integer Cuts (RIC)
+----------------------------------
+
+Instead of outer approximation, GDPs can be solved using the same MILP relaxation as in the previous two algorithms, but instead of using the subproblems to generate outer-approximation cuts, the algorithm adds only no-good cuts for every discrete solution encountered:
+
+.. code::
+
+  >>> SolverFactory('gdpopt.ric').solve(model)
+
+Again, this is a global algorithm if the subproblems are solved globally, and is not otherwise.
+
+.. note::
+
+  The RIC algorithm will not necessarily enumerate all discrete solutions as it is possible for the bounds to converge first. However, full enumeration is not uncommon.
+
+Logic-based Branch-and-Bound (LBB)
+----------------------------------
 
 The GDPopt-LBB solver branches through relaxed subproblems with inactive disjunctions.
 It explores the possibilities based on best lower bound,
@@ -139,7 +175,7 @@ To use the GDPopt-LBB solver, define your Pyomo GDP model as usual:
   >>> m.djn = Disjunction(expr=[m.y1, m.y2])
 
   Invoke the GDPopt-LBB solver
-  >>> results = SolverFactory('gdpopt').solve(m, strategy='LBB')
+  >>> results = SolverFactory('gdpopt.lbb').solve(m)
 
   >>> print(results)  # doctest: +SKIP
   >>> print(results.solver.status)
@@ -160,3 +196,15 @@ GDPopt implementation and optional arguments
 
 .. autoclass:: pyomo.contrib.gdpopt.GDPopt.GDPoptSolver
     :members:
+
+.. autoclass:: pyomo.contrib.gdpopt.loa.GDP_LOA_Solver
+    :members:
+
+.. autoclass:: pyomo.contrib.gdpopt.gloa.GDP_GLOA_Solver
+    :members:
+
+.. autoclass:: pyomo.contrib.gdpopt.ric.GDP_RIC_Solver
+    :members:
+
+.. autoclass:: pyomo.contrib.gdpopt.branch_and_bound.GDP_LBB_Solver
+    :members:

examples/gdp/eight_process/eight_proc_logical.py

@@ -162,7 +162,7 @@ def use_unit_or_not(m, unit):
     m = build_eight_process_flowsheet()
     from pyomo.environ import TransformationFactory
     TransformationFactory('core.logical_to_linear').apply_to(m)
-    SolverFactory('gdpopt').solve(m, tee=True, strategy='LOA')
+    SolverFactory('gdpopt.loa').solve(m, tee=True)
     update_boolean_vars_from_binary(m)
     m.Y.display()
     m.flow.display()

examples/gdp/nine_process/small_process.py

@@ -198,8 +198,8 @@ def build_nonexclusive_model():
 if __name__ == '__main__':
     from pyomo.environ import SolverFactory
     m = build_model()
-    result = SolverFactory('gdpopt').solve(
-        m, tee=True, strategy='GLOA',
+    result = SolverFactory('gdpopt.gloa').solve(
+        m, tee=True,
         mip_solver='gams',
         nlp_solver='gams',
         nlp_solver_args=dict(add_options=['option optcr=0.01;']),
@@ -211,8 +211,8 @@ def build_nonexclusive_model():
     m.x.display()
 
     m = build_nonexclusive_model()
-    result = SolverFactory('gdpopt').solve(
-        m, tee=True, strategy='GLOA',
+    result = SolverFactory('gdpopt.gloa').solve(
+        m, tee=True,
         mip_solver='gams',
         nlp_solver='gams',
         nlp_solver_args=dict(add_options=['option optcr=0.01;']),

examples/gdp/small_lit/ex1_Lee.py

@@ -34,6 +34,6 @@ def build_model():
 
 if __name__ == "__main__":
     model = build_model()
-    results = SolverFactory('gdpopt').solve(model, tee=True, strategy='LOA')
+    results = SolverFactory('gdpopt.loa').solve(model, tee=True)
     print(results)
 

examples/gdp/small_lit/ex_633_trespalacios.py

@@ -52,7 +52,7 @@ def build_simple_nonconvex_gdp():
 if __name__ == "__main__":
     model = build_simple_nonconvex_gdp()
     model.pprint()
-    res = SolverFactory('gdpopt').solve(model, tee=True, strategy='GLOA')
+    res = SolverFactory('gdpopt.gloa').solve(model, tee=True)
 
     model.display()
     print(res)

examples/gdp/small_lit/nonconvex_HEN.py

@@ -89,7 +89,7 @@ def exchanger_disjunction(m, disjctn):
         res = SolverFactory('gams').solve(model, tee=True, solver='baron', add_options=['option optcr = 0;'], keepfiles=True)
     else:
         # Note: MC++ needs to be properly installed to use strategy GLOA
-        res = SolverFactory('gdpopt').solve(model, tee=True, strategy='GLOA')
+        res = SolverFactory('gdpopt.gloa').solve(model, tee=True)
 
     # model.display()
     print(res)