gamspy 1.17.1__tar.gz → 1.17.2__tar.gz

{gamspy-1.17.1 → gamspy-1.17.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gamspy
-Version: 1.17.1
+Version: 1.17.2
 Summary: Python-based algebraic modeling interface to GAMS
 Author-email: GAMS Development Corporation <support@gams.com>
 Project-URL: homepage, https://gams.com/sales/gamspy_facts/

{gamspy-1.17.1 → gamspy-1.17.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gamspy"
-version = "1.17.1"
+version = "1.17.2"
 authors = [
   { name = "GAMS Development Corporation", email = "support@gams.com" },
 ]

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy/_container.py

@@ -1064,6 +1064,9 @@ class Container(gt.Container):
         >>> a = m.addAlias("a", i)
 
         """
+        if name is None:
+            name = self._get_symbol_name(prefix="a")
+
         return gp.Alias(self, name, alias_with)
 
     def addSet(
@@ -1121,6 +1124,9 @@ class Container(gt.Container):
         >>> i = m.addSet("i")
 
         """
+        if name is None:
+            name = self._get_symbol_name(prefix="s")
+
         return gp.Set(
             self,
             name,
@@ -1189,6 +1195,9 @@ class Container(gt.Container):
         >>> a = m.addParameter("a")
 
         """
+        if name is None:
+            name = self._get_symbol_name(prefix="p")
+
         return gp.Parameter(
             self,
             name,
@@ -1252,6 +1261,9 @@ class Container(gt.Container):
         >>> v = m.addVariable("v")
 
         """
+        if name is None:
+            name = self._get_symbol_name(prefix="v")
+
         return gp.Variable(
             self,
             name,
@@ -1322,6 +1334,9 @@ class Container(gt.Container):
         >>> i = m.addEquation("i")
 
         """
+        if name is None:
+            name = self._get_symbol_name(prefix="e")
+
         return gp.Equation(
             self,
             name,
@@ -1389,6 +1404,9 @@ class Container(gt.Container):
         >>> model = m.addModel("my_model", "LP", [e])
 
         """
+        if name is None:
+            name = self._get_symbol_name(prefix="m")
+
         return gp.Model(
             self,
             name,

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy/_model.py

@@ -73,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):
@@ -102,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):
@@ -118,24 +154,61 @@ 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):
@@ -185,21 +258,52 @@ 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 = [

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy/_symbols/equation.py

@@ -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):

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy/_symbols/variable.py

@@ -35,14 +35,31 @@ if TYPE_CHECKING:
 
 class VariableType(Enum):
     BINARY = "binary"
+    """Discrete variable that can only take values of 0 or 1."""
+
     INTEGER = "integer"
+    """Discrete variable that can only take integer values between the bounds."""
+
     POSITIVE = "positive"
+    """No negative values are allowed for variable. The user may change both bounds from the default value."""
+
     NEGATIVE = "negative"
+    """No positive values are allowed for variables. The user may change both bounds from the default value."""
+
     FREE = "free"
+    """No bounds on variable. Both bounds may be changed from the default values by the user."""
+
     SOS1 = "sos1"
+    """A set of variables, such that at most one variable within a group may have a non-zero value."""
+
     SOS2 = "sos2"
+    """A set of variables, such that at most two variables within a group may have non-zero values and the two non-zero values are adjacent."""
+
     SEMICONT = "semicont"
+    """Semi-continuous, must be zero or above a given minimum level."""
+
     SEMIINT = "semiint"
+    """Semi-integer, must be zero or above a given minimum level and integer."""
 
     @classmethod
     def values(cls):

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy/_validation.py

@@ -385,11 +385,6 @@ def validate_name(word: str) -> str:
             f" words: {RESERVED_WORDS}"
         )
 
-    if word.endswith("gpauto"):
-        raise ValidationError(
-            "Name cannot end with one of the reserved words. `gpauto` is a reserverd word."
-        )
-
     if not re.match(NAME_MATCH_REGEX, word):
         raise ValidationError(
             f"`{word}` is an invalid GAMSPy symbol name. "

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy/formulations/__init__.py

@@ -20,6 +20,7 @@ from gamspy.formulations.piecewise import (
     pwl_convexity_formulation,
     pwl_interval_formulation,
 )
+from gamspy.formulations.result import FormulationResult
 from gamspy.formulations.shape import flatten_dims
 
 __all__ = [
@@ -41,4 +42,5 @@ __all__ = [
     "pwl_convexity_formulation",
     "pwl_interval_formulation",
     "utils",
+    "FormulationResult",
 ]

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy/formulations/nn/torch_sequential.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import typing
 from functools import partial
 from typing import TYPE_CHECKING
 
@@ -196,11 +197,82 @@ class TorchSequential:
         l = self._layer_converters[clz](container, layer)
         return l
 
-    def __call__(self, input: gp.Variable) -> tuple[gp.Variable, list[gp.Equation]]:
-        out = input
-        equations = []
-        for layer in self.layers:
-            out, layer_eqs = layer(out)
-            equations.extend(layer_eqs)
-
-        return out, equations
+    def _update_dict_layered(
+        self, large: dict[str, typing.Any], small: dict[str, typing.Any], layer_num: int
+    ):
+        for key in small:
+            large[f"{layer_num}.{key}"] = small[key]
+
+    def __call__(self, input: gp.Variable) -> gp.formulations.FormulationResult:
+        """
+
+        This method returns a **`FormulationResult`** object, which includes symbols
+        and outputs created by its underlying layers.
+
+        The way to access these underlying symbols depends on what the sub-layer
+        returns:
+
+        1. **If a Sub-Layer Returns a `FormulationResult`**
+
+        All symbols created by that sub-layer can be accessed within the main
+        `FormulationResult`. Each symbol's name is **prefixed** with its layer
+        number, followed by a dot (`.`).
+
+        * **Access Format:** `<layer_num>.<symbol_name>`
+        * **Example:** If the first layer creates a parameter named `bias`, it is accessed as `0.bias` in `parameters_created`.
+
+        2. **If a Sub-Layer Returns the "Old Style" Output (Output Variable and List of Equations)**
+
+        For backward compatibility, if a sub-layer returns an output variable and
+        a list of equations instead of a `FormulationResult`, they are accessed
+        as follows:
+
+        * **Output Variable:** The main output variable is named:
+            * **Access Format:** `<layer_num>.output`
+        * **Equations:** Each returned equation is sequentially named:
+            * **Access Format:** `<layer_num>.eq_<eq_number>` (where `eq_number` starts at 0, 1, 2...)
+            * **Example:** The first equation from the third layer is accessed as `2.eq_0` in `equations_created`.
+
+
+         Returns
+         -------
+         FormulationResult
+
+        """
+        result = gp.formulations.FormulationResult()
+
+        out: gp.Variable | gp.Parameter | None = input
+        for layer_num, layer in enumerate(self.layers):
+            output = layer(out)
+            if isinstance(output, gp.formulations.FormulationResult):
+                self._update_dict_layered(
+                    result.equations_created, output.equations_created, layer_num
+                )
+                self._update_dict_layered(
+                    result.variables_created, output.variables_created, layer_num
+                )
+                self._update_dict_layered(
+                    result.sets_created, output.sets_created, layer_num
+                )
+                self._update_dict_layered(
+                    result.parameters_created, output.parameters_created, layer_num
+                )
+                self._update_dict_layered(result.other, output.other, layer_num)
+
+                # matches are not named
+                result.matches.update(output.matches)
+                out = output.result
+            else:
+                # old interface only provides output var and list of equations
+                out, layer_eqs = output
+                result.variables_created[f"{layer_num}.output"] = out
+                for eq_num, eq in enumerate(layer_eqs):
+                    result.equations_created[f"{layer_num}.eq_{eq_num}"] = eq
+
+        result.result = out
+
+        # to prevent forgetting matches when unpacking
+        if result.matches:
+            result.extra_return = result.matches
+
+        return result

gamspy-1.17.2/src/gamspy/formulations/result.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeAlias
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    import gamspy as gp
+
+    MatchesType: TypeAlias = dict[
+        gp.Equation | Sequence[gp.Equation],
+        gp.Variable | Sequence[gp.Variable],
+    ]
+
+
+class FormulationResult:
+    """
+    FormulationResult class provides a common interface for returning results
+    when formulations are called. In the old convention, formulations returned
+    a tuple of result variable and list of equations. In some cases it was
+    possible to get extra output from the formulation. To provide backwards
+    compatibility, FormulationResult class can be unpacked into a result
+    variable and list of equations. Also it supports returning extra output in
+    unpacking.
+
+    With the FormulationResult you can have more access to underlying symbols
+    created such as equations, variables, parameters and sets. Since many
+    formulations created symbols with randomized names, it was tedious to find
+    intermediate symbols created. FormulationResult has dictionaries where keys
+    are expected to be documented in the formulation returning the
+    FormulationResult therefore you can access a symbol via its known key.
+
+    For example:
+
+    Examples
+    --------
+    >>> import gamspy as gp
+    >>> m = gp.Container()
+    >>> x = gp.Variable(m)
+    >>> res = gp.math.activation.relu_with_binary_var(x)
+    >>> aux_binary_var = res.variables_created["binary"]
+
+    Therefore, it is important for the formulation returning a
+    FormulationResult to properly list the keys to the symbols that are
+    created.
+
+    FormulationResult has the following attributes that might be useful:
+        - `result`
+        - `equations_created`
+        - `sets_created`
+        - `parameters_created`
+        - `matches`
+        - `other`
+        - `extra_return`
+
+    """
+
+    def __init__(
+        self,
+        result: gp.Variable | gp.Parameter | None = None,
+        equations_created: dict[str, gp.Equation] | None = None,
+        extra_return: gp.Variable | MatchesType | None = None,
+    ) -> None:
+        self.result = result
+        self.equations_created: dict[str, gp.Equation] = (
+            equations_created if equations_created is not None else {}
+        )
+
+        self.variables_created: dict[str, gp.Variable] = {}
+        self.sets_created: dict[str, gp.Set] = {}
+        self.parameters_created: dict[str, gp.Parameter] = {}
+        self.matches: MatchesType = {}
+        self.other: dict[str, Any] = {}
+
+        # Extra return is only here for backwards compat reasons
+        # try to use other when you can
+        self.extra_return = extra_return
+
+    def __len__(self):
+        # For backwards compat
+        return 2 + (self.extra_return is not None)
+
+    def __iter__(self):
+        # For backwards compat
+        if self.extra_return is None:
+            return [
+                self.result,
+                list(self.equations_created.values()),
+            ].__iter__()
+
+        return [
+            self.result,
+            self.extra_return,
+            list(self.equations_created.values()),
+        ].__iter__()
+
+    def __str__(self) -> str:
+        return (
+            "FormulationResult(\n"
+            + "    Equations: "
+            + str(self.equations_created.keys())
+            + "\n"
+            + "    Variables: "
+            + str(self.variables_created.keys())
+            + "\n"
+            + "    Sets: "
+            + str(self.sets_created.keys())
+            + "\n"
+            + "    Parameters: "
+            + str(self.parameters_created.keys())
+            + "\n"
+            + "    Num Matches: "
+            + str(len(self.matches))
+            + "\n"
+            + "    Other: "
+            + str(self.other)
+            + "\n"
+            + ")"
+        )

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy/math/__init__.py

@@ -5,6 +5,7 @@ from gamspy.math.activation import (
     log_softmax,
     relu_with_binary_var,
     relu_with_complementarity_var,
+    relu_with_equilibrium,
     relu_with_sos1_var,
     softmax,
     softplus,
@@ -184,6 +185,7 @@ __all__ = [
     "rel_ne",
     "relu_with_binary_var",
     "relu_with_complementarity_var",
+    "relu_with_equilibrium",
     "relu_with_sos1_var",
     "rpower",
     "same_as",

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy/math/activation.py

@@ -5,10 +5,12 @@ from typing import TYPE_CHECKING
 import gamspy._symbols.implicits as implicits
 import gamspy.math
 import gamspy.utils as utils
+from gamspy._algebra.number import Number
 from gamspy._container import Container
 from gamspy._symbols.equation import Equation
 from gamspy._symbols.variable import Variable
 from gamspy.exceptions import ValidationError
+from gamspy.formulations.result import FormulationResult
 from gamspy.math.matrix import next_alias
 
 if TYPE_CHECKING:
@@ -272,7 +274,7 @@ def relu_with_binary_var(
     default_lb: float = -(10**6),
     default_ub: float = 10**6,
     return_binary_var: bool = False,
-):
+) -> FormulationResult:
     """
     Implements the ReLU activation function using binary variables. The ReLU
     function is defined as ReLU(x) = max(x, 0). This implementation **generates**
@@ -292,6 +294,10 @@ def relu_with_binary_var(
 
     Adapted from `OMLT <https://github.com/cog-imperial/OMLT/blob/e60563859a66ac5dd3348bf1763de57eec95171e/src/omlt/neuralnet/activations/relu.py>`_
 
+    FormulationResult:
+        - variables_created: ["output", "binary"]
+        - equations_created: ["y_gte_x", "y_lte_x_1", "y_lte_x_2"]
+
     Parameters
     ----------
     x : Parameter | Variable | implicits.ImplicitParameter | implicits.ImplicitVariable | Expression | Operation
@@ -301,7 +307,7 @@ def relu_with_binary_var(
 
     Returns
     -------
-    tuple[Variable, list[Equation]] | tuple[Variable, Variable, list[Equation]]
+    FormulationResult
 
     Examples
     --------
@@ -310,7 +316,7 @@ def relu_with_binary_var(
     >>> m = Container()
     >>> i = Set(m, "i", records=range(3))
     >>> x = Variable(m, "x", domain=[i])
-    >>> y, eqs = relu_with_binary_var(x)
+    >>> y, eqs = relu_with_binary_var(x) # FormulationResult can be unpacked for backwards compat
     >>> y.type
     'positive'
     >>> len(eqs)
@@ -322,6 +328,9 @@ def relu_with_binary_var(
     [Set(name='i', domain=['*'])]
     >>> b.domain # i many binary variables
     [Set(name='i', domain=['*'])]
+    >>> output = relu_with_binary_var(x) # You can use FormulationResult too
+    >>> binary_var = output.variables_created["binary"]
+    >>> y = output.result
 
     """
     assert isinstance(x.container, Container)
@@ -359,10 +368,127 @@ def relu_with_binary_var(
         eq[2][...] = y <= sigma * default_ub
         y.lo[...] = 0
 
-    if return_binary_var:
-        return y, sigma, eq
+    result = FormulationResult(
+        y,
+        {
+            "y_gte_x": eq[0],
+            "y_lte_x_1": eq[1],
+            "y_lte_x_2": eq[2],
+        },
+    )
+    result.variables_created = {"binary": sigma, "output": y}
+    result.extra_return = sigma if return_binary_var else None
+    return result
+
+
+def relu_with_equilibrium(
+    x: (
+        Parameter
+        | Variable
+        | implicits.ImplicitParameter
+        | implicits.ImplicitVariable
+        | Expression
+        | Operation
+    ),
+) -> FormulationResult:
+    """
+    Implements the ReLU activation function using Equilibrium Constraints.
+    This implementation is suitable for models of type Mathematical Program with
+    Equilibrium Constraints (MPEC) or Mixed Complementarity Problem (MCP).
+    One positive variable is **generated**, which serves as the activation
+    variable and no equations. The activation variable shares the same domain as
+    the input. Lower and upper bounds are not required for this formulation.
+
+    Returns FormulationResult which can be unpacked as activation variable,
+    matches dictionary and the equation list (empty).
+
+    FormulationResult:
+        - variables_created: ["output"]
+        - equations_created: []
+        - matches: {(output - x) : output}
+        - extra_return: yes (matches)
+
+    or if the provided input was not a Variable, this formulation assigns it to a
+    new variable and uses the new variable instead
+
+    FormulationResult:
+        - variables_created: ["output", "new_input"]
+        - equations_created: ["set_new_input"]
+        - matches: {(output - new_input) : output}
+        - extra_return: yes (matches)
+
+
+    Parameters
+    ----------
+    x : Variable
+
+    Returns
+    -------
+    FormulationResult
+
+    Examples
+    --------
+    >>> from gamspy import Container, Variable, Set
+    >>> from gamspy.math.activation import relu_with_equilibrium
+    >>> m = Container()
+    >>> i = Set(m, "i", records=range(3))
+    >>> x = Variable(m, "x", domain=[i])
+    >>> y, matches, eqs = relu_with_equilibrium(x)
+    >>> y.type
+    'positive'
+    >>> len(eqs)
+    0
+    >>> len(matches)
+    1
+    >>> result = relu_with_equilibrium(x)
+    >>> type(result)
+    <class 'gamspy.formulations.result.FormulationResult'>
+    >>> result = relu_with_equilibrium(x - 5)
+    >>> new_input = result.variables_created["new_input"]
+
+    """
+    assert isinstance(x.container, Container)
+    domain = x.domain
+
+    y = x.container.addVariable(
+        type="positive",
+        domain=domain,
+    )
+
+    new_input = None
+    set_new_input = None
+    if not isinstance(x, Variable):
+        new_input = Variable._constructor_bypass(
+            x.container,
+            _get_random_name("new_input"),
+            domain=domain,
+        )
+        set_new_input = Equation._constructor_bypass(
+            x.container,
+            _get_random_name("set_new_input"),
+            domain=domain,
+        )
+        set_new_input[...] = new_input == x
     else:
-        return y, eq
+        new_input = x
+
+    eq = Equation._constructor_bypass(
+        x.container,
+        _get_random_name("matches_eq"),
+        domain=domain,
+    )
+
+    eq[...] = y - new_input >= Number(0)
+
+    result = FormulationResult(y, {})
+    result.variables_created["output"] = y
+    if set_new_input is not None:
+        result.variables_created["new_input"] = new_input
+        result.equations_created["set_new_input"] = set_new_input
+
+    result.extra_return = {eq: y}
+    result.matches = {eq: y}
+    return result
 
 
 def relu_with_complementarity_var(

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy/utils.py

@@ -385,7 +385,8 @@ def _get_name_from_stack() -> str:
         # Current frame is this function (_get_name_from_stack)
         # The first f_back takes us to _get_symbol_name
         # The second f_back takes us to the __init__ function of
-        # the symbol. The third f_back takes us to the user code.
+        # the symbol or addX function of Container. The third f_back
+        # takes us to the user code.
         frame = inspect.currentframe().f_back.f_back.f_back
         assert frame is not None
 

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gamspy
-Version: 1.17.1
+Version: 1.17.2
 Summary: Python-based algebraic modeling interface to GAMS
 Author-email: GAMS Development Corporation <support@gams.com>
 Project-URL: homepage, https://gams.com/sales/gamspy_facts/

{gamspy-1.17.1 → gamspy-1.17.2}/src/gamspy.egg-info/SOURCES.txt

@@ -66,6 +66,7 @@ src/gamspy/_symbols/implicits/implicit_symbol.py
 src/gamspy/_symbols/implicits/implicit_variable.py
 src/gamspy/formulations/__init__.py
 src/gamspy/formulations/piecewise.py
+src/gamspy/formulations/result.py
 src/gamspy/formulations/shape.py
 src/gamspy/formulations/utils.py
 src/gamspy/formulations/ml/__init__.py

{gamspy-1.17.1 → gamspy-1.17.2}/tests/test_gamspy.py

@@ -17,7 +17,7 @@ from gamspy.exceptions import GamspyException, ValidationError
 
 @pytest.mark.unit
 def test_version():
-    assert gp.__version__ == "1.17.1"
+    assert gp.__version__ == "1.17.2"
 
 
 @pytest.mark.unit