gamspy 1.18.4__py3-none-any.whl → 1.19.1__py3-none-any.whl

gamspy/_container.py

@@ -585,7 +585,47 @@ class Container(gt.Container):
 
         return gams_string
 
-    def _load_records_from_gdx(self, load_from: str, names: Iterable[str]) -> None:
+    def _filter_load_symbols(
+        self,
+        symbol_names: dict[str, str] | list[str],
+        create_if_not_declared: bool = False,
+    ) -> dict[str, str] | list[str]:
+        if isinstance(symbol_names, list):
+            names = []
+            for name in symbol_names:
+                if name in self.data:
+                    symbol = self[name]
+                    if not isinstance(symbol, gt.Alias) and symbol.synchronize:
+                        names.append(name)
+                else:
+                    if create_if_not_declared:
+                        names.append(name)
+                    else:
+                        raise ValidationError(
+                            f"Cannot load records of `{name}` because it does not exist in the container."
+                        )
+
+            return names
+
+        mapping = {}
+        for gdx_name, gamspy_name in symbol_names.items():
+            if gamspy_name in self.data:
+                if self[gamspy_name].synchronize:
+                    mapping[gdx_name] = gamspy_name
+            else:
+                raise ValidationError(
+                    f"Invalid renaming. `{gamspy_name}` does not exist in the container."
+                )
+
+        return mapping
+
+    def _load_records_from_gdx(
+        self,
+        load_from: str,
+        names: Iterable[str],
+        *,
+        create_if_not_declared: bool = False,
+    ) -> None:
         self._temp_container.read(load_from, names)
         original_state = self._options.miro_protect
         self._options.miro_protect = False
@@ -596,7 +636,12 @@ class Container(gt.Container):
                 self[name].records = updated_records
                 self[name].domain_labels = self[name].domain_names
             else:
-                self._read(load_from, [name])
+                if create_if_not_declared:
+                    self._read(load_from, [name])
+                else:
+                    raise ValidationError(
+                        f"Cannot load records of `{name}` because it does not exist in the container."
+                    )
 
         self._options.miro_protect = original_state
         self._temp_container.data = {}
@@ -607,14 +652,9 @@ class Container(gt.Container):
         self._options.miro_protect = False
 
         for gdx_name, gamspy_name in names.items():
-            if gamspy_name in self.data:
-                updated_records = self._temp_container[gdx_name].records
-                self[gamspy_name].records = updated_records
-                self[gamspy_name].domain_labels = self[gamspy_name].domain_names
-            else:
-                raise ValidationError(
-                    f"Invalid renaming. `{gamspy_name}` does not exist in the container."
-                )
+            updated_records = self._temp_container[gdx_name].records
+            self[gamspy_name].records = updated_records
+            self[gamspy_name].domain_labels = self[gamspy_name].domain_names
 
         self._options.miro_protect = original_state
         self._temp_container.data = {}
@@ -901,7 +941,7 @@ class Container(gt.Container):
         """
         if self._debugging_level != "keep":
             raise ValidationError(
-                "`debug_level` argument of the container must be set to 'keep' to use this function."
+                "`debugging_level` argument of the container must be set to 'keep' to use this function."
             )
 
         gams_string = self._gams_string
@@ -916,7 +956,7 @@ class Container(gt.Container):
 
     def loadRecordsFromGdx(
         self,
-        load_from: str,
+        load_from: str | Path,
         symbol_names: Iterable[str] | dict[str, str] | None = None,
     ) -> None:
         """
@@ -940,24 +980,63 @@ class Container(gt.Container):
         >>> i = Set(m, "i", records=["i1", "i2"])
         >>> m.write("test.gdx")
         >>> m2 = Container()
+        >>> i = Set(m2, "i")
         >>> m2.loadRecordsFromGdx("test.gdx")
         >>> print(i.records.equals(m2["i"].records))
         True
 
         """
+        if isinstance(load_from, Path):
+            load_from = str(load_from.resolve())
+
+        create_if_not_declared = symbol_names is None
         if symbol_names is None:
             # If no symbol names are given, all records in the gdx should be loaded
             symbol_names = utils._get_symbol_names_from_gdx(
                 self.system_directory, load_from
             )
+            symbol_names = self._filter_load_symbols(
+                symbol_names,  # type: ignore
+                create_if_not_declared,
+            )
+            self._load_records_from_gdx(
+                load_from, symbol_names, create_if_not_declared=create_if_not_declared
+            )
+            self._synch_with_gams()
+            return
 
-        if isinstance(symbol_names, dict):
-            self._load_records_with_rename(load_from, symbol_names)
+        if isinstance(symbol_names, list):
+            symbol_names = self._filter_load_symbols(
+                symbol_names, create_if_not_declared
+            )
+            self._add_statement(f"$gdxIn {load_from}")
+            symbols_str = " ".join(symbol_names)
+            self._add_statement(f"$loadDC {symbols_str}")
+            self._add_statement("$gdxIn")
+        elif isinstance(symbol_names, dict):
+            symbol_names = self._filter_load_symbols(
+                symbol_names, create_if_not_declared
+            )
+            self._add_statement(f"$gdxIn {load_from}")
+            symbols_str = " ".join(
+                [f"{value}={key}" for key, value in symbol_names.items()]  # type: ignore
+            )
+            self._add_statement(f"$loadDC {symbols_str}")
+            self._add_statement("$gdxIn")
         else:
-            self._load_records_from_gdx(load_from, symbol_names)
+            raise TypeError("`symbol_names` must be either a list or a dictionary.")
 
+        self._options._debug_options["gdx"] = self._gdx_out
+        self._options._debug_options["gdxSymbols"] = "newOrChanged"
         self._synch_with_gams()
 
+        if isinstance(symbol_names, dict):
+            self._load_records_with_rename(load_from, symbol_names)
+        else:
+            self._load_records_from_gdx(
+                load_from, symbol_names, create_if_not_declared=create_if_not_declared
+            )
+
     def addGamsCode(self, gams_code: str) -> None:
         """
         Adds an arbitrary GAMS code to the generate .gms file.

gamspy/_convert.py

@@ -338,8 +338,8 @@ def get_convert_solver_options(
             solver_options[name] = str((path / value).resolve())
 
     if options is not None:
-        extra_options = options.model_dump(exclude_none=True)
-        for key, value in extra_options.items():
+        convert_options = options.model_dump(exclude_none=True)
+        for key, value in convert_options.items():
             name = OPTION_RENAME_MAP.get(key, key)
             solver_options[name] = int(value) if isinstance(value, bool) else value
 

gamspy/_miro.py

@@ -41,7 +41,9 @@ def load_miro_symbol_records(container: Container):
             for name in container._miro_input_symbols
             if not container[name]._already_loaded
         ]
-        container._load_records_from_gdx(MIRO_GDX_IN, names)
+        container._load_records_from_gdx(
+            MIRO_GDX_IN, names, create_if_not_declared=True
+        )
         for name in names:
             symbol = container[name]
             symbol._already_loaded = True
@@ -54,7 +56,9 @@ def load_miro_symbol_records(container: Container):
 
     # Load records of miro output symbols
     if MIRO_GDX_OUT and container._miro_output_symbols:
-        container._load_records_from_gdx(MIRO_GDX_OUT, container._miro_output_symbols)
+        container._load_records_from_gdx(
+            MIRO_GDX_OUT, container._miro_output_symbols, create_if_not_declared=True
+        )
 
     for name in container._miro_input_symbols + container._miro_output_symbols:
         container[name].modified = False

gamspy/_model.py

@@ -368,6 +368,7 @@ class Model:
         A human-readable description of the model.
     equations : Sequence[Equation], optional
         A list or sequence of Equation objects that define the constraints of the model.
+        No equations are used by default.
     problem : Problem | str, optional
         The type of mathematical problem to solve (e.g., 'LP', 'MIP', 'NLP').
         Default is Problem.MIP.
@@ -380,7 +381,7 @@ class Model:
         Used for defining complementarity problems (MCP). Maps equations to their complementary variables.
     limited_variables : Sequence[ImplicitVariable], optional
         Allows limiting the domain of variables included in the model to a specific subset.
-    external_module: str, optional
+    external_module : str, optional
         The name of an external module file (e.g., 'my_external.dll' or 'my_external.so')
         where external equations are implemented.
 
@@ -388,9 +389,21 @@ class Model:
     --------
     >>> import gamspy as gp
     >>> m = gp.Container()
-    >>> v = gp.Variable(m, "v")
-    >>> e = gp.Equation(m, "e", definition= v == 5)
-    >>> my_model = gp.Model(m, "my_model", problem="LP", equations=[e])
+    >>> i = gp.Set(m, description="items")
+    >>> p = gp.Parameter(m, description="profits", domain=i)
+    >>> w = gp.Parameter(m, description="weights", domain=i)
+    >>> c = gp.Parameter(m, description="capacity")
+    >>> x = gp.Variable(m, domain=i, type=gp.VariableType.BINARY)
+    >>> capacity_restriction = gp.Equation(m, definition=gp.Sum(i, w[i] * x[i]) <= c)
+
+    >>> # Instantiate the Model
+    >>> knapsack = gp.Model(
+    ...     m,
+    ...     equations=m.getEquations(), # Automatically grabs all equations in the container
+    ...     problem=gp.Problem.MIP,     # Mixed Integer Program
+    ...     sense=gp.Sense.MAX,         # Maximize profit
+    ...     objective=gp.Sum(i, p[i] * x[i]),
+    ... )
 
     """
 
@@ -1214,8 +1227,19 @@ class Model:
         >>> v = gp.Variable(m, "v")
         >>> e = gp.Equation(m, "e", definition= v == 5)
         >>> my_model = gp.Model(m, "my_model", problem="LP", equations=[e])
-        >>> my_model.convert("tmp", gp.FileFormat.GAMS)
-        >>> my_model.convert("tmp", [gp.FileFormat.GAMS, gp.FileFormat.AMPL])
+
+
+        Convert the model into scalar GAMS format.
+
+
+        >>> my_model.convert("tmp", gp.FileFormat.GAMS) # doctest: +SKIP
+
+
+        Add conversion options
+
+
+        >>> options = gp.ConvertOptions(GDXNames=False)
+        >>> my_model.convert("jacobian", file_format=gp.FileFormat.GDXJacobian, options=options) # doctest: +SKIP
 
         """
         path = Path(path)
@@ -1277,6 +1301,33 @@ class Model:
         Returns
         -------
         str
+
+        Examples
+        --------
+        >>> import gamspy as gp
+        >>> m = gp.Container()
+        >>> i = gp.Set(m, records=["item1", "item2"])
+        >>> v = gp.Variable(m, domain=i)
+        >>> z = gp.Variable(m)
+        >>> e = gp.Equation(m, domain=i)
+        >>> e[i] = v[i] * z >= 5
+        >>> model = gp.Model(m, "test", equations=[e], problem="NLP", sense="MIN", objective=z)
+        >>> summary = model.solve(options=gp.Options(variable_listing_limit=10))
+        >>> print(model.getVariableListing())
+        v(item1)
+                        (.LO, .L, .UP, .M = -INF, 0, +INF, 0)
+               (0)      e(item1)
+        <BLANKLINE>
+        v(item2)
+                        (.LO, .L, .UP, .M = -INF, 0, +INF, 0)
+               (0)      e(item2)
+        <BLANKLINE>
+        z
+                        (.LO, .L, .UP, .M = -INF, 0, +INF, 0)
+               (0)      e(item1)
+               (0)      e(item2)
+        <BLANKLINE>
+
         """
         if not hasattr(self, "_variables"):
             raise ValidationError(
@@ -1301,7 +1352,7 @@ class Model:
         >>> # ... define model ...
         >>> model = gp.Model(m, "my_model", problem="LP", equations=[])
         >>> # In a separate thread or signal handler:
-        >>> # model.interrupt()
+        >>> model.interrupt() # doctest: +SKIP
 
         """
         self.container._interrupt()
@@ -1415,12 +1466,82 @@ class Model:
 
         Examples
         --------
+        >>> import sys
+        >>> import os
         >>> import gamspy as gp
         >>> m = gp.Container()
-        >>> v = gp.Variable(m, "v")
-        >>> e = gp.Equation(m, "e", definition= v == 5)
-        >>> my_model = gp.Model(m, "my_model", problem="LP", equations=[e], sense="max", objective=v)
-        >>> solved = my_model.solve()
+        >>> i = gp.Set(m, description="items")
+        >>> p = gp.Parameter(m, description="profits", domain=i)
+        >>> w = gp.Parameter(m, description="weights", domain=i)
+        >>> c = gp.Parameter(m, description="capacity")
+        >>> x = gp.Variable(m, domain=i, type=gp.VariableType.BINARY)
+        >>> capacity_restriction = gp.Equation(m, definition=gp.Sum(i, w[i] * x[i]) <= c)
+        >>> knapsack = gp.Model(
+        ...     m,
+        ...     equations=m.getEquations(), # Automatically grabs all equations in the container
+        ...     problem=gp.Problem.MIP,     # Mixed Integer Program
+        ...     sense=gp.Sense.MAX,         # Maximize profit
+        ...     objective=gp.Sum(i, p[i] * x[i]),
+        ... )
+
+
+        Basic usage
+
+
+        >>> knapsack.solve() # doctest: +SKIP
+
+
+        Change solver
+
+
+        >>> knapsack.solve(solver="CPLEX") # doctest: +SKIP
+
+
+        Redirect output
+
+
+        >>> knapsack.solve(output=sys.stdout) # doctest: +SKIP
+
+
+        Add generic solve options
+
+
+        >>> knapsack.solve(options=gp.Options(iteration_limit=2)) # doctest: +SKIP
+
+
+        Add solver-specific options
+
+
+        >>> knapsack.solve(solver="CPLEX", solver_options={"preind": "off"}) # doctest: +SKIP
+
+
+        Solve on your own machine
+
+
+        >>> knapsack.solve() # doctest: +SKIP
+
+
+        Solve on GAMS Engine
+
+
+        >>> client = gp.EngineClient(
+        ...    host=os.getenv("ENGINE_URL", "https://<host_link>"),
+        ...    username=os.getenv("ENGINE_USER"),
+        ...    password=os.getenv("ENGINE_PASSWORD"),
+        ...    namespace=os.getenv("ENGINE_NAMESPACE"),
+        ... )
+        >>> knapsack.solve(backend="engine", client=client) # doctest: +SKIP
+
+
+        Solve on NEOS Server
+
+
+        >>> client = gp.NeosClient(
+        ...    email=os.getenv("NEOS_EMAIL"),
+        ...    username=os.getenv("NEOS_USER"),
+        ...    password=os.getenv("NEOS_PASSWORD"),
+        ... )
+        >>> knapsack.solve(backend="neos", client=client) # doctest: +SKIP
 
         """
         if output is None:
@@ -1626,7 +1747,7 @@ class Model:
         >>> v = gp.Variable(m, "v")
         >>> e = gp.Equation(m, "e", definition= v == 5)
         >>> my_model = gp.Model(m, "my_model", problem="LP", equations=[e])
-        >>> my_model.toGams("tmp")  # doctest: +ELLIPSIS
+        >>> my_model.toGams("tmp")  # doctest: +SKIP
         ================================================================================
         GAMS (.gms) file has been generated under ...
         ================================================================================
@@ -1668,7 +1789,7 @@ class Model:
         >>> v = gp.Variable(m, "v")
         >>> e = gp.Equation(m, "e", definition= v == 5)
         >>> my_model = gp.Model(m, "my_model", problem="LP", equations=[e])
-        >>> my_model.toLatex("tmp")  # doctest: +ELLIPSIS
+        >>> my_model.toLatex("tmp")  # doctest: +SKIP
         ================================================================================
         LaTeX (.tex) file has been generated under ...
         ================================================================================

gamspy/_model_instance.py

@@ -318,8 +318,8 @@ class ModelInstance:
             gams_file.write(scenario_str)
 
         # Write pf file
-        extra_options = self._prepare_gams_options()
-        options._set_extra_options(extra_options)
+        hidden_options = self._prepare_hidden_options()
+        options._set_hidden_options(hidden_options)
         options.log_file = os.path.join(self.container.working_directory, "gamslog.dat")
         options._export(self.pf_file, self.output)
 
@@ -632,9 +632,9 @@ class ModelInstance:
 
         return will_be_modified
 
-    def _prepare_gams_options(self) -> dict:
+    def _prepare_hidden_options(self) -> dict:
         scrdir = self.container._process_directory
-        extra_options = {
+        hidden_options = {
             "trace": self.trace_file,
             "input": self.gms_file,
             "output": self.lst_file,
@@ -646,11 +646,11 @@ class ModelInstance:
             "solvercntr": self.solver_control_file,
         }
         if self.container._network_license:
-            extra_options["netlicense"] = os.path.join(
+            hidden_options["netlicense"] = os.path.join(
                 self.container._process_directory, "gamslice.dat"
             )
 
-        return extra_options
+        return hidden_options
 
     def _get_columns_to_drop(self, attr: str) -> list[str]:
         attr_map = {

gamspy/_options.py

@@ -5,6 +5,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal
 
 from pydantic import BaseModel, ConfigDict
+from typing_extensions import override
 
 from gamspy.exceptions import ValidationError
 
@@ -381,8 +382,9 @@ class Options(BaseModel):
     zero_rounding_threshold: float | None = None
     report_underflow: bool | None = None
 
+    @override
     def model_post_init(self, context: Any) -> None:
-        self._extra_options: dict[str, Any] = {}
+        self._hidden_options: dict[str, Any] = {}
         self._debug_options: dict[str, Any] = {}
         self._solver: str | None = None
         self._problem: str | None = None
@@ -502,9 +504,9 @@ class Options(BaseModel):
         else:
             self._solver_options_file = "0"
 
-    def _set_extra_options(self, options: dict) -> None:
+    def _set_hidden_options(self, options: dict) -> None:
         """Set extra options of the backend"""
-        self._extra_options = options
+        self._hidden_options = options
 
     def _set_debug_options(self, options: dict) -> None:
         """Set debugging options"""
@@ -606,7 +608,7 @@ class Options(BaseModel):
         all_options["optfile"] = self._solver_options_file
 
         # Extra options
-        all_options.update(**self._extra_options)
+        all_options.update(**self._hidden_options)
         all_options.update(**self._debug_options)
 
         if self._frame is not None:
@@ -753,7 +755,7 @@ class ConvertOptions(BaseModel):
     >>> eq[i] = x[i] >= 1
     >>> model = gp.Model(m, "test_model", equations=[eq], problem="LP", sense="min", objective=gp.Sum(i, x[i]))
     >>> options = gp.ConvertOptions(GDXNames=False)
-    >>> # model.convert("jacobian", file_format=gp.FileFormat.GDXJacobian, options=options)
+    >>> model.convert("jacobian", file_format=gp.FileFormat.GDXJacobian, options=options) # doctest: +SKIP
 
     """
 

gamspy/_symbols/symbol.py

@@ -46,6 +46,15 @@ class Symbol:
         Returns
         -------
         str
+
+        Examples
+        --------
+        >>> import gamspy as gp
+        >>> m = gp.Container()
+        >>> i = gp.Set(m, "i")
+        >>> print(i.latexRepr())
+        i
+
         """
         return self._latex_name
 

gamspy/_workspace.py

@@ -18,7 +18,7 @@ def validate_arguments(
     if working_directory == "":
         raise ValidationError("`working_directory` cannot be an empty string.")
 
-    # Validate debug_level
+    # Validate debugging_level
     if not isinstance(debugging_level, str) or debugging_level not in DEBUGGING_LEVELS:
         raise ValidationError(f"debugging level must be one of {DEBUGGING_LEVELS}")
 

gamspy/formulations/piecewise.py

@@ -280,7 +280,7 @@ def _generate_ray(
     return x_var, b_var, eqs
 
 
-def points_to_intervals(
+def _points_to_intervals(
     x_points: typing.Sequence[int | float],
     y_points: typing.Sequence[int | float],
     discontinuous_points: typing.Sequence[int],
@@ -422,7 +422,7 @@ def pwl_interval_formulation(
     combined_indices = list({*discontinuous_indices, *none_indices})
     equations = []
 
-    intervals = points_to_intervals(x_points, y_points, combined_indices)
+    intervals = _points_to_intervals(x_points, y_points, combined_indices)
     lowerbounds_input = []
     upperbounds_input = []
     slopes_input = []

gamspy/math/activation.py

@@ -48,6 +48,22 @@ def tanh(x: Variable) -> tuple[Variable, list[Equation]]:
     Convenience wrapper that uses gamspy.math.tanh. Unlike gamspy.math.tanh,
     this function creates a new variable and the equation that
     sets it to follow formulations structure.
+
+    Parameters
+    ----------
+    x : Variable
+
+    Returns
+    -------
+    tuple[Variable, list[Equation]]
+
+    Examples
+    --------
+    >>> import gamspy as gp
+    >>> m = gp.Container()
+    >>> v1 = gp.Variable(m)
+    >>> v2, eqs = gp.math.activation.tanh(v1)
+
     """
     y = x.container.addVariable(domain=x.domain)
     set_y = x.container.addEquation(domain=x.domain)