Set#

class gamspy.Set(container: Container | None = None, name: str | None = None, domain: DomainType | None = None, is_singleton: bool = False, records: Any | None = None, domain_forwarding: bool | list[bool] = False, description: str = '', uels_on_axes: bool = False, is_miro_input: bool = False, is_miro_output: bool = False)[source]#

Bases: Set, Operable, Symbol, SetMixin

Represents a Set symbol in GAMS.

See https://gamspy.readthedocs.io/en/latest/user/basics/set.html for more details.

Parameters:

containerContainer: The Container object that this set belongs to.
namestr, optional: Name of the set. If not provided, a unique name is generated automatically.
domainSequence[Set | Alias | str] | Set | Alias | str, optional: The domain of the set. Can be a list of other Sets/Aliases, a single Set/Alias, or strings representing set names. Use “*” for the universe set. Default is [“*”].
is_singletonbool, optional: If True, restricts the set to contain at most one element. Default is False.
recordspd.DataFrame | np.ndarray | list, optional: Initial elements to populate the set.
domain_forwardingbool | list[bool], optional: If True, adding records to this set will implicitly add new elements to the domain sets (if they are dynamic). Default is False.
descriptionstr, optional: A human-readable description of the set.
uels_on_axesbool, optional: If True, implies that the Unique Element Labels (UELs) for the domain are contained in the axes (index/columns) of the provided records object (e.g., pandas DataFrame). Default is False.
is_miro_inputbool, optional: If True, flags this set as an input symbol for GAMS MIRO. Default is False.
is_miro_outputbool, optional: If True, flags this set as an output symbol for GAMS MIRO. Default is False.

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 if the element is the first in the set, otherwise 0.
is_singleton: Whether a 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: Number of 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: Records of the Set
rev: Returns the reverse element position in the current set.
summary: Returns a dict of only the metadata
synchronize: Synchronization state of the symbol.
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`()	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])	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])	Sets the records (elements) of the Set.
`toList`([include_element_text])	Convenience method to return symbol records as a python list

Examples

Simple set:

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = m.addSet("i", records=["a", "b"])

Indexed set:

>>> j = m.addSet("j", domain=i)

Singleton set:

>>> s = m.addSet("s", is_singleton=True, records=["s1"])

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

Raises:

ValueError: When type is not circular or linear

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

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) → 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]#

Sets the records (elements) of the Set.

This is a convenience method to load data into the set. It handles various input formats like lists and pandas DataFrames.

Parameters:

recordsAny

The data to load. Common formats:

List of strings: [‘i1’, ‘i2’]
List of tuples (for multi-dimensional sets): [(‘a’, ‘1’), (‘b’, ‘2’)]
pandas DataFrame.

uels_on_axesbool, optional

If True, assumes that the domain information is located in the axes (index/columns) of the records object rather than the data values. Use this when passing a DataFrame where the indices represent the set elements.

Examples

>>> import gamspy as gp
>>> 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: 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#

Whether a symbol is a singleton set

Returns:

bool: True if the symbol is a singleton set; 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#: Number of 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#

Records of the Set

Returns:

DataFrame | None

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: 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 synchronize: bool#

Synchronization state of the symbol. If True, the symbol data will be communicated with GAMS. Otherwise, GAMS state will not be updated.

Returns:

bool

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i", records=["i1"])
>>> i.synchronize = False
>>> i["i2"] = True
>>> i.records.uni.tolist()
['i1']
>>> i.synchronize = True
>>> i.records.uni.tolist()
['i1', 'i2']

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