GAMS Transfer Container stores (multiple) symbols. More...

Inherits handle.

GAMS Transfer Container stores (multiple) symbols.

A GAMS GDX file is a collection of GAMS symbols (e.g. variables or parameters), each holding multiple symbol records. In GAMS Transfer the Container is the main object that holds different symbols and allows to read and write those to GDX. See Container for more information.

Indexed Mode:

There are two different modes GAMS Transfer can be used in: indexed or default.

In default mode the main characteristic of a symbol is its domain that defines the symbol dimension and its dependencies. A size of symbol is here given by the number of records of the domain sets of each dimension. In default mode all GAMS symbol types can be used.
In indexed mode, there are no domain sets, but sizes (the shape of a symbol) can be set explicitly. Furthermore, there are no UELs and only GAMS Parameters are allowed to be used in indexed mode.

The mode is defined when creating a container and can't be changed thereafter. See Indexed GDX for more information.

Example:

c = Container();
c = Container('path/to/file.gdx');
c = Container('indexed', true, 'gams_dir', 'C:\GAMS');

See also: Set, Alias, Parameter, Variable, Equation

Public Member Functions
function	Container (in varargin)
	Constructs a GAMS Transfer Container.

function	equals (in obj, in container)
	Checks equivalence with other container.

function	read (in obj, in varargin)
	Reads symbols from GDX file.

function	write (in obj, in varargin)
	Writes symbols with symbol records to GDX file.

function	getSymbols (in obj, in names)
	Get symbol objects by names.

function	getSets (in obj, in varargin)
	Gets all Set objects.

function	getParameters (in obj, in varargin)
	Gets all Parameter objects.

function	getVariables (in obj, in varargin)
	Gets all Variable objects.

function	getEquations (in obj, in varargin)
	Gets all Equation objects.

function	getAliases (in obj, in varargin)
	Gets all Alias objects.

function	hasSymbols (in obj, in names)
	Checks if symbol exists in container (case insensitive)

function	getSymbolNames (in obj, in names)
	Get symbol names by names (case insensitive)

function	listSymbols (in obj, in varargin)
	Lists all symbols in container.

function	listSets (in obj, in varargin)
	Lists all sets in container.

function	listParameters (in obj, in varargin)
	Lists all parameters in container.

function	listVariables (in obj, in varargin)
	Lists all variables in container.

function	listEquations (in obj, in varargin)
	Lists all equations in container.

function	listAliases (in obj, in varargin)
	Lists all aliases in container.

function	describeSets (in obj, in varargin)
	Returns an overview over all sets in container.

function	describeParameters (in obj, in varargin)
	Returns an overview over all parameters in container.

function	describeVariables (in obj, in varargin)
	Returns an overview over all variables in container.

function	describeEquations (in obj, in varargin)
	Returns an overview over all equations in container.

function	describeAliases (in obj, in varargin)
	Returns an overview over all aliases in container.

function	addSet (in obj, in name, in varargin)
	Adds a set to the container.

function	addParameter (in obj, in name, in varargin)
	Adds a parameter to the container.

function	addVariable (in obj, in name, in varargin)
	Adds a variable to the container.

function	addEquation (in obj, in name, in etype, in varargin)
	Adds an equation to the container.

function	addAlias (in obj, in name, in alias_with)
	Adds an alias to the container.

function	addUniverseAlias (in obj, in name)
	Adds a universe alias to the container.

function	renameSymbol (in obj, in oldname, in newname)
	Rename a symbol.

function	removeSymbols (in obj, in names)
	Removes a symbol from container.

function	reorderSymbols (in obj)
	Reestablishes a valid GDX symbol order.

function	getDomainViolations (in obj, in varargin)
	Get domain violations for all symbols.

function	resolveDomainViolations (in obj, in varargin)
	Extends domain sets in order to remove domain violations.

function	isValid (in obj, in varargin)
	Checks correctness of all symbols.

function	getUELs (in obj, in varargin)
	Get UELs from all symbols.

function	removeUELs (in obj, in varargin)
	Removes UELs from all symbols.

function	renameUELs (in obj, in uels, in varargin)
	Renames UELs in all symbol.

function	lowerUELs (in obj, in varargin)
	Converts UELs to lower case.

function	upperUELs (in obj, in varargin)
	Converts UELs to upper case.

Public Attributes
Property	modified
	Flag to indicate modification.

Protected Attributes
Property	gams_dir
	GAMS system directory.

Property	indexed
	Flag for indexed mode.

Property	data
	GAMS (GDX) symbols.

Constructor & Destructor Documentation

◆ Container()

function Container ( in varargin )

Constructs a GAMS Transfer Container.

Optional Arguments:

source (string or Container): Path to GDX file or a Container object to be read

Parameter Arguments:

gams_dir (string): Path to GAMS system directory. Default is determined from PATH environment variable
indexed (logical): Specifies if container is used in indexed of default mode, see above.

Example:

c = Container();
c = Container('path/to/file.gdx');
c = Container('indexed', true, 'gams_dir', 'C:\GAMS');

See also: Set, Alias, Parameter, Variable, Equation, Container

Member Function Documentation

◆ addAlias()

function addAlias	(	in	obj,
		in	name,
		in	alias_with
	)

Adds an alias to the container.

Arguments are identical to the Alias constructor. Alternatively, use the constructor directly. In contrast to the constructor, this method may overwrite an alias.

Example:

c = Container();
s = c.addSet('s');
a = c.addAlias('a', s);

See also: Alias, Set

◆ addEquation()

function addEquation	(	in	obj,
		in	name,
		in	etype,
		in	varargin
	)

Adds an equation to the container.

Arguments are identical to the Equation constructor. Alternatively, use the constructor directly. In contrast to the constructor, this method may overwrite an equation if its definition (type, domain, domain_forwarding) doesn't differ.

Example:

c = Container();
e2 = c.addEquation('e2', 'l', {'*', '*'});
e3 = c.addEquation('e3', EquationType.EQ, '*', 'description', 'equ e3');

See also: Equation, EquationType

◆ addParameter()

function addParameter	(	in	obj,
		in	name,
		in	varargin
	)

Adds a parameter to the container.

Arguments are identical to the Parameter constructor. Alternatively, use the constructor directly. In contrast to the constructor, this method may overwrite a parameter if its definition (domain, domain_forwarding) doesn't differ.

Example:

c = Container();
p1 = c.addParameter('p1');
p2 = c.addParameter('p2', {'*', '*'});
p3 = c.addParameter('p3', '*', 'description', 'par p3');

See also: Parameter

◆ addSet()

function addSet	(	in	obj,
		in	name,
		in	varargin
	)

Adds a set to the container.

Arguments are identical to the Set constructor. Alternatively, use the constructor directly. In contrast to the constructor, this method may overwrite a set if its definition (is_singleton, domain, domain_forwarding) doesn't differ.

Example:

c = Container();
s1 = c.addSet('s1');
s2 = c.addSet('s2', {s1, '*', '*'});
s3 = c.addSet('s3', '*', 'records', {'e1', 'e2', 'e3'}, 'description', 'set s3');

See also: Set

◆ addUniverseAlias()

function addUniverseAlias	(	in	obj,
		in	name
	)

Adds a universe alias to the container.

Arguments are identical to the UniverseAlias constructor. Alternatively, use the constructor directly. In contrast to the constructor, this method may overwrite an alias.

Example:

c = Container();

u = c.addUniverseAlias('u');

See also: UniverseAlias, Alias, Set

◆ addVariable()

function addVariable	(	in	obj,
		in	name,
		in	varargin
	)

Adds a variable to the container.

Arguments are identical to the Variable constructor. Alternatively, use the constructor directly. In contrast to the constructor, this method may overwrite a variable if its definition (type, domain, domain_forwarding) doesn't differ.

Example:

c = Container();
v1 = c.addVariable('v1');
v2 = c.addVariable('v2', 'binary', {'*', '*'});
v3 = c.addVariable('v3', VariableType.BINARY, '*', 'description', 'var v3');

See also: Variable, VariableType

◆ describeAliases()

function describeAliases	(	in	obj,
		in	varargin
	)

Returns an overview over all aliases in container.

See Symbol Overview for more information.

Optional Arguments:

symbols (cellstr): List of symbols to include. Default: listAliases().

The overview is in form of a table listing for each symbol its main characteristics and some statistics.

◆ describeEquations()

function describeEquations	(	in	obj,
		in	varargin
	)

Returns an overview over all equations in container.

See Symbol Overview for more information.

Optional Arguments:

symbols (cellstr): List of symbols to include. Default: listEquations().

The overview is in form of a table listing for each symbol its main characteristics and some statistics.

◆ describeParameters()

function describeParameters	(	in	obj,
		in	varargin
	)

Returns an overview over all parameters in container.

See Symbol Overview for more information.

Optional Arguments:

symbols (cellstr): List of symbols to include. Default: listParameters().

The overview is in form of a table listing for each symbol its main characteristics and some statistics.

◆ describeSets()

function describeSets	(	in	obj,
		in	varargin
	)

Returns an overview over all sets in container.

See Symbol Overview for more information.

Note: This method includes set aliases.

Optional Arguments:

symbols (cellstr): List of symbols to include. Default: listSets().

The overview is in form of a table listing for each symbol its main characteristics and some statistics.

◆ describeVariables()

function describeVariables	(	in	obj,
		in	varargin
	)

Returns an overview over all variables in container.

See Symbol Overview for more information.

Optional Arguments:

symbols (cellstr): List of symbols to include. Default: listVariables().

The overview is in form of a table listing for each symbol its main characteristics and some statistics.

◆ equals()

function equals	(	in	obj,
		in	container
	)

Checks equivalence with other container.

Required Arguments:

container (any): Other Container

◆ getAliases()

function getAliases	(	in	obj,
		in	varargin
	)

Gets all Alias objects.

Parameter Arguments:

is_valid (logical or any): Enable valid filter if argument is of type logical. If true, only include symbols that are valid and, if false, only invalid symbols. Default: not logical.

See also: Container.listAliases, Container.getSymbols

◆ getDomainViolations()

function getDomainViolations	(	in	obj,
		in	varargin
	)

Get domain violations for all symbols.

Domain violations occur when a symbol uses other Sets as domain(s) – and is thus of domain type regular, see Symbol Domain – and uses a domain entry in its records that is not present in the corresponding referenced domain set. Such a domain violation will lead to a GDX error when writing the data!

See Domain Violations for more information.

dom_violations = getDomainViolations returns a list of domain violations.

Parameter Arguments:

symbols (cell): List of symbols to be considered. All if empty. Case doesn't matter. Default is {}.

See also: Container.resolveDomainViolations, Symbol.getDomainViolations, DomainViolation

◆ getEquations()

function getEquations	(	in	obj,
		in	varargin
	)

Gets all Equation objects.

Parameter Arguments:

is_valid (logical or any): Enable valid filter if argument is of type logical. If true, only include symbols that are valid and, if false, only invalid symbols. Default: not logical.
types (any): Enable filter for equation type, e.g. type = {"g", "l"}. Default: not applied.

See also: Container.listEquations, Container.getSymbols

◆ getParameters()

function getParameters	(	in	obj,
		in	varargin
	)

Gets all Parameter objects.

Parameter Arguments:

is_valid (logical or any): Enable valid filter if argument is of type logical. If true, only include symbols that are valid and, if false, only invalid symbols. Default: not logical.

See also: Container.listParameters, Container.getSymbols

◆ getSets()

function getSets	(	in	obj,
		in	varargin
	)

Gets all Set objects.

Parameter Arguments:

is_valid (logical or any): Enable valid filter if argument is of type logical. If true, only include symbols that are valid and, if false, only invalid symbols. Default: not logical.

See also: Container.listSets, Container.getSymbols

◆ getSymbolNames()

function getSymbolNames	(	in	obj,
		in	names
	)

Get symbol names by names (case insensitive)

s = c.getSymbolNames(a) returns GAMS symbol names named a where a may have different casing.
s = c.getSymbolNames(b) returns a list GAMS symbol names where names equal b case insensitively.

Example:

v1 = c.getSymbolNames('v1'); % equals c.getSymbolNames('V1');

matlab::gams::transfer::Container::equals

function equals(in obj, in container)

Checks equivalence with other container.

◆ getSymbols()

function getSymbols	(	in	obj,
		in	names
	)

Get symbol objects by names.

Note: The letter case of the name does not matter.

s = c.getSymbols() returns the handles to all GAMS symbols.
s = c.getSymbols(a) returns the handle to GAMS symbol named a.
s = c.getSymbols(b) returns a list of handles to the GAMS symbols with names equal to any element in cell b.

Example:

v1 = c.getSymbols('v1');

vars = c.getSymbols(c.listVariables());

◆ getUELs()

function getUELs	(	in	obj,
		in	varargin
	)

Get UELs from all symbols.

u = getUELs() returns the UELs across all symbols.
‘u = getUELs(_, 'symbols’, s)returns the UELs across symbolss. -u = getUELs(_, "ignore_unused", true)` returns only those UELs that are actually used in the records.

See Unique Elements (UELs) for more information.

Note: This can only be used if the container is valid. UELs are not available when using the indexed mode, see Indexed GDX.

See also: Container.indexed, Container.isValid

◆ getVariables()

function getVariables	(	in	obj,
		in	varargin
	)

Gets all Variable objects.

Parameter Arguments:

is_valid (logical or any): Enable valid filter if argument is of type logical. If true, only include symbols that are valid and, if false, only invalid symbols. Default: not logical.
types (any): Enable filter for variable type, e.g. type = {"binary", "integer"}. Default: not applied.

See also: Container.listVariables, Container.getSymbols

◆ hasSymbols()

function hasSymbols	(	in	obj,
		in	names
	)

Checks if symbol exists in container (case insensitive)

s = c.hasSymbols(a) returns true if GAMS symbol named a (case does not matter) exists. false otherwise.
s = c.hasSymbols(b) returns a list of bools where an entry s{i} is true if GAMS symbol named b{i} (case does not matter) exists. false otherwise.

◆ isValid()

function isValid	(	in	obj,
		in	varargin
	)

Checks correctness of all symbols.

See Validate Symbol Records for more information.

Optional Arguments:

verbose (logical): If true, the reason for an invalid symbol is printed
force (logical): If true, forces reevaluation of validity (resets cache)

Parameter Arguments:

symbols (cell): List of symbols to be considered. All if empty. Case doesn't matter. Default is {}.

See also: Symbol.isValid

◆ listAliases()

function listAliases	(	in	obj,
		in	varargin
	)

Lists all aliases in container.

Parameter Arguments:

is_valid (logical or any): Enable valid filter if argument is of type logical. If true, only include symbols that are valid and, if false, only invalid symbols. Default: not logical.

See also: Container.listSymbols, Container.listSets, Container.listParameters, Container.listVariables, Container.listEquations

◆ listEquations()

function listEquations	(	in	obj,
		in	varargin
	)

Lists all equations in container.

Parameter Arguments:

is_valid (logical or any): Enable valid filter if argument is of type logical. If true, only include symbols that are valid and, if false, only invalid symbols. Default: not logical.
types (any): Enable filter for equation type, e.g. type = {"g", "l"}. Default: not applied.

See also: Container.listSymbols, Container.listSets, Container.listParameters, Container.listVariables, Container.listAliases

◆ listParameters()

function listParameters	(	in	obj,
		in	varargin
	)

Lists all parameters in container.

Parameter Arguments:

is_valid (logical or any): Enable valid filter if argument is of type logical. If true, only include symbols that are valid and, if false, only invalid symbols. Default: not logical.

See also: Container.listSymbols, Container.listSets, Container.listVariables, Container.listEquations, Container.listAliases

◆ listSets()

function listSets	(	in	obj,
		in	varargin
	)

Lists all sets in container.

Parameter Arguments:

is_valid (logical or any): Enable valid filter if argument is of type logical. If true, only include symbols that are valid and, if false, only invalid symbols. Default: not logical.

See also: Container.listSymbols, Container.listParameters, Container.listVariables, Container.listEquations, Container.listAliases

◆ listSymbols()

function listSymbols	(	in	obj,
		in	varargin
	)

Lists all symbols in container.

Parameter Arguments:

is_valid (logical or any): Enable valid filter if argument is of type logical. If true, only include symbols that are valid and, if false, only invalid symbols. Default: not logical.

See also: Container.listSets, Container.listParameters, Container.listVariables, Container.listEquations, Container.listAliases

◆ listVariables()

function listVariables	(	in	obj,
		in	varargin
	)

Lists all variables in container.

Parameter Arguments:

is_valid (logical or any): Enable valid filter if argument is of type logical. If true, only include symbols that are valid and, if false, only invalid symbols. Default: not logical.
types (any): Enable filter for variable type, e.g. type = {"binary", "integer"}. Default: not applied.

See also: Container.listSymbols, Container.listSets, Container.listParameters, Container.listEquations, Container.listAliases

◆ lowerUELs()

function lowerUELs	(	in	obj,
		in	varargin
	)

Converts UELs to lower case.

lowerUELs() converts all UELs to lower case.
‘lowerUELs('symbols’, s)converts all UELs to lower case for symbolss`.

See Unique Elements (UELs) for more information.

Note: This can only be used if the symbol is valid. UELs are not available when using the indexed mode, see Indexed GDX.

See also: Container.indexed, Symbol.isValid

◆ read()

function read	(	in	obj,
		in	varargin
	)

Reads symbols from GDX file.

See Reading From GDX for more information.

Required Arguments:

source (string or Container): Path to GDX file or a Container object to be read

Parameter Arguments:

symbols (cell): List of symbols to be read. All if empty. Case doesn't matter. Default is {}.
format (string): Records format symbols should be stored in. Default is table.
records (logical): Enables reading of records. Default is true.
values (cell): Subset of {"level", "marginal", "lower", "upper", "scale"} that defines what value fields should be read. Default is all.

Example:

c = Container();
c.read('path/to/file.gdx');
c.read('path/to/file.gdx', 'format', 'dense_matrix');
c.read('path/to/file.gdx', 'symbols', {'x', 'z'}, 'format', 'struct', 'values', {'level'});

See also: RecordsFormat

◆ removeSymbols()

function removeSymbols	(	in	obj,
		in	names
	)

Removes a symbol from container.

Note: The letter case of the name does not matter.

c.removeSymbols() removes all symbols.
c.removeSymbols(a) removes GAMS symbol named a.
c.removeSymbols(b) removes a list of GAMS symbols with names equal elements in cell b.

Example:

c.removeSymbols('v1');

c.removeSymbols(c.listVariables());

◆ removeUELs()

function removeUELs	(	in	obj,
		in	varargin
	)

Removes UELs from all symbols.

removeUELs() removes all unused UELs for all symbols.
removeUELs(u) removes the UELs u for all symbols.
‘removeUELs(_, 'symbols’, s)removes UELs for symbolss`.

See Unique Elements (UELs) for more information.

Note: This can only be used if the container is valid. UELs are not available when using the indexed mode, see Indexed GDX.

See also: Container.indexed, Container.isValid

◆ renameSymbol()

function renameSymbol	(	in	obj,
		in	oldname,
		in	newname
	)

Rename a symbol.

renameSymbol(oldname, newname) renames the symbol with name oldname to newname. The symbol order in data will not change.

Example:

c.renameSymbol('x', 'xx');

◆ renameUELs()

function renameUELs	(	in	obj,
		in	uels,
		in	varargin
	)

Renames UELs in all symbol.

renameUELs(u) renames the UELs u for all symbols. u can be a struct (field names = old UELs, field values = new UELs), containers.Map (keys = old UELs, values = new UELs) or cellstr (full list of UELs, must have as many entries as current UELs). The codes for renamed UELs do not change.
‘renameUELs(_, 'symbols’, s)renames UELs for symbolss. -renameUELs(_, 'allow_merge', true)` enables support of merging one UEL into another one (renaming a UEL to an already existing one).

See Unique Elements (UELs) for more information.

Note: This can only be used if the symbol is valid. UELs are not available when using the indexed mode, see Indexed GDX.

See also: Container.indexed, Symbol.isValid

◆ resolveDomainViolations()

function resolveDomainViolations	(	in	obj,
		in	varargin
	)

Extends domain sets in order to remove domain violations.

Domain violations occur when a symbol uses other Sets as domain(s) – and is thus of domain type regular, see Symbol Domain – and uses a domain entry in its records that is not present in the corresponding referenced domain set. Such a domain violation will lead to a GDX error when writing the data!

See Domain Violations for more information.

resolveDomainViolations() extends the domain sets with the violated domain entries. Hence, the domain violations disappear.

Parameter Arguments:

symbols (cell): List of symbols to be considered. All if empty. Case doesn't matter. Default is {}.

See also: Container.getDomainViolations, Symbol.resolveDomainViolations, DomainViolation

◆ upperUELs()

function upperUELs	(	in	obj,
		in	varargin
	)

Converts UELs to upper case.

upperUELs() converts all UELs to upper case.
‘upperUELs('symbols’, s)converts all UELs to upper case for symbolss`.

See Unique Elements (UELs) for more information.

Note: This can only be used if the symbol is valid. UELs are not available when using the indexed mode, see Indexed GDX.

See also: Container.indexed, Symbol.isValid

◆ write()

function write	(	in	obj,
		in	varargin
	)

Writes symbols with symbol records to GDX file.

See Writing To GDX for more information.

Required Arguments:

filename (string): Path to GDX file to write to.

Parameter Arguments:

symbols (cell): List of symbols to be written. All if empty. Case doesn't matter. Default is {}.
compress (logical): Flag to compress GDX file (true) or not (false). Default is false.
sorted (logical): Flag to define records as sorted (true) or not (false). Default is false.
uel_priority (cellstr): UELs to be registered first before any symbol UELs. Default: {}.

Example:

c.write('path/to/file.gdx');

c.write('path/to/file.gdx', 'compress', true, 'sorted', true);

See also: Container.getDomainViolations

Member Data Documentation

◆ modified

Property modified

Flag to indicate modification.

If the container or any symbol within has been modified since last reset of flag (false), this flag will be true. Resetting will also reset symbol flag.

Public Member Functions

Public Attributes

Protected Attributes

Constructor & Destructor Documentation

◆ Container()

Member Function Documentation

◆ addAlias()

◆ addEquation()

◆ addParameter()

◆ addSet()

◆ addUniverseAlias()

◆ addVariable()

◆ describeAliases()

◆ describeEquations()

◆ describeParameters()

◆ describeSets()

◆ describeVariables()

◆ equals()

◆ getAliases()

◆ getDomainViolations()

◆ getEquations()

◆ getParameters()

◆ getSets()

◆ getSymbolNames()

◆ getSymbols()

◆ getUELs()

◆ getVariables()

◆ hasSymbols()

◆ isValid()

◆ listAliases()

◆ listEquations()

◆ listParameters()

◆ listSets()

◆ listSymbols()

◆ listVariables()

◆ lowerUELs()

◆ read()

◆ removeSymbols()

◆ removeUELs()

◆ renameSymbol()

◆ renameUELs()

◆ resolveDomainViolations()

◆ upperUELs()

◆ write()

Member Data Documentation

◆ modified