GAMS Symbol (Set, Alias, Parameter, Variable or Equation) More...

Inheritance diagram for Symbol:
Equation Parameter Set Variable

GAMS Symbol (Set, Alias, Parameter, Variable or Equation)

Use subclasses to create a GAMS Symbol, see subclass help.

See also
Set, Alias, Parameter, Variable, Equation

Public Member Functions

function setRecords (in obj, in varargin)
 Sets symbol records in supported format. More...
 
function transformRecords (in obj, in target_format)
 Transforms symbol records into given format. More...
 
function equals (in obj, in symbol)
 Checks equivalence with other symbol. More...
 
function copy (in obj, in varargin)
 Copies symbol to destination container. More...
 
function isValid (in obj, in varargin)
 Checks correctness of symbol. More...
 
function getDomainViolations (in obj)
 Get domain violations. More...
 
function resolveDomainViolations (in obj)
 Extends domain sets in order to resolve domain violations. More...
 
function getSparsity (in obj)
 Returns the sparsity of symbol records. More...
 
function getCardenality (in obj)
 Returns the cardenality of symbol records. More...
 
function getMaxValue (in obj, in varargin)
 Returns the largest value in records. More...
 
function getMinValue (in obj, in varargin)
 Returns the smallest value in records. More...
 
function getMeanValue (in obj, in varargin)
 Returns the mean value over all values in records. More...
 
function getMaxAbsValue (in obj, in varargin)
 Returns the largest absolute value in records. More...
 
function countNA (in obj, in varargin)
 Returns the number of GAMS NA values in records. More...
 
function countUndef (in obj, in varargin)
 Returns the number of GAMS UNDEF values in records. More...
 
function countEps (in obj, in varargin)
 Returns the number of GAMS EPS values in records. More...
 
function countPosInf (in obj, in varargin)
 Returns the number of GAMS PINF (positive infinity) values in records. More...
 
function countNegInf (in obj, in varargin)
 Returns the number of GAMS MINF (negative infinity) values in records. More...
 
function getNumberRecords (in obj)
 Returns the number of GDX records (not available for matrix formats) More...
 
function getNumberValues (in obj, in varargin)
 Returns the number of values stored for this symbol. More...
 
function getUELs (in obj, in varargin)
 Returns the UELs used in this symbol. More...
 
function getUELLabels (in obj, in dim, in codes)
 Returns the UELs labels for the given UEL codes. More...
 
function initUELs (in obj, in dim, in uels)
 Sets the UELs without modifying UEL codes in records. More...
 
function setUELs (in obj, in uels, in dim, in varargin)
 Sets UELs. More...
 
function reorderUELs (in obj, in uels, in dim)
 Reorders UELs. More...
 
function addUELs (in obj, in uels, in dim)
 Adds UELs to the symbol. More...
 
function removeUELs (in obj, in uels, in dim)
 Removes UELs from the symbol. More...
 
function renameUELs (in obj, in uels, in dim)
 Renames UELs in the symbol. More...
 

Public Attributes

Property dimension
 Dimension of symbol (in [0,20])
 
Property size
 Shape of symbol (length == dimension) More...
 
Property domain
 Domain of symbol (length == dimension) More...
 
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. More...
 
Property records
 Storage of symbol records. More...
 
Property modified
 Flag to indicate modification. More...
 

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_labels
 Expected domain labels in records.
 
Property domain_type
 Specifies if domains are stored 'relaxed' or 'regular'. More...
 
Property format
 Format in which records are stored in. More...
 

Member Function Documentation

◆ addUELs()

function addUELs ( in  obj,
in  uels,
in  dim 
)

Adds UELs to the symbol.

  • addUELs(u) adds the UELs u for all dimensions.
  • addUELs(u, d) adds the UELs u 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:

  1. destination (Container): Destination Container

Optional Arguments:

  1. overwrite (bool): Overwrites symbol with same name in destination if true. 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 values n 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 values n 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 values n 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 values n 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 values n 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:

  1. symbol (any): Other symbol

◆ getCardenality()

function getCardenality ( in  obj)

Returns the cardenality of symbol records.

  • s = getCardenality() returns cardenality s (maximum number of values) in the symbol records.

◆ getDomainViolations()

function getDomainViolations ( in  obj)

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.
See also
Symbol.resolveDomainViolations, Container.getDomainViolations, DomainViolation

◆ getMaxAbsValue()

function getMaxAbsValue ( in  obj,
in  varargin 
)

Returns the largest absolute value in records.

  • [v, w] = getMaxAbsValue(varargin) returns the largest absolute value in records v and where it is w. 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 records v and where it is w. 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 records v. 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 records v and where it is w. 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 formats n is NaN.

◆ 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 sparsity s in the symbol records.

◆ getUELLabels()

function getUELLabels ( in  obj,
in  dim,
in  codes 
)

Returns the UELs labels for the given UEL codes.

Deprecated:
Will be removed in version 1.x.x. Use Symbol.getUELs.
  • u = getUELLabels(d, i) returns the UELs labels u for the given UEL codes i for the UELs stored for dimension 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

◆ 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 UELs u for the given UEL codes i.
  • 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

◆ initUELs()

function initUELs ( in  obj,
in  dim,
in  uels 
)

Sets the UELs without modifying UEL codes in records.

Deprecated:
Will be removed in version 1.x.x. Use Symbol.setUELs.
  • initUELs(d, u) sets the UELs u for dimension d. In contrast to the method setUELs(u, d), this method does not modify UEL codes used in the property records.
Note
This can only be used if the symbol is valid. UELs are not available when using the indexed mode.
See also
Container.indexed, Symbol.isValid, Symbol.setUELs

◆ isValid()

function isValid ( in  obj,
in  varargin 
)

Checks correctness of symbol.

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
Container.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 UELs u for all dimensions.
  • removeUELs(u, d) removes the UELs u 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  dim 
)

Renames UELs in the symbol.

  • renameUELs(u) renames the UELs u for all dimensions. 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(u, d) renames the UELs u for dimension(s) d. u as above.

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.

See also
Symbol.setUELs

◆ resolveDomainViolations()

function resolveDomainViolations ( in  obj)

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. Hence, the domain violations disappear.
See also
Symbol.getDomainViolations, Container.resolveDomainViolations, DomainViolation

◆ 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 of cellstr must be equal to symbol dimension and second will be the number of records. Row i is interpreted to hold the domain entries for dimension i.
  • numeric vector/matrix: Interpreted to hold the level values (or value for Parameter). Must satisfy the shape given by symbol size since this can only be a matrix format (e.g. dense_matrix or sparse_matrix), because domain entries are not given.
  • cell: If element is the i-th cellstr, then this is considered to be the domain entries for the i-th domain. If element is the j-th numeric vector/matrix, it is interpreted as the j-th element of the following: level or value, marginal, lower, upper, scale. If symbol is a Set, the (dim+1)-th cellstr 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 are level, value, marginal, lower, upper, scale, 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:

c = Container();
i = Set(c, 'i', 'description', 'canning plants');
i.setRecords({'seattle', 'san-diego'});
a = Parameter(c, 'a', i, 'description', 'capacity of plant i in cases');
a.setRecords([350, 600]);
supply = Equation(c, 'supply', 'l', i, 'description', 'observe supply limit at plant i');
supply.setRecords(struct('level', [350, 550], 'marginal', [geteps(), 0], 'upper', [350, 600]));
See also
RecordsFormat

◆ setUELs()

function setUELs ( in  obj,
in  uels,
in  dim,
in  varargin 
)

Sets UELs.

  • setUELs(u, d) sets the UELs u 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 UELsufor 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

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_type

Property domain_type
private

Specifies if domains are stored 'relaxed' or 'regular'.

See Symbol Domain for more information.

◆ format

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