Merge branch 'main' into main

Author: slilonfe5

.github/workflows/test_branches.yml

@@ -23,7 +23,7 @@ env:
   PYTHON_CORE_PKGS: wheel
   PYPI_ONLY: z3-solver linear-tree
   PYPY_EXCLUDE: scipy numdifftools seaborn statsmodels linear-tree
-  CACHE_VER: v221013.1
+  CACHE_VER: v250820.0
   NEOS_EMAIL: tests@pyomo.org
   SRC_REF: ${{ github.head_ref || github.ref }}
   PYOMO_WORKFLOW: branch
@@ -147,7 +147,6 @@ jobs:
         else
             echo "GHA_JOBGROUP=other" >> $GITHUB_ENV
         fi
-        # Note: pandas 1.0.3 causes gams 29.1.0 import to fail in python 3.8
         EXTRAS=tests
         if test -z "${{matrix.slim}}"; then
             EXTRAS="$EXTRAS,docs,optional"
@@ -179,7 +178,7 @@ jobs:
       id: download-cache
       with:
         path: cache/download
-        key: download-${{env.CACHE_VER}}.0-${{runner.os}}
+        key: download-${{env.CACHE_VER}}-${{runner.os}}
 
     - name: Configure curl
       run: |
@@ -540,7 +539,7 @@ jobs:
             Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
         $INSTALLER = "${env:DOWNLOAD_DIR}/gams_install.exe"
         # Demo licenses are included for 5mo from the newest release
-        $URL = "https://d37drm4t2jghv5.cloudfront.net/distributions/50.1.0"
+        $URL = "https://d37drm4t2jghv5.cloudfront.net/distributions/latest"
         if ( "${{matrix.TARGET}}" -eq "win" ) {
             $URL = "$URL/windows/windows_x64_64.exe"
         } elseif ( "${{matrix.TARGET}}" -eq "osx" ) {

.github/workflows/test_pr_and_main.yml

@@ -31,7 +31,7 @@ env:
   PYTHON_CORE_PKGS: wheel
   PYPI_ONLY: z3-solver linear-tree
   PYPY_EXCLUDE: scipy numdifftools seaborn statsmodels linear-tree
-  CACHE_VER: v221013.1
+  CACHE_VER: v250820.0
   NEOS_EMAIL: tests@pyomo.org
   SRC_REF: ${{ github.head_ref || github.ref }}
   PYOMO_WORKFLOW: |
@@ -199,7 +199,6 @@ jobs:
         else
             echo "GHA_JOBGROUP=other" >> $GITHUB_ENV
         fi
-        # Note: pandas 1.0.3 causes gams 29.1.0 import to fail in python 3.8
         EXTRAS=tests
         if test -z "${{matrix.slim}}"; then
             EXTRAS="$EXTRAS,docs,optional"
@@ -231,7 +230,7 @@ jobs:
       id: download-cache
       with:
         path: cache/download
-        key: download-${{env.CACHE_VER}}.0-${{runner.os}}
+        key: download-${{env.CACHE_VER}}-${{runner.os}}
 
     - name: Configure curl
       run: |
@@ -592,7 +591,7 @@ jobs:
             Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
         $INSTALLER = "${env:DOWNLOAD_DIR}/gams_install.exe"
         # Demo licenses are included for 5mo from the newest release
-        $URL = "https://d37drm4t2jghv5.cloudfront.net/distributions/50.1.0"
+        $URL = "https://d37drm4t2jghv5.cloudfront.net/distributions/latest"
         if ( "${{matrix.TARGET}}" -eq "win" ) {
             $URL = "$URL/windows/windows_x64_64.exe"
         } elseif ( "${{matrix.TARGET}}" -eq "osx" ) {

pyomo/common/enums.py

@@ -24,6 +24,7 @@
 .. autosummary::
 
    ObjectiveSense
+   SolverAPIVersion
 
 """
 
@@ -213,5 +214,22 @@ def __str__(self):
         return self.name
 
 
+class SolverAPIVersion(NamedIntEnum):
+    """
+    Enum identifying Pyomo solver API version
+
+    The numeric values are intentionally a bit odd because APPSI came
+    between the official V1 and V2. We still want it to be chronologically
+    in order without sacrificing the human-logic of v1 vs. v2.
+    """
+
+    #: Original Coopr/Pyomo solver interface
+    V1 = 10
+    #: Automatic Persistent Pyomo Solver Interface (experimental)
+    APPSI = 15
+    #: Redesigned solver interface (circa 2024)
+    V2 = 20
+
+
 minimize = ObjectiveSense.minimize
 maximize = ObjectiveSense.maximize

pyomo/common/envvar.py

@@ -9,12 +9,39 @@
 #  This software is distributed under the 3-clause BSD License.
 #  ___________________________________________________________________________
 
+"""Attributes describing the current platform and user configuration.
+
+This module provides standardized attributes that other parts of Pyomo
+can use to interrogate aspects of the current platform, and to find
+information about the current user configuration (including where to
+locate the main Pyomo configuration directory).
+
+"""
+
 import os
 import platform
 
+_platform = platform.system().lower()
+#: bool : True if running in a "native" Windows environment
+is_native_windows = _platform.startswith('windows')
+#: bool : True if running on Windows (native or cygwin)
+is_windows = is_native_windows or _platform.startswith('cygwin')
+#: bool : True if running on Mac/OSX
+is_osx = _platform.startswith('darwin')
+#: bool: True if running under the PyPy interpreter
+is_pypy = platform.python_implementation().lower().startswith('pypy')
+
+#: str : Absolute path to the user's Pyomo Configuration Directory.
+#:
+#:     By default, this is ``~/.pyomo`` on Linux and OSX and
+#:     ``%LOCALAPPDATA%/Pyomo`` on Windows.  It can be overridden by
+#:     setting the ``PYOMO_CONFIG_DIR`` environment variable before
+#:     importing Pyomo.
+PYOMO_CONFIG_DIR = None
+
 if 'PYOMO_CONFIG_DIR' in os.environ:
     PYOMO_CONFIG_DIR = os.path.abspath(os.environ['PYOMO_CONFIG_DIR'])
-elif platform.system().lower().startswith(('windows', 'cygwin')):
+elif is_windows:
     PYOMO_CONFIG_DIR = os.path.abspath(
         os.path.join(os.environ.get('LOCALAPPDATA', ''), 'Pyomo')
     )

pyomo/common/fileutils.py

@@ -505,6 +505,50 @@ def import_file(path, clear_cache=False, infer_package=True, module_name=None):
     return module
 
 
+def to_legal_filename(name, universal=False) -> str:
+    """Convert a string to a legal filename on the current platform.
+
+    This converts a candidate file name (not a path) and converts it to
+    a legal file name on the current platform.  This includes replacing
+    any unallowable characters (including the path separator) with
+    underscores (``_``), and on some platforms, enforcing restrictions
+    on the allowable final character.
+
+    Parameters
+    ----------
+    name : str
+
+        The original (desired) file name
+
+    universal : bool
+
+        If True, this will attempt a form of "universal" standardization
+        that uses the most restrictive set of character translations and
+        rules.  Currently, ``universal=True`` is equivalent to running
+        the Windows translations.
+
+    """
+    if envvar.is_windows or universal:
+        tr = getattr(to_legal_filename, 'tr', None)
+        if tr is None:
+            # Windows illegal characters: 0-31, plus < > : " / \ | ? *
+            _illegal = r'<>:"/\|?*' + ''.join(map(chr, range(32)))
+            tr = to_legal_filename.tr = str.maketrans(_illegal, '_' * len(_illegal))
+        # Remove illegal characters
+        name = name.translate(tr)
+        if name:
+            # Windows allows filenames to end with space or dot, but the
+            # file explorer can't interact with them
+            if name[-1] in ' .':
+                name = name[:-1] + '_'
+            # Similarly, starting with a space is generally a bad idea
+            if name[0] == ' ':
+                name = '_' + name[1:]
+    else:
+        name = name.replace('/', '_').replace(chr(0), '_')
+    return name
+
+
 class PathData(object):
     """An object for storing and managing a :py:class:`PathManager` path"""
 

pyomo/common/tee.py

@@ -765,7 +765,8 @@ def open(self, mode="w", buffering=-1, encoding=None, newline=None):
         # Note that is it VERY important to close file handles in the
         # same thread that opens it.  If you don't you can see deadlocks
         # and a peculiar error ("libgcc_s.so.1 must be installed for
-        # pthread_cancel to work"; see https://bugs.python.org/issue18748)
+        # pthread_cancel to work"; see
+        # https://github.com/python/cpython/issues/62948)
         #
         # To accomplish this, we will keep two handle lists: one is the
         # set of "active" handles that the (merged reader) thread is

pyomo/common/tests/test_enums.py

@@ -13,7 +13,7 @@
 
 import pyomo.common.unittest as unittest
 
-from pyomo.common.enums import ExtendedEnumType, ObjectiveSense
+from pyomo.common.enums import ExtendedEnumType, ObjectiveSense, SolverAPIVersion
 
 
 class ProblemSense(enum.IntEnum, metaclass=ExtendedEnumType):
@@ -95,3 +95,25 @@ def test_call(self):
     def test_str(self):
         self.assertEqual(str(ObjectiveSense.minimize), 'minimize')
         self.assertEqual(str(ObjectiveSense.maximize), 'maximize')
+
+
+class TestSolverAPIVersion(unittest.TestCase):
+    def test_members(self):
+        self.assertEqual(
+            list(SolverAPIVersion),
+            [SolverAPIVersion.V1, SolverAPIVersion.APPSI, SolverAPIVersion.V2],
+        )
+
+    def test_call(self):
+        self.assertIs(SolverAPIVersion(10), SolverAPIVersion.V1)
+        self.assertIs(SolverAPIVersion(15), SolverAPIVersion.APPSI)
+        self.assertIs(SolverAPIVersion(20), SolverAPIVersion.V2)
+
+        self.assertIs(SolverAPIVersion('V1'), SolverAPIVersion.V1)
+        self.assertIs(SolverAPIVersion('APPSI'), SolverAPIVersion.APPSI)
+        self.assertIs(SolverAPIVersion('V2'), SolverAPIVersion.V2)
+
+        with self.assertRaisesRegex(
+            ValueError, "'foo' is not a valid SolverAPIVersion"
+        ):
+            SolverAPIVersion('foo')

pyomo/common/tests/test_fileutils.py

@@ -38,6 +38,7 @@
     _libExt,
     ExecutableData,
     import_file,
+    to_legal_filename,
 )
 from pyomo.common.download import FileDownloader
 
@@ -497,3 +498,35 @@ def test_PathManager(self):
         Executable(f_in_path2).rehash()
         self.assertTrue(Executable(f_in_path2).available())
         self.assertEqual(Executable(f_in_path2).path(), f_loc)
+
+    def test_to_legal_filename(self):
+        self.assertEqual('abc', to_legal_filename('abc'))
+        self.assertEqual('', to_legal_filename(''))
+        if envvar.is_windows:
+            self.assertEqual('_abc', to_legal_filename(' abc'))
+            self.assertEqual('abc_', to_legal_filename('abc.'))
+            self.assertEqual('abc_', to_legal_filename('abc '))
+            self.assertEqual('abc_def', to_legal_filename('abc/def'))
+            self.assertEqual('abc_def', to_legal_filename('abc\\def'))
+            self.assertEqual(
+                'a_b_c', to_legal_filename(''.join(['a', chr(0), 'b', chr(7), 'c']))
+            )
+        else:
+            self.assertEqual(' abc', to_legal_filename(' abc'))
+            self.assertEqual('abc.', to_legal_filename('abc.'))
+            self.assertEqual('abc ', to_legal_filename('abc '))
+            self.assertEqual('abc_def', to_legal_filename('abc/def'))
+            self.assertEqual('abc\\def', to_legal_filename('abc\\def'))
+            self.assertEqual(
+                'a_b' + chr(7) + 'c',
+                to_legal_filename(''.join(['a', chr(0), 'b', chr(7), 'c'])),
+            )
+
+        self.assertEqual('_abc', to_legal_filename(' abc', True))
+        self.assertEqual('abc_', to_legal_filename('abc.', True))
+        self.assertEqual('abc_', to_legal_filename('abc ', True))
+        self.assertEqual('abc_def', to_legal_filename('abc/def', True))
+        self.assertEqual('abc_def', to_legal_filename('abc\\def', True))
+        self.assertEqual(
+            'a_b_c', to_legal_filename(''.join(['a', chr(0), 'b', chr(7), 'c']), True)
+        )

pyomo/contrib/appsi/base.py

@@ -28,7 +28,7 @@
 
 from pyomo.common.config import ConfigDict, ConfigValue, NonNegativeFloat
 from pyomo.common.errors import ApplicationError
-from pyomo.common.enums import IntEnum
+from pyomo.common.enums import IntEnum, SolverAPIVersion
 from pyomo.common.factory import Factory
 from pyomo.common.timing import HierarchicalTimer
 from pyomo.core.base.constraint import ConstraintData, Constraint
@@ -635,6 +635,18 @@ def __str__(self):
             # preserve the previous behavior
             return self.name
 
+    @classmethod
+    def api_version(self):
+        """
+        Return the public API supported by this interface.
+
+        Returns
+        -------
+        ~pyomo.common.enums.SolverAPIVersion
+            A solver API enum object
+        """
+        return SolverAPIVersion.APPSI
+
     @abc.abstractmethod
     def solve(self, model: BlockData, timer: HierarchicalTimer = None) -> Results:
         """

pyomo/contrib/solver/common/base.py

@@ -18,7 +18,7 @@
 from pyomo.core.base.block import BlockData
 from pyomo.core.base.objective import Objective, ObjectiveData
 from pyomo.common.config import ConfigValue
-from pyomo.common.enums import IntEnum
+from pyomo.common.enums import IntEnum, SolverAPIVersion
 from pyomo.common.errors import ApplicationError
 from pyomo.common.deprecation import deprecation_warning
 from pyomo.common.modeling import NOTSET
@@ -105,6 +105,18 @@ def __enter__(self):
     def __exit__(self, exc_type, exc_value, exc_traceback):
         """Exit statement - enables `with` statements."""
 
+    @classmethod
+    def api_version(self):
+        """
+        Return the public API supported by this interface.
+
+        Returns
+        -------
+        ~pyomo.common.enums.SolverAPIVersion
+            A solver API enum object
+        """
+        return SolverAPIVersion.V2
+
     def solve(self, model: BlockData, **kwargs) -> Results:
         """Solve a Pyomo model.