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

Inheritance diagram for Container:

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 GAMSTransfer 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, ConstContainer

Public Member Functions
function	Container (in varargin)
	Constructs a GAMSTransfer 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	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	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.

Public Member Functions inherited from BaseContainer
function	BaseContainer (in gams_dir, in indexed, in features)
	Constructs a GAMSTransfer BaseContainer.

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	isValid (in obj, in varargin)
	Checks correctness of all symbols.

Public Attributes
Property	modified
	Flag to indicate modification.

Additional Inherited Members
Protected Attributes inherited from BaseContainer
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 GAMSTransfer Container.

Optional Arguments:

source (string or ConstContainer): Path to GDX file or a ConstContainer 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, ConstContainer

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

◆ 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

◆ equals()

function equals	(	in	obj,
		in	container
	)

Checks equivalence with other container.

Required Arguments:

container (any): Other Container

◆ 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

◆ 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(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

◆ 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

◆ read()

function read	(	in	obj,
		in	varargin
	)

Reads symbols from GDX file.

See Reading From GDX for more information.

Required Arguments:

source (string, Container or ConstContainer): Path to GDX file, a Container object or ConstContainer 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

◆ 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

◆ 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

Additional Inherited Members

Constructor & Destructor Documentation

◆ Container()

Member Function Documentation

◆ addAlias()

◆ addEquation()

◆ addParameter()

◆ addSet()

◆ addVariable()

◆ equals()

◆ getDomainViolations()

◆ getSymbols()

◆ getUELs()

◆ isValid()

◆ read()

◆ removeUELs()

◆ renameSymbol()

◆ renameUELs()

◆ resolveDomainViolations()

◆ write()

Member Data Documentation

◆ modified