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

Inheritance diagram for Container:
BaseContainer

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. More...
 
function equals (in obj, in container)
 Checks equivalence with other container. More...
 
function read (in obj, in varargin)
 Reads symbols from GDX file. More...
 
function write (in obj, in varargin)
 Writes symbols with symbol records to GDX file. More...
 
function getSymbols (in obj, in names)
 Get symbol objects by names. More...
 
function addSet (in obj, in name, in varargin)
 Adds a set to the container. More...
 
function addParameter (in obj, in name, in varargin)
 Adds a parameter to the container. More...
 
function addVariable (in obj, in name, in varargin)
 Adds a variable to the container. More...
 
function addEquation (in obj, in name, in etype, in varargin)
 Adds an equation to the container. More...
 
function addAlias (in obj, in name, in alias_with)
 Adds an alias to the container. More...
 
function renameSymbol (in obj, in oldname, in newname)
 Rename a symbol. More...
 
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)
 Get domain violations for all symbols. More...
 
function resolveDomainViolations (in obj)
 Extends domain sets in order to remove domain violations. More...
 
function getUniverseSet (in obj)
 Generate universe set (UEL order in GDX) More...
 
function isValid (in obj, in varargin)
 Checks correctness of all symbols. More...
 
function getUELs (in obj, in varargin)
 Get UELs from all symbols. More...
 
function removeUELs (in obj, in varargin)
 Removes UELs from all symbols. More...
 
function renameUELs (in obj, in uels, in varargin)
 Renames UELs in all symbol. More...
 
- 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) More...
 
function getSymbolNames (in obj, in names)
 Get symbol names by names (case insensitive) More...
 
function listSymbols (in obj, in varargin)
 Lists all symbols in container. More...
 
function listSets (in obj, in varargin)
 Lists all sets in container. More...
 
function listParameters (in obj, in varargin)
 Lists all parameters in container. More...
 
function listVariables (in obj, in varargin)
 Lists all variables in container. More...
 
function listEquations (in obj, in varargin)
 Lists all equations in container. More...
 
function listAliases (in obj, in varargin)
 Lists all aliases in container. More...
 
function describeSets (in obj, in varargin)
 Returns an overview over all sets in container. More...
 
function describeParameters (in obj, in varargin)
 Returns an overview over all parameters in container. More...
 
function describeVariables (in obj, in varargin)
 Returns an overview over all variables in container. More...
 
function describeEquations (in obj, in varargin)
 Returns an overview over all equations in container. More...
 
function describeAliases (in obj, in varargin)
 Returns an overview over all aliases in container. More...
 
function isValid (in obj, in varargin)
 Checks correctness of all symbols. More...
 

Public Attributes

Property modified
 Flag to indicate modification. More...
 

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:

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

  1. container (any): Other Container

◆ getDomainViolations()

function getDomainViolations ( in  obj)

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

◆ getUniverseSet()

function getUniverseSet ( in  obj)

Generate universe set (UEL order in GDX)

Deprecated:
Will be removed in version 1.x.x. Use Container.getUELs.

◆ isValid()

function isValid ( in  obj,
in  varargin 
)

Checks correctness of all symbols.

See Validate Symbol Records for more information.

Optional Arguments:

  1. verbose (logical): If true, the reason for an invalid symbol is printed
  2. force (logical): If true, forces reevaluation of validity (resets cache)
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:

  1. 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`.

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)

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

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

Parameter Arguments:

  • 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.

function Container(in varargin)
Constructs a GAMSTransfer Container.