Alias#

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

Bases: Alias, Operable, SetMixin

Represents an Alias symbol in GAMS. https://www.gams.com/latest/docs/UG_SetDefinition.html#UG_SetDefinition_TheAliasStatementMultipleNamesForASet

Parameters:

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

Examples

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

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 for the first set element, otherwise 0.
is_singleton: if symbol is a singleton set
last: Returns 1 for the last set element, otherwise 0.
len: Length of the set element name (a count of the number 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: Element position in the current set minus 1.
ord: Same as .pos but for ordered sets only.
pos: Element position in the current set, starting with 1.
records: Returns the main symbol records
rev: Reverse element position in the current set, so the value for the last element is 0, the value for the penultimate is 1, etc.
summary: Returns a dict of only the metadata
tlen: Length of the set element text (a count of the number of characters).
tval: If a set element text is a number, this attribute gives the value of the number.
uel: Element position in the unique element list.
val: If a set element is a number, this attribute gives the value of the number.

Methods

`addUELs`(uels[, dimensions])	Adds UELs to the parent set dimensions.
`capitalizeUELs`([dimensions])	Capitalizes the first character of UELs of an Alias
`casefoldUELs`([dimensions])	Casefolds the UELs of an Alias
`countDomainViolations`()	Returns the count of how many records in the parent set contain at least one domain violation
`countDuplicateRecords`()	Returns the count of how many (case insensitive) duplicate records exist in the parent set
`dropDomainViolations`()	Drop records from the parent set that contain a domain violation
`dropDuplicateRecords`([keep])	Drop records with (case insensitive) duplicate domains from the parent set
`equals`(other[, check_uels, ...])	Used to compare the symbol to another symbol.
`findDomainViolations`()	Get a view of the records DataFrame that contain any domain violations
`findDuplicateRecords`([keep])	Get a view of the records DataFrame that contain any domain violations.
`gamsRepr`()	Representation of this Alias in GAMS language.
`getDeclaration`()	Declaration of the Alias in GAMS
`getDomainViolations`()	Returns a list of DomainViolation objects if any (None otherwise)
`getSparsity`()	Gets the sparsity of the symbol w.r.t the cardinality
`getStatement`()	Statement of the Alias declaration
`getUELs`([dimensions, codes, ignore_unused])	Gets UELs from the parent set dimensions.
`hasDomainViolations`()	Returns True if there are domain violations in the records of the parent set, returns False if not.
`hasDuplicateRecords`()	Returns True if there are (case insensitive) duplicate records in the parent set, returns False if not.
`isValid`([verbose, force])	Checks if the symbol is in a valid format
`lag`(n[, type])	Lag operation shifts the values of a Set or Alias by one to the left
`lead`(n[, type])	Lead shifts the values of a Set or Alias by one to the right
`ljustUELs`(length[, fill_character, dimensions])	Left-justifies the UELs of an Alias, padding them with a specified fill character to reach the desired length.
`lowerUELs`([dimensions])	Lowercase the UELs of an Alias.
`lstripUELs`([dimensions])	Remove leading whitespaces from the UELs of an Alias.
`pivot`([index, columns, fill_value])	Convenience function to pivot records into a new shape (only symbols with > 1D can be pivoted).
`removeUELs`([uels, dimensions])	Removes UELs that appear in the parent set dimensions, If uels is None then remove all unused UELs (categories).
`renameUELs`(uels[, dimensions, allow_merge])	Renames UELs (case-sensitive) that appear in the parent set dimensions.
`reorderUELs`([uels, dimensions])	Reorders the UELs in the parent set dimensions.
`rjustUELs`(length[, fill_character, dimensions])	Left-justifies the UELs of an Alias, padding them with a specified fill character to reach the desired length.
`rstripUELs`([dimensions])	Remove trailing whitespaces from the UELs of an Alias.
`sameAs`(other)	Evaluates to true if this set is identical to the given set or alias, false otherwise.
`setRecords`(records[, uels_on_axes])	main convenience method to set standard pandas.DataFrame formatted records.
`setUELs`(uels[, dimensions, rename])	Set the UELs for parent set dimensions.
`stripUELs`([dimensions])	Remove leading and trailing whitespaces from the UELs of an Alias.
`titleUELs`([dimensions])	Converts the UELs of an Alias to title style; new-york -> New-York
`toList`([include_element_text])	Convenience method to return symbol records as a python list
`upperUELs`([dimensions])	Uppercase the UELs of an Alias.

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

property alias_with: Set#

Returns the aliased object

Returns:

Set: The aliased Set

gamsRepr() → str[source]#

Representation of this Alias in GAMS language.

Returns:

str

getDeclaration()[source]#

Declaration of the Alias in GAMS

Returns:

str

getStatement() → str[source]#

Statement of the Alias declaration

Returns:

str

addUELs(uels: List[str] | str, dimensions: int | List[int] | None = None) → None[source]#

Adds UELs to the parent set dimensions. If dimensions is None then add UELs to all dimensions. ** All trailing whitespace is trimmed **

Parameters:

uelsList[str] | str: UELs to be added
dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

capitalizeUELs(dimensions: int | List[int] | None = None) → Alias[source]#

Capitalizes the first character of UELs of an Alias

Parameters:

dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

Returns:

Alias: The Alias with processed UELs.

casefoldUELs(dimensions: int | List[int] | None = None) → Alias[source]#

Casefolds the UELs of an Alias

Parameters:

dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

Returns:

Alias: The Alias with processed UELs.

property container#: Container of the symbol

countDomainViolations() → int[source]#

Returns the count of how many records in the parent set contain at least one domain violation

Returns:

int: The count of how many records in the parent set contain at least one domain violation

countDuplicateRecords() → int[source]#

Returns the count of how many (case insensitive) duplicate records exist in the parent set

Returns:

int: The count of how many (case insensitive) duplicate records exist in the parent set

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:

Union[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

dropDomainViolations() → None[source]#: Drop records from the parent set that contain a domain violation

dropDuplicateRecords(keep: str | bool = 'first') → None[source]#

Drop records with (case insensitive) duplicate domains from the parent set

Parameters:

keepstr, optional: Specifies how to handle duplicates. Options are: - ‘first’ (default): keeps the first instance of a duplicate record - ‘last’: keeps the last instance of a record - False: drops all duplicates including the first and last

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

findDomainViolations() → DataFrame[source]#

Get a view of the records DataFrame that contain any domain violations

Returns:

DataFrame: A DataFrame containing the records that contain any domain violations. If there are no violations, an empty DataFrame is returned.

findDuplicateRecords(keep: str | bool = 'first') → DataFrame[source]#

Get a view of the records DataFrame that contain any domain violations.

Parameters:

keepstr, optional: Specifies how to handle duplicates. Options are: - ‘first’ (default): Keeps the first occurrence and removes subsequent duplicates. - ‘last’: Keeps the last occurrence and removes previous duplicates. - False: Keeps all duplicates.

Returns:

DataFrame: A DataFrame of the records that contain any domain violations. If there are no duplicates, an empty DataFrame is returned.

property first#

Returns 1 for the first set element, otherwise 0.

Returns:

ImplicitSet

getDomainViolations() → List[DomainViolation] | None[source]#

Returns a list of DomainViolation objects if any (None otherwise)

Returns:

List[DomainViolation] | None: A list of DomainViolation objects if any (None otherwise)

getSparsity() → float | None[source]#

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

Returns:

float | None: Sparsity of an alias

getUELs(dimensions: int | List[int] | None = None, codes: int | List[int] | None = None, ignore_unused: bool = False) → List[str][source]#

Gets UELs from the parent set dimensions. If dimensions is None then get UELs from all dimensions (maintains order). The argument codes accepts a list of str UELs and will return the corresponding int; must specify a single dimension if passing codes.

Parameters:

dimensionsList[int] | int, optional
codesList[int] | int, optional
ignore_unusedbool, optional

Returns:

List[str]: Returns only UELs in the data if ignore_unused=True, otherwise return all UELs.

hasDomainViolations() → bool[source]#

Returns True if there are domain violations in the records of the parent set, returns False if not.

Returns:

bool: True if there are domain violations in the records of the parent set; False otherwise

hasDuplicateRecords() → bool[source]#

Returns True if there are (case insensitive) duplicate records in the parent set, returns False if not.

Returns:

bool: True if there are (case insensitive) duplicate records in the parent set; False otherwise

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)

property is_singleton: bool#

if symbol is a singleton set

Returns:

bool: True if the alias is singleton; False otherwise

lag(n: int | Symbol | Expression, type: Literal['linear', 'circular'] = 'linear') → ImplicitSet#

Lag operation shifts the values of a Set or Alias by one to the left

Parameters:

nint | Symbol | Expression
type‘linear’ or ‘circular’, optional

Returns:

ImplicitSet

Raises:

ValueError: When type is not circular or linear

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])
>>> c = gp.Parameter(m, name="c", domain=[t])
>>> a[t] = 1986 + gp.Ord(t)
>>> b[t] = -1
>>> 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]]
>>> c[t] = a[t.lag(1, "circular")]
>>> c.records.values.tolist()
[['y-1987', 1991.0], ['y-1988', 1987.0], ['y-1989', 1988.0], ['y-1990', 1989.0], ['y-1991', 1990.0]]

property last#

Returns 1 for the last set element, otherwise 0.

Returns:

ImplicitSet

lead(n: int | Symbol | Expression, type: Literal['linear', 'circular'] = 'linear') → ImplicitSet#

Lead shifts the values of a Set or Alias by one to the right

Parameters:

nint | Symbol | Expression
type‘linear’ or ‘circular’, optional

Returns:

ImplicitSet

Raises:

ValueError: When type is not circular or linear

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])
>>> d = gp.Parameter(m, name="d", domain=[t])
>>> a[t] = 1986 + gp.Ord(t)
>>> c[t] = -1
>>> c[t.lead(2, "linear")] = a[t]
>>> c.records.values.tolist()
[['y-1987', -1.0], ['y-1988', -1.0], ['y-1989', 1987.0], ['y-1990', 1988.0], ['y-1991', 1989.0]]
>>> d[t.lead(2, "circular")] = a[t]
>>> d.records.values.tolist()
[['y-1987', 1990.0], ['y-1988', 1991.0], ['y-1989', 1987.0], ['y-1990', 1988.0], ['y-1991', 1989.0]]

property len#

Length of the set element name (a count of the number of characters).

Returns:

ImplicitSet

ljustUELs(length: int, fill_character: str | None = None, dimensions: int | List[int] | None = None) → Alias[source]#

Left-justifies the UELs of an Alias, padding them with a specified fill character to reach the desired length.

Parameters:

lengthint: The target length to which UELs will be left-justified.
fill_characterstr, optional: The character used for padding the UELs to the specified length. If not provided, it defaults to a whitespace.
dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

Returns:

Alias: The Alias with processed UELs.

lowerUELs(dimensions: int | List[int] | None = None) → Alias[source]#

Lowercase the UELs of an Alias.

Parameters:

dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

Returns:

Alias: The Alias with lowercase UELs.

lstripUELs(dimensions: int | List[int] | None = None) → Alias[source]#

Remove leading whitespaces from the UELs of an Alias.

Parameters:

dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

Returns:

Alias: The Alias with processed UELs.

property name#: Name of symbol

property number_records: int#

Returns the number of symbol records

Returns:

int: Number of symbol records

property off#

Element position in the current set minus 1. So .off = .pos - 1

Returns:

ImplicitSet

property ord#

Same as .pos but for ordered sets only.

Returns:

ImplicitSet

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

property pos#

Element position in the current set, starting with 1.

Returns:

ImplicitSet

property records: DataFrame | None#

Returns the main symbol records

Returns:

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

removeUELs(uels: str | List[str] | None = None, dimensions: int | List[int] | None = None) → None[source]#

Removes UELs that appear in the parent set dimensions, If uels is None then remove all unused UELs (categories). If dimensions is None then operate on all dimensions.

Parameters:

uelsList[str] | str, optional: UELs to be removed
dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

renameUELs(uels: List[str] | str, dimensions: int | List[int] | None = None, allow_merge: bool = False) → None[source]#

Renames UELs (case-sensitive) that appear in the parent set dimensions. If dimensions is None then operate on all dimensions of the symbol. If allow_merge=True, the categorical object will be re-created to offer additional data flexibility. ** All trailing whitespace is trimmed **

Parameters:

uelsList[str] | str: UELs to be renamed
dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.
allow_mergebool: If True, the categorical object will be re-created to offer additional data flexibility

reorderUELs(uels: str | List[str] | None = None, dimensions: int | List[int] | None = None) → None[source]#

Reorders the UELs in the parent set dimensions. If uels is None, reorder UELs to data order and append any unused categories. If dimensions is None then reorder UELs in all dimensions of the parent set.

Parameters:

uelsList[str] | str, optional
dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

property rev#

Reverse element position in the current set, so the value for the last element is 0, the value for the penultimate is 1, etc.

Returns:

ImplicitSet

rjustUELs(length: int, fill_character: str | None = None, dimensions: int | List[int] | None = None) → Alias[source]#

Left-justifies the UELs of an Alias, padding them with a specified fill character to reach the desired length.

Parameters:

lengthint: The target length to which UELs will be left-justified.
fill_characterstr, optional: The character used for padding the UELs to the specified length. If not provided, it defaults to a whitespace.
dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

Returns:

Alias: The Alias with processed UELs.

rstripUELs(dimensions: int | List[int] | None = None) → Alias[source]#

Remove trailing whitespaces from the UELs of an Alias.

Parameters:

dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

Returns:

Alias: The Alias with processed UELs.

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

Evaluates to true if this set is identical to the given set or alias, false otherwise.

Parameters:

otherSet | Alias

Returns:

Expression

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

setUELs(uels: List[str] | str, dimensions: int | List[int] | None = None, rename: bool = False) → None[source]#

Set the UELs for parent set dimensions. If dimensions is None then set UELs for all dimensions. If rename=True, then the old UEL names will be renamed with the new UEL names. ** All trailing whitespace is trimmed **

Parameters:

uelsList[str] | str: UELs to be set
dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.
renamebool, optional: If True, then the old UEL names will be renamed with the new UEL names. By default False

stripUELs(dimensions: int | List[int] | None = None) → Alias[source]#

Remove leading and trailing whitespaces from the UELs of an Alias.

Parameters:

dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

Returns:

Alias: The Alias with processed UELs.

property summary: dict#

Returns a dict of only the metadata

Returns:

dict: Outputs a dict of only the metadata

titleUELs(dimensions: int | List[int] | None = None) → Alias[source]#

Converts the UELs of an Alias to title style; new-york -> New-York

Parameters:

dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

Returns:

Alias: The Alias with processed UELs.

property tlen#

Length of the set element text (a count of the number of characters).

Returns:

ImplicitSet

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 tval#

If a set element text is a number, this attribute gives the value of the number. For extended range arithmetic symbols, the symbols are reproduced. If a set element text is a string that is not a number, then this attribute is not defined and trying to use it results in an error.

Returns:

ImplicitSet

property uel#

Element position in the unique element list.

Returns:

ImplicitSet

upperUELs(dimensions: int | List[int] | None = None) → Alias[source]#

Uppercase the UELs of an Alias.

Parameters:

dimensionsList[int] | int, optional: Dimensions of the Alias to be processed. You can provide a single dimension as an int or a list of dimensions. If not specified, it will process all dimensions.

Returns:

Alias: The Alias with uppercase UELs.

property val#

If a set element is a number, this attribute gives the value of the number. For extended range arithmetic symbols, the symbols are reproduced. If a set element is a string that is not a number, then this attribute is not defined and trying to use it results in an error.

Returns:

ImplicitSet