Equations

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.

Type Description
=e= Equality: right-hand side must equal left-hand side.
=g= Greater than: left-hand side must be greater than or equal to right-hand side.
=l= Less than: left-hand side must be less than or equal to right-hand side.
=n= No relationships enforced between left-hand side and right-hand side. This equation type is rarely used but can occur in MCP models and in the context of variational inequalities.
=x= Equation is defined by external programs. See External Equations.
=c= Conic constraint. See Conic Programming in GAMS.
=b= Boolean equations. See Logic Equations.

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.

Function Operator Alternative Notation Return Values Order of precedence
Negation not x bool_not(x) returns 1 if \(x=0\), else returns 0 1
Logical conjunction x and y bool_and(x,y) returns 1 if \(x=y=1\), else returns 0 2
Logical disjunction x or y bool_or(x,y) returns 0 if \(x=y=0\), else returns 1 3
Exclusive disjunctionx xor y bool_xor(x,y) returns 1 if exactly one argument is 1, else returns 0 3
Material implication x imp y or x -> y bool_imp(x,y) returns 0 if \(x=1\) and \(y=0\), else returns 1 3
Material equivalence x eqv y or x <=> y bool_eqv(x,y) returns 0 if exactly one argument is 0, else returns 1 3

Table 2: Boolean Functions and Operator Precedence

Note that in the table above \(x\) and \(y\) are binary variables.

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;

Note that currently logic equations are allowed only in models of the GAMS model type EMP. For more on GAMS model types see section Classification of Models.

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.

Functions are allowed ... Description of Functions
not at all Functions that are marked none in the third column of the tables listing all functions in section Functions.
only with exogenous arguments Functions that are marked any in the third column of the tables listing all functions in section Functions.
with endogenous arguments Smooth functions. They are marked NLP in the third column of the tables listing all functions in section Functions.
with endogenous arguments Discontinuous functions. They are marked DNLP in the third column of the tables listing all functions in section Functions.

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

Equation Attribute Symbol Description
Lower bound .lo Negative infinity or zero for a =g=, =e=, =c= or =b= equation.
Upper bound .up Positive infinity or zero for an =l=, =e= or =b= equation.
Equation level .l Level of the equation in the current solution, equal to the level of all terms involving variables.
Marginal .m Marginal value for equation. This attribute is reset to a new value when a model containing the equation is solved. The marginal value for an equation is also known as the shadow price for the equation and in general not defined before solution but if present it can help to provide a basis for the model
Scale factor .scale Numerical scaling factor that scales all coefficients in the equation. This is only used when the model attribute scaleopt is set to 1. For more on scaling, see section Model Scaling - The Scale Option.
Stage .stage This attribute allows to assign equations to stages in a stochastic program or other block structured model. Its current use is limited to 2-stage stochastic programs solved with DECIS.

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 be 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 but may be used in computations. They are given in Table 5.

Equation Attribute Symbol Description
Range .range The difference between the lower and upper bounds of an equation.
Slack lower bound .slacklo Slack from equation lower bound. This is defined as the greater of two values: zero or the difference between the level value and the lower bound of an equation.
Slack upper bound .slackupSlack from equation upper bound. This is defined as the greater of two values: zero or the difference between the upper bound and the level value of an equation.
Slack .slack Minimum slack from equation bound. This is defined as the minimum of two values: the slack from equation lower bound and the slack from equation upper bound.
Infeasibility .infeas Amount by which an equation is infeasible falling below its lower bound or above its upper bound. This is defined as max(0, lower bound - level, level - upper bound).

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]