GAMS Symbol (Set, Alias, Parameter, Variable or Equation) More...
GAMS Symbol (Set, Alias, Parameter, Variable or Equation)
Use subclasses to create a GAMS Symbol, see subclass help.
Public Member Functions | |
function | setRecords (in obj, in varargin) |
Sets symbol records in supported format. | |
function | transformRecords (in obj, in target_format) |
Transforms symbol records into given format. | |
function | equals (in obj, in symbol) |
Checks equivalence with other symbol. | |
function | copy (in obj, in varargin) |
Copies symbol to destination container. | |
function | isValid (in obj, in varargin) |
Checks correctness of symbol. | |
function | getDomainViolations (in obj, in varargin) |
Get domain violations. | |
function | resolveDomainViolations (in obj, in varargin) |
Extends domain sets in order to resolve domain violations. | |
function | getSparsity (in obj) |
Returns the sparsity of symbol records. | |
function | getMaxValue (in obj, in varargin) |
Returns the largest value in records. | |
function | getMinValue (in obj, in varargin) |
Returns the smallest value in records. | |
function | getMeanValue (in obj, in varargin) |
Returns the mean value over all values in records. | |
function | getMaxAbsValue (in obj, in varargin) |
Returns the largest absolute value in records. | |
function | countNA (in obj, in varargin) |
Returns the number of GAMS NA values in records. | |
function | countUndef (in obj, in varargin) |
Returns the number of GAMS UNDEF values in records. | |
function | countEps (in obj, in varargin) |
Returns the number of GAMS EPS values in records. | |
function | countPosInf (in obj, in varargin) |
Returns the number of GAMS PINF (positive infinity) values in records. | |
function | countNegInf (in obj, in varargin) |
Returns the number of GAMS MINF (negative infinity) values in records. | |
function | getNumberRecords (in obj) |
Returns the number of GDX records (not available for matrix formats) | |
function | getNumberValues (in obj, in varargin) |
Returns the number of values stored for this symbol. | |
function | getUELs (in obj, in varargin) |
Returns the UELs used in this symbol. | |
function | setUELs (in obj, in uels, in dim, in varargin) |
Sets UELs. | |
function | reorderUELs (in obj, in uels, in dim) |
Reorders UELs. | |
function | addUELs (in obj, in uels, in dim) |
Adds UELs to the symbol. | |
function | removeUELs (in obj, in uels, in dim) |
Removes UELs from the symbol. | |
function | renameUELs (in obj, in uels, in varargin) |
Renames UELs in the symbol. | |
function | lowerUELs (in obj, in dim) |
Converts UELs to lower case. | |
function | upperUELs (in obj, in dim) |
Converts UELs to upper case. | |
Public Attributes | |
Property | dimension |
Dimension of symbol (in [0,20]) | |
Property | size |
Shape of symbol (length == dimension) | |
Property | domain |
Domain of symbol (length == dimension) | |
Property | domain_labels |
Domain labels in records. | |
Property | domain_forwarding |
Enables domain entries in records to be recursively added to the domains in case they are not present in the domains already. | |
Property | records |
Storage of symbol records. | |
Property | modified |
Flag to indicate modification. | |
Protected Member Functions | |
function | Symbol (in container, in name, in description, in domain_size, in records, in domain_forwarding) |
Constructs a GAMS Symbol, see subclasses help. | |
Private Attributes | |
Property | domain_names |
Domain names of symbol. | |
Property | domain_type |
Specifies if domains are stored 'relaxed' or 'regular'. | |
Property | format |
Format in which records are stored in. | |
Member Function Documentation
◆ addUELs()
function addUELs | ( | in | obj, |
in | uels, | ||
in | dim | ||
) |
Adds UELs to the symbol.
addUELs(u)
adds the UELsu
for all dimensions.addUELs(u, d)
adds the UELsu
for dimension(s)d
.
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
◆ copy()
function copy | ( | in | obj, |
in | varargin | ||
) |
Copies symbol to destination container.
Symbol domains are downgraded to relaxed
if the destination container does not have equivalent domain sets, see also Symbol Domain.
Required Arguments:
- destination (
Container
): Destination Container
Optional Arguments:
- overwrite (
bool
): Overwrites symbol with same name in destination iftrue
. Default:false
.
◆ countEps()
function countEps | ( | in | obj, |
in | varargin | ||
) |
Returns the number of GAMS EPS values in records.
n = countEps(varargin)
returns the number of GAMS EPS valuesn
in records.varargin
can include a list of value fields that should be considered:"level"
,"value"
,"lower"
,"upper"
,"scale"
. If none is given all available for the symbol are considered.
- See also
- SpecialValues.EPS, SpecialValues.isEps
◆ countNA()
function countNA | ( | in | obj, |
in | varargin | ||
) |
Returns the number of GAMS NA values in records.
n = countNA(varargin)
returns the number of GAMS NA valuesn
in records.varargin
can include a list of value fields that should be considered:"level"
,"value"
,"lower"
,"upper"
,"scale"
. If none is given all available for the symbol are considered.
- See also
- SpecialValues.NA, SpecialValues.isNA
◆ countNegInf()
function countNegInf | ( | in | obj, |
in | varargin | ||
) |
Returns the number of GAMS MINF (negative infinity) values in records.
n = countNegInf(varargin)
returns the number of GAMS MINF valuesn
in records.varargin
can include a list of value fields that should be considered:"level"
,"value"
,"lower"
,"upper"
,"scale"
. If none is given all available for the symbol are considered.
◆ countPosInf()
function countPosInf | ( | in | obj, |
in | varargin | ||
) |
Returns the number of GAMS PINF (positive infinity) values in records.
n = countPosInf(varargin)
returns the number of GAMS PINF valuesn
in records.varargin
can include a list of value fields that should be considered:"level"
,"value"
,"lower"
,"upper"
,"scale"
. If none is given all available for the symbol are considered.
◆ countUndef()
function countUndef | ( | in | obj, |
in | varargin | ||
) |
Returns the number of GAMS UNDEF values in records.
n = countUndef(varargin)
returns the number of GAMS UNDEF valuesn
in records.varargin
can include a list of value fields that should be considered:"level"
,"value"
,"lower"
,"upper"
,"scale"
. If none is given all available for the symbol are considered.
◆ equals()
function equals | ( | in | obj, |
in | symbol | ||
) |
Checks equivalence with other symbol.
- Note
- A symbol is always linked to a container. This method does not check equivalence of the linked containers.
Required Arguments:
- symbol (
any
): Other symbol
◆ getDomainViolations()
function getDomainViolations | ( | in | obj, |
in | varargin | ||
) |
Get 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.
dom_violations = getDomainViolations
returns a list of domain violations for all dimensions.dom_violations = getDomainViolations(d)
returns a list of domain violations for dimension(s)d
.
◆ getMaxAbsValue()
function getMaxAbsValue | ( | in | obj, |
in | varargin | ||
) |
Returns the largest absolute value in records.
[v, w] = getMaxAbsValue(varargin)
returns the largest absolute value in recordsv
and where it isw
.varargin
can include a list of value fields that should be considered:"level"
,"value"
,"lower"
,"upper"
,"scale"
. If none is given all available for the symbol are considered.
◆ getMaxValue()
function getMaxValue | ( | in | obj, |
in | varargin | ||
) |
Returns the largest value in records.
[v, w] = getMaxValue(varargin)
returns the largest value in recordsv
and where it isw
.varargin
can include a list of value fields that should be considered:"level"
,"value"
,"lower"
,"upper"
,"scale"
. If none is given all available for the symbol are considered.
◆ getMeanValue()
function getMeanValue | ( | in | obj, |
in | varargin | ||
) |
Returns the mean value over all values in records.
v = getMinValue(varargin)
returns the mean value over all values in recordsv
.varargin
can include a list of value fields that should be considered:"level"
,"value"
,"lower"
,"upper"
,"scale"
. If none is given all available for the symbol are considered.
◆ getMinValue()
function getMinValue | ( | in | obj, |
in | varargin | ||
) |
Returns the smallest value in records.
[v, w] = getMinValue(varargin)
returns the smallest value in recordsv
and where it isw
.varargin
can include a list of value fields that should be considered:"level"
,"value"
,"lower"
,"upper"
,"scale"
. If none is given all available for the symbol are considered.
◆ getNumberRecords()
function getNumberRecords | ( | in | obj | ) |
Returns the number of GDX records (not available for matrix formats)
n = getNumberRecords()
returns the number of records that would be stored in a GDX file if this symbol would be written to GDX. For matrix formatsn
isNaN
.
◆ getNumberValues()
function getNumberValues | ( | in | obj, |
in | varargin | ||
) |
Returns the number of values stored for this symbol.
n = getNumberValues(varargin)
is the sum of values stored of the following fields:"level"
,"value"
,"marginal"
,"lower"
,"upper"
,"scale"
. The number of values is the basis for the sparsity computation.varargin
can include a list of value fields that should be considered:"level"
,"value"
,"lower"
,"upper"
,"scale"
. If none is given all available for the symbol are considered.
- See also
- Symbol.getSparsity
◆ getSparsity()
function getSparsity | ( | in | obj | ) |
Returns the sparsity of symbol records.
s = getSparsity()
returns sparsitys
in the symbol records.
◆ getUELs()
function getUELs | ( | in | obj, |
in | varargin | ||
) |
Returns the UELs used in this symbol.
u = getUELs()
returns the UELs across all dimensions.u = getUELs(d)
returns the UELs used in dimension(s)d
.u = getUELs(d, i)
returns the UELsu
for the given UEL codesi
.u = getUELs(d, _, "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 symbol is valid. UELs are not available when using the indexed mode, see Indexed GDX.
- See also
- Container.indexed, Symbol.isValid
◆ isValid()
function isValid | ( | in | obj, |
in | varargin | ||
) |
Checks correctness of symbol.
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)
- See also
- Container.isValid
◆ lowerUELs()
function lowerUELs | ( | in | obj, |
in | dim | ||
) |
Converts UELs to lower case.
lowerUELs()
converts the UELs for all dimension(s).lowerUELs(d)
converts the UELs for dimension(s)d
.
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
◆ removeUELs()
function removeUELs | ( | in | obj, |
in | uels, | ||
in | dim | ||
) |
Removes UELs from the symbol.
removeUELs()
removes all unused UELs for all dimensions.removeUELs({}, d)
removes all unused UELs for dimension(s)d
.removeUELs(u)
removes the UELsu
for all dimensions.removeUELs(u, d)
removes the UELsu
for dimension(s)d
.
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
◆ renameUELs()
function renameUELs | ( | in | obj, |
in | uels, | ||
in | varargin | ||
) |
Renames UELs in the symbol.
renameUELs(u)
renames the UELsu
for all dimensions.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(u, d)
renames the UELsu
for dimension(s)d
.u
as above.- ‘renameUELs(_, 'allow_merge’, true)` enables support of merging one UEL into another one (renaming a UEL to an already existing one).
If an old UEL is provided in struct
or containers.Map
that is not present in the symbol UELs, it will be silently ignored.
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
◆ reorderUELs()
function reorderUELs | ( | in | obj, |
in | uels, | ||
in | dim | ||
) |
Reorders UELs.
Same functionality as setUELs(uels, dim)
, but checks that no new categories are added. The meaning of records does not change.
reorderUELs()
reorders UELs by record order for each dimension. Unused UELs are appended.
- See also
- Symbol.setUELs
◆ resolveDomainViolations()
function resolveDomainViolations | ( | in | obj, |
in | varargin | ||
) |
Extends domain sets in order to resolve 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 for all domains. Hence, the domain violations disappear.resolveDomainViolations(d)
extends the domain sets with the violated domain entries for dimension(s)d
. Hence, the domain violations disappear for those dimension(s).
◆ setRecords()
function setRecords | ( | in | obj, |
in | varargin | ||
) |
Sets symbol records in supported format.
If records are not given in any of the supported formats, e.g. struct or dense_matrix, this function tries to convert the given data into one of them.
Conversion is applied based on the following rules:
string
: Interpreted as domain entry for first dimension.cellstr
: First dimension ofcellstr
must be equal to symbol dimension and second will be the number of records. Rowi
is interpreted to hold the domain entries for dimensioni
.numeric vector/matrix
: Interpreted to hold thelevel
values (orvalue
for Parameter). Must satisfy the shape given by symbol size since this can only be a matrix format (e.g.dense_matrix
orsparse_matrix
), because domain entries are not given.cell
: If element is thei
-thcellstr
, then this is considered to be the domain entries for thei
-th domain. If element is thej
-th numeric vector/matrix, it is interpreted as thej
-th element of the following:level
orvalue
,marginal
,lower
,upper
,scale
. If symbol is a Set, the(dim+1)
-thcellstr
is considered to be the set element texts.struct
: Fields which names match domain labels, are interpreted as domain entries of the given domain. Other supported fields arelevel
,value
,marginal
,lower
,upper
,scale
,element_text
. Unsopprted fields are ignored.table
: used as is.
- Note
- Instead of a
cell
, it is possible to provide the elements as separate arguments to the function.
Example:
- See also
- RecordsFormat
◆ setUELs()
function setUELs | ( | in | obj, |
in | uels, | ||
in | dim, | ||
in | varargin | ||
) |
Sets UELs.
setUELs(u, d)
sets the UELsu
for dimension(s)d
. This may modify UEL codes used in the property records such that records still point to the correct UEL label when UEL codes have changed.- ‘setUELs(u, d, 'rename’, true)
sets the UELs
ufor dimension(s)
d`. This does not modify UEL codes used in the property records. This can change the meaning of the records.
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
◆ transformRecords()
function transformRecords | ( | in | obj, |
in | target_format | ||
) |
Transforms symbol records into given format.
- See also
- RecordsFormat
◆ upperUELs()
function upperUELs | ( | in | obj, |
in | dim | ||
) |
Converts UELs to upper case.
upperUELs()
converts the UELs for all dimension(s).upperUELs(d)
converts the UELs for dimension(s)d
.
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
Member Data Documentation
◆ domain
Property domain |
Domain of symbol (length == dimension)
See Symbol Domain for more information.
◆ domain_forwarding
Property domain_forwarding |
Enables domain entries in records to be recursively added to the domains in case they are not present in the domains already.
See Domain Violations for more information.
◆ domain_labels
Property domain_labels |
Domain labels in records.
Domain labels mirror the field/column names for domains in records. They only exist for formats table and struct. Setting domain labels may modify the given labels to make them unique by adding _<dim>. * is changed to uni.
◆ domain_type
|
private |
Specifies if domains are stored 'relaxed' or 'regular'.
See Symbol Domain for more information.
◆ format
|
private |
Format in which records are stored in.
If records are changed, this gets reset to RecordsFormat.UNKNOWN. Calling Alias.isValid will detect the format again.
See Records Format for more information.
◆ modified
Property modified |
Flag to indicate modification.
If the symbol has been modified since last reset of flag (false
), this flag will be true
.
◆ records
Property records |
Storage of symbol records.
See Records Format for more information.
◆ size
Property size |
Shape of symbol (length == dimension)
See Symbol Domain and Indexed GDX for more information.