gamspy 1.17.0__py3-none-any.whl → 1.17.2__py3-none-any.whl

gamspy/_model.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
 import inspect
-import io
 import logging
 import os
 import threading
 import warnings
 from collections.abc import Sequence
 from enum import Enum
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar
 
 from gams.core.gdx import GMS_UEL_IDENT_SIZE
@@ -37,6 +37,7 @@ from gamspy._options import (
 from gamspy.exceptions import GamspyException, ValidationError
 
 if TYPE_CHECKING:
+    import io
     from typing import Literal
 
     import pandas as pd
@@ -72,21 +73,52 @@ class Problem(Enum):
     """An enumeration for problem all problem types"""
 
     LP = "LP"
+    "Linear Programming"
+
     NLP = "NLP"
+    """Non-Linear Programming"""
+
     QCP = "QCP"
+    """Quadratically Constrained Programs"""
+
     DNLP = "DNLP"
+    """Nonlinear Programming with Discontinuous Derivatives"""
+
     MIP = "MIP"
+    """Mixed Integer Programming"""
+
     RMIP = "RMIP"
+    """Relaxed Mixed Integer Program"""
+
     MINLP = "MINLP"
+    """Mixed Integer Nonlinear Program"""
+
     RMINLP = "RMINLP"
+    """Relaxed Mixed Integer Nonlinear Program"""
+
     MIQCP = "MIQCP"
+    """Mixed Integer Quadratically Constrained Program"""
+
     RMIQCP = "RMIQCP"
+    """Relaxed Mixed Integer Quadratically Constrained Program"""
+
     MCP = "MCP"
+    """Mixed Complementarity Problem"""
+
     CNS = "CNS"
+    """Constrained Nonlinear System"""
+
     MPEC = "MPEC"
+    """Mathematical Programs with Equilibrium Constraints"""
+
     RMPEC = "RMPEC"
+    """Relaxed Mathematical Program with Equilibrium Constraints"""
+
     EMP = "EMP"
+    """Extended Mathematical Program"""
+
     MPSGE = "MPSGE"
+    """General Equilibrium"""
 
     @classmethod
     def values(cls):
@@ -101,8 +133,13 @@ class Sense(Enum):
     """An enumeration for sense types"""
 
     MIN = "MIN"
+    """Minimize the objective."""
+
     MAX = "MAX"
+    """Maximize the objective."""
+
     FEASIBILITY = "FEASIBILITY"
+    """Assess feasibility."""
 
     @classmethod
     def values(cls):
@@ -117,63 +154,156 @@ class ModelStatus(Enum):
     """An enumeration for model status types"""
 
     OptimalGlobal = 1
+    """The solution is optimal, that is, it is feasible (within tolerances) and it has been proven that no other feasible solution with better objective value exists."""
+
     OptimalLocal = 2
+    """A local optimum for an NLP has been found. That is, a solution that is feasible (within tolerances) and it has been proven that there exists a neighborhood of this solution in which no other feasible solution with better objective value exists."""
+
     Unbounded = 3
+    """The solution is unbounded. This message is reliable if the problem is linear, but occasionally it appears for difficult nonlinear problems that are not truly unbounded, but that lack some strategically placed bounds to limit the variables to sensible values."""
+
     InfeasibleGlobal = 4
+    """The problem has been proven to be infeasible. If this was not intended, something is probably misspecified in the logic or the data."""
+
     InfeasibleLocal = 5
+    """No feasible point could be found for the NLP problem from the given starting point. It does not necessarily mean that no feasible point exists."""
+
     InfeasibleIntermed = 6
+    """The current solution is not feasible, but the solver stopped, either because of a limit (for example, iteration or resource) or because of some sort of difficulty. The solver status will give more information."""
+
     Feasible = 7
+    """A feasible solution to a problem without discrete variables has been found."""
+
     Integer = 8
+    """A feasible solution to a problem with discrete variables has been found."""
+
     NonIntegerIntermed = 9
+    """An incomplete solution to a problem with discrete variables. A feasible solution has not yet been found."""
+
     IntegerInfeasible = 10
+    """It has been proven that there is no feasible solution to a problem with discrete variables."""
+
     LicenseError = 11
+    """The solver cannot find the appropriate license key needed to use a specific subsolver."""
+
     ErrorUnknown = 12
+    """After a solver error the model status is unknown."""
+
     ErrorNoSolution = 13
+    """An error occurred and no solution has been returned. No solution will be returned to GAMS because of errors in the solution process."""
+
     NoSolutionReturned = 14
+    """A solution is not expected for this solve. For example, the CONVERT solver only reformats the model but does not give a solution."""
+
     SolvedUnique = 15
+    """Indicates the solution returned is unique, i.e. no other solution exists. Used for CNS models. Examples where this status could be returned include non-singular linear models, triangular models with constant non-zero elements on the diagonal, and triangular models where the functions are monotone in the variable on the diagonal."""
+
     Solved = 16
+    """Indicates the model has been solved: used for CNS models. The solution might or might not be unique. If the solver uses status SOLVED SINGULAR wherever possible then this status implies that the Jacobian is non-singular, i.e. that the solution is at least locally unique."""
+
     SolvedSingular = 17
+    """Indicates the CNS model has been solved, but the Jacobian is singular at the solution. This can indicate that other solutions exist, either along a line (for linear models) or a curve (for nonlinear models) including the solution returned."""
+
     UnboundedNoSolution = 18
+    """The model is unbounded and no solution can be provided."""
+
     InfeasibleNoSolution = 19
+    """The model is infeasible and no solution can be provided."""
 
 
 class SolveStatus(Enum):
     """An enumeration for solve status types"""
 
     NormalCompletion = 1
+    """The solver terminated in a normal way."""
+
     IterationInterrupt = 2
+    """The solver was interrupted because it used too many iterations. The option `iteration_limit` may be used to increase the iteration limit if everything seems normal."""
+
     ResourceInterrupt = 3
+    """The solver was interrupted because it used too much time. The option `time_limit` may be used to increase the time limit if everything seems normal."""
+
     TerminatedBySolver = 4
+    """The solver encountered some difficulty and was unable to continue."""
+
     EvaluationInterrupt = 5
+    """Too many evaluations of nonlinear terms at undefined values. We recommend to use variable bounds to prevent forbidden operations, such as division by zero. The rows in which the errors occur are listed just before the solution."""
+
     CapabilityError = 6
+    """The solver does not have the capability required by the model. For example, some solvers do not support certain types of discrete variables or support a more limited set of functions than other solvers."""
+
     LicenseError = 7
+    """The solver cannot find the appropriate license key needed to use a specific subsolver."""
+
     UserInterrupt = 8
+    """The user has sent a signal to interrupt the solver."""
+
     SetupError = 9
+    """The solver encountered a fatal failure during problem set-up time."""
+
     SolverError = 10
+    """The solver encountered a fatal error."""
+
     InternalError = 11
+    """The solver encountered an internal fatal error."""
+
     Skipped = 12
+    """The entire solve step has been skipped."""
+
     SystemError = 13
+    """This indicates a completely unknown or unexpected error condition."""
 
 
 class FileFormat(Enum):
     """An enumeration for file format types"""
 
     AMPL = "ampl.mod"
+    """AMPL input format."""
+
     AMPLNL = "ampl.nl"
+    """AMPL nl format."""
+
     CPLEXLP = "cplex.lp"
+    """CPLEX LP format."""
+
     CPLEXMPS = "cplex.mps"
+    """CPLEX MPS format."""
+
     GAMSDict = "dict.txt"
+    """GAMS dictionary format."""
+
     GAMSDictMap = "dictmap.gdx"
+    """GAMS dictionary map format."""
+
     GAMSJacobian = "jacobian.gms"
+    """Jacobian in GAMS."""
+
     GAMSPyJacobian = "jacobian.py"
+    """Jacobian in GAMSPy."""
+
     GDXJacobian = "jacobian.gdx"
+    """GDX file with model data incl. Jacobian and Hessian evaluated at current point."""
+
     FileList = "files.txt"
+    """List of file formats generated."""
+
     FixedMPS = "fixed.mps"
+    """Fixed format mps file."""
+
     GAMS = "gams.gms"
+    """GAMS scalar model."""
+
     JuMP = "jump.jl"
+    """JuMP scalar model."""
+
     LINGO = "lingo.lng"
+    """Lingo format."""
+
     OSiL = "osil.xml"
+    """Optimization Services instance Language (OSiL) format."""
+
     Pyomo = "pyomo.py"
+    """Pyomo concrete scalar model."""
 
 
 INTERRUPT_STATUS = [
@@ -394,7 +524,7 @@ class Model:
 
         # matches
         if self._matches is not None:
-            matches: dict = dict()
+            matches: dict = {}
             for key, value in self._matches.items():
                 if isinstance(key, gp.Equation):
                     if isinstance(value, gp.Variable):
@@ -924,19 +1054,19 @@ class Model:
         return assignment
 
     def _generate_solve_string(self) -> str:
-        solve_string = f"solve {self.name} using {self.problem}"
+        solve_statement = [f"solve {self.name} using {self.problem}"]
 
         if self.sense == gp.Sense.FEASIBILITY:
             # Set sense as min or max for feasibility
             self.sense = gp.Sense("MIN")
 
         if self.problem not in (Problem.MCP, Problem.CNS, Problem.EMP):
-            solve_string += f" {self.sense}"
+            solve_statement.append(str(self.sense))
 
         if self._objective_variable is not None:
-            solve_string += f" {self._objective_variable.gamsRepr()}"
+            solve_statement.append(self._objective_variable.gamsRepr())
 
-        return solve_string
+        return " ".join(solve_statement)
 
     def _add_runtime_options(self, options: Options, backend: str = "local") -> None:
         for key, value in options.model_dump(exclude_none=True).items():
@@ -1058,7 +1188,7 @@ class Model:
 
     def convert(
         self,
-        path: str,
+        path: str | Path,
         file_format: FileFormat | Sequence[FileFormat],
         options: ConvertOptions | None = None,
     ) -> None:
@@ -1067,7 +1197,7 @@ class Model:
 
         Parameters
         ----------
-        path : str
+        path : str | Path
             Path to the directory where the converted model files will be saved.
         file_format : FileFormat | Sequence[FileFormat]
             File format(s) to convert the model to. Can be a single FileFormat or a list of FileFormats.
@@ -1090,6 +1220,7 @@ class Model:
         >>> my_model.convert("output_directory", [gp.FileFormat.GAMS, gp.FileFormat.AMPL])
 
         """
+        path = Path(path)
         os.makedirs(path, exist_ok=True)
         solver_options = get_convert_solver_options(path, file_format, options)
         self.solve(solver="convert", solver_options=solver_options)
@@ -1358,7 +1489,7 @@ class Model:
                 if isinstance(key, gp.Equation):
                     equations_in_matches.append(key)
                 else:
-                    equations_in_matches += [equation for equation in key]
+                    equations_in_matches += list(key)
 
         equations = []
         for equation in self.equations:
@@ -1413,7 +1544,7 @@ class Model:
 
     def toGams(
         self,
-        path: str,
+        path: str | Path,
         options: Options | None = None,
         *,
         dump_gams_state: bool = False,
@@ -1423,7 +1554,7 @@ class Model:
 
         Parameters
         ----------
-        path : str
+        path : str | Path
             Path to the directory which will contain the GAMS model.
         options : Options | None, optional
             GAMSPy options, by default None
@@ -1440,18 +1571,20 @@ class Model:
                 f"`options` must be of type gp.Options of found {type(options)}"
             )
 
+        path = Path(path)
         converter = GamsConverter(self, path, options, dump_gams_state)
         converter.convert()
 
-    def toLatex(self, path: str, generate_pdf: bool = False) -> None:
+    def toLatex(self, path: str | Path, generate_pdf: bool = False) -> None:
         """
         Generates a latex file that contains the model definition under path/<model_name>.tex
 
         Parameters
         ----------
-        path : str
+        path : str | Path
             Path to the directory which will contain the .tex file.
         """
+        path = Path(path)
         converter = LatexConverter(self, path)
         converter.convert()
 

gamspy/_model_instance.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import io
 import logging
 import os
 import sys
@@ -66,7 +65,6 @@ from gamspy._database import (
     GamsParameter,
     GamsVariable,
 )
-from gamspy._options import FreezeOptions, Options
 from gamspy.exceptions import (
     GamspyException,
     ValidationError,
@@ -74,7 +72,10 @@ from gamspy.exceptions import (
 )
 
 if TYPE_CHECKING:
+    import io
+
     from gamspy import Container, Model, Parameter
+    from gamspy._options import FreezeOptions, Options
     from gamspy._symbols.implicits import ImplicitParameter
 
 logger = logging.getLogger("FROZEN MODEL")

gamspy/_options.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import io
 import os
 import warnings
 from pathlib import Path
@@ -11,6 +10,7 @@ from pydantic import BaseModel, ConfigDict
 from gamspy.exceptions import ValidationError
 
 if TYPE_CHECKING:
+    import io
     from types import FrameType
 
     from gamspy import Container
@@ -374,8 +374,8 @@ class Options(BaseModel):
     report_underflow: bool | None = None
 
     def model_post_init(self, context: Any) -> None:
-        self._extra_options: dict[str, Any] = dict()
-        self._debug_options: dict[str, Any] = dict()
+        self._extra_options: dict[str, Any] = {}
+        self._debug_options: dict[str, Any] = {}
         self._solver: str | None = None
         self._problem: str | None = None
         self._solver_options_file: str = "0"
@@ -458,7 +458,7 @@ class Options(BaseModel):
                 exist_ok=True,
             )
 
-        gams_options = dict()
+        gams_options = {}
         for key, value in gamspy_options.items():
             if key not in OPTION_MAP:
                 continue
@@ -530,7 +530,7 @@ class Options(BaseModel):
         if not os.path.isfile(path):
             raise ValidationError(f"No such file in the given path: {path}")
 
-        attributes = dict()
+        attributes = {}
         with open(path, encoding="utf-8") as file:
             lines = file.readlines()
 
@@ -562,7 +562,7 @@ class Options(BaseModel):
         pf_file : str
         output : io.TextIOWrapper | None, optional
         """
-        all_options = dict()
+        all_options = {}
         # Solver options
         if self._solver is not None:
             all_options[self._problem] = self._solver

gamspy/_serialization.py

@@ -5,12 +5,15 @@ import os
 import shutil
 import tempfile
 import zipfile
-from collections.abc import Sequence
+from typing import TYPE_CHECKING
 
 from gamspy import Container
 from gamspy._model import ATTRIBUTE_MAP
 from gamspy.exceptions import ValidationError
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
 
 def serialize(container: Container, path: str) -> None:
     """
@@ -46,15 +49,15 @@ def serialize(container: Container, path: str) -> None:
         # Dump the GAMS State to disc
         container._options._set_debug_options({"save": g00_path})
         container._synch_with_gams()
-        container._options._set_debug_options(dict())
+        container._options._set_debug_options({})
 
         # Serialize symbols
-        info = dict()
+        info = {}
         for name, symbol in container.data.items():
             info[name] = symbol._serialize()
 
         # Serialize models
-        models = dict()
+        models = {}
         for model in container.models.values():
             models[model.name] = model._serialize()
             info["models"] = models
@@ -113,7 +116,7 @@ def deserialize(path: str) -> Container:
         deserialized_matches: dict[str, str | Sequence[str]] = model.get(
             "_matches", None
         )
-        matches = dict()
+        matches = {}
         if deserialized_matches is not None:
             for key, value in deserialized_matches.items():
                 if isinstance(value, str):

gamspy/_symbols/alias.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import os
 import threading
-from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any
 
 import gams.transfer as gt
@@ -20,6 +19,8 @@ from gamspy._symbols.symbol import Symbol
 from gamspy.exceptions import ValidationError
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from gamspy import Container, Set
     from gamspy._algebra.expression import Expression
 
@@ -72,7 +73,7 @@ class Alias(gt.Alias, operable.Operable, Symbol, SetMixin):
         # gamspy attributes
         obj.where = condition.Condition(obj)
         obj.container._add_statement(obj)
-        obj._metadata = dict()
+        obj._metadata = {}
 
         return obj
 
@@ -118,7 +119,7 @@ class Alias(gt.Alias, operable.Operable, Symbol, SetMixin):
         name: str | None = None,
         alias_with: Set | Alias = None,  # type: ignore
     ):
-        self._metadata: dict[str, Any] = dict()
+        self._metadata: dict[str, Any] = {}
         self._assignment: Expression | None = None
         # does symbol exist
         has_symbol = False

gamspy/_symbols/equation.py

@@ -27,11 +27,11 @@ from gamspy.exceptions import ValidationError
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
+    from types import EllipsisType
 
     from gamspy import Alias, Container, Set, Variable
     from gamspy._algebra.expression import Expression
     from gamspy._algebra.operation import Operation
-    from gamspy._types import EllipsisType
 
 
 EQ_TYPES = ["=e=", "=l=", "=g=", "=n=", "=x=", "=b="]
@@ -45,9 +45,16 @@ IRREGULAR_EQ_MAP = {
 
 class EquationType(Enum):
     REGULAR = "regular"
+    """Regular equations with =, >= and <= sign."""
+
     NONBINDING = "nonbinding"
+    """No relationship implied between left-hand side and right-hand side. This equation type is ideally suited for use in MCP models and in variational inequalities."""
+
     EXTERNAL = "external"
+    """Equation is defined by external programs."""
+
     BOOLEAN = "boolean"
+    """Boolean equations."""
 
     @classmethod
     def values(cls):
@@ -155,7 +162,7 @@ class Equation(gt.Equation, Symbol):
         obj.where = condition.Condition(obj)
         obj.container._add_statement(obj)
         obj._synchronize = True
-        obj._metadata = dict()
+        obj._metadata = {}
         obj._winner = "python"
 
         # create attributes
@@ -227,7 +234,7 @@ class Equation(gt.Equation, Symbol):
         is_miro_output: bool = False,
         definition_domain: list | None = None,
     ):
-        self._metadata: dict[str, Any] = dict()
+        self._metadata: dict[str, Any] = {}
         self._assignment: Expression | None = None
         if is_miro_output and name is None:
             raise ValidationError("Please specify a name for miro symbols.")

gamspy/_symbols/implicits/implicit_parameter.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import logging
-from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any
 
 import gamspy._algebra.expression as expression
@@ -17,6 +16,9 @@ from gamspy.exceptions import ValidationError
 from gamspy.math.matrix import permute
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from types import EllipsisType
+
     import pandas as pd
 
     from gamspy import (
@@ -28,7 +30,6 @@ if TYPE_CHECKING:
     )
     from gamspy._algebra.expression import Expression
     from gamspy._algebra.operation import Operation
-    from gamspy._types import EllipsisType
 
 logger = logging.getLogger("GAMSPy")
 logger.setLevel(logging.WARNING)
@@ -240,7 +241,7 @@ class ImplicitParameter(ImplicitSymbol, operable.Operable):
         [Set(name='i', domain=['*']), Set(name='j', domain=['*'])]
 
         """
-        dims = [x for x in range(len(self.domain))]
+        dims = list(range(len(self.domain)))
         if len(dims) < 2:
             raise ValidationError(
                 "Parameter must contain at least 2 dimensions to transpose"

gamspy/_symbols/implicits/implicit_set.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
 import gamspy._algebra.expression as expression
@@ -12,11 +11,13 @@ from gamspy._symbols.implicits.implicit_symbol import ImplicitSymbol
 from gamspy.exceptions import ValidationError
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from types import EllipsisType
+
     import pandas as pd
 
     from gamspy import Alias, Set
     from gamspy._algebra.expression import Expression
-    from gamspy._types import EllipsisType
 
 
 class ImplicitSet(ImplicitSymbol, operable.Operable):

gamspy/_symbols/implicits/implicit_symbol.py

@@ -76,7 +76,7 @@ class ImplicitSymbol(ABC):
         self.domain = domain
 
         scalars.extend(parent_scalar_domains)
-        scalars = list(sorted(scalars, key=lambda k: k[0]))
+        scalars = sorted(scalars, key=lambda k: k[0])
         self._scalar_domains = scalars
 
     def fix_permutation(self):
@@ -147,7 +147,7 @@ class ImplicitSymbol(ABC):
             raise ValidationError("Sum operation is not possible on scalar parameters.")
 
         if not indices:
-            indices = self.domain
+            return gp.Sum(self.domain, self[self.domain])
 
         return gp.Sum(indices, self[self.domain])
 
@@ -179,7 +179,7 @@ class ImplicitSymbol(ABC):
             )
 
         if not indices:
-            indices = self.domain
+            return gp.Product(self.domain, self[self.domain])
 
         return gp.Product(indices, self[self.domain])
 
@@ -211,7 +211,7 @@ class ImplicitSymbol(ABC):
             )
 
         if not indices:
-            indices = self.domain
+            return gp.Smin(self.domain, self[self.domain])
 
         return gp.Smin(indices, self[self.domain])
 
@@ -243,7 +243,7 @@ class ImplicitSymbol(ABC):
             )
 
         if not indices:
-            indices = self.domain
+            return gp.Smax(self.domain, self[self.domain])
 
         return gp.Smax(indices, self[self.domain])
 
@@ -275,7 +275,7 @@ class ImplicitSymbol(ABC):
             )
 
         if not indices:
-            indices = self.domain
+            return gp.Sand(self.domain, self[self.domain])
 
         return gp.Sand(indices, self[self.domain])
 
@@ -305,6 +305,6 @@ class ImplicitSymbol(ABC):
             raise ValidationError("Sor operation is not possible on scalar parameters.")
 
         if not indices:
-            indices = self.domain
+            return gp.Sor(self.domain, self[self.domain])
 
         return gp.Sor(indices, self[self.domain])