Introduction

The keyword equation defines GAMS names that may be used in the model statement. A GAMS equation name is associated with the symbolic algebraic relationships that will be used to generate the constraints in a model. The algebraic relationships are defined by using constants, mathematical operators, functions, sets, parameters and variables. As with variables, one GAMS equation may be defined over a group of sets and in turn map into several individual constraints associated with the elements of those sets. Most of the example code in this chapter is from the model location.

This chapter is organized as follows. First, we introduce how equations are declared and defined, then we discuss expressions in equation definitions, followed by a section on equation attributes. A summary and quick reference conclude the chapter.

Declaring Equations

An equation must be declared before it can be defined and used in a model.

The Syntax

The declaration of an equation is similar to a set or parameter declaration. The syntax is given below.

Equation[s] eqn_name [(index_list)] [explanatory text] [/eqn_data/] {, eqn_name [(index_list)] [explanatory text] [/eqn_data/]} ;

Equation[s] is the reserved word that indicates that one or more blocks of equations are about to be declared. A block of equations may initiate one or more individual constraints. Eqn_name is the internal name of the equation, an identifier in GAMS. In the optional index_list the set or sets are specified over which an indexed equation is declared. The optional explanatory text may be used to describe the equation for future reference and to ease readability. Specifying equation data is another optional element in the equation declaration. Equation data allows to initialize equation attributes at compile time. For an example see the next section. For more on equation attributes see section Equation Attributes.

One or more equations may be declared in one equation statement. The equation names have to be separated by commas or by a line break as in the example that follows. The end of the declaration statement is indicated by a semicolon.

Note

It is good practice to end the equation declaration with a semicolon, even though it is not mandatory if the next statement starts with a GAMS keyword.

For advice on choosing equation names and phrasing the explanatory text see chapter Good Modeling Practices.

An Illustrative Example

The following example is from the model location. In addition to the equation declarations the relevant set definitions are given.

Sets
  sl                      'supply locations'               /s1, s2/
  wh                      'warehouse locations'            /a, b, c/;

Equations
  tcost_eq                'total cost accounting equation'
  supply_eq(sl)           'limit on supply available at supply location'
  capacity_eq(wh)         'warehouse capacity'  /a.scale 50, a.l 10, b.m 20/;

The keyword Equations marks the beginning of the equation declaration. Each equation name is optionally followed by its domain (associated set or sets) unless it is a scalar equation. It is possible but not good practice to declare indexed equations without their domains. The name of the first equation is tcost_eq and it is followed by the explanatory text 'total cost accounting equation'. The name of the equation tcost_eq is not followed by any associated sets. Since we follow good practice here we assume that tcost_eq is a scalar equation. Scalar equations do not have any associated sets and will generally produce one equation in the model. For more on scalar equations see subsection Scalar Equations.

The other two equations are indexed equations, they are declared over a set. The equation supply_eq is declared over the set sl and the equation capacity_eq is declared over the set wh. In typical circumstances an indexed equation declaration implies that a block of constraints will be generated. For example, equation supply_eq(sl) implies that two constraints will be generated, one for each element of the set sl. For more on indexed equations see subsection Indexed Equations.

The declaration of the equation capacity_eq specifies some equation attributes. The first entry indicates that the equation capacity_eq('a') is scaled by a factor of 50, which means division of all entries in that equation by 50 upon model passage to the solver. For more on scaling see section Model Scaling - The Scale Option. The second entry sets the initial value of the equation capacity_eq('a') to 10 and b.m means that the initial marginal value of the equation capacity_eq('b') is set to 20. Alternatively, a table structure may be used to specify the values of equation attributes. The following table may replace the notation above.

Equation Table capacity_eq(wh)  'warehouse capacity'
      scale    l       m
   a   50      10
   b                   20 ;

For more on equation attributes see section Equation Attributes.

Note

An equation may be declared over more than one set.

Defining Equations

After declaring equations they have to be defined. The definition of an equation specifies the algebraic structure of the equation in GAMS. The syntax is given first, an illustrative example follows and in the remainder of this section some of the key components of equation definitions are discussed.

The Syntax

The syntax for defining an equation is as follows:

eqn_name(index_list)[$logical_condition(s)].. expression eqn_type expression ;

Eqn_name is the name of the equation as introduced in the equation declaration, that may be followed by an index_list for indexed equations. In the index_list the set or sets are specified over which an indexed equation is defined. These sets are also called domain of definition of the equation. One or more logical conditions are optional. For an example see Indexed Equations. For more on logical conditions in equation definitions see Dollar Control over the Domain of Definition. The two dots '..' are mandatory and indicate the start of the algebra. It is good practice to end the definition of an equation with a semicolon, even though it is not mandatory if the next statement starts with a GAMS keyword.

Attention

An equation must be declared before it is defined.

Expression refers to an algebraic expression which may include variables, parameters, functions, and constants among other items. For details on expressions in GAMS, see section Expressions.

Attention

Only variables that appear at least once with a nonzero coefficient in an equation definition will appear in a model.

Eqn_type refers to the equation type denoted by the symbol between the right-hand side and left-hand side expressions that form the equation. The symbols that are allowed are given in Table 1.

Table 1: Equation Types

Equation definitions may be carried over as many lines of input as needed. Blanks may be inserted to improve readability, and expressions may be arbitrarily complicated.

Note that an equation can only be defined once. By using logical conditions it is possible to control which constraints are generated. In addition, the components of an equation may be modified by changing the data it uses. However, if the logic of the equation needs to be changed then a new equation with a new name has to be declared and defined.

An Illustrative Example

Consider the following example adapted from the model [mexss]. The associated variable and equation declarations are also included.

Variables  phi, phipsi, philam, phipi, phieps ;
Equations  obj ;
obj.. phi  =e=  phipsi + philam + phipi - phieps ;

The name of the equation being defined is obj and the symbol =e= indicates that this is an equality. Any of the following forms of the equation are mathematically equivalent.

obj..  phipsi + philam + phipi - phieps =e= phi  ;
obj..  phieps - phipsi  =e=  philam - phi + phipi  ;
obj..  phi + phieps - phipsi - philam - phipi  =e=  0 ;
obj..  0 =e= phi + phieps - phipsi - philam - phipi  ;

Note

The arrangement of the terms in the equation is a matter of choice, but often a particular one is chosen because it makes the model easier to understand.

Scalar Equations

A scalar equation will produce one equation in the associated optimization problem. The equation obj defined above is an example of a scalar equation which contains only scalar variables. Note that scalar equations may contain indexed variables. However, they must occur with an indexed operator such as sum or prod, unless the indexed variables refer to a singleton set (a set with only one element). Consider the following example from the model location. Note that the set wh has three elements.

configure_eq..  sum(wh,build(wh)) =l= 1;

The variable build is defined over the set wh, it is an indexed variable. It may be used in the scalar equation configure_eq since it occurs in conjunction with the indexed operator sum.

Indexed Equations

All the set references in scalar equations are within the scope of indexed operators or they refer to singleton sets; thus many variable, set and parameter references can be included in one equation. In addition, GAMS also allows for equations to be defined over a domain, thereby developing a compact representation for constraints. The index sets to the left of '..' are called the domain of definition of the equation.

Note

• Domain checking ensures that the domain over which an equation is defined is the set (or the sets) or a subset of the set (or the sets) over which the equation was declared.
• As a corollary, domain checking also catches the error of the indices being listed in an inconsistent order. For example, declaring an equation as myequation(s,t) and then naming it in the definition as myequation(t,s) causes an error (unless s and t are aliases of the same set). For more information, see section Domain Checking.

The following indexed equation with a single index generates a separate constraint for each member of the driving (or controlling) set. It is taken from the model [chenery]. In this example, t is a set with three members, mew and xsi are parameters and m and g are variables.

dg(t)..  g(t)  =e= mew(t) + xsi(t)*m(t)  ;

As the set t has three members, three constraints will be generated, one for each member of t specifying the dependence of g on m. The data associated with the parameters mew and xsi are used to build the individual constraints. This data does not have to be known when the equation is defined, but it has to be populated before a model containing the equation is solved.

The extension to two or more indices on the left of '..' is obvious. There will be one constraint generated for each combination of set elements that can be constructed using the indices inside the parenthesis. Here are two examples from the model [aircraft], a scheduling model.

bd(j,h)..  b(j,h)  =e=  dd(j,h) - y(j,h) ;
yd(j,h)..  y(j,h)  =l=  sum(i, p(i,j)*x(i,j)) ;

The domain of definition of both equations is the Cartesian product of j and h: constraints will be generated for every set element pair that can be constructed from the members of these two sets.

The next example illustrates the use of the optional logical conditions in the definition of equations. It is taken from the production and distribution model [ferts].

CC(m,i)$mpos(m,i)..  sum(p$ppos(p,i), b(m,p)*z(p,i)) =l= util*k(m,i) ;

CC is a capacity constraint defined for elements of the sets m and i. However, in this case not all cases of m exist at each location i, and the mapping set mpos(m,i) tells the cases where m exists at i and thus is used to restrict the domain cases for which the constraints are actually generated. The control of the summation over p with ppos(p,i) is an additional logical condition, and is required because not all processes p are possible at all locations i.

The equation may alternatively written in the following way:

CC(mpos(m,i))..  sum(ppos(p,i), b(m,p)*z(p,i)) =l= util*k(m,i) ;

Instead of defining the equation over the indices (m,i) the equation is defined over the set mpos that is itself defined over the indices (m,i). A similar logic applies to restricting the summation.

Conditional expressions are introduced and discussed in the section Conditional Expressions, Assignments and Equations. See specifically Dollar Control over the Domain of Definition for logical conditions in equation definitions.

Using Labels Explicitly in Equations

Sometimes it can be necessary to refer to specific set elements in equations. This can be done as with parameters - by using quotes or double quotes around the label. Consider the following example from the model location:

sum(m, ship_wm(wh,m)) =l= build(wh)*data(wh,"capacity") ;

Logic Equations

Logic equations use Boolean algebra and have to evaluate to TRUE (or 1) to be feasible. The Boolean functions available in GAMS and the default order of precedence of the operators are given in Table 2. Note that 1 denotes the highest order of precedence or the most binding operator and 3 denotes the lowest order of precedence or the least binding operators. As usual, the default order of precedence holds only in the absence of parentheses and operators on the same level are evaluated from left to right.

Table 2: Boolean Functions and Operator Precedence

There are three ways to declare and define logic equations:

1. The logic equation is declared using the keyword Logic Equation and the definition contains only Boolean algebra symbols.
2. The logic equation is declared like any other equation using the keyword Equation and in the definition the symbol =b= appears indicating that it is a logic equation.
3. This is a combination of the first two options: the equation is declared with the keyword Logic Equation and defined using the symbol =b=.

The following example demonstrates the first way to declare and define a logic equation. It is adapted from the food manufacturing problem [foodemp]. In this problem the blending of oils is modeled.

Sets
  m             "planning period (month)"    / m1*m6 / 
  p             "raw oils"                   / v1*v2, o1*o3 / ;

Variables
  induse(m,p)   "indicator for usage of raw oil per month" ;
Binary variable induse;

Logic Equation
  deflogic(m)  "if some vegetable raw oil is used we also need to use the non-vegetable oil o3" ;

deflogic(m)..  induse(m,'v1') or  induse(m,'v2') -> induse(m,'o3');

The variable induse is a binary variable, it can only take the values 0 and 1. The equation ensures that in an optimal solution if either vegetable oil v1 or vegetable oil v2 is blended in a product, then non-vegetable oil o3 is also blended in that product.

An alternative formulation of the equation deflogic using the =b= notation is given below.

deflogic(m)..  induse(m,'v1') or induse(m,'v2') -> induse(m,'o3') =b= 1;

Note that the value of 1 on the right-hand side means that the logic expression on the left-hand side must evaluate to TRUE in a feasible solution. To illustrate further, we could negate the left-hand side expression using the logic operator not and then the right-hand side would have to evaluate to zero or FALSE to yield the same result as above. The respective equation definition follows.

deflogic(m)..  not (induse(m,'v1') or  induse(m,'v2') -> induse(m,'o3')) =b= 0;

Logic equations with binary variables and boolean functions/operators are reformulated into linear constraints by the LOGMip solver using GAMS model type EMP. Solver CONVERT writes scalar models with logic equations, but no other solver currently can utilize logic equations. In principle (but currently not implemented), logic constraints can be used to express complex algebra, like indicator constraints:

defindic(m)..  induse(m,'v1') = 1 -> sum(p, use(m,p)) >= minuse(m);

Expressions in Equation Definitions

The arithmetic operators and some of the functions that are described in section Expressions may be used in equation definitions.

Consider the following example adapted from the model [chenery] demonstrating the use of parentheses and exponentiation.

dem(i) ..    y(i)  =e= ynot(i)*(pd*p(i))**thet(i)  ;

A list of arithmetic operators is given in subsections Standard Arithmetic Operations and Indexed Operations.

Functions in Equation Definitions

All available GAMS functions are listed in the section Functions. Some functions are not allowed at all in equation definitions. They include random distribution functions and are marked with none in the third column of the tables listing all functions.

Attention

Some functions like uniform and normal are not allowed in equation definitions.

The use of the other functions is determined by the type of arguments in the model. There are two types of arguments:

1. Exogenous arguments: The arguments are known. Parameters and variable attributes (for example, .l and .m attributes) are used as arguments. The expression is evaluated once when the model is being set up and most mathematical functions as well as time and calendar functions are allowed.
2. Endogenous arguments: The arguments are variables and therefore unknown at the time of model setup. The function will be evaluated many times at intermediate points while the model is being solved. Note that the occurrence of any function with endogenous arguments implies that the model is not linear.

Functions that are allowed only with exogenous arguments are marked with any in the tables listing all functions.

There are two types of functions allowing endogenous arguments: smooth functions and discontinuous functions. Smooth functions are continuous functions with continuous derivatives (like sin, exp, log). Discontinuous functions include continuous functions with discontinuous derivatives (like max, min, abs) and discontinuous functions (like ceil, sign). Smooth functions may be used routinely in nonlinear models. However, discontinuous functions may cause numerical problems and should be used only if unavoidable, and only in a special model type called DNLP. For more details on model types see section Classification of Models.

Attention

The best way to model discontinuous functions is with binary variables. The result is a model of the type MINLP. The model [ABSMIP] demonstrates this formulation technique for the functions abs, min, max and sign. See also section Reformulating DNLP Models. We strongly discourage the use of the DNLP model type.

In Table 3 the use of functions in equation definitions is summarized.

Table 3: Functions in Equation Definitions

Preventing Undefined Operations in Equations

Some operations are not defined at particular values of the arguments. Two examples are division by 0 and the log- of 0. While this can easily be identified at model setup for exogenous functions and expressions, it is a lot more difficult when the terms involve variables. The expression may be evaluated many times when the problem is being solved and the undefined result may arise only under certain cases. One way to avoid an expression becoming undefined is adding bounds to the respective variables. Consider the following example from the model [ramsey]:

c.lo(t) = 0.01 ;
util ..   utility  =e= sum(t, beta(t)*log(c(t))) ;

Specifying a lower bound for c(t) that is slightly larger than 0 prevents the log-function from becoming undefined.

Equation Attributes

Equation attributes may be specified in a similar way as variable attributes. Five values are associated with each unique label combination of every equation. They are denoted by the suffixes .l, .m, .lo, .up and .scale. A list of the attributes and their description is given in Table 4.

Table 4: Equation Attributes

Note that all attributes except for .scale and .stage contain the attribute values of equations after a solution of the model has been obtained. For some solvers it can be useful to specify marginal values .m and level values .l on input to provide starting information. Also note that the marginal value is also known as the dual or shadow price. Roughly speaking, the marginal value .m of an equation is the amount by which the value of the objective variable would change if the equation level were moved one unit.

Equation attributes may be referenced in expressions and can be used to specify starting values (see section Declaring Equations). In addition, they serve for scaling purposes and for reporting after a model was solved. For example, they may be displayed using the display statement. The following example is from the model location.

Model warehouse 'warehouse location model'  /all/;
solve warehouse using mip min tcost;
display supply_eq.l;

The display statement generates the following output at the end of the listing file:

----    108 EQUATION supply_eq.L  limit on supply available at supply location

s1 50.000,    s2 75.000

The level values of the equation supply_eq are displayed. As expected, there are two level values, one for each member of the set sl over which the equation supply_eq was defined.

Note

By default, all equation attributes introduced above except for .scale are echoed to the solution report that is part of the listing file.

In addition to the equation attributes introduced above, there are a number of equation attributes that cannot be assigned or exported via execute_unload* but may be used in computations. They are given in Table 5.

Table 5: Additional Equation Attributes that Cannot Be Assigned but May Be Used in Computations.

Summary and Quick Reference

In this chapter we have covered the declaration and definition of equations in GAMS, arithmetic operations and functions that may be used in equations and equation attributes. A list summarizing the main points to keep in mind follows.

• Equations must be declared before they may be defined. [1]
• It is good practice to add an explanatory text to the declaration. [2]
• More than one equation may be declared at once. The equation names have to be separated by commas or by a line break. [3]
• Equations may be declared and defined over sets which are called the domain of definition of the equation. [4]
• One indexed equation may generate many constraints depending on the size of the set(s) over which it is defined. [5]
• Equations may be defined over subsets. The dollar condition may be used to filter the members of a set so that only a subset of the members are considered. [6]
• The set(s) over which an equation is defined must be consistent with the set(s) over which the equation was declared, being the set(s) themselves or a subset of the set(s). [7]
• The arrangement of terms in an equation is up to the other. Variables can appear on both sides of an equation. [8]
• Labels of specific set elements may be used explicitly in equations. [9]
• All arithmetic operations that may be used to evaluate expressions are also allowed in equations. [10]
• Many functions that are defined in GAMS may be used in equations. [11]
• It is good practice to set bounds for variables to avoid undefined operations if equations contain operations that are undefined at certain values. [12]
• Equations have attributes similar to variables (.l, .m, .lo, .up and .scale). [13]