Abstract Symbol. More...

Inheritance diagram for Abstract:

Abstract Symbol.

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

See also: symbol.Set, symbol.Parameter, symbol.Variable, symbol.Equation

Public Member Functions
function	copy (in obj, in varargin)
	(Abstract) Copies symbol to destination container

function	equals (in obj, in symbol)
	Checks equivalence with other symbol.

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	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	countDuplicateRecords (in obj)
	Counts duplicate records.

function	findDuplicateRecords (in obj, in varargin)
	Finds duplicate records.

function	hasDuplicateRecords (in obj)
	Checks if duplicate records exist.

function	dropDuplicateRecords (in obj, in varargin)
	Drops duplicate records.

function	countDomainViolations (in obj)
	Counts domain violations.

function	findDomainViolations (in obj)
	Counts domain violations.

function	hasDomainViolations (in obj)
	Checks if duplicate records exist.

function	dropDomainViolations (in obj)
	Drops duplicate records in symbols.

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	dropDefaults (in obj, in varargin)
	Drops default values from records.

function	dropNA (in obj, in varargin)
	Drops NA values from records.

function	dropUndef (in obj, in varargin)
	Drops Undef values from records.

function	dropMissing (in obj, in varargin)
	Drops NaN (includes NA and Undef) values from records.

function	dropEps (in obj, in varargin)
	Drops Eps values from records.

function	getUELs (in obj, in varargin)
	Returns the UELs used in this symbol.

function	setUELs (in obj, in varargin)
	Sets UELs.

function	reorderUELs (in obj, in varargin)
	Reorders UELs.

function	addUELs (in obj, in varargin)
	Adds UELs to the symbol.

function	removeUELs (in obj, in varargin)
	Removes UELs from the symbol.

function	renameUELs (in obj, in varargin)
	Renames UELs in the 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	container
	Container the symbol is stored in.

Property	name
	Symbol name.

Property	description
	Symbol description.

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	format
	Format in which records are stored in.

Property	modified
	Flag to indicate modification.

Private Attributes
Property	domain_names
	Domain names of symbol.

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

Property	indexed
	(Abstract) Flag if symbol can be used in indexed mode

Member Function Documentation

◆ addUELs()

function addUELs	(	in	obj,
		in	varargin
	)

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.

◆ copy()

function copy	(	in	obj,
		in	varargin
	)

(Abstract) 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 if true. Default: false.

◆ countDomainViolations()

function countDomainViolations ( in obj )

Counts 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!

Only relevant for symbols with table-like record formats.

◆ countDuplicateRecords()

function countDuplicateRecords ( in obj )

Counts duplicate records.

In table-like record formats it may happen that duplicates occur. Duplicates are values that refer to the same domain entry.

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

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

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.

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

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.

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

See also: SpecialValues.NEGINF, SpecialValues.isNegInf

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

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

See also: SpecialValues.POSINF, SpecialValues.isPosInf

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

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

See also: SpecialValues.UNDEF, SpecialValues.isUndef

◆ dropDefaults()

function dropDefaults	(	in	obj,
		in	varargin
	)

Drops default values from records.

For table-like record formats rows are dropped if all columns of that row hold default values. For matrix-like records formats, nothing happens.

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

◆ dropDomainViolations()

function dropDomainViolations ( in obj )

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.

◆ dropDuplicateRecords()

function dropDuplicateRecords	(	in	obj,
		in	varargin
	)

Drops duplicate records.

In table-like record formats it may happen that duplicates occur. Duplicates are values that refer to the same domain entry.

Parameter Arguments:

keep (string): Specify which record to keep in case of duplicates. Possible values: 'first' or 'last'. Default: 'first'.

◆ dropEps()

function dropEps	(	in	obj,
		in	varargin
	)

Drops Eps values from records.

For table-like record formats rows are dropped if any column of that row holds Eps. For matrix-like records formats, Eps elements are replaced by the corresponding default value.

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

See also: SpecialValues.EPS

◆ dropMissing()

function dropMissing	(	in	obj,
		in	varargin
	)

Drops NaN (includes NA and Undef) values from records.

For table-like record formats rows are dropped if any column of that row holds NaN. For matrix-like records formats, NaN elements are replaced by the corresponding default value.

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

See also: SpecialValues.NA, SpecialValues.UNDEF

◆ dropNA()

function dropNA	(	in	obj,
		in	varargin
	)

Drops NA values from records.

For table-like record formats rows are dropped if any column of that row holds NA. For matrix-like records formats, NA elements are replaced by the corresponding default value.

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

See also: SpecialValues.NA

◆ dropUndef()

function dropUndef	(	in	obj,
		in	varargin
	)

Drops Undef values from records.

For table-like record formats rows are dropped if any column of that row holds Undef. For matrix-like records formats, Undef elements are replaced by the corresponding default value.

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

See also: SpecialValues.UNDEF

◆ 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

◆ findDomainViolations()

function findDomainViolations ( in obj )

Counts 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!

Returned indices are rows in table-like formats.

Only relevant for symbols with table-like record formats.

◆ findDuplicateRecords()

function findDuplicateRecords	(	in	obj,
		in	varargin
	)

Finds duplicate records.

In table-like record formats it may happen that duplicates occur. Duplicates are values that refer to the same domain entry.

Returned indices are rows in table-like formats.

Parameter Arguments:

keep (string): Specify which record to keep in case of duplicates. Possible values: 'first' or 'last'. Default: 'first'.

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

domain_violations = getDomainViolations returns a list of domain violations for all dimensions.
domain_violations = getDomainViolations(d) returns a list of domain violations for dimension(s) d.

See also: symbol.Abstract.resolveDomainViolations, Container.getDomainViolations, symbol.domain.Violation

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

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

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

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

◆ getMeanValue()

function getMeanValue	(	in	obj,
		in	varargin
	)

Returns the mean value over all values in records.

[v, w] = getMeanValue(varargin) returns the mean value over all values in records v and where it is w.

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

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

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

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

Parameter Arguments:

values (cell): List of value fields that should be considered, e.g. ‘{'level’, 'marginal', 'lower', 'upper', 'scale'}`. Default: All value fields of symbol.

See also: symbol.Abstract.getSparsity

◆ getSparsity()

function getSparsity ( in obj )

Returns the sparsity of symbol records.

s = getSparsity() returns sparsity s 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 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.

◆ hasDomainViolations()

function hasDomainViolations ( in obj )

Checks if duplicate records exist.

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.

◆ hasDuplicateRecords()

function hasDuplicateRecords ( in obj )

Checks if duplicate records exist.

In table-like record formats it may happen that duplicates occur. Duplicates are values that refer to the same domain entry.

◆ isValid()

function isValid	(	in	obj,
		in	varargin
	)

Checks correctness of symbol.

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)

See also: Container.isValid

◆ lowerUELs()

function lowerUELs	(	in	obj,
		in	varargin
	)

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.

◆ removeUELs()

function removeUELs	(	in	obj,
		in	varargin
	)

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.

◆ renameUELs()

function renameUELs	(	in	obj,
		in	varargin
	)

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

◆ reorderUELs()

function reorderUELs	(	in	obj,
		in	varargin
	)

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

See also: symbol.Abstract.getDomainViolations, Container.resolveDomainViolations, symbol.domain.Violation

◆ 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, 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:

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]));

◆ setUELs()

function setUELs	(	in	obj,
		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.

◆ transformRecords()

function transformRecords	(	in	obj,
		in	target_format
	)

Transforms symbol records into given format.

Required Arguments:

target_format (string): Name of format to transform data to (table, struct, dense_matrix or sparse_matrix).

If the target format is a matrix format, the UELs will be updated to the ones from the domain plus the added ones. Thus, if there are no domain violations, the matrix size will equal the size defined by the symbol domain.

After the transformation UELs will be trimmed which means that unused UELs will be removed if possible.

◆ upperUELs()

function upperUELs	(	in	obj,
		in	varargin
	)

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.

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

Property domain_type

private

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

See Symbol Domain for more information.

◆ format

Property format

Format in which records are stored in.

If records are changed, this gets reset to 'unknown'. Calling symbol.Abstract.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.

Public Member Functions

Public Attributes

Private Attributes

Member Function Documentation

◆ addUELs()

◆ copy()

◆ countDomainViolations()

◆ countDuplicateRecords()

◆ countEps()

◆ countNA()

◆ countNegInf()

◆ countPosInf()

◆ countUndef()

◆ dropDefaults()

◆ dropDomainViolations()

◆ dropDuplicateRecords()

◆ dropEps()

◆ dropMissing()

◆ dropNA()

◆ dropUndef()

◆ equals()

◆ findDomainViolations()

◆ findDuplicateRecords()

◆ getDomainViolations()

◆ getMaxAbsValue()

◆ getMaxValue()

◆ getMeanValue()

◆ getMinValue()

◆ getNumberRecords()

◆ getNumberValues()

◆ getSparsity()

◆ getUELs()

◆ hasDomainViolations()

◆ hasDuplicateRecords()

◆ isValid()

◆ lowerUELs()

◆ removeUELs()

◆ renameUELs()

◆ reorderUELs()

◆ resolveDomainViolations()

◆ setRecords()

◆ setUELs()

◆ transformRecords()

◆ upperUELs()

Member Data Documentation

◆ domain

◆ domain_forwarding

◆ domain_labels

◆ domain_type

◆ format

◆ modified

◆ records