Basic Solver Usage

Introduction

For the novice GAMS user, solver usage can be very simple: you run the model and inspect the listing file to see what the solution is. No knowledge of solver options or solver return codes is required. While this is enough for some users, most will quickly find they need some basic knowledge of how to control the solver and interpret the results. This section describes the GAMS options used to control a solver, how the GAMS solvers interpret these options, and how to interpret the model and solver status codes the solvers return.

While most solvers allow the user to set additional, solver-specific options, we will not be concerned with those here. In most cases, it is not necessary to use any solver-specific options: use of the generic GAMS options is sufficient. This carries an important benefit: since the solvers interpret the GAMS options in a consistent way, a GAMS option setting applies to all solvers, not just to a specific one.

GAMS Options

Options exist in two forms: global or model-specific. The option statement sets a global GAMS option, e.g.

option iterlim = 100;

while the model suffix sets a GAMS option for an individual model:

mymodel.iterlim = 10;

In addition, the default value of a global GAMS option can be set on the GAMS command line:

gams trnsport iterlim = 100

If a model-specific option is set, this takes precedence over the global setting. You can unset any model-specific option by assigning it the default value of NA:

mymodel.iterlim = NA;

Most GAMS options for controlling solvers are described in the Solver related options section of the GAMS User's Guide. Additionally, the following options are available. These can only be set as model attribute.

  • cheat: Cheat value, i.e. minimum solution improvement threshold (Default: 0)

    For a global solver, each new feasible solution must be at least cheat better than the previous one. This can speed up the search, but the search may miss the optimal solution. The cheat option is specified in absolute terms (like the optca option), so that non-negative values are appropriate for both minimization and maximization models. Using the cheat option invalidates any reporting of the dual bound or optimality gaps.

  • cutoff: Cutoff value for branch and bound (Default: 0)

    During a branch-and-bound search, the parts of the tree with an objective worse than cutoff are deleted. This can sometimes speed up the initial phase of the branch-and-bound algorithm, at the cost of ignoring feasible solutions whose value is worse than cutoff.

  • prioropt: Priority option for variable attribute .prior (Default: 0)

    Instructs the solver to use the priority branching information passed by GAMS through variable suffix values variable.prior. If and how priorities are used is solver-dependent.

  • tryint: Whether solver should make use of a partial integer-feasible solution

    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.

The Solver Option File

To specify solver-specific options, it is necessary to use a solver option file. Two things are required to do this: you must create an option file having a proper name, and you must tell the solver to read and use this option file.

To tell a solver to use an option file, you can set the optfile model suffix to a positive value. For example,

model mymodel /all/;
mymodel.optfile = 1;
solve mymodel using nlp maximizing dollars;

The option file takes its name from the solver being used: solvername.XXX, where solvername is the name of the solver that is specified, and the suffix XXX depends on the value to which the model suffix optfile has been set. If its value is 1, the suffix is opt. For example, the option file for CONOPT is called conopt.opt; for DICOPT, it is dicopt.opt.

If you do not set the .optfile suffix to a nonzero value, no option file will be used even if one exists.

To allow different option file names for the same solver, the .optfile model suffix can take on values between 2 and 999. In this case, the option file extension is computed from the .optfile value by replacing the characters in opt with the digits in the characters in the .optfile value, starting from the right. For example,

optfile model suffix value Name of option file
0 No option file used
1 solvername.opt
2 solvername.op2
3 solvername.op3
10 solvername.o10
91 solvername.o91
100 solvername.100
999 solvername.999

For example, setting mymodel.optfile to 23 will result in the option file conopt.o23 being used for CONOPT, and dicopt.o23 being used for DICOPT.

The format of the options file is not completely standard and changes marginally from solver to solver. This section illustrates some of the common features of the option file format. Please check the solver-specific documentation before using an option file.

Blank lines in an option file are ignored. Each nonblank line falls into one of two categories:

  • a comment line
  • an option specification line

A comment line begins with an asterisk (*) in the first column, is not interpreted by either GAMS or the solver, and is used purely for documentation. Each option specification line can contain only one option. The format for specifying options is as follows:

keyword(s) [modifier] [value]

The keyword may consist of one or more words and is not case sensitive. The value might be an integer, a real, or a string. All solvers will accept real numbers expressed in scientific (i.e. E) format. Note that not all options require modifiers or values.

Any errors in the spelling of keyword(s) or modifiers will lead to that option being misunderstood and therefore ignored. Errors in the value of an option can result in unpredictable behavior. When detected, errors are either ignored or pushed to a default or limiting value, but not all can or will be detected. Option values should be chosen thoughtfully and with some care.

Consider the following CPLEX options file,

* CPLEX options file
barrier
crossover 2

The first line begins with an asterisk and therefore contains comments. The first option specifies the use of the barrier algorithm to solve the linear programming problem, while the second option specifies that the crossover option 2 is to be used. Details of these options can be found in the CPLEX section of this manual.

Consider the following MINOS options file,

* MINOS options file
scale option 2
completion partial

The first option sets the scale option to a value of 2. In this case, the keyword 'scale option' consists of two words. In the second line, the completion option is set to partial. Details of these options can be found in the MINOS section of this manual.

GAMS Dot Options

Dot options in a solver option file allow users to associate values to variables and equations using the GAMS name of the variables and equations. The general syntax of a dot option in the option file is as follows:

(variable/equation name).optionname (value)

Dot options can be specified for all, a block, a slice, and a single variable and equation. Please note that a specific dot option may only apply to variables or equations (e.g. the GAMS/Gurobi dot option prior applies to variables only). The following example makes the use of the dot option clear.

For example, suppose we have a GAMS declaration:

Set i /i1*i5/;
Set j /j2*j4/;
Variable v(i,j);
Equation e(i,j);

Consider the following lines in an option file with the imaginary option name dotopt:

Line in option file Explanation
variables.dotopt 1 Sets the value of all variables to 1
equations.dotopt 2 Sets the value of all equations to 2
v.dotopt 3 Sets the value of the variables in block v to 3
e.dotopt(*,*) 4 Sets the value of the equations in block e to 4
v.dotopt(*,’j2’) 5 Sets the value of the variables v that have j2 in the second index position (slice) to 5
e.dotopt(’i3’,*) 6 Sets the value of the equations e that have i3 in the first index position (slice) to 6
w.dotopt(’i2’) 7 Sets the value of the single variables v(’i2’) to 7
e.dotopt(’i3’,’j3’) 8 Sets the value of the single equations e(’i3’,’i3’) to 8

The values of the dot option are applied in correspondence to the sequence in which they appear in the option file. In the current example, the values of dotopt for the equation e would be as follows:

e.dotopt i1 i2 i3
j2 4 4 6
j3 4 4 8
j4 4 4 6