Merge remote-tracking branch 'upstream/main' into pyomonlp-scaling

doc/OnlineDocs/contributed_packages/alternative_solutions.rst

@@ -0,0 +1,107 @@
+###############################################
+Generating Alternative (Near-)Optimal Solutions
+###############################################
+
+Optimization solvers are generally designed to return a feasible solution
+to the user. However, there are many applications where a user needs
+more context than this result. For example,
+
+* alternative solutions can support an assessment of trade-offs between competing objectives;
+
+* if the optimization formulation may be inaccurate or untrustworthy, then comparisons amongst alternative solutions provide additional insights into the reliability of these model predictions; or
+
+* the user may have unexpressed objectives or constraints, which only are realized in later stages of model analysis.
+
+The *alternative-solutions library* provides a variety of functions that
+can be used to generate optimal or near-optimal solutions for a pyomo
+model. Conceptually, these functions are like pyomo solvers. They can
+be configured with solver names and options, and they return a list of
+solutions for the pyomo model. However, these functions are independent
+of pyomo's solver interface because they return a custom solution object.
+
+The following functions are defined in the alternative-solutions library:
+
+* ``enumerate_binary_solutions``
+
+    * Finds alternative optimal solutions for a binary problem using no-good cuts.
+
+* ``enumerate_linear_solutions``
+
+    * Finds alternative optimal solutions for a (mixed-integer) linear program.
+
+* ``enumerate_linear_solutions_soln_pool``
+
+    * Finds alternative optimal solutions for a (mixed-binary) linear program using Gurobi's solution pool feature.
+
+* ``gurobi_generate_solutions``
+
+    * Finds alternative optimal solutions for discrete variables using Gurobi's built-in solution pool capability.
+
+* ``obbt_analysis_bounds_and_solutions``
+
+    * Calculates the bounds on each variable by solving a series of min and max optimization problems where each variable is used as the objective function. This can be applied to any class of problem supported by the selected solver.
+
+
+Usage Example
+-------------
+
+Many of functions in the alternative-solutions library have similar options, so we simply illustrate the ``enumerate_binary_solutions`` function.  We define a simple knapsack example whose alternative solutions have integer objective values ranging from 0 to 90.
+
+.. doctest::
+
+   >>> import pyomo.environ as pyo
+
+   >>> values = [10, 40, 30, 50]
+   >>> weights = [5, 4, 6, 3]
+   >>> capacity = 10
+
+   >>> m = pyo.ConcreteModel()
+   >>> m.x = pyo.Var(range(4), within=pyo.Binary)
+   >>> m.o = pyo.Objective(expr=sum(values[i] * m.x[i] for i in range(4)), sense=pyo.maximize)
+   >>> m.c = pyo.Constraint(expr=sum(weights[i] * m.x[i] for i in range(4)) <= capacity)
+
+We can execute the ``enumerate_binary_solutions`` function to generate a list of ``Solution`` objects that represent alternative optimal solutions:
+
+.. doctest::
+   :skipif: not glpk_available
+
+   >>> import pyomo.contrib.alternative_solutions as aos
+   >>> solns = aos.enumerate_binary_solutions(m, num_solutions=100, solver="glpk")
+   >>> assert len(solns) == 10
+
+Each ``Solution`` object contains information about the objective and variables, and it includes various methods to access this information.  For example:
+
+.. doctest::
+   :skipif: not glpk_available
+
+   >>> print(solns[0])
+   {
+       "fixed_variables": [],
+       "objective": "o",
+       "objective_value": 90.0,
+       "solution": {
+           "x[0]": 0,
+           "x[1]": 1,
+           "x[2]": 0,
+           "x[3]": 1
+       }
+   }
+
+
+Interface Documentation
+-----------------------
+
+.. currentmodule:: pyomo.contrib.alternative_solutions
+
+.. autofunction:: enumerate_binary_solutions
+
+.. autofunction:: enumerate_linear_solutions
+
+.. autofunction:: enumerate_linear_solutions_soln_pool
+
+.. autofunction:: gurobi_generate_solutions
+
+.. autofunction:: obbt_analysis_bounds_and_solutions
+
+.. autoclass:: Solution
+

doc/OnlineDocs/contributed_packages/index.rst

@@ -15,6 +15,7 @@ Contributed packages distributed with Pyomo:
 .. toctree::
    :maxdepth: 1
 
+   alternative_solutions.rst
    community.rst
    doe/doe.rst
    gdpopt.rst

pyomo/common/fileutils.py

@@ -286,10 +286,17 @@ def find_dir(
     )
 
 
-_exeExt = {'linux': None, 'windows': '.exe', 'cygwin': '.exe', 'darwin': None}
+_exeExt = {
+    'linux': None,
+    'freebsd': None,
+    'windows': '.exe',
+    'cygwin': '.exe',
+    'darwin': None,
+}
 
 _libExt = {
     'linux': ('.so', '.so.*'),
+    'freebsd': ('.so', '.so.*'),
     'windows': ('.dll', '.pyd'),
     'cygwin': ('.dll', '.so', '.so.*'),
     'darwin': ('.dylib', '.so', '.so.*'),

pyomo/common/tests/test_download.py

@@ -22,7 +22,7 @@
 import pyomo.common.envvar as envvar
 
 from pyomo.common import DeveloperError
-from pyomo.common.fileutils import this_file
+from pyomo.common.fileutils import this_file, Executable
 from pyomo.common.download import FileDownloader, distro_available
 from pyomo.common.log import LoggingIntercept
 from pyomo.common.tee import capture_output
@@ -173,7 +173,8 @@ def test_get_os_version(self):
                 self.assertTrue(v.replace('.', '').startswith(dist_ver))
 
             if (
-                subprocess.run(
+                Executable('lsb_release').available()
+                and subprocess.run(
                     ['lsb_release'],
                     stdout=subprocess.DEVNULL,
                     stderr=subprocess.DEVNULL,
@@ -206,7 +207,7 @@ def test_get_os_version(self):
             self.assertEqual(_os, 'win')
             self.assertEqual(_norm, _os + ''.join(_ver.split('.')[:2]))
         else:
-            self.assertEqual(ans, '')
+            self.assertEqual(_os, '')
 
         self.assertEqual((_os, _ver), FileDownloader._os_version)
         # Exercise the fetch from CACHE

pyomo/common/unittest.py

@@ -858,7 +858,7 @@ def filter_file_contents(self, lines, abstol=None):
 
         return filtered
 
-    def compare_baseline(self, test_output, baseline, abstol=1e-6, reltol=None):
+    def compare_baseline(self, test_output, baseline, abstol=1e-6, reltol=1e-8):
         # Filter files independently and then compare filtered contents
         out_filtered = self.filter_file_contents(
             test_output.strip().split('\n'), abstol

pyomo/contrib/alternative_solutions/README.md

@@ -0,0 +1,8 @@
+# alternative_solutions
+
+pyomo.contrib.alternative_solutions is a collection of functions that
+that generate a set of alternative (near-)optimal solutions
+(AOS).  These functions rely on a pyomo solver to search for solutions,
+and they iteratively adapt the search process to find a variety of
+alternative solutions.
+

pyomo/contrib/alternative_solutions/__init__.py

@@ -0,0 +1,20 @@
+#  ___________________________________________________________________________
+#
+#  Pyomo: Python Optimization Modeling Objects
+#  Copyright (c) 2008-2024
+#  National Technology and Engineering Solutions of Sandia, LLC
+#  Under the terms of Contract DE-NA0003525 with National Technology and
+#  Engineering Solutions of Sandia, LLC, the U.S. Government retains certain
+#  rights in this software.
+#  This software is distributed under the 3-clause BSD License.
+#  ___________________________________________________________________________
+
+from pyomo.contrib.alternative_solutions.aos_utils import logcontext
+from pyomo.contrib.alternative_solutions.solution import Solution
+from pyomo.contrib.alternative_solutions.solnpool import gurobi_generate_solutions
+from pyomo.contrib.alternative_solutions.balas import enumerate_binary_solutions
+from pyomo.contrib.alternative_solutions.obbt import (
+    obbt_analysis,
+    obbt_analysis_bounds_and_solutions,
+)
+from pyomo.contrib.alternative_solutions.lp_enum import enumerate_linear_solutions