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

The Option Statement

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:

  1. 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;
  1. a recognized name, number following an = sign, then an unsigned integer value.
  2. a recognized name, number following an = sign, then an unsigned real number.
  3. 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.

<identifier>

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.

asyncsollst   (0)

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

bratio   (0.25)

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]

cns   (default)

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.

decimals   (3)

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

Range: [0,8]

dnlp   (default)

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

domlim   (0)

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.

eject

Advances output in the listing file to the next page.

integer1 to integer5

Integer communication cell that can contain any integer number.

iterlim   (2000000000)

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

limcol   (3)

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.

limrow   (3)

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.

mcprholdfx   (0)

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

mpec   (default)

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

lp   (default)

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

mcp    (default)

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

minlp    (default)

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

mip    (default)

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

miqcp    (default)

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

nlp    (default)

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

optca    (0.0)

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.

optcr    (0.1)

This option sets a relative termination tolerance for 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.

profile    (0)

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.

profiletol    (0.0)

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.

qcp    (default)

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

real1 to real 5

Real communication cell that can contain any real number.

reslim    (1000)

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.

rmip    (default)

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

rminlp    (default)

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

savepoint    (0)

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

seed    (3141)

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

shuffle   (identifier)

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

Below 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

solprint    (on)

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

solslack    (0)

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

solvelink    (0)

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

solver    (default)

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.

solveopt    (merge)

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.

strictSingleton    (1)

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

sysout    (off)

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.

threads    (1)

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)