Set Element Expressions

Use of set element expressions

Set element expressions reference a particular element or element tuple model from a set or a tuple domain. Set element expressions allow for sliced assignment-executing an assignment only for a lesser-dimensional subdomain by fixing certain dimensions to a specific set element. Potentially, this may lead to a vast reduction in execution times for time-consuming calculations.

Passing elements from the GUI

The most elementary form of a set element expression is an element parameter, which turns out to be a useful device for communicating set element information with the graphical interface. You can instruct AIMMS to locate the position in a table or other object where an end-user made changes to a numerical value, and have AIMMS pass the corresponding set element(s) to an element parameter. As a result, you can execute data input checks defined over these element parameters, thereby limiting the amount of computation. This issue is discussed in more detail in the help regarding the Identifier Selection dialog.

Element expressions

AIMMS supports several types of set element expressions, including references to parameters and (bound) indices, lag-lead-expressions, element-valued functions, and iterative-expressions. The last category turns out to be a useful device for computing the proper value of element parameters in your model.

Syntax

element-expression:

The format of list expressions are the same for element and numerical expressions. They are discussed in List Expressions.

Element references

An element reference is any reference to either an element parameter or a (bound) index.

Intrinsic Functions for Sets and Set Elements

The element-related functions…

AIMMS supports functions to obtain the position of an element within a set, the cardinality (i.e. number of elements) of a set, the \(n\)-th element in a set, the element in a non-compatible set with the identical string representation, and the numerical value represented by a set element. If S is a set identifier, i an index bound to S, \(l\) an element, and \(n\) a positive integer, then possible calls to the Ord, Card, Sets and set elements, ElementCast and Val functions are given in this table.

Table 2 Intrinsic functions operating on sets and set elements

Function	Value	Meaning
Ord(i)	integer	Ordinal, returns the relative position of the index i in the set S. Does not bind i.
Ord(\(l\),S)	integer	Returns the relative position of the element \(l\) in set S. Returns zero if \(l\) is not an element of S.
Card(S)	integer	Cardinality of set S.
Element(S,\(n\))	element	Returns the element in set S at relative position \(n\). Returns the empty element tuple if S contains less then \(n\) elements.
ElementCast(S, \(l\))	element	Returns the element in set S, which corresponds to the textual representation of an element \(l\) in any other index set.
Val(\(l\))	numerical	Returns the numerical value represented by \(l\), or a runtime error if \(l\) cannot be interpreted as a number
Max\((e_1,\dots,e_n)\)	Max	Returns the set element with the highest ordinal
Min\((e_1,\dots,e_n)\)	Min	Returns the set element with the lowest ordinal

…for simple sets

The Ord, Card and Sets and set elements functions can be applied to simple sets. In fact you can even apply Card to parameters and variables-it simply returns the number of nondefault elements associated with a certain data structure.

Crossing root set boundaries

By default, AIMMS does not allow you to use indices associated with one root set hierarchy in your model, in references to index domains associated with another root set hierarchy of your model. The function ElementCast allows you to cross root set boundaries, by returning the set element in the root set associated with the first (set) argument that has the identical name as the element (in another root set) passed as the second argument. The function ElementCast has an optional third argument create (values 0 or 1, with a default of 0), through which you can indicate whether you want elements which cannot be cast to the indicated set must be created within that set. In this case, a call to ElementCast will never fail. You can find more information about root sets, as well as an illustrative example of the use of ElementCast, in Binding Rules.

Example

In this example, we again use the set Cities initialized through the statement

Cities := DATA { Amsterdam, Rotterdam, 'The Hague', London, Paris, Berlin, Madrid } ;

The following table illustrates the intrinsic element-valued functions.

Expression	Result
Ord('Amsterdam', Cities)	1
Ord('New York', Cities)	0 (i.e. not in the set)
Card(Cities)	7
Element(Cities, 1)	'Amsterdam'
Element(Cities, 8)	" (i.e. no 8-th element)

The Val function

If your model contains a set with elements that represent numerical values, you cannot directly use such elements as a numerical value in numerical expressions, unless the set is an integer set (see Integer Sets). To obtain the numerical value of such set elements, you can use the Val function. You can also apply the Val function to strings that represent a numerical value. In both cases, a runtime error will occur if the element or string argument of the Val function cannot be interpreted as a numerical value.

The Min and Max functions

The element-valued Min and Max functions operate on two or more element-valued expressions in the same (sub-)set hierarchy. If the arguments are references to element parameters (or bound indices), then the Range attributes of these element parameters or indices must be sets in a single set hierarchy. Through these functions you can obtain the elements with the lowest and highest ordinal relative to the set equal to highest ranking range set in the subset hierarchy of all its arguments. If one or more of the arguments are explicit labels, then AIMMS will verify that these labels are contained in that set, or will return an error otherwise. A compiler error will result, if no such set can be determined (i.e., when the function call refers to explicit labels only).

Element-valued Iterative Expressions

Selecting elements

AIMMS offers special iterative operators that let you select a specific element from a domain. this table shows all such operators that result in a set element value. The syntax of iterative operators is explained in Iterative Set Operators. The second column in this table refers to the required number of expression arguments following the binding domain argument.

Table 3 Element-valued iterative operators

Name	# Expr.	Computes for all elements in the domain
First	0	the first element (tuple)
Last	0	the last element (tuple)
Nth	1	the \(n\)-th element (tuple)
Min	1	the value of the element expression for which the expression reaches its minimum ordinal value
Max	1	the value of the element expression for which the expression reaches its maximum ordinal value
ArgMin	1	the first element (tuple) for which the expression reaches its minimum value
ArgMax	1	the first element (tuple) for which the expression reaches its maximum value

Single index

The binding domain of the First, Last, Nth, Min, Max, ArgMin, and ArgMax operator can only consist of a single index in either a simple set, and the result is a single element in that domain. You can use this result directly for indexing or referencing an indexed parameter or variable. Alternatively, you can assign it to an element parameter in the appropriate domain.

Compared expressions

The ArgMin and ArgMax operators return the element for which an expression reaches its minimum or maximum value. The allowed expressions are:

• numerical expressions, in which case AIMMS performs a numerical comparison,

• string expressions, in which case AIMMS uses the normal alphabetic ordering, and

• element expressions, in which case AIMMS compares the ordinal numbers of the resulting elements.

For element expressions, the iterative Min and Max operators return expression values with the minimum and maximum ordinal value.

Example

The following assignments illustrate the use of some of the domain related iterative operators. The identifiers on the left are all element parameters.

FirstNonSupplyCity    := First ( i | not Exists(j | Transport(i,j)) ) ;
SecondSupplyCity      := Nth   ( i | Exists(j | Transport(i,j)), 2  ) ;
SmallestSupplyCity    := ArgMin( i, Sum(j, Transport(i,j))          ) ;
LargestTransportRoute := ArgMax( r, Transport(r)                    ) ;

Note that the iterative operators Exists and Sum are used here for illustrative purposes, and are not set- or element-related. They are treated in Logical Iterative Expressions and Numerical Iterative Operators, respectively.

Lag and Lead Element Operators

Lag and lead operators…

There are four binary element operators, namely the lag and lead operators +, ++, - and --. The first operand of each of these operators must be an element reference (such as an index or element parameter), while the second operand must be an integer numerical expression. There are no unary element operators.

…explained

Lag and lead operators are used to relate an index or element parameter to preceding and subsequent elements in a set. Such correspondence is well-defined, except when a request extends beyond the bounds of the set.

Noncircular versus circular

There are two kinds of lag and lead operators, namely noncircular and circular operators which behave differently when pushed beyond the beginning and the end of a set.

• The noncircular operators (+ and -) consider the ordered set elements as a sequence with no elements before the first element or after the last element.

• The circular operators (++ and --) consider ordered set elements as a circular chain, in which the first and last elements are linked.

Definition

Let S be a set, i a set element expression, and \(k\) an integer-valued expression. The lag and lead operators +, ++, -, -- return the element of S as defined in this table. Please note that these operators are also available in the form of +=, -=, ++= and --=. The operators in this form can be used in statements like:

CurrentCity := 'Amsterdam';
CurrentCity --= 1; ! Equal to CurrentCity := CurrentCity -- 1;

Table 4 Lag and lead operators

Lag/lead expr.	Meaning
\(\mathtt{i}\mathbin{\mathrm{+}}k\)	The element of S positioned \(k\) elements after i; the empty element if there is no such element.
\(\mathtt{i}\mathbin{\mathrm{++}}k\)	The circular version of \(\mathtt{i}\mathbin{\mathtt{+}}k\).
\(\mathtt{i}\mathbin{\mathrm{-}}k\)	The member of S positioned \(k\) elements before i; the empty element if there is no such element.
\(\mathtt{i}\mathbin{\mathrm{--}}k\)	The circular version of \(\mathtt{i}\mathbin{\mathtt{-}}k\).

Lag and lead operators for integer sets

For elements in integer sets, AIMMS may interpret the + and - operators either as lag/lead operators or as numerical operators. Integer Sets discusses the way in which you can steer which interpretation AIMMS will employ.

Not for literal elements

You cannot always use lag and lead operators in combination with literal set elements. The reason for this is clear: a literal element can be an element of more than one set, and in general, unless the context in which the lag or lead operator is used dictates a particular (domain) set, it is impossible for AIMMS to determine which set to work with.

Verify the effect of lags and leads

Lag and lead operators are frequently used in indexed parameters and variables, and may appear on the left- and right-hand side of assignments. You should be careful to check the correct use of the lag and lead operators to avoid making conceptual errors. For more specific information on the lag and lead operators refer to Assignment Statements, which treats assignments to parameters and variables.

Example

Consider the set Cities initialized through the assignment

Cities := DATA { Amsterdam, Rotterdam, 'The Hague', London, Paris, Berlin, Madrid } ;

Assuming that the index i and the element parameter CurrentCity both currently refer to 'Rotterdam', this table illustrates the results of various lag/lead expressions.

Table 5 Example of lag and lead operators

Lag/lead expression	Result
i+1	'The Hague'
i+6	"
i++6	'Amsterdam'
i++7	'Rotterdam'
i-2	"
i-2	'Madrid'
CurrentCity+2	'London'
'Rotterdam' + 1	ERROR