### Table of Contents

# Introduction

The `option`

statement is used to set various global system parameters that control output detail, solution process and the layout of displays. They are processed at execution time unlike the dollar control options discussed in Chapter Dollar Control Options . They are provided to give flexibility to the user who would like to change the way GAMS would normally do things. GAMS does provide default values that are adequate for the most purposes, but there are always cases when the user would like to maintain control of aspects of the run.

## The Syntax

The general form of an option statement is

option 'keyword1' [ = 'valuel'] { ,|EOL 'keyword2' [ = 'value2'] } ;

where the `'keyword1'`

and `'keyword2'`

are recognized option names (but not reserved words) and the `'value1'`

and `'value2'`

are valid values for each of the respective options. Note that commas or end-of-line characters are both legal separators between options.

- Attention
- Option names are not reserved words and therefore do not conflict with other uses of their name.

There are five possible formats:

- a
`display`

specifier.Commas or end-of-line characters are both legal separators between options. The below code snippet demonstrates how GAMS options can be used with recognized names. In case you want to see the options in action, you can copy and paste the below code snippet at the end of the GAMS Model Library example [dice].

option measure, limcol = 100 optcr = 0.00, mip = xpress ; solve xdice using mip max wnx; option clear = comp;

- a recognized name, number following an
`=`

sign, then an unsigned integer value.- a recognized name, number following an
`=`

sign, then an unsigned real number.- a recognized name, number following an
`=`

sign, then either of two recognized words.

- Attention
- An option statement is executed by GAMS in sequence with other instructions. Therefore, if an option statement comes between two solve statements, the new values are assigned between the solves and thus apply only to the second one.
- The values associated with an option can be changed as often as necessary, with the new value replacing the older one each time.

An example of a list of option statements is shown below,

option profit:0:3:2; option eject iterlim = 100 , solprint = off ; solve mymodel using lp maximizing profit ; display profit.l ; input("val1") = 5.3 ; option iterlim = 50 ; solve mymodel using lp maximizing profit ;

The `option`

statement in the second line affects the display format of the identifier `profit`

. More details on this option can be found under the heading `<identifier>`

in the following section. The option on the second line has no value associated with it, and serves to advance the output in the listing file to the next page. The third line contains two options - `iterlim`

, and `solprint`

. The values associated with the two options on the fourth line are of different types - `iterlim`

has an integer value while `solprint`

requires a character string as a value. Note also that the end of line and the comma serve as legal separators between two options.

The `option`

`iterlim`

serves to limit the number of iterations taken by the solver while attempting to solve the `lp`

model `mymodel`

. After `mymodel`

is solved for the first time, some of the input data is changed and the model is solved again. However, before the second solve statement, the `option`

`iterlim`

is changed to 50. The effect of the sequence above is to limit the first solve to less than 100 iterations and the second to less than 50.

# List of Options

The options available through the option statement are grouped into the following functional categories affecting

- output detail
- solver specific parameters
- input program control
- choice of solver

The following subsections briefly describes the various options in each of the categories. Section Detailed Description of Options contains a reference list of all options available through the `option`

statement in alphabetical order with detailed description for each.

## Options controlling output detail

Option | Description |
---|---|

<identifier> | controls print format |

asyncsollst | Print solution listing when asynchronous solve (Grid or Threads) is used |

decimals | global control of print format |

eject | advances output to next page |

limcol | number of columns listed |

limrow | number of rows listed |

mcprholdfx | Print list of rows that are perpendicular to variables removed due to the holdfixed setting |

profile | lists program execution profile |

profiletol | sets tolerance for execution profile |

solprint | controls printing of solution |

solslack | controls type of equation information |

sysout | controls printing of solver status file |

## Options controlling solver specific parameters

Option | Description |
---|---|

bratio | use of advanced basis |

domlim | limits number of domain errors |

iterlim | limits number of solver iterations |

optca | sets absolute optimality tolerance |

optcr | sets relative optimality tolerance |

reslim | limits amount of solver time |

savepoint | save solver point in GDX file |

solvelink | solver link options |

threads | number of threads to be used by a solver |

## Options controlling choice of solver

Option | Description |
---|---|

cns | sets solver for `cns` model type |

dnlp | sets solver for `dnlp` model type |

lp | sets solver for `lp` model type |

mcp | sets solver for `mcp` model type |

minlp | sets solver for `minlp` model typ |

mip | sets solver for `mip` model type |

mpec | sets solver for `mpec` model type |

nlp | sets solver for `nlp` model type |

rminlp | sets solver for `rminlp` model type |

rmip | sets solver for `rmip` model type |

solver | sets solver for all model types that the solver can process |

## Options affecting input program control

Option | Description |
---|---|

seed | resets seed for pseudo random number generator |

solveopt | controls return of solution values to |

strictsingleton | error if assignment to singleton set has multiple elements |

## Other options

Option | Description |
---|---|

integer1 | integer communication cell |

real1 | real communication cell |

shuffle | rearranges the values of a parameter in random order |

# Detailed Description of Options

This section describes each of the options in detail. The options are listed in alphabetical order for easy reference. In each of the following options, the default value, if available, is bracketed.

Display specifier:

`identifier:d`

,`identifier:d:r:c`

Defines print formats for`identifier`

when used in a display statement.`d`

is the number of decimal places,`r`

is the number of index positions printed as row labels,`c`

is the number of index positions printed as column labels; the remaining index positions (if any) will be used to index the planes (index order: plane, row, column); if`r`

is zero list format will be used. The default setting is described in Section The Label Order in Displays.

Print solution listing when asynchronous solve (Grid or Threads) is used.

Certain solution procedures can restart from an advanced basis that is constructed automatically. This option is used to specify whether or not basis information (probably from an earlier solve) is used. The use of this basis is rejected if the number of basic variables is smaller than bratio times the size of the basis. Setting

`bratio`

to 1 will cause all existing basis information to be discarded, which is sometimes needed with nonlinear problems. A`bratio`

of 0 accepts any basis, and a`bratio`

of 1 always rejects the basis. Setting`bratio`

to 0 forces GAMS to construct a basis using whatever information is available. If`bratio`

has been set to 0 and there was no previous solve, an'all slack'(sometimes called'all logical') basis will be provided. This option is not useful for MIP solvers.Range: [10,31]

The default

`cns`

solver is set during installation.The user can change this default by setting this option to the required solver. The list of`cns`

solvers available with your system can be obtained by reading the`gamscmp**.txt`

file that is present in the GAMS system directory. A value of`default`

will change the`cns`

solver back to the default one as specified in`gamscmp**.txt`

.

Number of decimals printed for symbols not having a specific print format attached.

Range: [0,8]

This option controls the solver used to solve dnlp models. For details cf. option cns.

This controls the maximum number of domain errors (undefined operations like division by zero) a nonlinear solver will perform, while calculating function and derivative values, before it terminates the run. Nonlinear solvers have difficulty recovering after attempting an undefined operation.

Advances output in the listing file to the next page.

Integer communication cell that can contain any integer number.

This option will cause the solver to interrupt the solution process after iterlim iterations and return the current solution values to GAMS.

This controls the number of columns that are listed for each variable in the

`COLUMN LISTING`

section of the listing file. Specify zero to suppress the`COLUMN LISTING`

altogether.

This controls the number of rows that are listed for each equation in the

`EQUATION LISTING`

section of the listing file. Specify zero to suppress the`EQUATION LISTING`

altogether.

Print list of rows that are perpendicular to variables removed due to the holdfixed setting.

This option controls the solver used to solve mpec models. For details cf. option cns.

This option controls the solver used to solve lp models. For details cf. option cns.

This option controls the solver used to solve mcp models. For details cf. option cns .

This option controls the solver used to solve minlp models. For details cf. option cns .

This option controls the solver used to solve mip models. For details cf. option cns .

This option controls the solver used to solve miqcp models. For details cf. option cns.

This option controls the solver used to solve nlp models. For details cf. option cns.

This option is only used with problems containing discrete variables (i.e. the GAMS model type

`mip`

). General mixed integer problems are often extremely difficult to solve, and proving that a solution found is the best possible can use enormous amounts of resources. This option sets an`absolute termination tolerance`

, which means that the solver will stop and report on the first solution found whose objective value is within`optca`

of the best possible solution.

This option sets a

relative termination tolerancefor problems containing discrete variables, which means that the solver will stop and report on the first solution found whose objective value is within`100*optcr`

of the best possible solution.

This option is used to generate more information on program execution profiles. This option is equivalent in function to the profile command line parameter.

0 No execution profile is generated in listing file

1 The listing file reports execution times for each statement and the number of set elements over which the particular statement is executed.

2 Specific times for statements inside control structures like loops.

This option sets profile tolerance in seconds. All statements that take less time to execute than this tolerance are not reported in the listing file.

This option controls the solver used to solve qcp models. For details cf. option cns .

Real communication cell that can contain any real number.

This option specifies the maximum time in wall clock seconds that the computer can run during execution of a solver, before the solver terminates the run.

This option controls the solver used to solve rmip models. For details cf. option cns .

This option controls the solver used to solve rminlp models. For details cf. option cns .

This option tells GAMS to save a point format GDX file that contains the information on the current solution point.

0 no point GDX file is to be saved

1 a point gdx file from the last solve is to be saved

2 a point gdx file from every solve is to be saved

This option resets the seed for the pseudo random number generator.

This option rearranges the values of a parameter in random order.

The command is invoked using the syntax

Option Shuffle=itemname;Where itemname is a one dimensional parameter. There are four cases that we can distinguish for how the parameter has been declared:

No Data Has Data No domain Use the universe to initialize the data Use the universe to add zero values before shuffling the data Domain Use the domain to initialize the data Use the domain to add zero values before shuffling the data When the parameter has no data, the domain or the universe is used to assign the numbers 1 to N where N is the number of elements in the domain or the universe. (See declaration of A and B below). When the parameter has data, the domain or the universe is used to insert zeroes for the missing entries. These zero values participate in the random shuffle, but will not be stored in the parameter (See declaration of C and D below):

* some different declarations to show their impact on the shuffle option set i /i1*i5/ j /j1*j5/; *case no domain no data parameter A(*); option shuffle=A; display A; *case has domain no data parameter B(j); option shuffle=B; display B; *case no domain has data parameter C(*) /j2 2, j4 4/; option shuffle=C; display C; *case has domain and has data parameter D(i) /i1 10, i3 30, i5 50/; option shuffle=D; display D;The output from the code above (because we use random numbers, your results may vary):

Parameter A: (The universe is used to fill the parameter) i1 4.000, i2 1.000, i3 7.000, i4 9.000, i5 6.000, j1 10.000 j2 3.000, j3 5.000, j4 8.000, j5 2.000 Parameter B: (The set J is used to fill the parameter) j1 1.000, j2 5.000, j3 2.000, j4 4.000, j5 3.000 Parameter C: (The universe is used to add zeroes) j1 2.000, j2 4.000 Parameter D: (The set i is used to add zeroes) i2 30.000, i4 50.000, i5 10.000Below an example how we can generate a random mapping of a set:

set i /i1*i6/, rmi(i, i); parameter A(i); option shuffle=A; rmi(i, i + (- Ord(i) + A(i))) = yes;Below is the output; there is exactly one element in each row and each column:

i1 i2 i3 i4 i5 i6 i1 YES i2 YES i3 YES i4 YES i5 YES i6 YES

This option controls the printing of the model solution in the listing file. Using this specification suppresses the list of the solution following a

`solve`

.on The solution is printed one line per row and column in the listing file.

off Solution details are not printed. Although this saves paper, we do not recommend it unless you understand your model very well and solve it often.

silent Suppress all solution information

This option causes the equation output in the listing file to contain slack variable values instead of level values.

0 Equation output in listing file contains level values between lower and upper bound values

1 Equation output in listing file contains slack values between lower and upper bound values

This option controls GAMS function when linking to solve.

0 GAMS operates as always

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

The solver for multiple model types can be set via the Option solver=abc; in the GAMS model source code. This sets the solver for model types abc can handle to abc. With the option solver=abc; the order among other solver setting options is significant. For example, option lp=conopt, solver=bdmlp; will first set the solver for LP to Conopt and in the next step to BDMLP because BDMLP is capable of handling model type LP. Setting solver twice can also make sense: option solver=conopt, solver=cbc; will result into setting the solver for model types CNS, DNLP, NLP, QCP, RMIQCP, and RMINLP to Conopt and the solver for model types LP, RMIP, and MIP to CBC.

This option tells GAMS how to manage the model solution when only part of the variables and equations are in the particular problem being solved.

replace All equations appearing in the model list will be completely replaced by the new model results. Variables are only replaced if they appear in the final model.

merge The new model results are merged into the existing structures.

clear Similar to the replace option; in addition, variables appearing in the symbolic equations but squeezed out in the final model, are removed.

This option affects the behavior of a membership assignment to a

`singleton set`

.0 GAMS does not complain about an assignment with more than one element on the right hand side but takes the first one

1 GAMS creates an error for an assignment with more than one element on the right hand side

This option controls the printing of the solver status file as part of the listing file. The contents of the solver status file are useful if you are interested in the behavior of the solver. If the solver crashes or encounters any difficulty, the contents of the solver status file will be automatically sent to the listing file.

on Prints the system output file of the solver

off No subsystem output appears on output file unless a subsystem error has occurred.

This option controls the number of threads or CPU cores to be used by a solver.

-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)