Table of Contents
A symbol is either a GAMS Set, Alias, Parameter, Variable or Equation.
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: Here,Parameter(c, 'p_scalar');Parameter(c, 'p_vector', {'*'});Parameter(c, 'p_matrix', {'*', '*'});
*
represents the universe set. Any domain entries are allowed. The size of the symbol is defined by the number of UELs.
- Regular: Symbol is Defined Over Another Set.
- For example: Only domain entries that are in the Setsi = Set(c, 'i');j = Set(c, 'j');Parameter(c, 'p_vector', {i});Parameter(c, 'p_matrix', {i, j});Parameter(c, 'p_matrix2', {*, j});function Parameter(in container, in varargin)GAMS Parameter Creator.
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 ini
andj
(undefined for thep_matrix3
).
- Relaxed: Symbol is Defined Over a (Set) Name.
- For example: Any domain entries are allowed (independently of possible previously defined SetsParameter(c, 'p_vector', {'i'});Parameter(c, 'p_matrix', {'i', 'j'});
i
andj
). Domain violation checking is disabled! The size of the symbol is defined by the number of UELs.
Creating a Symbol
To create a symbol, two equivalent ways exist:
- The factory methods Set, Alias, Parameter, Variable and Equation, e.g.: c = Container();p = Parameter(c, 'p');
- The methods Container.addSet, Container.addAlias, Container.addParameter, Container.addVariable and Container.addEquation, e.g.: c = Container();p = c.addParameter('p');
Both options allow overwriting a symbol with same name if the main symbol definition (e.g. type, domain) doesn't differ.
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 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 *
.
- Note
- If any domain element is passed as string except for
*
(universe set), the domain is handledrelaxed
instead ofregular
as indicated by the property domain_type, see also Symbol Domain. This means that domain checking does not apply, see also Domain Violations.
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.
For more convenience (but with performance costs!), 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 if 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.recordsans =tablei_______seattle
- cellstr:
- First dimension of
cellstr
must be equal to symbol dimension and second will be the number of records. Rowi
is interpreted to hold the domain entries for dimensioni
.>> a.setRecords({'seattle', 'san-diego'});>> a.transformRecords('table'); % format was struct>> a.recordsans =2×1 tablei_________seattlesan-diego
- numeric vector/matrix:
- Interpreted to hold the
level
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.>> a.setRecords([300 400]);>> a.transformRecords('table'); % format was dense_matrix>> a.recordsans =2×2 tablei value_________ _____seattle 300san-diego 400
- cell:
If element is the
i
-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: (1)level
orvalue
, (2)marginal
, (3)lower
, (4)upper
, (5)scale
. If symbol is a Set, the(dim+1)
-th cellstr is considered to be the setelement_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.recordsans =2×5 tablei level marginal lower upper_________ _____ ________ _____ _____seattle 1 11 111 1111san-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.recordsans =2×6 tablei j_2 level marginal lower upper_______ ________ _____ ________ _____ _____seattle new-york 1 11 111 1111seattle 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
,element_text
. Unsopprted fields are ignored.
- table:
- Used as is, but checked for correctness.