Container#

class gamspy.Container(load_from=None, system_directory=None, working_directory=None, debugging_level='delete', delayed_execution=False, miro_protect=True, options=None)[source]#

Bases: Container

A container is an object that holds all symbols and operates on them.

Parameters:
load_fromstr, optional

Path to the GDX file to be loaded from, by default None

system_directorystr, optional

Path to the directory that holds the GAMS installation, by default None

working_directorystr, optional

Path to the working directory to store temporary files such .lst, .gms, .gdx, .g00 files.

debugging_levelstr, optional

Decides on keeping the temporary files generate by GAMS, by default “delete”

delayed_executionbool, optional

Delayed execution mode, by default False

optionsOptions

Global options for the overall execution

miro_protectbool

Protects MIRO input symbol records from being re-assigned

Parameters:
  • load_from (str | None) –

  • system_directory (str | None) –

  • working_directory (str | None) –

  • debugging_level (str) –

  • delayed_execution (bool) –

  • miro_protect (bool) –

  • options (Options | None) –

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i")
Attributes:
data
delayed_execution

Delayed execution mode.

modified
summary

This property returns a summary of the container.

system_directory
Parameters:
  • load_from (str | None) –

  • system_directory (str | None) –

  • working_directory (str | None) –

  • debugging_level (str) –

  • delayed_execution (bool) –

  • miro_protect (bool) –

  • options (Options | None) –

Methods

addAlias(name, alias_with)

Creates a new Alias and adds it to the container

addEquation(name[, type, domain, ...])

Creates an Equation and adds it to the Container

addModel(name, problem[, equations, sense, ...])

Creates a Model and adds it to the Container

addParameter(name[, domain, records, ...])

Creates a Parameter and adds it to the Container

addSet(name[, domain, is_singleton, ...])

Creates a Set and adds it to the container

addUniverseAlias(name)

Add a Universe Alias to the GAMS container

addVariable(name[, type, domain, records, ...])

Creates a Variable and adds it to the Container

capitalizeUELs([symbols])

This function capitalizes the UELs of specific symbols.

casefoldUELs([symbols])

This function performs case folding on the UELs of specific symbols, converting them to lowercase.

copy(working_directory)

Creates a copy of the Container.

countDomainViolations([symbols])

Count domain violations for one or more symbols in the GAMS Container.

countDuplicateRecords([symbols])

Count duplicate records for one or more symbols in the GAMS Container.

describeAliases([symbols])

Generate a DataFrame describing alias symbols in the GAMS Container.

describeEquations([symbols])

Generate a DataFrame describing equation symbols in the GAMS Container.

describeParameters([symbols])

Generate a DataFrame describing parameter symbols in the GAMS Container.

describeSets([symbols])

Generate a DataFrame describing sets within the GAMS Container.

describeVariables([symbols])

Generate a DataFrame describing variable symbols in the GAMS Container.

dropDomainViolations([symbols])

Drop domain violations for one or more symbols in the GAMS Container.

dropDuplicateRecords([symbols, keep])

Remove duplicate records from the specified symbols in the GAMS Container.

gamsJobName()

Returns the name of the latest GAMS job that was executed

gdxInputPath()

Path to the input gdx file

gdxOutputPath()

Path to the output gdx file

generateGamsString()

Generates the GAMS code

getAliases([is_valid])

Retrieve alias objects from the GAMS Container.

getDomainViolations([symbols])

Get domain violations for one or more symbols in the GAMS Container.

getEquations()

Retrieve equation objects from the GAMS Container.

getParameters([is_valid])

Retrieve parameter objects from the GAMS Container.

getSets([is_valid])

Retrieve set objects from the GAMS Container.

getSymbols([symbols])

Retrieve symbol objects from the GAMS Container.

getUELs([symbols, ignore_unused, unique_only])

Retrieve the (UELs) associated with one or more symbols in the GAMS Container.

getVariables([is_valid, types])

Retrieve variable objects from the GAMS Container.

hasDomainViolations([symbols])

Check if domain violations exist for one or more symbols in the GAMS Container.

hasDuplicateRecords([symbols])

Check if the GAMS Container has any duplicate records for one or more symbols.

hasSymbols(symbols)

Checks if specific symbol names exist in a Container

isValid([symbols, verbose, force])

Check the validity of symbols in the GAMS Container.

listAliases([is_valid])

Get a list of alias names in the GAMS Container.

listEquations([is_valid, types])

Get a list of equation names in the GAMS Container.

listParameters([is_valid])

Get a list of parameter names in the GAMS Container.

listSets([is_valid])

Get a list of set names in the GAMS Container.

listSymbols([is_valid])

Get a list of symbol names in the GAMS Container.

listVariables([is_valid, types])

Get a list of variable names in the GAMS Container.

ljustUELs(length[, fill_character, symbols])

This function left-justifies the UELs of specific symbols within the container, padding them with a specified fill character to reach the desired length.

loadRecordsFromGdx(load_from[, symbol_names])

Loads data of the given symbols from a gdx file.

lowerUELs([symbols])

This function converts the UELs of specific symbols to lowercase.

lstripUELs([symbols])

This function removes leading whitespaces from the UELs of specific symbols.

read(load_from[, symbol_names, ...])

Reads specified symbols from the gdx file.

removeSymbols([symbols])

Remove symbols from the Container.

removeUELs([uels, symbols])

Remove specific unique element labels (UELs) from one or more symbols in the GAMS Container.

renameSymbol(old_name, new_name)

Rename a symbol in the Container

renameUELs(uels[, symbols, allow_merge])

Rename unique element labels (UELs) associated with symbols in the GAMS Container.

reorderSymbols()

Reorder symbols in order to avoid domain violations

rjustUELs(length[, fill_character, symbols])

This function right-justifies the UELs of specific symbols within the container, padding them with a specified fill character to reach the desired length.

rstripUELs([symbols])

This function removes trailing whitespaces from the UELs of specific symbols.

stripUELs([symbols])

This function removes leading and trailing whitespaces from the UELs of specific symbols.

titleUELs([symbols])

This function capitalizes the UELs of specific symbols in title case.

upperUELs([symbols])

This function converts the UELs of specific symbols to uppercase.

write(write_to[, symbol_names, compress, ...])

Writes specified symbols to the gdx file.

property delayed_execution: bool#

Delayed execution mode.

Returns:
bool
gamsJobName()[source]#

Returns the name of the latest GAMS job that was executed

Returns:
str | None
Return type:

str | None

gdxInputPath()[source]#

Path to the input gdx file

Returns:
str
Return type:

str

gdxOutputPath()[source]#

Path to the output gdx file

Returns:
str
Return type:

str

addAlias(name, alias_with)[source]#

Creates a new Alias and adds it to the container

Parameters:
namestr
alias_withSet | Alias
Returns:
Alias
Raises:
TypeError

In case the alias_with is different than a Set or an Alias

ValueError

If there is symbol with same name but different type in the Container

Parameters:
  • name (str) –

  • alias_with (Set | Alias) –

Return type:

Alias

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = m.addSet("i")
>>> a = m.addAlias("a", i)
addSet(name, domain=None, is_singleton=False, records=None, domain_forwarding=False, description='', uels_on_axes=False)[source]#

Creates a Set and adds it to the container

Parameters:
namestr
domainList[Set | str], optional
is_singletonbool, optional
recordsAny, optional
domain_forwardingbool, optional
descriptionstr, optional
uels_on_axesbool, optional
Returns:
Set
Raises:
err

In case arguments are not valid

ValueError

When there is symbol with same name in the Container

Parameters:
  • name (str) –

  • domain (list[Set | str] | None) –

  • is_singleton (bool) –

  • records (Any | None) –

  • domain_forwarding (bool) –

  • description (str) –

  • uels_on_axes (bool) –

Return type:

Set

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = m.addSet("i")
addParameter(name, domain=None, records=None, domain_forwarding=False, description='', uels_on_axes=False)[source]#

Creates a Parameter and adds it to the Container

Parameters:
namestr
domainList[str | Set]], optional
recordsAny, optional
domain_forwardingbool, optional
descriptionstr, optional
uels_on_axesbool, optional
Returns:
Parameter
Raises:
err

In case arguments are not valid

ValueError

If there is symbol with same name but different type in the Container

Parameters:
  • name (str) –

  • domain (list[str | Set] | None) –

  • records (Any | None) –

  • domain_forwarding (bool) –

  • description (str) –

  • uels_on_axes (bool) –

Return type:

Parameter

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> a = m.addParameter("a")
addVariable(name, type='free', domain=None, records=None, domain_forwarding=False, description='', uels_on_axes=False)[source]#

Creates a Variable and adds it to the Container

Parameters:
namestr
typestr, optional
domainList[str | Set]], optional
recordsAny, optional
domain_forwardingbool, optional
descriptionstr, optional
uels_on_axesbool, optional
Returns:
Variable
Raises:
err

In case arguments are not valid

ValueError

If there is symbol with same name but different type in the Container

Parameters:
  • name (str) –

  • type (str) –

  • domain (list[str | Set] | None) –

  • records (Any | None) –

  • domain_forwarding (bool) –

  • description (str) –

  • uels_on_axes (bool) –

Return type:

Variable

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> v = m.addVariable("v")
addEquation(name, type='regular', domain=None, definition=None, records=None, domain_forwarding=False, description='', uels_on_axes=False, definition_domain=None)[source]#

Creates an Equation and adds it to the Container

Parameters:
namestr
typestr
domainList[Set | str], optional
definitionDefinition, optional
recordsAny, optional
domain_forwardingbool, optional
descriptionstr, optional
uels_on_axesbool, optional
definition_domainList[Set | str], optional
Returns:
Equation
Raises:
err

In case arguments are not valid

ValueError

If there is symbol with same name but different type in the Container

Parameters:
  • name (str) –

  • type (str | EquationType) –

  • domain (list[Set | str] | None) –

  • definition (Expression | None) –

  • records (Any | None) –

  • domain_forwarding (bool) –

  • description (str) –

  • uels_on_axes (bool) –

  • definition_domain (list[Set | str] | None) –

Return type:

Equation

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = m.addEquation("i")
addModel(name, problem, equations=[], sense=None, objective=None, matches=None, limited_variables=None)[source]#

Creates a Model and adds it to the Container

Parameters:
namestr
equationsList[Equation]
problemstr
sense“MIN”, “MAX”, optional
objectiveVariable | Expression, optional
matchesdict, optional
limited_variableslist, optional
Returns:
Model
Parameters:
  • name (str) –

  • problem (str) –

  • equations (list[Equation]) –

  • sense (Literal['MIN', 'MAX'] | Sense | None) –

  • objective (Variable | Expression | None) –

  • matches (dict | None) –

  • limited_variables (list | None) –

Return type:

Model

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> e = gp.Equation(m, "e")
>>> model = m.addModel("my_model", "LP", [e])
copy(working_directory)[source]#

Creates a copy of the Container. Should not be invoked after creating the model.

Parameters:
working_directorystr, optional

Working directory of the new Container, by default None

Returns:
Container
Raises:
ValidationError
Parameters:

working_directory (str) –

Return type:

Container

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i")
>>> new_cont = m.copy(working_directory="test")
>>> new_cont.data.keys() == m.data.keys()
True
generateGamsString()[source]#

Generates the GAMS code

Returns:
str
Return type:

str

getEquations()[source]#

Retrieve equation objects from the GAMS Container.

This method allows you to retrieve equation objects from the GAMS Container based on their names.

Parameters:
is_validbool, optional

An optional boolean flag used to filter the list of equations. If None (default), all equations in the Container are returned. If True, only valid equations are included in the list. If False, only invalid equations are included in the list.

typesstr | List[str], optional

An optional string or list of strings specifying the types of equations to include in the list. If None (default), all equation types are included in the list. If a string or list of strings is provided, only equations of the specified types are included in the list.

Returns:
List[ABCEquation]

A list of equation objects that match the specified names.

loadRecordsFromGdx(load_from, symbol_names=None)[source]#

Loads data of the given symbols from a gdx file. If no symbol names are given, data of all symbols are loaded.

Parameters:
load_fromstr

Path to the gdx file

symbolsList[str], optional

Symbols whose data will be load from gdx, by default None

Parameters:
  • load_from (str) –

  • symbol_names (list[str] | None) –

Return type:

None

Examples

>>> from gamspy import Container, Set
>>> m = Container()
>>> i = Set(m, "i", records=["i1", "i2"])
>>> m.write("test.gdx")
>>> m2 = Container()
>>> m2.loadRecordsFromGdx("test.gdx")
>>> print(i.records.equals(m2["i"].records))
True
read(load_from, symbol_names=None, load_records=True, mode=None, encoding=None)[source]#

Reads specified symbols from the gdx file. If symbol_names are not provided, it reads all symbols from the gdx file.

Parameters:
load_fromstr
symbol_namesList[str], optional
load_recordsbool
modestr, optional
encodingstr, optional
Parameters:
  • load_from (str) –

  • symbol_names (list[str] | None) –

  • load_records (bool) –

  • mode (str | None) –

  • encoding (str | None) –

Return type:

None

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i", records=['i1', 'i2'])
>>> m.write("test.gdx")
>>> new_container = gp.Container()
>>> new_container.read("test.gdx")
>>> new_container.data.keys() == m.data.keys()
True
addUniverseAlias(name)[source]#

Add a Universe Alias to the GAMS container

Parameters:
namestr

The name of the Universe Alias symbol

Returns:
UniverseAlias

The Universe Alias object that was added

Parameters:

name (str) –

Return type:

UniverseAlias

Examples

>>> import gams.transfer as gt
>>> m = gt.Container()
>>> i = m.addSet("i", records=['i1','i2'])
>>> j = m.addSet("j", records=['j1','j2','j3'])
>>> ij = m.addUniverseAlias("ij")
>>> print(ij.getUELs())
['i1', 'i2', 'j1', 'j2', 'j3']
capitalizeUELs(symbols=None)[source]#

This function capitalizes the UELs of specific symbols. If the ‘symbols’ parameter is set to None (default), all symbols in the container will undergo this capitalization operation.

Parameters:
symbolsstr | List[str], optional

The symbol or list of symbols whose UELs you wish to capitalize. By default, it is set to None.

Returns:
Container

The updated container with UELs capitalized for some symbols.

Parameters:

symbols (str | List[str] | None) –

Return type:

Container

casefoldUELs(symbols=None)[source]#

This function performs case folding on the UELs of specific symbols, converting them to lowercase. If the ‘symbols’ parameter is set to None (default), all symbols in the container will undergo this case folding operation.

Parameters:
symbolsstr | List[str], optional

The symbol or list of symbols whose UELs you wish to convert to lowercase. By default, it is set to None.

Returns:
Container

The updated container with UELs converted to lowercase for some symbols.

Parameters:

symbols (str | List[str] | None) –

Return type:

Container

countDomainViolations(symbols=None)[source]#

Count domain violations for one or more symbols in the GAMS Container.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the symbols to count domain violations for, by default None

Returns:
Dict[str, int]

A dictionary where keys are symbol names with domain violations, and values are the corresponding counts of domain violations.

Raises:
TypeError

If ‘symbols’ is not of type list, str, or NoneType.

TypeError

If an element in ‘symbols’ is not of type str.

Parameters:

symbols (str | List[str] | None) –

Return type:

Dict[str, int]

countDuplicateRecords(symbols=None)[source]#

Count duplicate records for one or more symbols in the GAMS Container.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the symbols to count duplicate records for, by default None

Returns:
Dict[str, int]

A dictionary where keys are symbol names with duplicate records, and values are the count of duplicate records for each symbol.

Raises:
TypeError

If ‘symbols’ is not of type list, str, or NoneType.

TypeError

If an element in ‘symbols’ is not of type str.

Parameters:

symbols (str | List[str] | None) –

Return type:

Dict[str, int]

property data: Dict[str, AnyContainerSymbol]#

!! processed by numpydoc !!

describeAliases(symbols=None)#

Generate a DataFrame describing alias symbols in the GAMS Container.

This method generates a DataFrame providing detailed information about alias symbols in the GAMS Container.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the alias symbol names to describe. If None (default), Describe all alias symbols in the Container.

Returns:
DataFrame | None

A pandas DataFrame containing the description of alias symbols that match the specified symbol names. If no matching alias symbols are found, None is returned.

Raises:
ValueError
  • If the ‘symbols’ argument is not of type str, list, or NoneType.

  • If an alias symbol name specified in ‘symbols’ does not exist in the Container.

Parameters:

symbols (str | List[str] | None) –

Return type:

DataFrame | None

Notes

  • This method provides a tabular summary of alias symbols, including information such as alias relationships, dimension, sparsity, etc.

  • The ‘symbols’ parameter allows you to describe one or more alias symbols in the Container.

  • If ‘symbols’ is None (default), the method describes all alias symbols in the Container.

  • The method raises a ValueError if any alias symbol name specified in ‘symbols’ does not exist in the Container.

describeEquations(symbols=None)#

Generate a DataFrame describing equation symbols in the GAMS Container.

This method generates a DataFrame providing detailed information about equation symbols in the GAMS Container.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the equation symbol names to describe. If None (default), Describe all equation symbols in the Container.

Returns:
DataFrame | None

A pandas DataFrame containing the description of equation symbols that match the specified symbol names. If no matching equation symbols are found, None is returned.

Raises:
ValueError
  • If the ‘symbols’ argument is not of type str, iterable, or NoneType.
  • If an equation symbol name specified in ‘symbols’ does not exist in the Container.
Parameters:

symbols (str | List[str] | None) –

Return type:

DataFrame | None

Notes

  • This method provides a tabular summary of equation symbols, including information such as type, domain, dimension, sparsity, etc.

  • The ‘symbols’ parameter allows you to describe one or more equation symbols in the Container.

  • If ‘symbols’ is None (default), the method describes all equation symbols in the Container.

  • The method raises a ValueError if any equation symbol name specified in ‘symbols’ does not exist in the Container.

describeParameters(symbols=None)#

Generate a DataFrame describing parameter symbols in the GAMS Container.

This method generates a DataFrame providing detailed information about parameter symbols in the GAMS Container.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the parameter symbol names to describe. If None (default), Describe all parameter symbols in the Container.

Returns:
DataFrame | None

A pandas DataFrame containing the description of parameter symbols that match the specified symbol names. If no matching parameter symbols are found, None is returned.

Raises:
ValueError
  • If the ‘symbols’ argument is not of type str, iterable, or NoneType.

  • If a parameter symbol name specified in ‘symbols’ does not exist in the Container.

Parameters:

symbols (str | List[str] | None) –

Return type:

DataFrame | None

Notes

  • This method provides a tabular summary of parameter symbols, including information such as domain, dimension, sparsity, etc.

  • The ‘symbols’ parameter allows you to describe one or more parameter symbols in the Container.

  • If ‘symbols’ is None (default), the method describes all parameter symbols in the Container.

  • The method raises a ValueError if any parameter symbol name specified in ‘symbols’ does not exist in the Container.

describeSets(symbols=None)#

Generate a DataFrame describing sets within the GAMS Container.

This method creates a DataFrame that provides descriptive information about sets within the GAMS Container. You can specify the sets to describe using the ‘symbols’ parameter. If ‘symbols’ is None (default), all sets are described.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying which sets to describe.

Returns:
DataFrame | None

A Pandas DataFrame containing descriptive information about the specified sets. The DataFrame includes the following columns: - ‘name’: The name of the set. - ‘is_singleton’: Whether the set is a singleton set (True) or not (False). - ‘domain’: The domain of the set. - ‘domain_type’: The type of the set’s domain. - ‘dimension’: The dimension of the set. - ‘number_records’: The number of records (size) of the set. - ‘sparsity’: The sparsity of the set.

If ‘symbols’ includes alias sets, the DataFrame will also contain the following additional columns: - ‘is_alias’: Whether the set is an alias set (True) or not (False). - ‘alias_with’: The name of the set that the alias set is associated with (if it is an alias set).

The DataFrame is sorted by set name in ascending order.

Raises:
TypeError

If the ‘symbols’ argument is not of type str, list, or NoneType. If ‘symbols’ contains elements that are not of type str.

Parameters:

symbols (str | List[str] | None) –

Return type:

DataFrame | None

Notes

  • This method generates a descriptive summary of sets within the GAMS Container, including their properties and characteristics.

  • The ‘symbols’ parameter allows you to specify which sets to describe. If None (default), all sets are described.

  • The resulting DataFrame provides insights into each set’s attributes, such as dimensionality, size, and sparsity.

describeVariables(symbols=None)#

Generate a DataFrame describing variable symbols in the GAMS Container.

This method generates a DataFrame providing detailed information about variable symbols in the GAMS Container.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the variable symbol names to describe. If None (default), Describe all variable symbols in the Container.

Returns:
DataFrame | None

A pandas DataFrame containing the description of variable symbols that match the specified symbol names. If no matching variable symbols are found, None is returned.

Raises:
ValueError
  • If the ‘symbols’ argument is not of type str, iterable, or NoneType.
  • If a variable symbol name specified in ‘symbols’ does not exist in the Container.
Parameters:

symbols (str | List[str] | None) –

Return type:

DataFrame | None

Notes

  • This method provides a tabular summary of variable symbols, including information such as type, domain, dimension, sparsity, etc.

  • The ‘symbols’ parameter allows you to describe one or more variable symbols in the Container.

  • If ‘symbols’ is None (default), the method describes all variable symbols in the Container.

  • The method raises a ValueError if any variable symbol name specified in ‘symbols’ does not exist in the Container.

dropDomainViolations(symbols=None)[source]#

Drop domain violations for one or more symbols in the GAMS Container.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the symbols to drop domain violations for, by default None

Raises:
TypeError

If ‘symbols’ is not of type list, str, or NoneType.

TypeError

If an element in ‘symbols’ is not of type str.

Parameters:

symbols (str | List[str] | None) –

Return type:

None

dropDuplicateRecords(symbols=None, keep='first')[source]#

Remove duplicate records from the specified symbols in the GAMS Container.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the symbols from which to remove duplicate records, by default None

keepstr, optional

A string indicating which duplicate records to keep, by default “first”

Raises:
TypeError

If ‘symbols’ is not of type list, str, or NoneType.

TypeError

If an element in ‘symbols’ is not of type str.

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

  • keep (str) –

Return type:

None

getAliases(is_valid=None)#

Retrieve alias objects from the GAMS Container.

This method allows you to retrieve alias objects from the GAMS Container based on their names.

Parameters:
is_validbool, optional

An optional boolean flag used to filter the list of aliases. If None (default), all aliases in the Container are returned. If True, only valid aliases are included in the list. If False, only invalid aliases are included in the list.

Returns:
List[ABCAlias]

A list of alias objects that match the specified names.

Parameters:

is_valid (bool | None) –

Return type:

List[ABCAlias]

getDomainViolations(symbols=None)[source]#

Get domain violations for one or more symbols in the GAMS Container.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the symbols for which to retrieve domain violations, by default None

Returns:
list | None

A list of domain violations for the specified symbols, or None if there are no domain violations.

Raises:
TypeError

If ‘symbols’ is not of type list, str, or NoneType.

TypeError

If an element in ‘symbols’ is not of type str.

Parameters:

symbols (str | List[str] | None) –

Return type:

list | None

getParameters(is_valid=None)#

Retrieve parameter objects from the GAMS Container.

This method allows you to retrieve parameter objects from the GAMS Container based on their names.

Parameters:
is_validbool, optional

An optional boolean flag used to filter the list of parameters. If None (default), all parameters in the Container are returned. If True, only valid parameters are included in the list. If False, only invalid parameters are included in the list.

Returns:
List[ABCAlias]

A list of parameter objects that match the specified names.

Parameters:

is_valid (bool | None) –

Return type:

List[ABCParameter]

getSets(is_valid=None)#

Retrieve set objects from the GAMS Container.

This method allows you to retrieve set objects from the GAMS Container based on their names.

Parameters:
is_validbool, optional

An optional boolean flag used to filter the list of sets. If None (default), all sets in the Container are returned. If True, only valid sets are included in the list. If False, only invalid sets are included in the list.

Returns:
List[ABCSet]

A list of set objects that match the specified names.

Parameters:

is_valid (bool | None) –

Return type:

List[ABCSet]

getSymbols(symbols=None)#

Retrieve symbol objects from the GAMS Container.

This method allows you to retrieve symbol objects from the GAMS Container based on their names.

Parameters:
symbolsstr | Sequence[str], optional

An optional parameter specifying the symbol names to retrieve. If None (default), Retrieve all symbols stored in the Container.

Returns:
List[AnyContainerSymbol]

A list of symbol objects that match the specified symbol names.

Raises:
ValueError
  • If the ‘symbols’ argument is not of type str, iterable, or NoneType.

  • If a symbol name specified in ‘symbols’ does not exist in the Container.

Parameters:

symbols (str | Sequence[str] | None) –

Return type:

List[AnyContainerSymbol]

getUELs(symbols=None, ignore_unused=False, unique_only=False)[source]#

Retrieve the (UELs) associated with one or more symbols in the GAMS Container.

This method retrieves the (UELs) corresponding to the specified symbols in the GAMS Container.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the symbol names for which to retrieve UELs, by default None.

ignore_unusedbool, optional

A flag to whether or not include unused symbols, by default False

unique_onlybool, optional

A flag to whether or not return only unique UELs, by default False

Returns:
List[str]

A list of (UELs) associated with the specified symbols.

Raises:
TypeError

If ‘unique_only’ is not of type bool.

TypeError

If ‘symbols’ is not of type str, iterable, or NoneType.

TypeError

If ‘ignore_unused’ is not of type bool.

Exception

If an element in ‘symbols’ is not of type str.

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

  • ignore_unused (bool) –

  • unique_only (bool) –

Return type:

List[str]

getVariables(is_valid=None, types=None)#

Retrieve variable objects from the GAMS Container.

This method allows you to retrieve variable objects from the GAMS Container based on their names.

Parameters:
is_validbool, optional

An optional boolean flag used to filter the list of variables. If None (default), all variables in the Container are returned. If True, only valid variables are included in the list. If False, only invalid variables are included in the list.

typesstr | List[str], optional

An optional string or list of strings specifying the types of variables to include in the list. If None (default), all variable types are included in the list. If a string or list of strings is provided, only variables of the specified types are included in the list.

Returns:
List[ABCVariable]

A list of variable objects that match the specified names.

Parameters:
  • is_valid (bool | None) –

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

Return type:

List[ABCVariable]

hasDomainViolations(symbols=None)[source]#

Check if domain violations exist for one or more symbols in the GAMS Container.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the symbols to check for domain violations, by default None

Returns:
bool

True if domain violations exist for any of the specified symbols, False otherwise.

Raises:
TypeError

If ‘symbols’ is not of type list, str, or NoneType.

TypeError

If an element in ‘symbols’ is not of type str.

Parameters:

symbols (str | List[str] | None) –

Return type:

bool

hasDuplicateRecords(symbols=None)[source]#

Check if the GAMS Container has any duplicate records for one or more symbols.

Parameters:
symbolsstr | List[str], optional

An optional parameter specifying the symbols to check for duplicate records, by default None

Returns:
bool

True if duplicate records are found for any of the specified symbols; False otherwise.

Raises:
TypeError

If ‘symbols’ is not of type list, str, or NoneType.

TypeError

If an element in ‘symbols’ is not of type str.

Parameters:

symbols (str | List[str] | None) –

Return type:

bool

hasSymbols(symbols)[source]#

Checks if specific symbol names exist in a Container

Parameters:
symbolsList[str] | str

Symbols to check from the Container

Returns:
List[bool] | bool

Flag to indicate whether a symbol exists or not

Parameters:

symbols (List[str] | str) –

Return type:

List[bool] | bool

isValid(symbols=None, verbose=False, force=False)#

Check the validity of symbols in the GAMS Container.

This method checks the validity of symbols in the GAMS Container to ensure that they are consistent and correctly defined. It can check the validity of specific symbols or all symbols in the Container.

Parameters:
symbolsstr | List[str], optional

A list of symbol names or a single symbol name to be checked for validity. If None, all symbols in the Container will be checked.

verbosebool, by default False

A boolean flag indicating whether to raise an exception if an invalid symbol is found. If True, an exception is raised; if False, the method returns False for invalid symbols.

forcebool, by default False

A boolean flag indicating whether to force a recheck of the symbols’ validity.

Returns:
bool

Returns True if specified symbols (or all symbols in the Container) are valid. If any symbol is invalid and verbose is False, it returns False. If verbose is True, an exception is raised for the first invalid symbol encountered.

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

  • verbose (bool) –

  • force (bool) –

Return type:

bool

listAliases(is_valid=None)#

Get a list of alias names in the GAMS Container.

This method returns a list of alias names that are stored in the GAMS Container. You can optionally filter the list based on the validity of the aliases.

Parameters:
is_validbool, optional

An optional boolean flag used to filter the list of aliases. If None (default), all aliases in the Container are returned. - If True, only valid aliases are included in the list. - If False, only invalid aliases are included in the list.

Returns:
List[str]

A list of alias names in the Container, optionally filtered by validity.

Raises:
TypeError

If the ‘is_valid’ argument is not of type bool or NoneType.

Parameters:

is_valid (bool | None) –

Return type:

List[str]

Examples

>>> import gams.transfer as gt
>>> m = gt.Container()
>>> plants = gt.Set(m, name="plants", records=["seattle", "san-diego"])
>>> markets = gt.Set(m, name="markets", records=["new-york", "chicago", "topeka"])
>>> i = gt.Alias(m, name="i", alias_with=plants)
>>> j = gt.Alias(m, name="j", alias_with=markets)
>>> a = gt.Parameter(m, name="a", domain=[i], records=[["seattle", 350], ["san-diego", 600]])
>>> b = gt.Parameter(m, name="b", domain=[j], records=[["new-york", 325], ["chicago", 300], ["topeka", 275]])
>>> print(m.listAliases())
['i', 'j']
listEquations(is_valid=None, types=None)#

Get a list of equation names in the GAMS Container.

This method returns a list of equation names that are stored in the GAMS Container. You can optionally filter the list based on the validity and type of the equations.

Parameters:
is_validbool, optional

An optional boolean flag used to filter the list of equations based on their validity. - If True, only valid equations are included in the list. - If False, only invalid equations are included in the list. - If None (default), all equations are included in the list.

typesstr | List[str], optional

An optional string or list of strings specifying the types of equations to include in the list. - If None (default), all equation types are included in the list. - If a string or list of strings is provided, only equations of the specified types are included in the list.

Returns:
List[str]

A list of equation names in the Container, optionally filtered by validity and type.

Raises:
TypeError

If the ‘is_valid’ argument is not of type bool or NoneType, or if the ‘types’ argument is not of type str, list, or NoneType.

ValueError

If the ‘types’ argument contains unrecognized equation types.

Parameters:
  • is_valid (bool | None) –

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

Return type:

List[str]

Examples

>>> import gams.transfer as gt
>>> m = gt.Container()
>>> i = gt.Set(m, name="i", records=["seattle", "san-diego"])
>>> j = gt.Set(m, name="j", records=["new-york", "chicago", "topeka"])
>>> a = gt.Parameter(m, name="a", domain=[i], records=[["seattle", 350], ["san-diego", 600]])
>>> b = gt.Parameter(m, name="b", domain=[j], records=[["new-york", 325], ["chicago", 300], ["topeka", 275]])
>>> x = gt.Variable(m, name="x", domain=[i, j], type="positive")
>>> z = gt.Variable(m, name="z", type="free")
>>> cost = gt.Equation(m, name="cost", type="eq")
>>> supply = gt.Equation(m, name="supply", type="leq", domain=[i])
>>> demand = gt.Equation(m, name="demand", type="geq", domain=[j])
>>> print(m.listEquations())
['cost', 'supply', 'demand']
>>> print(m.listEquations(types="geq"))
['demand']
listParameters(is_valid=None)#

Get a list of parameter names in the GAMS Container.

This method returns a list of parameter names that are stored in the GAMS Container. You can optionally filter the list based on the validity of the parameters.

Parameters:
is_validbool, optional

An optional boolean flag used to filter the list of parameters. If None (default), all parameters in the Container are returned. - If True, only valid parameters are included in the list. - If False, only invalid parameters are included in the list.

Returns:
List[str]

A list of parameter names in the Container, optionally filtered by validity.

Raises:
TypeError

If the ‘is_valid’ argument is not of type bool or NoneType.

Parameters:

is_valid (bool | None) –

Return type:

List[str]

Examples

>>> import gams.transfer as gt
>>> m = gt.Container()
>>> i = gt.Set(m, name="i", records=["seattle", "san-diego"])
>>> j = gt.Set(m, name="j", records=["new-york", "chicago", "topeka"])
>>> a = gt.Parameter(m, name="a", domain=[i], records=[["seattle", 350], ["san-diego", 600]])
>>> b = gt.Parameter(m, name="b", domain=[j], records=[["new-york", 325], ["chicago", 300], ["topeka", 275]])
>>> print(m.listParameters())
['a', 'b']
listSets(is_valid=None)#

Get a list of set names in the GAMS Container.

This method returns a list of set names that are stored in the GAMS Container. You can optionally filter the list based on the validity of the sets.

Parameters:
is_validbool, optional

An optional boolean flag used to filter the list of sets. If None (default), all sets in the Container are returned. - If True, only valid sets are included in the list. - If False, only invalid sets are included in the list.

Returns:
List[str]

A list of set names in the Container, optionally filtered by validity.

Raises:
TypeError

If the ‘is_valid’ argument is not of type bool or NoneType.

Parameters:

is_valid (bool | None) –

Return type:

List[str]

Examples

>>> import gams.transfer as gt
>>> m = gt.Container()
>>> i = gt.Set(m, name="i", records=["seattle", "san-diego"])
>>> j = gt.Set(m, name="j", records=["new-york", "chicago", "topeka"])
>>> a = gt.Parameter(m, name="a", domain=[i], records=[["seattle", 350], ["san-diego", 600]])
>>> b = gt.Parameter(m, name="b", domain=[j], records=[["new-york", 325], ["chicago", 300], ["topeka", 275]])
>>> print(m.listSets())
['i', 'j']
listSymbols(is_valid=None)#

Get a list of symbol names in the GAMS Container.

This method returns a list of symbol names that are stored in the GAMS Container. You can optionally filter the list based on the validity of the symbols.

Parameters:
is_validbool, optional

An optional boolean flag used to filter the list of symbols. If None (default), all symbols in the Container are returned. - If True, only valid symbols are included in the list. - If False, only invalid symbols are included in the list.

Returns:
List[str]

A list of symbol names in the Container.

Raises:
TypeError

If the ‘is_valid’ argument is not of type bool or NoneType.

Parameters:

is_valid (bool | None) –

Return type:

List[str]

Examples

>>> import gams.transfer as gt
>>> m = gt.Container()
>>> i = gt.Set(m, name="i", records=["seattle", "san-diego"])
>>> j = gt.Set(m, name="j", records=["new-york", "chicago", "topeka"])
>>> a = gt.Parameter(m, name="a", domain=[i], records=[["seattle", 350], ["san-diego", 600]])
>>> b = gt.Parameter(m, name="b", domain=[j], records=[["new-york", 325], ["chicago", 300], ["topeka", 275]])
>>> print(m.listSymbols())
['i', 'j', 'a', 'b']
listVariables(is_valid=None, types=None)#

Get a list of variable names in the GAMS Container.

This method returns a list of variable names that are stored in the GAMS Container. You can optionally filter the list based on the validity and type of the variables.

Parameters:
is_validbool, optional

An optional boolean flag used to filter the list of variables based on their validity. - If True, only valid variables are included in the list. - If False, only invalid variables are included in the list. - If None (default), all variables are included in the list.

typesstr | List[str], optional

An optional string or list of strings specifying the types of variables to include in the list. - If None (default), all variable types are included in the list. - If a string or list of strings is provided, only variables of the specified types are included in the list.

Returns:
List[str]

A list of variable names in the Container, optionally filtered by validity and type.

Raises:
TypeError

If the ‘is_valid’ argument is not of type bool or NoneType, or if the ‘types’ argument is not of type str, list, or NoneType.

ValueError

If the ‘types’ argument contains unrecognized variable types.

Parameters:
  • is_valid (bool | None) –

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

Return type:

List[str]

Examples

>>> import gams.transfer as gt
>>> m = gt.Container()
>>> i = gt.Set(m, name="i", records=["seattle", "san-diego"])
>>> j = gt.Set(m, name="j", records=["new-york", "chicago", "topeka"])
>>> a = gt.Parameter(m, name="a", domain=[i], records=[["seattle", 350], ["san-diego", 600]])
>>> b = gt.Parameter(m, name="b", domain=[j], records=[["new-york", 325], ["chicago", 300], ["topeka", 275]])
>>> x = gt.Variable(m, name="x", domain=[i, j], type="positive")
>>> z = gt.Variable(m, name="z", type="free")
>>> print(m.listVariables())
['x', 'z']
>>> print(m.listVariables(types="free"))
['z']
ljustUELs(length, fill_character=None, symbols=None)[source]#

This function left-justifies the UELs of specific symbols within the container, 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.

symbolsstr | List[str], optional

The symbol or list of symbols whose UELs you want to left-justify. By default, it is set to None, meaning all symbols in the container will undergo this left-justification.

Returns:
Container

The updated container with UELs left-justified for some symbols.

Parameters:
  • length (int) –

  • fill_character (str | None) –

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

Return type:

Container

lowerUELs(symbols=None)[source]#

This function converts the UELs of specific symbols to lowercase. If the ‘symbols’ parameter is set to None (default), all symbols in the container will be processed.

Parameters:
symbolsstr | List[str], optional

The symbol or list of symbols whose UELs you want to convert to lowercase. By default, it is set to None.

Returns:
Container

The updated container with some UELs converted to lowercase.

Parameters:

symbols (str | List[str] | None) –

Return type:

Container

lstripUELs(symbols=None)[source]#

This function removes leading whitespaces from the UELs of specific symbols. If the ‘symbols’ parameter is set to None (default), all symbols in the container will undergo this operation.

Parameters:
symbolsstr | List[str], optional

The symbol or list of symbols whose UELs you wish to process. By default, it is set to None.

Returns:
Container

The updated container with leading whitespaces removed from the UELs of some symbols.

Parameters:

symbols (str | List[str] | None) –

Return type:

Container

property modified: bool | None#

!! processed by numpydoc !!

removeSymbols(symbols=None)[source]#

Remove symbols from the Container. If symbols=None, it will remove all symbols.

Parameters:
symbolsList[str] | str, optional

Symbols to remove from the Container, also sets the symbols container to None. If symbols=None, will remove all symbols.

Parameters:

symbols (str | List[str] | None) –

Return type:

None

removeUELs(uels=None, symbols=None)[source]#

Remove specific unique element labels (UELs) from one or more symbols in the GAMS Container.

Parameters:
uelsstr | List[str], optional

An optional parameter specifying the unique element labels (UELs) to be removed from the symbols, by default None

symbolsList[str], optional

An optional parameter specifying the symbols from which to remove the specified UELs, by default None

Raises:
TypeError

If ‘uels’ is not of type list, str, or NoneType.

TypeError

If an element in ‘uels’ is not of type str.

TypeError

If ‘symbols’ is not of type list or NoneType.

TypeError

If an element in ‘symbols’ is not of type str.

Exception

If the Container is currently invalid, as it must be valid to access UELs (categories).

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

  • symbols (List[str] | None) –

Return type:

None

renameSymbol(old_name, new_name)[source]#

Rename a symbol in the Container

Parameters:
old_namestr

Old name of the symbol

new_namestr

New name of the symbol

Parameters:
  • old_name (str) –

  • new_name (str) –

Return type:

None

renameUELs(uels, symbols=None, allow_merge=False)[source]#

Rename unique element labels (UELs) associated with symbols in the GAMS Container.

Parameters:
uelsDict[str, str]

A dictionary mapping old UELs to their new names. The keys are the old UELs that you want to rename, and the values are the new names for those UELs

symbolsList[str]], optional

An optional parameter specifying the symbol names for which you want to rename UELs, by default None

allow_mergebool, optional

A flag that allows merging UELs with existing UELs, by default False

Raises:
Exception

If the GAMS Container is currently invalid (not valid) because UELs (categories) cannot be accessed.

TypeError

If ‘uels’ is not of type dict.

TypeError

If ‘symbols’ is not of type list or NoneType.

TypeError

If an element in ‘symbols’ is not of type str.

Parameters:
  • uels (Dict[str, str]) –

  • symbols (List[str] | None) –

  • allow_merge (bool) –

Return type:

None

reorderSymbols()[source]#

Reorder symbols in order to avoid domain violations

Return type:

None

rjustUELs(length, fill_character=None, symbols=None)[source]#

This function right-justifies the UELs of specific symbols within the container, padding them with a specified fill character to reach the desired length.

Parameters:
lengthint

The target length to which UELs will be right-justified.

fill_characterstr, optional

The character used for padding the UELs to the specified length. If not provided, it defaults to a whitespace.

symbolsstr | List[str], optional

The symbol or list of symbols whose UELs you want to right-justify. By default, it is set to None, meaning all symbols in the container will undergo this right-justification.

Returns:
Container

The updated container with UELs right-justified for some symbols.

Parameters:
  • length (int) –

  • fill_character (str | None) –

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

Return type:

Container

rstripUELs(symbols=None)[source]#

This function removes trailing whitespaces from the UELs of specific symbols. If the ‘symbols’ parameter is set to None (default), all symbols in the container will undergo this operation.

Parameters:
symbolsstr | List[str], optional

The symbol or list of symbols whose UELs you wish to process. By default, it is set to None.

Returns:
Container

The updated container with trailing whitespaces removed from the UELs of some symbols.

Parameters:

symbols (str | List[str] | None) –

Return type:

Container

stripUELs(symbols=None)[source]#

This function removes leading and trailing whitespaces from the UELs of specific symbols. If the ‘symbols’ parameter is set to None (default), all symbols in the container will undergo this operation.

Parameters:
symbolsstr | List[str], optional

The symbol or list of symbols whose UELs you wish to process. By default, it is set to None.

Returns:
Container

The updated container with leading and trailing whitespaces removed from the UELs of some symbols.

Parameters:

symbols (str | List[str] | None) –

Return type:

Container

property summary: dict#

This property returns a summary of the container.

Returns:
dict

A summary including the container’s system directory and its number of symbols.

property system_directory#

!! processed by numpydoc !!

titleUELs(symbols=None)[source]#

This function capitalizes the UELs of specific symbols in title case. If the ‘symbols’ parameter is set to None (default), all symbols in the container will undergo this capitalization operation.

Parameters:
symbolsstr | List[str], optional

The symbol or list of symbols whose UELs you wish to capitalize in title case. By default, it is set to None.

Returns:
Container

The updated container with UELs capitalized in title case for some symbols.

Parameters:

symbols (str | List[str] | None) –

Return type:

Container

upperUELs(symbols=None)[source]#

This function converts the UELs of specific symbols to uppercase. If the ‘symbols’ parameter is set to None (default), all symbols in the container will be processed.

Parameters:
symbolsstr | List[str], optional

The symbol or list of symbols whose UELs you want to convert to uppercase. By default, it is set to None.

Returns:
Container

The updated container with some UELs converted to uppercase.

Parameters:

symbols (str | List[str] | None) –

Return type:

Container

write(write_to, symbol_names=None, compress=False, mode=None, eps_to_zero=True)[source]#

Writes specified symbols to the gdx file. If symbol_names are not provided, it writes all symbols to the gdx file.

Parameters:
write_tostr
symbol_namesList[str], optional
compressbool
modestr, optional
eps_to_zerobool
Parameters:
  • write_to (str) –

  • symbol_names (list[str] | None) –

  • compress (bool) –

  • mode (str | None) –

  • eps_to_zero (bool) –

Return type:

None

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i", records=['i1', 'i2'])
>>> m.write("test.gdx")