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.
Example:
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 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 | countDuplicateRecords (in obj, in varargin) |
Counts duplicate records in symbols. | |
function | hasDuplicateRecords (in obj, in varargin) |
Checks if duplicate records exist in symbols. | |
function | dropDuplicateRecords (in obj, in varargin) |
Drops duplicate records in symbols. | |
function | countDomainViolations (in obj, in varargin) |
Counts domain violations in symbols. | |
function | hasDomainViolations (in obj, in varargin) |
Checks if duplicate records exist in symbols. | |
function | dropDomainViolations (in obj, in varargin) |
Drops duplicate records in symbols. | |
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 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 | data |
GAMS (GDX) symbols. | |
Constructor & Destructor Documentation
◆ Container()
function Container | ( | in | varargin | ) |
Member Function Documentation
◆ addAlias()
function addAlias | ( | in | obj, |
in | name, | ||
in | alias_with | ||
) |
Adds an alias to the container.
Required Arguments:
- name (
string
): name of alias - alias_with (
Set
orAlias
): symbol.Set to be linked to.
Example:
- See also
- alias.Set, Alias, symbol.Set
◆ addEquation()
function addEquation | ( | in | obj, |
in | name, | ||
in | varargin | ||
) |
Adds an equation to the container.
Required Arguments:
- name (
string
): Name of equation - type (
string
,int
or EquationType): Specifies the variable type, either asstring
, asinteger
given by any of the constants in EquationType or EquationType.
Optional Arguments:
- domain (
cellstr
orSet
): List of domains given either asstring
or as reference to a symbol.Set object. Default is{}
(for scalar).
Parameter Arguments:
- records: Equation records. Default is
[]
. - description (
string
): Description of symbol. Default is""
. - domain_forwarding (
logical
): Iftrue
, domain entries in records will recursively be added to the domains in case they are not present in the domains already. With a logical vector domain forwarding can be enabled/disabled independently for each domain. Default:false
.
Note, this method may overwrite an equation if its definition (type, domain, domain_forwarding) doesn't differ.
Example:
- See also
- symbol.Equation, Equation, EquationType
◆ addParameter()
function addParameter | ( | in | obj, |
in | name, | ||
in | varargin | ||
) |
Adds a parameter to the container.
Required Arguments:
- name (
string
): Name of parameter
Optional Arguments:
- domain (
cellstr
orSet
): List of domains given either asstring
or as reference to a symbol.Set object. Default is{}
(for scalar).
Parameter Arguments:
- records: Parameter records. Default is
[]
. - description (
string
): Description of symbol. Default is""
. - domain_forwarding (
logical
): Iftrue
, domain entries in records will recursively be added to the domains in case they are not present in the domains already. With a logical vector domain forwarding can be enabled/disabled independently for each domain. Default:false
.
Note, this method may overwrite a parameter if its definition (domain, domain_forwarding) doesn't differ.
Example:
- See also
- symbol.Parameter, Parameter
◆ addSet()
function addSet | ( | in | obj, |
in | name, | ||
in | varargin | ||
) |
Adds a set to the container.
Required Arguments:
- name (
string
): Name of set
Optional Arguments:
- domain (
cellstr
orSet
): List of domains given either asstring
or as reference to a symbol.Set object. Default is{"*"}
(for 1-dim with universe domain).
Parameter Arguments:
- records: Set records, e.g. a list of strings. Default is
[]
. - description (
string
): Description of symbol. Default is""
. - is_singleton (
logical
): Indicates if set is a is_singleton set (true
) or not (false
). Default isfalse
. - domain_forwarding (
logical
): Iftrue
, domain entries in records will recursively be added to the domains in case they are not present in the domains already. With a logical vector domain forwarding can be enabled/disabled independently for each domain. Default:false
.
Note, this method may overwrite a set if its definition (is_singleton, domain, domain_forwarding) doesn't differ.
Example:
- See also
- symbol.Set, Set
◆ addUniverseAlias()
function addUniverseAlias | ( | in | obj, |
in | name | ||
) |
Adds a universe alias to the container.
Required Arguments:
- name (
string
): name of alias
Example:
- See also
- alias.Universe, UniverseAlias
◆ addVariable()
function addVariable | ( | in | obj, |
in | name, | ||
in | varargin | ||
) |
Adds a variable to the container.
Required Arguments:
- name (
string
): Name of variable
Optional Arguments:
- type (
string
,int
or VariableType): Specifies the variable type, either asstring
, asinteger
given by any of the constants in VariableType or VariableType. Default is"free"
. - domain (
cellstr
orSet
): List of domains given either as string or as reference to a symbol.Set object. Default is{}
(for scalar).
Parameter Arguments:
- records: Set records, e.g. a list of strings. Default is
[]
. - description (
string
): Description of symbol. Default is""
. - domain_forwarding (
logical
): Iftrue
, domain entries in records will recursively be added to the domains in case they are not present in the domains already. With a logical vector domain forwarding can be enabled/disabled independently for each domain. Default:false
.
Note, this method may overwrite a variable if its definition (type, domain, domain_forwarding) doesn't differ.
Example:
- See also
- symbol.Variable, Variable, VariableType
◆ countDomainViolations()
function countDomainViolations | ( | in | obj, |
in | varargin | ||
) |
Counts domain violations in 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!
Only relevant for symbols with table-like record formats.
Parameter Arguments:
- symbols (
cell
): List of symbols to be considered. Case doesn't matter. Default is all.
◆ countDuplicateRecords()
function countDuplicateRecords | ( | in | obj, |
in | varargin | ||
) |
Counts duplicate records in symbols.
In table-like record formats it may happen that duplicates occur. Duplicates are values that refer to the same domain entry.
Parameter Arguments:
- symbols (
cell
): List of symbols to be considered. Case doesn't matter. Default is all.
◆ 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.
◆ dropDomainViolations()
function dropDomainViolations | ( | in | obj, |
in | varargin | ||
) |
Drops duplicate records in 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!
Only relevant for symbols with table-like record formats.
Parameter Arguments:
- symbols (
cell
): List of symbols to be considered. Case doesn't matter. Default is all.
◆ dropDuplicateRecords()
function dropDuplicateRecords | ( | in | obj, |
in | varargin | ||
) |
Drops duplicate records in symbols.
In table-like record formats it may happen that duplicates occur. Duplicates are values that refer to the same domain entry.
Parameter Arguments:
- symbols (
cell
): List of symbols to be considered. Case doesn't matter. Default is all. - keep (
string
): Specify which record to keep in case of duplicates. Possible values: 'first' or 'last'. Default: 'first'.
◆ 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
orany
): Enablevalid
filter if argument is of type logical. Iftrue
, only include symbols that are valid and, iffalse
, only invalid symbols. Default: not logical.
◆ 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. Case doesn't matter. Default is all.
◆ getEquations()
function getEquations | ( | in | obj, |
in | varargin | ||
) |
Gets all Equation objects.
Parameter Arguments:
- is_valid (
logical
orany
): Enablevalid
filter if argument is of type logical. Iftrue
, only include symbols that are valid and, iffalse
, only invalid symbols. Default: not logical. - types (
any
): Enable filter for equation type, e.g.type = {"g", "l"}
. Default: not applied.
◆ getParameters()
function getParameters | ( | in | obj, |
in | varargin | ||
) |
Gets all Parameter objects.
Parameter Arguments:
- is_valid (
logical
orany
): Enablevalid
filter if argument is of type logical. Iftrue
, only include symbols that are valid and, iffalse
, only invalid symbols. Default: not logical.
◆ getSets()
function getSets | ( | in | obj, |
in | varargin | ||
) |
Gets all Set objects.
Parameter Arguments:
- is_valid (
logical
orany
): Enablevalid
filter if argument is of type logical. Iftrue
, only include symbols that are valid and, iffalse
, 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 nameda
wherea
may have different casing.s = c.getSymbolNames(b)
returns a list GAMS symbol names where names equalb
case insensitively.
Example:
◆ 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 nameda
.s = c.getSymbols(b)
returns a list of handles to the GAMS symbols with names equal to any element in cellb
.
Example:
◆ 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 symbols
s. -
u = getUELs(_, "ignore_unused", true)` returns only those UELs that are actually used in the records.
See Unique Elements (UELs) for more information.
◆ getVariables()
function getVariables | ( | in | obj, |
in | varargin | ||
) |
Gets all Variable objects.
Parameter Arguments:
- is_valid (
logical
orany
): Enablevalid
filter if argument is of type logical. Iftrue
, only include symbols that are valid and, iffalse
, only invalid symbols. Default: not logical. - types (
any
): Enable filter for variable type, e.g.type = {"binary", "integer"}
. Default: not applied.
◆ hasDomainViolations()
function hasDomainViolations | ( | in | obj, |
in | varargin | ||
) |
Checks if duplicate records exist in 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!
Only relevant for symbols with table-like record formats.
Parameter Arguments:
- symbols (
cell
): List of symbols to be considered. Case doesn't matter. Default is all.
◆ hasDuplicateRecords()
function hasDuplicateRecords | ( | in | obj, |
in | varargin | ||
) |
Checks if duplicate records exist in symbols.
In table-like record formats it may happen that duplicates occur. Duplicates are values that refer to the same domain entry.
Parameter Arguments:
- symbols (
cell
): List of symbols to be considered. Case doesn't matter. Default is all.
◆ hasSymbols()
function hasSymbols | ( | in | obj, |
in | names | ||
) |
Checks if symbol exists in container (case insensitive)
s = c.hasSymbols(a)
returnstrue
if GAMS symbol nameda
(case does not matter) exists.false
otherwise.s = c.hasSymbols(b)
returns a list of bools where an entrys{i}
istrue
if GAMS symbol namedb{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
): Iftrue
, the reason for an invalid symbol is printed - force (
logical
): Iftrue
, forces reevaluation of validity (resets cache)
Parameter Arguments:
- symbols (
cell
): List of symbols to be considered. Case doesn't matter. Default is all.
- See also
- symbol.Abstract.isValid
◆ listAliases()
function listAliases | ( | in | obj, |
in | varargin | ||
) |
Lists all aliases in container.
Parameter Arguments:
- is_valid (
logical
orany
): Enablevalid
filter if argument is of type logical. Iftrue
, only include symbols that are valid and, iffalse
, only invalid symbols. Default: not logical.
◆ listEquations()
function listEquations | ( | in | obj, |
in | varargin | ||
) |
Lists all equations in container.
Parameter Arguments:
- is_valid (
logical
orany
): Enablevalid
filter if argument is of type logical. Iftrue
, only include symbols that are valid and, iffalse
, only invalid symbols. Default: not logical. - types (
any
): Enable filter for equation type, e.g.type = {"g", "l"}
. Default: not applied.
◆ listParameters()
function listParameters | ( | in | obj, |
in | varargin | ||
) |
Lists all parameters in container.
Parameter Arguments:
- is_valid (
logical
orany
): Enablevalid
filter if argument is of type logical. Iftrue
, only include symbols that are valid and, iffalse
, only invalid symbols. Default: not logical.
◆ listSets()
function listSets | ( | in | obj, |
in | varargin | ||
) |
Lists all sets in container.
Parameter Arguments:
- is_valid (
logical
orany
): Enablevalid
filter if argument is of type logical. Iftrue
, only include symbols that are valid and, iffalse
, only invalid symbols. Default: not logical.
◆ listSymbols()
function listSymbols | ( | in | obj, |
in | varargin | ||
) |
Lists all symbols in container.
Parameter Arguments:
- is_valid (
logical
orany
): Enablevalid
filter if argument is of type logical. Iftrue
, only include symbols that are valid and, iffalse
, only invalid symbols. Default: not logical.
◆ listVariables()
function listVariables | ( | in | obj, |
in | varargin | ||
) |
Lists all variables in container.
Parameter Arguments:
- is_valid (
logical
orany
): Enablevalid
filter if argument is of type logical. Iftrue
, only include symbols that are valid and, iffalse
, only invalid symbols. Default: not logical. - types (
any
): Enable filter for variable type, e.g.type = {"binary", "integer"}
. Default: not applied.
◆ 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 symbols
s`.
See Unique Elements (UELs) for more information.
◆ read()
function read | ( | in | obj, |
in | varargin | ||
) |
Reads symbols from GDX file.
See Reading From GDX for more information.
Required Arguments:
- source (
string
orContainer
): 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 all. - format (
string
): Records format symbols should be stored in. Default istable
. - records (
logical
): Enables reading of records. Default istrue
. - values (
cell
): Subset of{"level", "marginal", "lower", "upper", "scale"}
that defines what value fields should be read. Default is all. - indexed (
logical
): Specifies if indexed GDX should be read. Default isfalse
.
Example:
◆ 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 nameda
.c.removeSymbols(b)
removes a list of GAMS symbols with names equal elements in cellb
.
Example:
◆ removeUELs()
function removeUELs | ( | in | obj, |
in | varargin | ||
) |
Removes UELs from all symbols.
removeUELs()
removes all unused UELs for all symbols.removeUELs(u)
removes the UELsu
for all symbols.- ‘removeUELs(_, 'symbols’, s)
removes UELs for symbols
s`.
See Unique Elements (UELs) for more information.
◆ renameSymbol()
function renameSymbol | ( | in | obj, |
in | oldname, | ||
in | newname | ||
) |
Rename a symbol.
renameSymbol(oldname, newname)
renames the symbol with nameoldname
tonewname
. The symbol order in data will not change.
Example:
◆ renameUELs()
function renameUELs | ( | in | obj, |
in | varargin | ||
) |
Renames UELs in all symbol.
renameUELs(u)
renames the UELsu
for all symbols.u
can be astruct
(field names = old UELs, field values = new UELs),containers.Map
(keys = old UELs, values = new UELs) orcellstr
(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 symbols
s. -
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.
◆ 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. Case doesn't matter. Default is all.
◆ 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 symbols
s`.
See Unique Elements (UELs) for more information.
◆ 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. List of symbols to be considered. Case doesn't matter. Default is all. - compress (
logical
): Flag to compress GDX file (true
) or not (false
). Default isfalse
. - sorted (
logical
): Flag to define records as sorted (true
) or not (false
). Default isfalse
. - uel_priority (
cellstr
): UELs to be registered first before any symbol UELs. Default:{}
. - indexed (
logical
): Specifies if indexed GDX should be written. Default isfalse
. - eps_to_zero (
logical
): Specifies if EPS values should be written as zero. Default istrue
.
Example:
- 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.