GAMS [ Home | Downloads | Documentation | Solvers | APIs | Tools | Model Libraries | Resources | Sales | Support | Contact Us | Search ]

Model and Solve Statements

Introduction

This chapter brings together all the concepts discussed in previous chapters by explaining how to specify a model and solve it.

The Model Statement

The model statement is used to collect equations into groups and to label them so that they can be solved. The simplest form of the model statement uses the keyword all: the model consists of all equations declared before the model statement is entered. For most simple applications this is all you need to know about the model statement.

The Syntax

In general, the syntax in GAMS for a model declaration is:

model[s] model_name [text] [/ all | eqn_name {, eqn_name} /]
       {,model_name [text] [/ all | eqn_name {, eqn_name} /]} ;

Model_name is the internal name of the model (also called an identifier) in GAMS . The accompanying text is used to describe the set or element immediately preceding it. Eqn_name is the name of an equation that has been declared prior to the model statement.

As with all identifiers, model_name has to start with a letter followed by more letters or digits. It can only contain alphanumeric characters, and can be up to 63 characters long. Explanatory text must not exceed 80 characters and must all be contained on the same line as the identifier or label it describes.

An example of a model definition in GAMS is shown below.

Model   transport   "a transportation model"   / all /  ;

The model is called transport and the keyword all is a shorthand for all known (declared) equations.

Several models can be declared (and defined) in one model statement. This is useful when experimenting with different ways of writing a model, or if one has different models that draw on the same data. Consider the following example, adapted from [PROLOG], in which different groups of the equations are used in alternative versions of the problem. Three versions are solved – the linear, nonlinear, and 'expenditure' versions. The model statement to define all three is

model  nortonl   "linear version"      / cb,rc,dfl,bc,obj /
       nortonn   "nolinear version"    / cb,rc,dfn,bc,obj /
       nortone   "expenditure version  / cb,rc,dfe,bc,obj /  ;

where cb, rc, etc. are the names of the equations. We will describe below how to obtain the solution to each of the three models.

Classification of Models

Various types of problems can be solved with GAMS. The type of the model must be known before it is solved. The model types are briefly discussed in this section. GAMS checks that the model is in fact the type the user thinks it is, and issues explanatory error messages if it discovers a mismatch - for instance, that a supposedly linear model contains nonlinear terms. This is because some problems can be solved in more than one way, and the user has to choose which way to go. For instance, if there are binary or integer variable in the model, it can be solved either as a MIP or as a RMIP.

The problem type and their identifiers, which are needed in the a solve statement, are listed below.

Problem Type Description
LP Linear programming. There are no nonlinear terms or discrete (binary or integer) variables in your model.
QCP Quadratic constraint programming. There are linear and quadratic terms but no general nonlinear term or discrete (binary or integer) variables in your model.
NLP Nonlinear programming. There are general nonlinear terms involving only smooth functions in the model, but no discrete variables. The functions were classified as to smoothness in the previous chapter.
DNLP Nonlinear programming with discontinuous derivatives. This is the same as NLP, except that non-smooth functions can appear as well. These are more difficult to solve than normal NLP problems. The user is strongly recommended not to use this model type.
RMIP Relaxed mixed integer programming. The model can contain discrete variables but the discrete requirements are relaxed, meaning that the integer and binary variables can assume any values between their bounds.
MIP Mixed integer programming. Like RMIP but the discrete requirements are enforced: the discrete variables must assume integer values between their bounds.
RMIQCP Relaxed mixed integer quadratic constraint programming. The model can contain both discrete variables and quadratic terms. The discrete requirements are relaxed. This class of problem is the same as QCP in terms of difficulty of solution.
RMINLP Relaxed mixed integer nonlinear programming. The model can contain both discrete variables and general nonlinear terms. The discrete requirements are relaxed. This class of problem is the same as NLP in terms of difficulty of solution.
MIQCP Mixed integer quadratic constraint programming. Characteristics are the same as for RMIQCP, but the discrete requirements are enforced.
MINLP Mixed integer nonlinear programming. Characteristics are the same as for RMINLP, but the discrete requirements are enforced.
RMPEC Relaxed Mathematical Programs with Equilibrium Constraints.
MPEC Mathematical Programs with Equilibrium Constraints.
MCP Mixed Complementarity Problem.
CNS Constrained Nonlinear System.
EMP Extended Mathematical Program.

Constrained Nonlinear Systems

Mathematically, a Constrained Nonlinear System (CNS) model looks like:

\begin{equation} \begin{array}{ll} \textrm{find} & x \\ & \\ & F(x) = 0 \\ \textrm{subject to} & L \leq x \leq U \\ & G(x) \leq b \\ \end{array} \end{equation}

where \(F\) and \(x\) are of equal dimension and the variables \(x\) are continuous. The (possibly empty) constraints \(L \leq x \leq U \) are not intended to be binding at the solution, but instead are included to constrain the solution to a particular domain or to avoid regions where \(F(x)\) is undefined. The (possibly empty) constraints \(G(x) \leq b\) are intended for the same purpose and are silently converted to equations with bounded slacks.

The CNS model is a generalization of the square system of equations \(F(x) = 0\). There are a number of advantages to using the CNS model type (compared to solving as an NLP with a dummy objective, say), including:

  • A check by GAMS that the model is really square,
  • solution/model diagnostics by the solver (e.g. singular at solution, locally unique solution),
  • and potential improvement in solution times, by taking better advantage of the model properties.

The CNS model class is solved with a solve statement of the form:

    SOLVE <MODEL> USING CNS;

without the usual objective term. The CNS solver can be selected during installation or with the usual OPTION CNS = Solver;statement.

For information on CNS solvers that can be used through GAMS see the Solver/Model type Matrix.

Solve Status values

A CNS solver will return one of the following solver status values:

Status Value Meaning
Solverstat = 1Normal completion
Solverstat = 2Iteration Interrupt
Solverstat = 3Resource Interrupt
Solverstat = 5Evaluation Error Limit
Solverstat = 8User Interrupt

where the definitions are the same as for other model classes. The CNS solver will return one of the following model status values:

Status Value Meaning and Description
Modelstat = 15Solved Unique : The model was solved and the solution is globally unique.
Modelstat = 16Solved : The model was solved.
Modelstat = 17Solved Singular : The model was solved, but the Jacobian is singular.
Modelstat = 4 Infeasible : The model is guaranteed to have no solution, for example because the model or a critical subset of the model is linear and inconsistent.
Modelstat = 5 Locally infeasible : The model could not be solved. The word locally indicates that the solver has not determined that no solution could exist, as compared to the global infeasibility implied by Modelstat=4.
Modelstat = 6 Intermediate infeasible : The solver was stopped by an iteration, resource, or evaluation error limit or by a user interrupt.

Additional comments

Some special comments relating to CNS models apply:

  • There is no objective and therefore no marginal values, either for variables or for equations. The solution listing will therefore not have the MARGINAL column. Any marginal values already stored in the GAMS database will remain untouched.
  • A singular model flags a set of linearly dependent rows and columns with DEPND in the solution listing. The number of dependencies reported is made available by GAMS via the <model>.numdepnd model attribute. This can be tested in the usual way. Note that a row/column pair for a linear dependence contributes one to numdepnd. Also note that there may be more linear dependencies than the ones reported.
  • An infeasible or locally infeasible model, or a singular model with infeasibilities, flags the infeasible constraints and variables with the usual INFES flag. The number of infeasibilities is available via the usual <model>.numinfes model attribute.

Nonlinear Programming with Discontinuous Derivatives

Mathematically, the Nonlinear Programming with Discontinuous Derivatives (DNLP) Problem looks like:

\begin{equation*} \begin{array}{ll} \textrm{Minimize} & f(x)\\ & \\ \textrm{ st } & g(x) \leq 0 \\ & L \leq x \leq U \\ \end{array} \end{equation*}

where \(x\) is a vector of variables that are continuous real numbers. \(f(x)\) is the objective function, and \(g(x)\) represents the set of constraints. \(L\) and \(U\) are vectors of lower and upper bounds on the variables. This is the same as NLP , except that non-smooth functions (abs, min,max) can appear in \(f(x)\) and \(g(x)\).

For information on DNLP solvers that can be used through GAMS see the Solver/Model type Matrix.

Linear Programming

Mathematically, the Linear Programming (LP) Problem looks like:

\begin{equation*} \begin{array}{ll} \textrm{ Minimize or maximize} & cx \\ \textrm{subject to} & Ax \geq b \\ & L \leq x \leq U \\ \end{array} \end{equation*}

where \(x\) is a vector of variables that are continuous real numbers. \(cx\) is the objective function, and \(Ax \geq b\) represents the set of constraints. \(L\) and \(U\) are vectors of lower and upper bounds on the variables.

GAMS supports both free variables (unrestricted), positive variables, and negative variables. In addition user specified lower and upper bounds can be provided.

In a GAMS model equations are specified as a combination of less-than-or-equal-to or greater-than-or-equal-to inequalities and equalities (equal-to constraints).

For information on LP solvers that can be used through GAMS see the Solver/Model type Matrix.

Mixed Complementarity Problem

Mathematically, the Mixed Complementarity Problem (MCP) looks like:

\begin{equation*} \begin{array}{ll} \textrm{Find } & z,~w,~v \\ \textrm{ such that} & F(z) = w-v \\ & l \leq z \leq u,~ w \geq 0,~ v \geq 0 \\ & w'(z-l) = 0,~ v'(u-z) = 0\\ \end{array} \end{equation*}

MCP's are a class of mathematical programs which can be formulated in GAMS and solved by one of the MCP solvers that are hooked up to GAMS: see the Solver/Model type Matrix.

MCP's arise in many application areas including applied economics, game theory, structural engineering and chemical engineering.

Complementarity problems are easily formulated in the GAMS language. The only additional requirement beyond general NLP's is the definition of complementarity pairs.

MCP's constitute a fairly general problem class. It encompasses systems of nonlinear equations, non-linear complementarity problems and finite dimensional variational inequalities. Also inequality-constrained linear, quadratic and nonlinear programs are MCP's (although for these problems you may expect specialized solvers to do better). For instance, when we set the lower bounds \(l\) to minus infinity and \(u\) to plus infinity, both \(w\) and \(v\) have to be zero. This results in the problem

\begin{equation*} \begin{array}{ll} \textrm{Find } & z \\ \textrm{such that} & F(z) = 0 \\ \end{array} \end{equation*}

which is a system of non-linear equations.

Mixed Integer Nonlinear Programming

Mathematically, the Mixed Integer Nonlinear Programming (MINLP) Problem looks like:

\begin{equation*} \begin{array}{ll} \textrm{Minimize} & f(x) + Dy \\ \textrm{st} & g(x) + Hy \leq 0 \\ & L \leq x \leq U \\ & y = \{0,1,2,\cdots\}\\ \end{array} \end{equation*}

where \(x\) is a vector of variables that are continuous real numbers. \(f(x)+ Dy\) is the objective function, and \(g(x) + Hy\) represents the set of constraints. \(L\) and \(U\) are vectors of lower and upper bounds on the variables.

For information on MINLP solvers that can be used through GAMS see the Solver/Model type Matrix.

Mixed Integer Programming

Mathematically, the Mixed Integer Linear Programming (MIP) Problem looks like:

\begin{equation*} \begin{array}{ll} \textrm{Minimize} & cx + dy \\ \textrm{st} & Ax + By \geq b \\ & L \leq x \leq U \\ & y = \{0,1,2,\cdots\}\\ \end{array} \end{equation*}

where \(x\) is a vector of variables that are continuous real numbers, and \(y\) is a vector in variables that can only take integer values. \(cx + dy\) is the objective function, and \(Ax + By \geq b\) represents the set of constraints. \(L\) and \(U\) are vectors of lower and upper bounds on the continuous variables, and \(y=\{0,1,2,\cdots\}\) is the integrality requirement on the integer variables \(y\).

For information on MIP solvers that can be used through GAMS see the Solver/Model type Matrix.

Mathematical Program with Equilibrium Constraints

Mathematically, the Mathematical Program with Equilibrium Constraints (MPEC) Problem looks like:

\begin{equation*} \begin{array}{ll} \textrm{Maximize or Minimize} & f(x,y) \\ \textrm{subject to} & g(x,y) \leq 0 \\ & Lx \leq x \leq Ux \\ & F(x,y)~perp-to~ Ly \leq y \leq Uy \\ \end{array} \end{equation*}

where \(x\) and \(y\) are vectors of continuous real variables. The variables \(x\) are often called the control or upper-level variables, while the variables \(y\) are called the state or lower-level variables. \(f(x,y)\) is the objective function. \(g(x,y)\) represents the set of traditional (i.e. NLP-type) contraints; in some cases, they can only involve the control variables \(x\). The function \(F(x,y)\) and the bounds \(Ly\) and \(Uy\) define the equilibrium constraints. If \(x\) is fixed, then \(F(x,y)\) and the bounds \(Ly\) and \(Uy\) define an MCP; the perp-to indicates that such a complementary relationship holds. From this definition, we see that the MPEC model type contains NLP and MCP models as special cases of MPEC.

While the MPEC model formulation is very general, it also results in problems that are very difficult to solve. Work on MPEC algorithms is not nearly so advanced as that for the other model types. As a result, the MPEC solvers included in the GAMS distribution are experimental or beta versions.

For information on MPEC solvers that can be used through GAMS see the Solver/Model type Matrix.

Nonlinear Programming

Mathematically, the Nonlinear Programming (NLP) Problem looks like:

\begin{equation*} \begin{array}{ll} \textrm{Minimize} & f(x) \\ \textrm{st} & g(x) \leq 0 \\ & L \leq x \leq U \\ \end{array} \end{equation*}

where \(x\) is a vector of variables that are continuous real numbers. \(f(x)\) is the objective function, and \(g(x)\) represents the set of constraints. \(L\) and \(U\) are vectors of lower and upper bounds on the variables.

For information on NLP solvers that can be used through GAMS see the Solver/Model type Matrix.

Quadratically Constrained Programs

A Quadratically Constrained Program (QCP) is a special case of the NLP in which all the nonlinearities are required to be quadratic. As such, any QCP model can also be solved as an NLP. However, most "LP" vendors provide routines to solve LP models with a quadratic objective. Some allow quadratic constraints as well. Solving a model using the QCP model type allows these "LP" solvers to be used to solve quadratic models as well as linear ones. Some NLP solvers may also take advantage of the special (quadratic) form when solving QCP models. In case a model with quadratic constraints is passed to a QCP solver that only allows a quadratic objective, a capability error (solver status 6 CAPABILITY PROBLEMS) will be returned.

For information on QCP solvers that can be used through GAMS see the Solver/Model type Matrix.

Mixed Integer Quadratically Constrained Programs

A Mixed Integer Quadratically Constrained Program (MIQCP) is a special case of the MINLP in which all the nonlinearities are required to be quadratic. For details see the description of the QCP, a special case of the NLP.

For information on MIQCP solvers that can be used through GAMS see the Solver/Model type Matrix.

Model Attributes

Model attributes can be accessed through

        model_name.attribute

Some of the attributes are mainly used before the solve statement to provide information to GAMS or the solver link. Others are set by GAMS or the solver link and hence are mainly used after a solve statement.

Moreover, some of the input attributes can also be set globally via an option statement or the command line, e.g.

        option reslim = 10
        gamsmodel.gms reslim = 10

Note that a model specific option takes precedence over the global setting and that a setting via an option statement takes precedence over one via the command line parameter.

The complete list of model attributes is shown below. The third and fourth column indicate whether there is also a global option and/or a command line parameter.

Model Attributes mainly used before solve

AttributeDescriptionoptioncommand
bRatio Basis acceptance test. A bratio of 0 accepts any basis, and a bratio of 1 always rejects the basis. x x
cheat Cheat value. Requires a new integer solution to be a given amount better than the current best integer solution. Default value is 0.
cutOff Cutoff value. Occasionally used attribute that causes MIP solvers to delete parts of the branch and bound tree with an objective worse than the numerical value of the cutoff attribute.
dictFile Force writing of a dictionary file if dictfile \(>\) 0
domLim Maximum number of domain errors. This attribute allows errors to occur up to a given number during solution. Default value is 0.x x
holdFixedThis attribute can reduce the problem size by treating fixed variables as constants. Allowable values are:

0: fixed variables are not treated as constants (default)
1: fixed variables are treated as constants

x
integer1 Integer communication cell that can contain any integer number.x x
integer2 Integer communication cell that can contain any integer number.x x
integer3 Integer communication cell that can contain any integer number.x x
integer4 Integer communication cell that can contain any integer number.x x
integer5 Integer communication cell that can contain any integer number.x x
iterLim Iteration limit. The solvers will interrupt the solution process when the iteration count reaches that limit. The default value is 2 billion.x x
limCol Maximum number of cases written to the LST file for each named variable in a model. The default value is 3.x x
limRow Maximum number of cases written to the LST file for each named equation in a model. The default value is 3.x x
MCPRHoldfxThis attribute can be set to print a list of rows that are perpendicular to variables removed due to the holdfixed setting when solvin an MCP. Allowable values are:

0: do not print the list (default)
1: print the list

x x
nodLim Node limit. This attribute specifies the maximum number of nodes to process in the branch and bound tree for a MIP problem. The default value is 0 and is interpreted as 'not set'.x
optCA Absolute optimality criterion. This attribute specifies an absolute termination tolerance for use in solving all mixed-integer models. The default value is 0.x x
optCR Relative optimality criterion. This attribute specifies a relative termination tolerance for use in solving all mixed-integer models. The default value is 0.1.x x
optFile Look for a solver options file if optFile \(>\) 0. The value of optfiledetermines which option file is used:

If Optfile = 1 the option file solvername.opt will be used.
If Optfile = 2 the option file solvername.op2 will be used.
If Optfile = 3 the option file solvername.op3 will be used.
If Optfile = 15 the option file solvername.o15 will be used.
If Optfile = 222 the option file solvername.222 will be used.
If Optfile = 1234 the option file solvername.1234 will be used.
If Optfile = 0 no option file will be used. (default)

x
priorOpt Priority option. Variables in mixed integer programs can have a priority attribute. One can use this parameter to specify an order for picking variables to branch on during a branch and bound search for MIP model solutions. The default value is 0 in which case priorities will not be used.
real1 Real communication cell that can contain any real number.x
real2 Real communication cell that can contain any real number.x
real3 Real communication cell that can contain any real number.x
real4 Real communication cell that can contain any real number.x
real5 Real communication cell that can contain any real number.x
reform Reformulation level.x
resLim Maximum time available in wall clock seconds to solve in seconds. The default value is 1000.x x
savePointThis parameter tells GAMS to save a point format GDX file that contains the information on the current solution point. One can save the solution information from the last solve or from every solve. Numeric input with the following values is expected:

0: no point gdx file is to be saved
1: a point gdx file called model_name_p.gdxis to be saved from the last solve in the GAMS model
2: a point gdx file called model_name_pnn.gdx is to be saved from every solve in the GAMS model, where nnis the solve number as determined internally by GAMS

x x
scaleOpt This attribute tells GAMS whether to employ user specified variable and equation scaling factors. It must be set to a nonzero value if the scaling factors are to be used.
solPrint This attribute controls the printing of the model solution to the LST file. Note that the corresponding option expects a text, while the use of model_name.solPrintand the command line expect a numeric value. Allowed are:

0/Off: remove solution listings following solves
1/On: include solution listings following solves
2/Silent: suppress all solution information

The default value is 1 respectively 'On'.
x x
solveLinkThis attribute controls GAMS function when linking to solve. Allowable values are:

0: GAMS operates as always (default)
1: the solver is called from a shell and GAMS remains open
2: the solver is called with a spawn (if possible as determined by GAMS) or a shell (if the spawn is not possible) and GAMS remains open
3: GAMS starts the solution and continues in a Grid computing environment
4: GAMS starts the solution and waits (same submission process as 3) in a Grid computing environment
5: the problem is passed to the solver in core without use of temporary files
6: the problem is passed to the solver in core without use of temporary files, GAMS does not wait for the solver to come back
7: the problem is passed to the solver in core without use of temporary files, GAMS waits for the solver to come back but uses same submission process as 6

x x
solveOpt This attribute tells GAMS how to manage the model solution when only part of the variables and equations are in the particular problem being solved. Note that the corresponding option expects a text, while the use of model_name.solveOptand the command line expect a numeric value. Allowed are:

0/replace: the solution information for all equations appearing in the model is completely replaced by the new model results; variables are only replaced if they appear in the final model
1/merge: the solution information for all equations and variables is merged into the existing solution information; (default)
2/clear: the solution information for all equations appearing in the model is completely replaced; in addition, variables appearing in the symbolic equations but removed by conditionals will be removed
There is an example called 'solveopt' in the model library.

x
sysOut This attribute controls the incorporation of additional solver generated output (that in the solver status file) to the LST file. Note that the corresponding option expects a text, while the use of model_name.solPrintand the command line expect a numeric value. Allowed are:

0/Off: suppress additional solver generated output (default)
1/On: include additional solver generated output

x x
threads This attribute controls the number of threads or CPU cores to be used by a solver. Allowable values are:

-n: number of cores to leave free for other tasks
0: use all available cores
n: use n cores (will be reduced to the available number of cores if n is too large)

x x
tolInfeasInfeasibility tolerance for an empty row of the form a.. 0*x =e= 0.0001;. If not set, a tolerance of 10 times the machine precision is used. Empty rows failing this infeasibility check are flagged with the listing file message 'Equation infeasible due to rhs value'.
tolInfRepThis attribute sets the tolerance for marking infeasible in the equation listing. The default value is 1.0e-6.
tolProj This attribute controls the tolerance for filtering marginals (i.e.setting marginals within the tolerance to 0) and projecting levels to the lower or upper bound that are within the tolerance when reading a solution, default is 1e-8.
tryInt Signals the solver to make use of a partial or near-integer-feasible solution stored in current variable values to get a quick integer-feasible point. If or how tryint is used is solver-dependent.
tryLinearExamine empirical NLP model to see if there are any NLP terms active. If there are none the default LP solver will be used. To activate use model_name.trylinear=1. Default value is 0. The procedure also checks to see if QCP, and DNLP models can be reduced to an LP; MIQCP and MINLP can be solved as an MIP; RMIQCP and RMINLP can be solved as an RMIP.
workFactorThis attribute tells the solver how much workspace to allocate for problem solution relative to the GAMS estimate.x
workSpaceThis attribute tells the solver how much workspace in Megabytes to allocate for problem solution.x

Model Attributes mainly used after solve

AttributeDescription
domUsd Number of domain violations.
etAlg This attribute returns the elapsed time it took to execute the solve algorithm. The time does not include the time to generate the model, reading and writing of files etc. The time is expressed in seconds of wall-clock time.
etSolve This attribute returns the elapsed time it took to execute a solve statement in total. This time includes the model generation time, time to read and write files, time to create the solution report and the time taken by the actual solve. The time is expressed in seconds of wall-clock time.
etSolver This attribute returns the elapsed time taken by the solver only. This does not include the GAMS model generation time and time taken to report and load the solution back into the GAMS database. The time is expressed in seconds of wall-clock time.
handle Every solve gets unique handle number that may be used by handlecollect, handlestatus or handledelete. See Chapter The Grid and Multi-Threading Solve Facility .
iterUsd Number of iterations used.
line Line number of last solve of the corresponding model
linkUsed Integer number that indicates the value of solveLink used for the last solve
maxInfes Max of infeasibilities
meanInfes Mean of infeasibilities
modelStat Model status. Range from 1 to 19. For details check Section Model Status.
nodUsd The number of nodes used by the MIP solver.
number Model instance serial number. The first model solved gets number 1, the second number 2 etc. The user can also set a value and the next model solved will get value+1 as number.
numDepnd Number of dependencies in a CNS model.
numDVar Number of discrete variables.
numEqu Number of equations.
numInfes Number of infeasibilities.
numNLIns Number of nonlinear instructions.
numNLNZ Number of nonlinear nonzeros.
numNOpt Number of nonoptimalities.
numNZ Number of nonzero entries in the model coefficient matrix.
numRedef Number of MCP redefinitions.
numVar Number of variables.
numVarProj Number of bound projections during model generation.
objEst The estimate of the best possible solution for a mixed-integer model.
objVal The objective function value.
procUsed Integer number that indicates the used model type. Possible values are:

1: LP
2: MIP
3: RMIP
4: NLP
5: MCP
6: MPEC
7: RMPEC
8: CNS
9: DNLP
10: RMINLP
11: MINLP
12: QCP
13: MIQCP
14: RMIQCP
15: EMP

resGen Time GAMS took to generate the model in CPU seconds.
resUsd Time the solver used to solve the model in CPU seconds.
rObj The objective function value from the relaxed solve of a mixed-integer model when the integer solver did not finish.
solveStat This model attribute indicates the solver termination condition. Range from 1 to 13. For details check Section The Solve Summary .
sumInfes Sum of infeasibilities.

The Solve Statement

Once the model has been put together through the model statement, one can now attempt to solve it using the solve statement. On seeing this statement, GAMS calls one of the available solvers for the particular model type.

Attention
It is important to remember that GAMS itself does not solve your problem, but passes the problem definition to one of a number of separate solver programs.

The next few sub-sections discuss the solve statement in detail.

The Syntax

In general, the syntax in GAMS for a model declaration is:

solve model_name using model_type maximizing|minimizing var_name|;
solve model_name maximizing|minimizing var_name using model_type ;

Model_name is the name of the model as defined by a model statement. Var_name is the name of the objective variable that is being optimized. Model_type is one of the model types described before. An example of a solve statement in GAMS is shown below.

Solve transport using lp minimizing cost ;

Solve and using are reserved words.Transport is the name of the model, lp is the model type, minimizing is the direction of optimization, and cost is the objective variable. The opposite of minimizing is maximizing , both reserved words. Note that an objective variable is used instead of an objective row or function

Attention
The objective variable must be scalar and of type free, and must appear in at least one of the equations in the model.

The next two sub-sections will describe briefly below what happens when a solve statement is processed, and more details on how the resulting output is to be interpreted will be given in the next chapter. After that sequences of solve statements will be discussed. The final section will describe options that are important in controlling solve statements.

Requirements for a Valid Solve Statement

Requirements for a Valid Solve Statement When GAMS encounters a solve statement, the following are verified:

  1. All symbolic equations have been defined and the objective variable is used in at least one of the equations
  2. The objective variable is scalar and of type free
  3. Each equation fits into the specified problem class (linearity for lp, continuous derivatives for nlp, as we outlined above)
  4. All sets and parameters in the equations have values assigned.

Actions Triggered by the Solve Statement

The solve statement triggers a sequence of steps that are as follows:

  1. The model is translated into the representation required by the solution system to be used.
  2. Debugging and comprehension aids are produced and written to the output file (EQUATION LISTING, etc).
  3. GAMS verifies that there are no inconsistent bounds or unacceptable values (for example NA or UNDF) in the problem.
  4. Any errors detected at this stage cause termination with as much explanation as possible, using the GAMS names for the identifiers causing the trouble.
  5. GAMS passes control to the solution subsystem and waits while the problem is solved.
  6. GAMS reports on the status of the solution process and loads solution values back into the GAMS database. This causes new values to be assigned to the .l and .m fields for all individual equations and variables in the model. A row by row and column by column listing of the solution is provided by default. Any apparent difficulty with the solution process will cause explanatory messages to be displayed. Errors caused by forbidden nonlinear operations are reported at this stage.

The outputs from these steps, including any possible error messages, are discussed in detail in Chapter GAMS Output.

Programs with Several Solve Statements

Several solve statements can be processed in the same program. If you have to solve sequences of expensive or difficult models, you should read the chapter on workfiles to find out how to interrupt and continue program execution. The next few sub-sections discuss various instances where several solve statements may be needed in the same file.

Several Models

If there are different models then the solves may be sequential, as below. Each of the models in [PROLOG] from gamslib consists of a different set of equations, but the data are identical, so the three solves appear in sequence with no intervening assignments:

solve nortonl using nlp maximizing  z;
solve nortonn using nlp maximizing  z;
solve nortone using nlp maximizing  z;

When there is more than one solve statement in your program, GAMS uses as much information as possible from the previous solution to provide a starting point in the search for the next solution.

Sensitivity or Scenario Analysis

Multiple solve statements can be used not only to solve different models, but also to conduct sensitivity tests, or to perform case (or scenario) analysis of models by changing data or bounds and then solving the same model again. While some commercial LP systems allow access to sensitivity analysis through GAMS it is possible to be far more general and not restrict the analysis to either solver or model type. This facility is even more useful for studying many scenarios since no commercial solver will provide this information.

An example of sensitivity testing is in the simple oil-refining model [MARCO]. Because of pollution control, one of the key parameters in oil refinery models is an upper bound on the sulfur content of the fuel oil produced by the refinery. In this example, the upper bound on the sulfur content of the fuel oil produced in the refinery. In this example, the upper bound on the sulfur content of fuel oil was set at 3.5 percent in the original data for the problem. First the model is solved with this value. Next a slightly lower value of 3.4 percent is used and the model is solved again. Finally, the considerably higher value of 5 percent is used and the model is solved for the last time. After each solve, key solution values (the activity levels are associated with z, the process levels by process p and by crude oil type cr) are saved for later reporting. This is necessary because a following solve replaces any existing values. The complete sequence is :

parameter report(*,*,*)  "process level report" ;

qs('upper','fuel-oil','sulfur')  =  3.5  ;
solve oil using lp maximizing phi;
report(cr,p,'base')  =  z.l(cr,p) ;

report('sulfur','limit','base') = qs('upper','fuel-oil','sulfur');
qs ('upper','fuel-oil','sulfur')  =  3.4  ;
solve oil using lp maximizing phi ;
report(cr,p,'one')  =  z.l(cr,p) ;
report('sulfur','limit','one') = qs ('upper','fuel-oil','sulfur');

qs('upper','fuel-oil','sulfur')  =  5.0  ;
solve oil using lp maximizing phi ;
report(cr,p,'two')  =  z.l(cr,p) ;
report('sulfur','limit','two') = qs('upper','fuel-oil','sulfur');

display report ;

This example shows not only how simply sensitivity analysis can be done, but also how the associated multi-case reporting can be handled. The parameter qs is used to set the upper bound on the sulfur content in the fuel oil, and the value is retrieved for the report.

The output from the display is shown below. Notice that there is no production at all if the permissible sulfur content is lowered. The case attributes have been listed in the row SULFUR.LIMIT. The wild card domain is useful when generating reports: otherwise it would be necessary to provide special sets containing the labels used in the report. Any mistakes made in spelling labels used only in the report should be immediately apparent, and their effects should be limited to the report. Section Global Display Controls , contains more detail on how to arrange reports in a variety of ways.

-----   205   PARAMETER REPORT      PROCESS LEVEL REPORT

                           BASE      ONE        TWO
MID-C   .A-DIST            89.718               35.139
MID-C   .N-REFORM          20.000                6.772
MID-C   .CC-DIST           7.805                 3.057
W-TEX   .CC-GAS-OIL                              5.902
W-TEX   .A-DIST                                 64.861
W-TEX   .N-REFORM                               12.713
W-TEX   .CC-DIST                                 4.735
W-TEX   .HYDRO                                  28.733
SULFUR.LIMIT               3.500     3.400       5.000

Iterative Implementation of Non-Standard Algorithms

Another use of multiple solve statements is to permit iterative solution of different blocks of equations, solution values from the first are used as data in the next. These decomposition methods are useful for certain classes of problems because the sub-problems being solved are smaller, and therefore more tractable. One of the most common examples of such a method is the Generalized Bender's Decomposition method.

An example of a problem that is solved in this way is an input-output system with endogenous prices, described in Henaff (1980) 1) . The model consists of two groups of equations. The first group uses a given final demand vector to determine the output level in each sector. The second group uses some exogenous process and input-output data to compute sectoral price levels. Then the resulting prices are used to compute a new vector of final demands, and the two block of equations are solved again. This iterative procedure is repeated until satisfactory convergence is obtained. Henaff has used GAMS statements to perform this kind of calculation. The statements that solve the system for the first time and the next iteration are shown below:

model usaio       / mb, output /;
model dualmodel   / dual, totp /;

solve usaio using lp maximizing  total ;
solve dualmodel using lp maximizing totprice;

pbar(ta)  =  (sum(ipd.l(i,ta))/4.);
d(i,t)  =  (db(i)*g(t))/(pd.l(i,t)/pbar(t))  ;

solve usaio using lp maximizing total;
solve dualmodel using lp maximizing totprice;

Mb is a set of material balance (input-output) equations, and output is a total output equation. Dual is a group of price equations, and totp is an equation that sums all the sectoral prices. The domestic prices pd used in the calculation of the average price pbar are divided by four because there are four sectors in this example. Also the .l is appended to pd to indicate that this is the level of the variable in the solution of the model namely in dualmodel. Thus the iterative procedure uses solution values from one iteration to obtain parameter values for the next one. In particular, both pbar and pd are used to compute the demand d for the i-th product in time period t, d(i,t). Also, the base year demand db and the growth factor g are used in that calculation. Then when the new final demand vector d is calculated, the two blocks of equations are solved again.

Making New Solvers Available with GAMS

This short section is to encourage those of you who have a favorite solver not available through GAMS . Linking a solver program with GAMS is a straightforward task, and we can provide documents that describe what is necessary and provide the source code that has been used for existing links. The benefits of a link with GAMS to the developer of a solver are several. They include:

  • Immediate access to a wide variety of test problems.
  • An easy way of making performance comparisons between solvers.
  • The guarantee that a user has not somehow provided an illegal input specification.
  • Elaborate documentation, particularly of input formats, is not needed.
  • Access to the existing community of GAMS users, for marketing or testing.

This completes the discussion of the model and solve statements. In Chapter GAMS Output the various components of GAMS output are described in some detail.

1) Henaff, Patrick (1980). An Input-Output Model of the French Economy, Master's Thesis, Department of Economics, University of Maryland.