Set#

Bases: Set, Operable, Symbol, SetMixin

Represents a Set symbol in GAMS. https://gamspy.readthedocs.io/en/latest/user/basics/set.html

Parameters:

containerContainer: Container of the set.
namestr, optional: Name of the set. Name is autogenerated by default.
domainlist[Set | Alias | str] | Set | Alias | str, optional: Domain of the set.
is_singletonbool, optional: Whether the set is a singleton set. Singleton sets cannot contain more than one element.
recordspd.DataFrame | np.ndarray | list, optional: Records of the set.
domain_forwardingbool, optional: Whether the set forwards the domain.
descriptionstr, optional: Description of the set.
uels_on_axesbool: Assume that symbol domain information is contained in the axes of the given records.
is_miro_inputbool: Whether the symbol is a GAMS MIRO input symbol. See: https://gams.com/miro/tutorial.html
is_miro_outputbool: Whether the symbol is a GAMS MIRO output symbol. See: https://gams.com/miro/tutorial.html

Attributes:

container: Container of the symbol
description: Description of the symbol
dimension: The dimension of symbol
domain: List of domains given either as string (* for universe set) or as reference to the Set/Alias object
domain_forwarding: A boolean indicating whether domain forwarding is enabled
domain_labels: The column headings for the records DataFrame
domain_names: String version of domain names
domain_type: State of the domain links
first: Returns 1 for the first set element, otherwise 0.
is_singleton: Whether a 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: Number of 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: Records of the Set
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

`equals`(other[, check_uels, ...])	Used to compare the symbol to another symbol
`gamsRepr`()	Representation of this Set in GAMS language.
`generateRecords`([density, seed])	Convenience method to set standard pandas.DataFrame formatted records given domain set information.
`getAssignment`()	Latest assignment to the Set in GAMS
`getDeclaration`()	Declaration of the Set in GAMS
`getSparsity`()	Get 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])	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
`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 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.
`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", records=['i1','i2'])

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

Used to compare the symbol to another symbol

Parameters:

otherSet | Alias: Other Symbol to compare with
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, by default True
check_element_textbool, optional: If True, check that all set elements have the same descriptive element text, otherwise skip, by default True
check_meta_databool, optional: If True, check that symbol name and description are the same, otherwise skip, by default True
verbosebool, optional: If True, will return an exception from the asserter describing the nature of the difference, by default False

Returns:

bool: True if symbols are equal, False otherwise

gamsRepr() → str[source]#

Representation of this Set in GAMS language.

Returns:

str

Examples

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

generateRecords(density: int | float | list | None = None, seed: int | None = None) → None#

Convenience method to set standard pandas.DataFrame formatted records given domain set information. Will generate records with the Cartesian product of all domain sets

Parameters:

densityint | float | list, optional: Takes any value on the interval [0,1]. If density is <1 then randomly selected records will be removed. density will accept a list of length dimension – allows users to specify a density per symbol dimension, by default None
seedint, optional: Random number state can be set with seed argument, by default None

getAssignment() → str[source]#

Latest assignment to the Set in GAMS

Returns:

str

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i", records=['i1','i2'])
>>> i['i1'] = False
>>> i.getAssignment()
'i("i1") = no;'

getDeclaration() → str[source]#

Declaration of the Set in GAMS

Returns:

str

Examples

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

getSparsity() → float#

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

Returns:

float: Sparsity of the symbol w.r.t the cardinality

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: 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]]

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]]

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

Parameters:

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

Returns:

DataFrame: Pivoted records dataframe

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

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

Examples

>>> import gamspy as gp
>>> import numpy as np
>>> m = gp.Container()
>>> i = gp.Set(m, name="i")
>>> i.setRecords(["seattle", "san-diego"])
>>> i.records.values.tolist()
[['seattle', ''], ['san-diego', '']]

toList(include_element_text=False) → List[str | tuple] | None[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 | None: A list containing the records of the symbol, None if no record was assigned

Examples

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

property container#: Container of the symbol

property description#: Description of the symbol

property dimension#: The dimension of symbol

property domain#: List of domains given either as string (* for universe set) or as reference to the Set/Alias object

property domain_forwarding#: A boolean indicating whether domain forwarding is enabled

property domain_labels#: The column headings for the records DataFrame

property domain_names#: String version of domain names

property domain_type#: State of the domain links

property first#

Returns 1 for the first set element, otherwise 0.

Returns:

ImplicitSet

Examples

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

property is_singleton: bool#

Whether a symbol is a singleton set

Returns:

bool: True if the symbol is a singleton set; False otherwise

property last#

Returns 1 for the last set element, otherwise 0.

Returns:

ImplicitSet

Examples

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

property len#

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

Returns:

ImplicitSet

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego", "new-york"], description="canning plants")
>>> attr = gp.Parameter(m, "attr", domain = [i, "*"], description = "Set length values")
>>> attr[i,"length"]  =  i.len
>>> attr.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#: Number of records

property off#

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

Returns:

ImplicitSet

Examples

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

property ord#

Same as .pos but for ordered sets only.

Returns:

ImplicitSet

Examples

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

property pos#

Element position in the current set, starting with 1.

Returns:

ImplicitSet

Examples

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

property records#

Records of the Set

Returns:

DataFrame

Examples

>>> import gamspy as gp
>>> import numpy as np
>>> m = gp.Container()
>>> i = gp.Set(m, name="i")
>>> i.setRecords(["seattle", "san-diego"])
>>> i.records.values.tolist()
[['seattle', ''], ['san-diego', '']]

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

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego", "new-york"], description="canning plants")
>>> attr = gp.Parameter(m, "attr", domain = [i, "*"], description = "Set reverse values")
>>> attr[i,"reverse"]  =  i.rev
>>> attr.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#

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

Returns:

ImplicitSet

Examples

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

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

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")
>>> attr = gp.Parameter(m, "attr", domain = [i, "*"], description = "Set text values")
>>> attr[i,"text_value"]  =  i.tval
>>> attr.records.values.tolist()
[['seattle', 'text_value', 12.0], ['new-york', 'text_value', -13.4]]

property uel#

Element position in the unique element list.

Returns:

ImplicitSet

Examples

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

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

Examples

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