Alias#

class gamspy.Alias(container, name, alias_with)[source]#

Bases: Alias, Operable, Symbol, SetMixin

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

Parameters:
containerContainer
namestr
alias_withSet
Parameters:
  • container (Container) –

  • name (str) –

  • alias_with (Set) –

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.

Parameters:
  • container (Container) –

  • name (str) –

  • alias_with (Set) –

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.

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 definition

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()[source]#

Representation of this Alias in GAMS language.

Returns:
str
Return type:

str

getStatement()[source]#

Statement of the Alias definition

Returns:
str
Return type:

str

addUELs(uels, dimensions=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.

Parameters:
  • uels (List[str] | str) –

  • dimensions (int | List[int] | None) –

Return type:

None

capitalizeUELs(dimensions=None)[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.

Parameters:

dimensions (int | List[int] | None) –

Return type:

Alias

casefoldUELs(dimensions=None)[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.

Parameters:

dimensions (int | List[int] | None) –

Return type:

Alias

property container#

Container of the symbol

countDomainViolations()[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

Return type:

int

countDuplicateRecords()[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

Return type:

int

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()[source]#

Drop records from the parent set that contain a domain violation

Return type:

None

dropDuplicateRecords(keep='first')[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

Parameters:

keep (str | bool) –

Return type:

None

equals(other, check_uels=True, check_element_text=True, check_meta_data=True, verbose=False)[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.

Parameters:
  • other (Set | Alias) –

  • check_uels (bool) –

  • check_element_text (bool) –

  • check_meta_data (bool) –

  • verbose (bool) –

Return type:

bool

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()[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.

Return type:

DataFrame

findDuplicateRecords(keep='first')[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.

Parameters:

keep (str | bool) –

Return type:

DataFrame

property first#

Returns 1 for the first set element, otherwise 0.

Returns:
ImplicitSet
getDomainViolations()[source]#

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

Returns:
List[DomainViolation] | None

A list of DomainViolation objects if any (None otherwise)

Return type:

List[DomainViolation] | None

getSparsity()[source]#

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

Returns:
float | None

Sparsity of an alias

Return type:

float | None

getUELs(dimensions=None, codes=None, ignore_unused=False)[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.

Parameters:
  • dimensions (int | List[int] | None) –

  • codes (int | List[int] | None) –

  • ignore_unused (bool) –

Return type:

List[str]

hasDomainViolations()[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

Return type:

bool

hasDuplicateRecords()[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

Return type:

bool

isValid(verbose=False, force=False)#

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)

Parameters:
  • verbose (bool) –

  • force (bool) –

Return type:

bool

property is_singleton: bool#

if symbol is a singleton set

Returns:
bool

True if the alias is singleton; False otherwise

lag(n, type='linear')#

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

Parameters:
  • self (Alias | Set) –

  • n (int | Symbol | Expression) –

  • type (Literal['linear', 'circular']) –

Return type:

ImplicitSet

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, type='linear')#

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

Parameters:
  • self (Set | Alias) –

  • n (int | Symbol | Expression) –

  • type (Literal['linear', 'circular']) –

Return type:

ImplicitSet

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, fill_character=None, dimensions=None)[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.

Parameters:
  • length (int) –

  • fill_character (str | None) –

  • dimensions (int | List[int] | None) –

Return type:

Alias

lowerUELs(dimensions=None)[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.

Parameters:

dimensions (int | List[int] | None) –

Return type:

Alias

lstripUELs(dimensions=None)[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.

Parameters:

dimensions (int | List[int] | None) –

Return type:

Alias

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
pivot(index=None, columns=None, fill_value=None)[source]#

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.

Parameters:
  • index (str | List[str] | None) –

  • columns (str | List[str] | None) –

  • fill_value (int | float | None) –

Return type:

DataFrame

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=None, dimensions=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.

Parameters:
  • uels (str | List[str] | None) –

  • dimensions (int | List[int] | None) –

Return type:

None

renameUELs(uels, dimensions=None, allow_merge=False)[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

Parameters:
  • uels (List[str] | str) –

  • dimensions (int | List[int] | None) –

  • allow_merge (bool) –

Return type:

None

reorderUELs(uels=None, dimensions=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.

Parameters:
  • uels (str | List[str] | None) –

  • dimensions (int | List[int] | None) –

Return type:

None

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, fill_character=None, dimensions=None)[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.

Parameters:
  • length (int) –

  • fill_character (str | None) –

  • dimensions (int | List[int] | None) –

Return type:

Alias

rstripUELs(dimensions=None)[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.

Parameters:

dimensions (int | List[int] | None) –

Return type:

Alias

sameAs(other)#

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

Parameters:
otherSet | Alias
Returns:
Expression
Parameters:
Return type:

Expression

setRecords(records, uels_on_axes=False)[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
Parameters:
  • records (Any) –

  • uels_on_axes (bool) –

Return type:

None

setUELs(uels, dimensions=None, rename=False)[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

Parameters:
  • uels (List[str] | str) –

  • dimensions (int | List[int] | None) –

  • rename (bool) –

Return type:

None

stripUELs(dimensions=None)[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.

Parameters:

dimensions (int | List[int] | None) –

Return type:

Alias

property summary: dict#

Returns a dict of only the metadata

Returns:
dict

Outputs a dict of only the metadata

titleUELs(dimensions=None)[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.

Parameters:

dimensions (int | List[int] | None) –

Return type:

Alias

property tlen#

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

Returns:
ImplicitSet
toList(include_element_text=False)[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.

Parameters:

include_element_text (bool) –

Return type:

list

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=None)[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.

Parameters:

dimensions (int | List[int] | None) –

Return type:

Alias

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