Alias#

class gamspy.Alias(container: Container | None = None, name: str | None = None, alias_with: Set | Alias | None = None)[source]#

Bases: Alias, Operable, Symbol, SetMixin

Represents an Alias symbol in GAMS. https://gamspy.readthedocs.io/en/latest/user/basics/alias.html

Parameters:

containerContainer: Container of the alias.
namestr, optional: Name of the alias.
alias_withSet: Alias set object.

Attributes:

alias_with: Returns the aliased object
container: Container of the symbol
description: Returns description of symbol
dimension: Returns the dimension of symbol
domain: Returns list of domains given either as string (* for universe set) or as reference to the Set/Alias object
domain_labels: Returns the column headings for the records DataFrame
domain_names: Returns the string version of domain names
domain_type: Returns the state of domain links
first: Returns 1 if the element is the first in the set, otherwise 0.
is_singleton: if symbol is a singleton set
last: Returns 1 if the element is the last in the set, otherwise 0.
len: Returns the length of the set element name (count of characters).
modified: Flag that identifies if the symbol has been modified
name: Name of symbol
number_records: Returns the number of symbol records
off: Returns the element position in the current set minus 1.
ord: Same as .pos but for ordered sets only.
pos: Returns the element position in the current set, starting with 1.
records: Returns the main symbol records
rev: Returns the reverse element position in the current set.
summary: Returns a dict of only the metadata
tlen: Returns the length of the set element explanatory text (count of characters).
tval: Returns the numerical value if the set element text is a number.
uel: Returns the element position in the global Unique Element List (UEL).
val: Returns the numerical value if the set element name is a number.

Methods

`equals`(other[, check_uels, ...])	Used to compare the symbol to another symbol.
`gamsRepr`()	Returns the string representation of this Alias in the GAMS language.
`getDeclaration`()	Returns the GAMS declaration statement for this Alias.
`getSparsity`()	Gets the sparsity of the symbol w.r.t the cardinality
`isValid`([verbose, force])	Checks if the symbol is in a valid format
`lag`(n[, type])	Shifts the values of a Set or Alias by n positions to the left (lag).
`lead`(n[, type])	Shifts the values of a Set or Alias by n positions to the right (lead).
`pivot`([index, columns, fill_value])	Convenience function to pivot records into a new shape (only symbols with > 1D can be pivoted).
`sameAs`(other)	Evaluates to True if the current set element is identical to the given symbol or string.
`setRecords`(records[, uels_on_axes])	main convenience method to set standard pandas.DataFrame formatted records.
`toList`([include_element_text])	Convenience method to return symbol records as a python list

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i")
>>> j = gp.Alias(m, "j", i)

equals(other: Set | Alias, check_uels: bool = True, check_element_text: bool = True, check_meta_data: bool = True, verbose: bool = False) → bool[source]#

Used to compare the symbol to another symbol.

Parameters:

otherSet or Alias: The other symbol (Set or Alias) to compare with the current alias.
check_uelsbool, optional: If True, check both used and unused UELs and confirm same order, otherwise only check used UELs in data and do not check UEL order.
check_element_textbool, optional: If True, check that all set elements have the same descriptive element text, otherwise skip.
check_meta_databool, optional: If True, check that symbol name and description are the same, otherwise skip.
verbosebool, optional: If True, return an exception from the asserter describing the nature of the difference.

Returns:

bool: True if the two symbols are equal in the specified aspects; False if they are not equal and verbose is False.

Examples

>>> m = gt.Container()
>>> i = gt.Set(m, "i")
>>> j = gt.Alias(m, "j", i)
>>> print(i.equals(j))  # Compare the Set 'i' with the Alias 'j'
True

gamsRepr() → str[source]#

Returns the string representation of this Alias in the GAMS language.

(e.g., ‘j’).

Returns:

str: The GAMS string representation.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i", domain=["*"], records=['i1','i2'])
>>> j = gp.Alias(m, "j", i)
>>> j.gamsRepr()
'j'

getDeclaration() → str[source]#

Returns the GAMS declaration statement for this Alias.

(e.g., ‘Alias(i, j);’).

Returns:

str: The GAMS declaration string.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i", records=['i1','i2'])
>>> j = gp.Alias(m, "j", i)
>>> j.getDeclaration()
'Alias(i,j);'

getSparsity() → float | None[source]#

Gets the sparsity of the symbol w.r.t the cardinality

Returns:

float | None: Sparsity of an alias

isValid(verbose: bool = False, force: bool = False) → bool#

Checks if the symbol is in a valid format

Parameters:

verbosebool, optional: Throw exceptions if verbose=True, by default False
forcebool, optional: Recheck a symbol if force=True, by default False

Returns:

bool: True if a symbol is in valid format, False otherwise (throws exceptions if verbose=True)

lag(n: OperableType, type: Literal['linear', 'circular'] = 'linear') → ImplicitSet#

Shifts the values of a Set or Alias by n positions to the left (lag).

Parameters:

nOperableType: The number of positions to shift. Can be an integer or a GAMS symbol.
type‘linear’ or ‘circular’, optional: The type of lag to perform: - ‘linear’ (default): Elements shifted out of bounds are dropped. - ‘circular’: Elements shifted out of bounds wrap around to the end.

Returns:

ImplicitSet: The shifted set expression.

Raises:

ValueError: If type is not ‘linear’ or ‘circular’.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> t = gp.Set(m, name="t", description="time sequence", records=[f"y-{x}" for x in range(1987, 1992)])
>>> a = gp.Parameter(m, name="a", domain=[t])
>>> b = gp.Parameter(m, name="b", domain=[t])
>>> a[t] = 1986 + gp.Ord(t)
>>> b[t] = a[t.lag(1, "linear")]
>>> b.records.values.tolist()
[['y-1988', 1987.0], ['y-1989', 1988.0], ['y-1990', 1989.0], ['y-1991', 1990.0]]

lead(n: OperableType, type: Literal['linear', 'circular'] = 'linear') → ImplicitSet#

Shifts the values of a Set or Alias by n positions to the right (lead).

Parameters:

nOperableType: The number of positions to shift. Can be an integer or a GAMS symbol.
type‘linear’ or ‘circular’, optional: The type of lead to perform: - ‘linear’ (default): Elements shifted out of bounds are dropped. - ‘circular’: Elements shifted out of bounds wrap around to the beginning.

Returns:

ImplicitSet: The shifted set expression.

Raises:

ValueError: If type is not ‘linear’ or ‘circular’.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> t = gp.Set(m, name="t", description="time sequence", records=[f"y-{x}" for x in range(1987, 1992)])
>>> a = gp.Parameter(m, name="a", domain=[t])
>>> c = gp.Parameter(m, name="c", domain=[t])
>>> a[t] = 1986 + gp.Ord(t)
>>> c[t.lead(2, "linear")] = a[t]
>>> c.records.values.tolist()
[['y-1989', 1987.0], ['y-1990', 1988.0], ['y-1991', 1989.0]]

Convenience function to pivot records into a new shape (only symbols with > 1D can be pivoted).

Parameters:

indexlist[str] | str, optional: If index is None then it is set to dimensions [0..dimension-1]
columnslist[str] | str, optional: If columns is None then it is set to the last dimension.
fill_valueint | float, optional: Missing values in the pivot will take the value provided by fill_value

Returns:

DataFrame: A new DataFrame containing the pivoted data.

Examples

>>> m = gt.Container()
>>> i = gt.Set(m, "i", records=["seattle", "san-diego"])
>>> j = gt.Set(m, "j", records=["new-york", "chicago", "topeka"])
>>> ij = gt.Set(m, "ij", [i,j], records=[("seattle", "chicago"), ("seattle", "topeka"), ("san-diego", "new-york")])
>>> routes = gt.Alias(m, name="routes", alias_with=ij)
>>> print(routes.pivot(fill_value=""))
          chicago topeka new-york
seattle      True   True
san-diego                    True

sameAs(other: Set | Alias | str) → MathOp#

Evaluates to True if the current set element is identical to the given symbol or string.

This corresponds to the sameAs operator in GAMS.

Parameters:

otherSet | Alias | str: The other set, alias, or string label to compare against.

Returns:

MathOp: A boolean expression that evaluates to True (1) if they match, False (0) otherwise.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego"])
>>> j = gp.Set(m, name="j", records=["new-york", "seattle"])
>>> attr = gp.Parameter(m, "attr", domain=[i, j])
>>> attr[i,j] = i.sameAs(j)
>>> attr.records.values.tolist()
[['seattle', 'seattle', 1.0]]

setRecords(records: Any, uels_on_axes: bool = False) → None[source]#

main convenience method to set standard pandas.DataFrame formatted records. If uels_on_axes=True setRecords will assume that all domain information is contained in the axes of the pandas object – data will be flattened (if necessary).

Parameters:

recordsAny
uels_on_axesbool, optional

toList(include_element_text: bool = False) → list[source]#

Convenience method to return symbol records as a python list

Parameters:

include_element_textbool, optional: If True, include the element text as tuples (record, element text). If False, return a list of records only.

Returns:

list: A list containing the records of the symbol.

Examples

>>> m = gt.Container()
>>> i = gt.Set(m, "i", records=["new-york", "chicago", "topeka"])
>>> j = gt.Alias(m, "j", i)
>>> print(j.toList())
['new-york', 'chicago', 'topeka']

property alias_with: Set#

Returns the aliased object

Returns:

Set: The aliased Set

property container#: Container of the symbol

property description: str#

Returns description of symbol

Returns:

str: Description of symbol

property dimension: int#

Returns the dimension of symbol

Returns:

int: Dimension of symbol

property domain: list[Set | str]#

Returns list of domains given either as string (* for universe set) or as reference to the Set/Alias object

Returns:

list[Set | str]: A list of domains given either as string (* for universe set) or as reference to the Set/Alias object

property domain_labels: list[str] | None#

Returns the column headings for the records DataFrame

Returns:

list[str] | None: Column headings for the records DataFrame

property domain_names: list[str]#

Returns the string version of domain names

Returns:

list[str]: A list of string version of domain names

property domain_type: str | None#

Returns the state of domain links

Returns:

str: none, relaxed or regular

property first: ImplicitParameter#

Returns 1 if the element is the first in the set, otherwise 0.

This attribute corresponds to the .first attribute in GAMS.

Returns:

ImplicitParameter: An implicit parameter with value 1 for the first element.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego", "new-york"], description="canning plants")
>>> i.first.records.values.tolist()
[['seattle', 'is_first', 1.0]]

property is_singleton: bool#

if symbol is a singleton set

Returns:

bool: True if the alias is singleton; False otherwise

property last: ImplicitParameter#

Returns 1 if the element is the last in the set, otherwise 0.

This attribute corresponds to the .last attribute in GAMS.

Returns:

ImplicitParameter: An implicit parameter with value 1 for the last element.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego", "new-york"], description="canning plants")
>>> i.last.records.values.tolist()
[['new-york', 'is_last', 1.0]]

property len: ImplicitParameter#

Returns the length of the set element name (count of characters).

This attribute corresponds to the .len attribute in GAMS.

Returns:

ImplicitParameter: The character count of the element name.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego", "new-york"], description="canning plants")
>>> i.len.records.values.tolist()
[['seattle', 'length', 7.0], ['san-diego', 'length', 9.0], ['new-york', 'length', 8.0]]

property modified#: Flag that identifies if the symbol has been modified

property name#: Name of symbol

property number_records: int#

Returns the number of symbol records

Returns:

int: Number of symbol records

property off: ImplicitParameter#

Returns the element position in the current set minus 1.

Mathematically: .off = .pos - 1. This attribute corresponds to the .off attribute in GAMS.

Returns:

ImplicitParameter: The offset position of the element.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego", "new-york"], description="canning plants")
>>> i.off.records.values.tolist()
[['san-diego', 'off', 1.0], ['new-york', 'off', 2.0]]

property ord: ImplicitParameter#

Same as .pos but for ordered sets only.

Returns:

ImplicitParameter: The ordinal position of the element.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego", "new-york"], description="canning plants")
>>> i.ord.records.values.tolist()
[['seattle', 'order', 1.0], ['san-diego', 'order', 2.0], ['new-york', 'order', 3.0]]

property pos: ImplicitParameter#

Returns the element position in the current set, starting with 1.

This attribute corresponds to the .pos attribute in GAMS.

Returns:

ImplicitParameter: The position of the element.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego", "new-york"], description="canning plants")
>>> i.pos.records.values.tolist()
[['seattle', 'position', 1.0], ['san-diego', 'position', 2.0], ['new-york', 'position', 3.0]]

property records: pd.DataFrame | None#

Returns the main symbol records

Returns:

DataFrame | None: The main symbol records, None if no records were set

property rev: ImplicitParameter#

Returns the reverse element position in the current set.

The value for the last element is 0, the penultimate is 1, and so on. This attribute corresponds to the .rev attribute in GAMS.

Returns:

ImplicitParameter: The reverse position value.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego", "new-york"], description="canning plants")
>>> i.rev.records.values.tolist()
[['seattle', 'reverse', 2.0], ['san-diego', 'reverse', 1.0]]

property summary: dict#

Returns a dict of only the metadata

Returns:

dict: Outputs a dict of only the metadata

property tlen: ImplicitParameter#

Returns the length of the set element explanatory text (count of characters).

This attribute corresponds to the .tlen attribute in GAMS.

Returns:

ImplicitParameter: The character count of the element text.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=[("seattle", "Wisconsin"), ("san-diego", ""), ("new-york", " ")], description="canning plants")
>>> i.tlen.records.values.tolist()
[['seattle', 'text_length', 9.0], ['new-york', 'text_length', 1.0]]

property tval: ImplicitParameter#

Returns the numerical value if the set element text is a number.

If the element text is not a number, this attribute is undefined. This attribute corresponds to the .tval attribute in GAMS.

Returns:

ImplicitParameter: The numerical value of the element text.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=[("seattle", "12"), ("san-diego", ""), ("new-york", "-13.4")], description="canning plants")
>>> i.tval.records.values.tolist()
[['seattle', 'text_value', 12.0], ['new-york', 'text_value', -13.4]]

property uel: ImplicitParameter#

Returns the element position in the global Unique Element List (UEL).

This attribute corresponds to the .uel attribute in GAMS.

Returns:

ImplicitParameter: The position index in the UEL table.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego", "new-york"], description="canning plants")
>>> i.uel.records.values.tolist()
[['seattle', 'uel_position', 1.0], ['san-diego', 'uel_position', 2.0], ['new-york', 'uel_position', 3.0]]

property val: ImplicitParameter#

Returns the numerical value if the set element name is a number.

If the element is not a number, this attribute is undefined and may result in an error or ignored record. This attribute corresponds to the .val attribute in GAMS.

Returns:

ImplicitParameter: The numerical value of the element name.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["12", "20", "-13.4"], description="canning plants")
>>> i.val.records.values.tolist()
[['12', 'value', 12.0], ['20', 'value', 20.0], ['-13.4', 'value', -13.4]]