Symbols

Symbols (Set, Alias, Parameter, Variable, Equation) More...

Symbols (Set, Alias, Parameter, Variable, Equation)

A symbol is either a GAMS Set, Alias, Parameter, Variable or Equation. In GAMS Transfer Matlab, a symbol cannot live on it's own, but is always part of a container.

Symbol Domain

Before we can dive into the symbol details, it is important to learn about some GDX basics. In GDX, symbols are defined over a domain. The domain specifies the dimension and size of a symbol, e.g., whether it's a scalar, a vector or a matrix. There are three different domain types, none, regular and relaxed. For GAMS Transfer Matlab users it is important to especially know the difference between the latter two.

  • None: Symbol is Either a Scalar or Defined Over the Universe Set.

    For example:

    Parameter(c, 'p_scalar');
    Parameter(c, 'p_vector', {'*'});
    Parameter(c, 'p_matrix', {'*', '*'});

    Here, * represents the universe set. Any domain entries are allowed. If a universe set is part of the domain, the size of the symbol is undefined.

  • Regular: Symbol is Defined Over Another Set.

    For example:

    i = Set(c, 'i');
    j = Set(c, 'j');
    Parameter(c, 'p_vector', {i});
    Parameter(c, 'p_matrix', {i, j});
    Parameter(c, 'p_matrix2', {*, j});

    Only domain entries that are in the Sets i, i x j or * x j, respectively, are allowed. Incorrect domain entries will lead to domain violations, see Domain Violations. The size of a symbol is given by the number of records in i and j (undefined for the p_matrix3).

  • Relaxed: Symbol is Defined Over a (Set) Name.

    For example:

    Parameter(c, 'p_vector', {'i'});
    Parameter(c, 'p_matrix', {'i', 'j'});
    Parameter(c, 'p_matrix2', {i, 'j'});
    Parameter(c, 'p_matrix3', {'i', *});

    Any domain entries are allowed (independently of possible previously defined Sets i and j). Domain violation checking is disabled! The size is undefined.

Creating a Symbol

To create a symbol, two equivalent ways exist:

The following table lists the required and possible arguments creating a the symbol. Here, the argument can be either of type required, optional (argument is positional but not required) or parameter (argument name and value have to be passed as pair, argument is not required). A # indicates the position if the argument is positional. The value in brackets is the default value if the argument is not required.

Argument Type Description Set Alias Parameter Variable Equation
name string Name of symbol required #1 required #1 required #1 required #1 required #1
alias_with Set Set an alias is linked to - required #2 - - -
type string, int Variable or Equation type, see VariableType and EquationType - - - optional #2 ('free') required #2
domain cell, Set, string List of domains given either as string ('*' for universe set) or as reference to a Set object optional #2 ('*') - optional #2 ({}) optional #3 ({}) optional #3 ({})
description string Description of symbol parameter ('') - parameter ('') parameter ('') parameter ('')
records any Symbol records, see also Efficiently Assigning Symbol Records parameter ([]) - parameter ([]) parameter ([]) parameter ([])
is_singleton logical Indicates if set is a singleton set (true) or not (false) parameter (false) - - - -

The other symbol properties are implied by those listed above. For example, dimension is the number of elements in domain.

All the above symbol properties can be modified at any time after the addition to the container. Furthermore, changing the property dimension has the following effect: Decreasing the dimension will remove domain elements at the back, while increasing the dimension will append appropriately many universe set domains *. Changing symbol properties may cause reevaluation of validity once an operation requires this changed symbol to be valid.

Note
If any domain element is passed as string except for * (universe set), the domain is handled relaxed instead of regular as indicated by the property domain_type, see also Symbol Domain. This means that domain checking does not apply, see also Domain Violations.

Efficiently Assigning Symbol Records

Need more convenience by sacrificing efficiency? Go to Conveniently Assigning Symbol Records.

Symbol records are stored in the property Symbol.records. It is most efficient to modify the data inplace. Note that the records have to satisfy the chosen records format. Otherwise, the symbol will be marked as invalid. Records are checked whenever a valid symbol is required. See Validate Symbol Records for more information.

Note
Performance hint: In case symbol records are updated within a loop, try to avoid checking the symbol validity within the loop. Note that symbol methods to query, for example, the number of records will check for a valid symbol internally. You can use the Matlab Profiler to verify that Symbol.isValid is not called within your loop.

Conveniently Assigning Symbol Records

Modifying the data as described in Efficiently Assigning Symbol Records requires to provide the data in one of the supported records format. For more convenience, the method Symbol.setRecords accepts a wide range of formats that will be transformed internally to one of the records format. Note that Symbol.setRecords is also called by the symbol constructor of the argument records is provided.

The following transformations are supported (sample code uses symbols of Example):

  • string:

    Interpreted as domain entry for first dimension.

    >> a.setRecords('seattle');
    >> a.transformRecords('table'); % format was struct
    >> a.records
    ans =
    table
    i_1
    _______
    seattle

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

    >> a.setRecords({'seattle', 'san-diego'});
    >> a.transformRecords('table'); % format was struct
    >> a.records
    ans =
    2×1 table
    i_1
    _________
    seattle
    san-diego

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

    >> a.setRecords([300 400]);
    >> a.transformRecords('table'); % format was dense_matrix
    >> a.records
    ans =
    2×2 table
    i_1 value
    _________ _____
    seattle 300
    san-diego 400

  • 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: (1) level or value, (2) marginal, (3) lower, (4) upper, (5) scale. If symbol is a Set, the (dim+1)-th cellstr is considered to be the set element text.

    Note
    Instead of a cell, it is possible to provide the elements as separate arguments to the method Symbol.setRecords.
    >> v.setRecords([1 2], [11 22], [111 222], [1111 2222]);
    >> v.transformRecords('table'); % format was dense_matrix
    >> v.records
    ans =
    2×5 table
    i_1 level marginal lower upper
    _________ _____ ________ _____ _____
    seattle 1 11 111 1111
    san-diego 2 22 222 2222
>> x.setRecords({'seattle', 'seattle'}, {'new-york', 'chicago'}, [1 2], [11 22], [111 222], [1111 2222]);
>> x.transformRecords('table'); % format was struct
>> x.records
ans =
2×6 table
i_1 j_2 level marginal lower upper
_______ ________ _____ ________ _____ _____
seattle new-york 1 11 111 1111
seattle chicago 2 22 222 2222
  • struct:
    Fields which names match domain labels, are interpreted as domain entries of the corresponding domain. Other supported fields are level, value, marginal, lower, upper, scale, text. Unsopprted fields are ignored.
  • table:
    Used as is, but checked for correctness.

Classes

class  Alias
 GAMS Alias. More...
 
class  Equation
 GAMS Equation. More...
 
class  EquationType
 GAMS Equation Types. More...
 
class  Parameter
 GAMS Parameter. More...
 
class  Set
 GAMS Set. More...
 
class  Symbol
 GAMS Symbol (Set, Alias, Parameter, Variable or Equation) More...
 
class  SymbolType
 GAMSTransfer Symbol Types. More...
 
class  Variable
 GAMS Variable. More...
 
class  VariableType
 GAMS Variable Types. More...