The GAMS Call and Command Line Parameters

There are multiple way to trigger the run of a GAMS model: Running a model via F9 from the IDE, executing GAMSJob.Run method in the object oriented APIs or calling the gams executable from a command line. In all cases the same GAMS engine runs the user's model. Several options are available to customize the GAMS run. Depending on the particular way GAMS is triggered these options are supplied in different ways. For example, in the IDE via the parameter field in the main window, in the object oriented API through the GAMSOptions class, and from the command line via command line arguments. In order to avoid confusion with the often used word option we refer to theses entities as command line parameters and demonstrate its with the gams executable from the command line. Although details will vary with the type of computer and operating system used, the general operating principles are the same on all machines.

In this chapter we will introduce how GAMS is called from the command line and how parameters may be specified on the command line or in other ways. In addition, we will discuss user-defined command line parameters, compile-time variables and compile-time constants, which are GAMS specialties, and environment variables in GAMS. Moreover, most of the chapter is dedicated to the detailed description of all GAMS options (i.e. options available via command line parameters, option statement, and model attribute.

In almost all cases such a run continues from start to end without any user interaction. A GAMS run usually consists of two phases: the compilation and execution phase.

The Generic GAMS Call

The simplest way to start GAMS from a command shell is to enter the following command from the system prompt:

> gams myfile

GAMS will compile and execute the GAMS statements in the file myfile. If a file with this name cannot be found, GAMS will look for a file with the extended name myfile.gms. During the run GAMS will print a log to the console and create a listing file that is written by default to the file myfile.lst. For example, the following statements retrieves and runs the model [TRNSPORT] from the GAMS model library with the responds from the GAMS system:

> gamslib trnsport
Copy ASCII : trnsport.gms
> gams trnsport
--- Job trnsport Start 06/21/17 06:23:45 24.8.4 r60966 WEX-WEI x86 64bit/MS Windows
GAMS 24.8.4   Copyright (C) 1987-2017 GAMS Development. All rights reserved
Licensee: GAMS Development Corporation, Washington, DC   G871201/0000CA-ANY
          Free Demo,  202-342-0180,  sales@gams.com,  www.gams.com   DC0000
--- Starting compilation
--- trnsport.gms(69) 3 Mb
--- Starting execution: elapsed 0:00:00.010
--- trnsport.gms(45) 4 Mb
--- Generating LP model transport
--- trnsport.gms(66) 4 Mb
---   6 rows  7 columns  19 non-zeroes
--- Executing CBC: elapsed 0:00:00.018

COIN-OR CBC      24.8.4 r60966 Released Apr 10, 2017 WEI x86 64bit/MS Windows

COIN-OR Branch and Cut (CBC Library 2.9)
written by J. Forrest

Calling CBC main solution routine...
0  Obj 0 Primal inf 900 (3)
4  Obj 153.675
Optimal - objective value 153.675
Optimal objective 153.675 - 4 iterations time 0.052

Solved to optimality.
--- Restarting execution
--- trnsport.gms(66) 2 Mb
--- Reading solution for model transport
--- trnsport.gms(68) 3 Mb
*** Status: Normal completion
--- Job trnsport.gms Stop 06/21/17 06:23:46 elapsed 0:00:01.249

Observe that some GAMS options may be specified on the command line as part of the GAMS call. In addition, command line parameters may be set by specifying a secondary customization parameter file and by modifying the GAMS system parameter file. As command line parameters may be specified in several different ways, there are rules of precedence in case of conflicting instructions. We will discuss these topics in the next four subsections.

Specifying Options Through the Command Line

GAMS permits certain options to be passed through the command line. The syntax of the simple GAMS call is extended as follows:

> gams myfile key1=value1 key2=value2 ...

Here key1 is the name of the option that is being set on the command line and value1 is the value to which the option is set. Depending on the option, value1 could be a character string, an integer number or a real number. Note that the options that may be set on the command line are called GAMS command line parameters.

For example, consider the following commands to run the transportation model [TRNSPORT]:

> gams trnsport  o myrun.lst  logOption 2
> gams trnsport -o myrun.lst -logOption 2
> gams trnsport /o myrun.lst /logOption 2
> gams trnsport  o=myrun.lst  logOption=2
> gams trnsport -o=myrun.lst -logOption=2
> gams trnsport /o=myrun.lst /logOption=2

All six commands above are equivalent: each directs the output listing to the file myrun.lst. Note that o is the synonym of the command line parameter Output and it is set to the value myrun.lst. In addition, the parameter LogOption is set to 2, which has the effect that the log output is redirected to the file trnsport.log. Please also note that the option name can be specified without consideration of the casing of the option. Hence logoption works as well as LogOption or any other casing. The way options are specified can vary with each option. So a mixed alternative, e.g. gams trnsport -o=myrun.lst /logoption 3 is valid too.

In addition to predefined command line parameters, GAMS also allows user-defined command line parameters which work in tandem with compile-time variables. User-defined parameters, also called double dash parameters, and compile-time variables are introduced in section Double Dash Parameters, Compile-Time Variables and Environment Variables below.

Specifying Options Through a Secondary Parameter File

Command line parameters may also be set by specifying a secondary customization parameter file. For example, we will create a file with the following two lines, call it moreOptions.txt and save it in the current working directory.

limCol=0
limRow=0

Note that setting limcol and limrow to zero will suppress the column listing and equation listing respectively. Moreover, note that we can specify the option in different way in this secondary parameter file, even have multiple options on one line. In the next step we will use the following command to run the transportation model [TRNSPORT]:

> gams trnsport parmFile=moreOptions.txt

Note that this call has the same effect as the following specification:

> gams trnsport limCol=0 limRow=0

Observe that command line parameter include files are particularly useful if modelers wish to use the same set of command line parameters repeatedly.

If options are listed multiple times on the command line, the last specification sets the option. This is important in particular in combination with a secondary parameter file. In the following example, GAMS will operate with limRow=0:

> gams trnsport limRow=10 parmFile=moreOptions.txt

while with the order reversed, GAMS operates with limrow=10:

> gams trnsport parmFile=moreOptions.txt limRow=10

Specifying Options Through the GAMS System Parameter File

A third way to specify command line parameters is by modifying the GAMS system parameter file, which is part of the GAMS system. It has different names depending on the operating system: gmsprmnt.txt for Windows and gmsprmun.txt for UNIX/Linux and Mac OS X. The parameter file may be modified in the following way:

******************************************************************
* GAMS 2.50 default Unix parameter file                          *
* Gams Development Corp.                                         *
* Date : 4 May, 1998                                             *
******************************************************************
* entries required by CMEX, put in by the gams script
* SYSDIR
* SCRDIR
* SCRIPTNEXT
* INPUT
PageWidth 95
ParmFile "c:\some\central\location\moreOptions.txt"

Note that the last two lines were added to the standard GAMS system parameter file. As a consequence, each GAMS run will have a print width of 95 columns on the pages of the listing file. In addition, the command line parameters specified in the file moreOptions.txt will now apply to each GAMS run.

Order of Precedence for Options

The order of precedence for command line parameters including customization specifications in the GAMS IDE is as follows:

  1. Command line parameters that are specified on the command line or in the IDE command line field.
  2. Command line specifications in the IDE options window Execute (this is reached through File|Options|Execute).
  3. Command line specifications in the specific IDE dialogs, e.g. Output (this is reached through File|Options|...).
  4. Entries in the GAMS system parameter file.

Many command line parameters initialize the default for a GAMS Option also accessible inside the GAMS program. For example, the system default for option MIQCP is SBB. If the command line parameter MIQCP has been set, e.g. to DICOPT, DICOPT will be new default MIQCP solver. Inside the GAMS program, one can reset the MIQCP via option MIQCP=BonMin; but setting it back to the default will result in DICOPT (not SBB) being the default solver: option MIQCP=default;.

Double Dash Parameters, Compile-Time Variables and Environment Variables

In this section we will cover double-dash parameters that enable users to set values for specific variables on the command line. These variables are substituted with their respective specified values at compile time. We will also discuss how operating system specific environment variables may be accessed and modified from a GAMS program.

Double Dash Parameters and Compile-Time Variables: A Simple Example

We will introduce double dash parameters and compile-time variables using as an example the well-known transportation model [TRNSPORT]. Assume we wish to explore how the solution changes if the demand assumes various values. To model this, we will introduce the compile-time variable DMULT, a multiplier for the demand b:

$set DMULT 1
...
demand(j) ..   sum(i, x(i,j))  =g=  %DMULT% * b(j) ;

Note that DMULT is defined with the dollar control option $set and its value is set to 1, which corresponds to the base line. Observe that the compile-time variable is referenced in the equation with the %...% notation. %DMULT% will be replaced at compile time by its value, in this case 1. We are now in the position to run the program multiple times by just changing the value of DMULT in the first line, which will automatically change the multiplier in the equation to the respective value.

GAMS offers a more convenient way for setting a compile-time variable like DMULT to a variety of values:

$if not set DMULT $set DMULT 1
...
demand(j) ..   sum(i, x(i,j))  =g=  %DMULT% * b(j) ;

Note that we set a default value for DMULT using conditional compilation. We may change this default on the command line when calling GAMS by specifying DMULT as a double dash parameter as follows:

> gams trnsport.gms --DMULT=0.9

Observe that with the specification –DMULT=0.9 the compile-time variable DMULT is set and therefore the default does not apply. Thus the double dash parameter facilitates changing the value of a compile-time variable directly on the command line as part of the GAMS call while the respective GAMS file remains unchanged.

Assume that the model contains a second compile-time variable called METHOD that acts as a switch for various methods of solving the model and it may take the values 1, 2 and 3. In this case both compile-time variables may be set on the command line as follows:

> gams trnsport.gms --DMULT=1.12 --METHOD=3

In the next two subsections we will discuss double dash parameters and compile-time variables in more detail.

Double Dash Parameters

Double dash parameters are user-defined command line parameters that are used to define scoped compile-time variables or to assign values to scoped compile-time variables. The general syntax is:

> gams myfile --NAME=value

Here NAME is the name of the double dash parameter and value is its assigned value that may be any string. If the string contains spaces or other token terminating characters, the string value should be quoted. Consider the following simple example:

> gams myfile --keycity=Boston --myvalue=7.6 --dothis="display x;"

Suppose that myfile.gms contains the following lines with the scoped compile-time variables keycity, myvalue and dothis:

x("%keycity%")=%myvalue%;
%dothis%

Note that the compile-time variables are referenced using the notation %...%. The GAMS call above has the effect that at compile time the compile-time variables are substituted with the values specified through the double dash parameters resulting in the following:

x("Boston")=7.6;
display x;

GAMS offers three alternative syntax variants for defining double dash parameters:

> gams myfile //NAME=value
> gams myfile /-NAME=value
> gams myfile -/NAME=value

Note that the four syntax variants may be used interchangeably and have the same effect.

Double dash parameters are particularly useful for specifying granularity when modeling a discretization of time and or space. For example, in the model [CHAIN] the problem is to find the chain with minimal potential energy, assuming the chain has uniform density, is suspended between two points and has a given length L. Consider the following code snippet:

$if not set nh $set nh 50 
Set nh / i0*i%nh% /;

The first two lines use conditional compilation" to set a default value for the compile-time variable nh. Note that the value of nh determines the cardinality of the set nh, which is used for the discretization. The value of nh may be easily set on the command line to any desired value using nh as a double dash parameter:

> gams chain --nh=100

Note that the double dash functionality supersedes the command line parameters user1, ..., user5 which are accessible in the source file via %gams.user1%, ..., %gams.user5%. The example above would work with user1 in the following way:

$set nh 50 
$if not "%gams.user1"=="" $set nh %gams.user1% 
Set nh / i0*i%nh% /;

The modified code could be called with:

> gams chain user1=100

Note that the double dash parameters facilitate using meaningful names instead of the generic names user1, ..., user5. This is especially useful if there are multiple parameters to pass on to the GAMS program.

Observe that the dollar control option $setDDList may be used to ensure that a model can only be run with the listed double dash parameters:

$setDDList nh
$if not errorFree $log *** Only allowed double dash options is: --nh=value

Compile-Time Variables

Compile-time variables are special variables that are substituted with their values at compile-time. They are not declared and defined with regular declaration statements like standard symbols (sets, parameters, ...), but they are defined with the dollar control option $set and its variants. There are three kinds of compile-time variables that differ in their scope level: local, scoped and global. An overview is given in Table 1.

ScopeAvailability Defined with Removed from the system with
Local Available only in the input file where they are defined $setLocal. $dropLocal
Scoped Available in the input file where they are defined and in all include files of the input file. $set $drop
Global Available in the input file where they are defined, in all parent files and in all include files. $setGlobal $dropGlobal

Table 1: Scope Levels for Compile-Time Variables in GAMS

Note that scoped compile-time variables may also be defined on the command line with double dash parameters. For example, in the example above the compile-time variable DMULT may be referenced in the equation demand without being defined with the dollar control option $set as long as it is defined and set on the command line. Note further, that global compile-time variables are saved in work files.

While the scope of a compile-time variable cannot be directly changed, but dropping and adding variables in different scopes accomplishes the same. Consider the following example:

$set MYVAR xxx

* From scoped to global
$ifThen set MYVAR
$  setGlobal MYVAR %MYVAR%
$  show
$  drop MYVAR
$  show
$endIf

* From global to local
$ifThen setGlobal MYVAR
$  setLocal MYVAR %MYVAR%
$  show
$  dropGlobal MYVAR
$  show
$endIf

Note that the compile-time variable MYVAR is first defined as a scoped variable with the value xxx. The dollar control option ifThen tests whether MYVAR was defined with $set and since this is TRUE the next four dollar control statements are processed: a new global compile-time variable called MYVAR is defined and is set to the value of the scoped compile-time variable MYVAR, the resulting compile-time variables are shown, the scoped compile-time variable is removed from the system with the option $drop and the resulting compile-time variables are shown again. A similar procedure is followed to change the global compile-time variable MYVAR to a local compile-time variable with the same name and value.

The output generated by the four dollar control options $show follows:

Level SetVal                          Type       Text
-----------------------------------------------------
    0 MYVAR                           SCOPED     xxx
    0 MYVAR                           GLOBAL     xxx

Level SetVal                          Type       Text
-----------------------------------------------------
    0 MYVAR                           GLOBAL     xxx

Level SetVal                          Type       Text
-----------------------------------------------------
    0 MYVAR                           LOCAL      xxx
    0 MYVAR                           GLOBAL     xxx

Level SetVal                          Type       Text
-----------------------------------------------------
    0 MYVAR                           LOCAL      xxx

Observe that this report is called Environment Report. This name is unfortunate, since the variables reported are in fact compile-time variables. Environment variables in GAMS are discussed in section Environment Variables in GAMS below.

Note that if a compile-time variable is referenced with %MYVAR%, it could reference a global, scoped or local compile-time variable called MYVAR. GAMS will always access the compile-time variable MYVAR with the most local scope. Thus if all three scopes are defined, the local compile-time variable is accessed first, then the scoped and then the global, as demonstrated in the following example:

$set XXX scoped
$setLocal XXX local
$setGlobal XXX global
$log %XXX%
$dropLocal XXX
$log %XXX%
$drop XXX
$log %XXX%
$dropGlobal XXX
$log %XXX%

The resulting log output will be:

local
scoped
global
%XXX%

Note that how %XXX% will be handled if no compile-time variable XXX is defined, is determined by the command line parameter stringChk.

For a full list of dollar control options that affect compile-time variables, see section Dollar Control Options for Compile-Time Variables and Environment Variables.

Environment Variables in GAMS

GAMS programs have access to operating system environment variables via %sysEnv.NAME%. Operating system environment variables may be modified or new environment variables may be defined with the dollar control option $setEnv. Consider the following artificial example:

$log %sysEnv.GEORGE%
$setEnv GEORGE Dantzig
$log %sysEnv.GEORGE%
$dropEnv GEORGE
$log %sysEnv.GEORGE%

Note that the dollar control option $dropEnv removes an environment variable. The log output follows:

%sysEnv.GEORGE%
Dantzig
%sysEnv.GEORGE%

There are two environment variables in GAMS that are specific to the GDX facility: GDXCONVERT and GDXCOMPRESS. Since GDX is used by utilities and other programs some general customization can be achieved via these environment variables. Their values determine the type of GDX files that are written. These environment variables may be overwritten through the command line parameters gdxConvert and gdxCompress or inside the GAMS file with the dollar control option $setEnv. Consider the following example that uses the latter functionality:

Scalar x /1/;
$log %sysEnv.GDXCONVERT%
$log %sysEnv.GDXCOMPRESS%
$gdxOut x.gdx
$unLoad x
$gdxOut
$call gdxdump x.gdx -v | grep "File format\|Compression"

$setEnv GDXCONVERT v6
$setEnv GDXCOMPRESS 1
$gdxOut x.gdx
$unLoad x
$gdxOut
$call gdxdump x.gdx -v | grep "File format\|Compression"

$setEnv GDXCONVERT v7
$setEnv GDXCOMPRESS 0
$gdxOut x.gdx
$unLoad x
$gdxOut
$call gdxdump x.gdx -v | grep "File format\|Compression"

Note that gdxdump is a GDX utility that writes the contents of a GDX file as a GAMS formatted text file. The switch -v lets gdxdump print the file version information. With the grep utility we filter the lines that contain either File format or Compression. This code is run with the following call that initializes GDXCOMPRESS and GDXCONVERT:

> gams gdxenv.gms gdxCompress=0 gdxConvert=v6 lo=3

The output follows:

--- Starting compilation
v6
0
--- gdxenv.gms(7) 2 Mb
--- call gdxdump x.gdx -v | grep "File format\|Compression"
*  File format    :    6
*  Compression    :    0
--- gdxenv.gms(14) 2 Mb
--- call gdxdump x.gdx -v | grep "File format\|Compression"
*  File format    :    6
*  Compression    :    1
--- gdxenv.gms(21) 2 Mb
--- call gdxdump x.gdx -v | grep "File format\|Compression"
*  File format    :    7
*  Compression    :    0
--- gdxenv.gms(22) 2 Mb
--- Starting execution - empty program

Compile-Time Constants

Compile-time constants are constants that are related to some functions, model attributes or options. They have a fixed value and are referenced as %prefix.constant%. Here prefix is the name of the respective function, model attribute or option and constant is the name of the constant.

For example, the function handleStatus is used in the context of grid computing. Typically, a collection loop may take the following form:

loop(pp$(handleStatus(h(pp)) = 2), ... );

Alternatively, the following formulation may be used:

loop(pp$(handleStatus(h(pp)=%handleStatus.ready%), ... );

Observe that the compile-time constant %handleStatus.ready% equals the value of 2. See the table below for other compile-time constants that are related to the function handleStatus.

Note
Compile-time constants are replaced at compile time and cannot be manipulated or reassigned.

Though compile-time constants are most often used in the context of the function, model attribute or option indicated with the prefix, they are in fact context free and may be used anywhere where an integer is expected. Consider the following example:

Scalar x / %solPrint.on% /; display x;

A complete list of the compile-time constants is given in Table 2. Note that in the table the term "option" is used in a generic way and may refer to a command line parameter, a model attribute or an option that is used in an option statement.Table 2: Compile-Time Constants

Compile-Time Constant Value
%handleStatus.Unknown% 0
%handleStatus.running% 1
%handleStatus.ready% 2
%handleStatus.failure% 3
%modelStat.optimal% 1
%modelStat.locally Optimal% 2
%modelStat.unbounded% 3
%modelStat.infeasible% 4
%modelStat.locallyInfeasible% 5
%modelStat.intermediateInfeasible% 6
%modelStat.feasibleSolution% 7
%modelStat.integerSolution% 8
%modelStat.intermediateNon-Integer% 9
%modelStat.integerInfeasible% 10
%modelStat.licensingProblem% 11
%modelStat.errorUnknown% 12
%modelStat.errorNoSolution% 13
%modelStat.noSolutionReturned% 14
%modelStat.solvedUnique% 15
%modelStat.solved% 16
%modelStat.solvedSingular% 17
%modelStat.unbounded-NoSolution% 18
%modelStat.infeasible-NoSolution% 19
%solPrint.off% 0
%solPrint.on% 1
%solPrint.silent% 2
%solPrint.summary% (deprecated) 0
%solPrint.report% (deprecated) 1
%solPrint.quiet% (deprecated) 2
%solveLink.chainScript% 0
%solveLink.callScript% 1
%solveLink.callModule% 2
%solveLink.aSyncGrid% 3
%solveLink.aSyncSimulate% 4
%solveLink.loadLibrary% 5
%solveLink.aSyncThreads% 6
%solveLink.threadsSimulate% 7
%solveOpt.replace% 0
%solveOpt.merge% 1
%solveOpt.clear% 2
%solveStat.normalCompletion% 1
%solveStat.iterationInterrupt% 2
%solveStat.resourceInterrupt% 3
%solveStat.terminatedBySolver% 4
%solveStat.evaluationInterrupt% 5
%solveStat.capabilityProblems% 6
%solveStat.licensingProblems% 7
%solveStat.userInterrupt% 8
%solveStat.setupFailure% 9
%solveStat.solverFailure% 10
%solveStat.internalSolverFailure% 11
%solveStat.solveProcessingSkipped% 12
%solveStat.systemFailure% 13

GAMS Compile Time and Execution Time Phase

The GAMS log indicates different phases of a job run in the log file:

...
--- Starting compilation
...
--- Starting execution: elapsed 0:00:00.056
...

During compilation GAMS converts the GAMS user program into lower-level instructions that are executed during execution time. Before the user program is converted into lower-level instructions the compiler processes the input: the compile time variables and macros are substituted and comments are removed. Moreover, during compilation any dollar control option present in the user code is executed. Many of these dollar control options impact the behavior of the compilation phase (e.g. $include instructs the compiler to process a file before continuing processing the remaining part of the current file). The code the compiler actually converts into lower-level instructions is echoed (by default) to the listing file. The compiler also assembles the list of user symbols (sets, parameters, variables, ...) and the list of labels. These lists become immutable after the compiler finishes. So during execution time, for example, no new labels can be added. The only exception from this is during a continued compilation/execution using the save and restart facility. The separation between compile time and execution time is confusing especially for novice users and mistakes as the following are frequent:

file fInput / data.txt /;
scalar iCnt; for (iCnt=1 to 100, put fInput iCnt:0:0 /); putClose fInput;
set i /
$include data.txt
      /;

The intention of the code, that does not work, is clear: The put facility is used to create the input file data.txt that is included via the $include instruction. The problem with this code is that the $include instruction is executed at compile time while the code using the put statement is executed at execution time, i.e. after the compilation phase is over. Hence, the compiler tries to include this file before the put instructions are executed. If the file data.txt is not present, the compiler will terminate with a compilation error, but if a file with name data.txt is present this one will be processed by the $include and a mistake like this might remain undiscovered for a long time.

Most of the time GAMS performs compilation and execution in one GAMS job which makes it even harder to grasp the concept of compile and execution time. The command line parameter action can be used to separate the compilation and execution phase into multiple jobs.

List of Command Line Parameters

In the following two subsections we will present an overview of the command line parameters with brief descriptions. Detailed descriptions of all command line parameters follow in section Detailed Descriptions of All Options below.

General Options

Option Description
actionGAMS processing request
appendExpandExpand file append option
appendLogLog file append option
appendOutOutput file append option
asyncSolLstPrint solution listing when asynchronous solve (Grid or Threads) is used
caseOutput case option for LST file
cErrCompile time error limit
charSetCharacter set flag
curDirCurrent directory
dFormatDate format
dumpOptWrites preprocessed input to the file input.dmp
dumpParmsGAMS parameter logging
dumpParmsLogPrefixPrefix of lines triggered by DumpParms>1
eolOnlySingle key-value pairs (immediate switch)
errMsgPlacing of compilation error messages
errNamName of error message file
errorForce a compilation error with message
errorLogMax error message lines written to the log for each error
etLimElapsed time limit in seconds
execErrExecution time error limit
execModeLimits on external programs that are allowed to be executed
expandExpanded (include) input file name
fdDeltaStep size for finite differences
fdOptOptions for finite differences
fErrAlternative error message file
fileCaseCasing of new file names (put, gdx, ref etc.)
fileStemSets the file stem for output files which use the input file name as stem by default
forceWorkForce GAMS systems to process save files for example with an execution error
forLimGAMS looping limit
G205Use GAMS version 2.05 syntax
GDXGAMS data exchange file name
gdxCompressCompression of generated GDX file
gdxConvertVersion of GDX files generated (for backward compatibility)
gdxUelsUnload labels or UELs to GDX either squeezed or full
gridDirGrid file directory
gridScriptGrid submission script
heapLimitMaximum Heap size allowed in MB
IDEIntegrated Development Environment flag
inputInput file
inputDir, inputDir1..40Input file directories
interactiveSolverAllow solver to interact via command line input
jobTraceJob trace string to be written to the trace file at the end of a GAMS job
keepControls keeping or deletion of process directory and scratch files
libIncDirLibInclude directory
licenseUse alternative license file
logFileLog file name
logLineAmount of line tracing to the log file
logOptionLog option
maxProcDirMaximum number of 225* process directories
MCPRHoldFxPrint list of rows that are perpendicular to variables removed due to the holdfixed setting
multiPassMultipass facility
noNewVarEquTriggers a compilation error when new equations or variable symbols are introduced
on115Generate errors for unknown unique element in an equation
outputListing file name
pageContrOutput file page control option
pageSizeOutput file page size (=0 no paging)
pageWidthOutput file page width
parmFileCommand Line Parameter include file
pLicensePrivacy license file name
prefixLoadPathPrepend GAMS system directory to library load path
procDirProcess Directory
procDirPathDirectory to create process directory in
profileExecution profiling
profileFileWrite profile information to this file
profileTolMinimum time a statement must use to appear in profile generated output
putDirPut file directory
pyMultInstGAMS/Python Multiple Instance Interpreter
pySetupGAMS/Python Setup
referenceSymbol reference file
scrDirScratch directory
scrExtScratch file extension to be used with temporary files
scrNamWork file names stem
seedRandom number seed
stepSumSummary of computing resources used by job steps
strictSingletonError if assignment to singleton set has multiple elements
stringChkString substitution options
suppressCompiler listing option
symbolSymbol table file
sys10Changes rpower to ipower when the exponent is constant and within 1e-12 of an integer
sys11Dynamic resorting if indices in assignment/data statements are not in natural order
sys12Pass model with generation errors to solver
sys15Automatic switching of data structures used in search records
sys16Disable search record memory (aka execute this as pre-GAMS 24.5)
sys17Disable sparsity trees growing with permutation (aka execute this as pre-GAMS 24.5)
sysDirGAMS system directory where GAMS executables reside
sysIncDirSysInclude directory
tabInTab spacing
tFormatTime format
threadsAsyncNumber of threads to be used for asynchronous solve (solveLink=6)
timerInstruction timer threshold in milli seconds
traceTrace file name
traceLevelSolvestat threshold used in conjunction with action=GT
traceOptTrace file format option
user1..5User strings
warningsNumber of warnings permitted before a run terminates
workDirWorking directory
zeroResThe results of certain operations will be set to zero if abs(result) LE ZeroRes
zeroResRepReport underflow as a warning when abs(results) LE ZeroRes and result set to zero

Solver-Related Options

Option Description
bRatioBasis acceptance threshold
CNSConstrained Nonlinear Systems - default solver
DNLPNon-Linear Programming with Discontinuous Derivatives - default solver
domLimDomain violation limit solver default
EMPExtended Mathematical Programs - default solver
forceOptFileOverwrites other option file section mechanism
holdFixedTreat fixed variables as constants
integer1..5Integer communication cells
intVarUpSet default upper bound on integer variables
iterLimIteration limit of solver
limColMaximum number of columns listed in one variable block
limRowMaximum number of rows listed in one equation block
LPLinear Programming - default solver
MCPMixed Complementarity Problems - default solver
MINLPMixed-Integer Non-Linear Programming - default solver
MIPMixed-Integer Programming - default solver
MIQCPMixed Integer Quadratically Constrained Programs - default solver
MPECMathematical Programs with Equilibrium Constraints - default solver
NLPNon-Linear Programming - default solver
nodLimNode limit in branch and bound tree
optCAAbsolute Optimality criterion solver default
optCRRelative Optimality criterion solver default
optDirOption file directory
optFileDefault option file
QCPQuadratically Constrained Programs - default solver
resLimWall-clock time limit for solver
RMINLPRelaxed Mixed-Integer Non-Linear Programming - default solver
RMIPRelaxed Mixed-Integer Programming - default solver
RMIQCPRelaxed Mixed Integer Quadratically Constrained Programs - default solver
RMPECRelaxed Mathematical Programs with Equilibrium Constraints - default solver
savePointSave solver point in GDX file
scriptExitProgram or script to be executed at the end of a GAMS run
scriptFrstFirst line to be written to GAMSNEXT file.
scriptNextScript mailbox file name (GAMSNEXT)
solPrintSolution report print option
solveLinkSolver link option
solverDefault solver for all model types that the solver is capable to process
solverCntrSolver control file name
solverDictSolver dictionary file name
solverInstSolver instruction file name
solverMatrSolver matrix file name
solverSoluSolver solution file name
solverStatSolver status file name
subSysName of subsystem configuration file
sysOutSolver Status file reporting option
threadsNumber of threads to be used by a solver
workFactorMemory Estimate multiplier for some solvers
workSpaceWork space for some solvers in MB

Solve and Restart Options

Option Description
fSaveCreates a forced work file, i.e., the file is saved even if execution errors or other errors occured
restartName of a restart file, see The Save and Restart Feature
restartNamedName of another matching restart file, see Obfuscated Work Files
saveCreates a work file, see The Save and Restart Feature
saveObfuscateCreates an obfuscated work file, see Obfuscated Work Files
symPrefixPrefix all symbols encountered during compilation by the specified string in work file
xSaveCreates a compressed work file
xSaveObfuscateCreates a compressed obfuscated work file

Detailed Descriptions of All Options

In this section we will give detailed descriptions of all options that may be used as command line parameters, in option statements or as model attributes. Note that we indicate for each entry the context in which the option is available. Observe that the options are listed in alphabetical order for easy reference.

action (string): GAMS processing request

Synonym: A

Available: Command line

GAMS currently processes the input file in multiple phases. The two phases in order are:

  • Compilation During this pass, the file is compiled, and syntax errors are checked for. Data initialization statements like scalar, parameter, and table statements are also processed during this stage.
  • Execution During this stage, all execution time statements including assignments, loops, and solves are executed.

The special action GT is related to processing trace records. See option traceLevel for details.

Default: CE

ValueMeaning
R Restart After Solve
C CompileOnly
E ExecuteOnly
CE Compile and Execute
GT Trace Report

appendExpand (boolean): Expand file append option

Synonym: AE

Available: Command line

This option controls the manner of file opening of the option expand.

Default: 1

ValueMeaning
0 Reset expand file
1 Append to expand file

appendLog (boolean): Log file append option

Synonym: AL

Available: Command line

This option is used in conjunction with the setting of logOption to 2 and 4, where the log from the GAMS run is redirected to a file. Setting this option to 1 will ensure that the log file is appended to and not overwritten (replaced).

Default: 0

ValueMeaning
0 Reset log file
1 Append to logfile

appendOut (boolean): Output file append option

Synonym: AO

Available: Command line

Setting this option to 1 will ensure that the listing file is appended to and not overwritten (replaced).

Default: 0

ValueMeaning
0 Reset listing file
1 Append to listing file

asyncSolLst (boolean): Print solution listing when asynchronous solve (Grid or Threads) is used

Available: Command line, Option statement

This option determines whether the solution listing is printed in the listing file when an asynchronous (grid or threads) solve is used and the function handleCollect or command execute_loadHandle successfully collect the results.

Default: 0

ValueMeaning
0 Do not print solution listing into lst file for asynchronous solves
1 Print solution listing into lst file for asynchronous solves

bRatio (real): Basis acceptance threshold

Available: Command line, Option statement, Attribute statement (use before solve)

The value specified for bRatio will cause a basis to be discarded if the number of basic variables is smaller than bRatio times the number of equations.

Certain (pivotal) solution procedures can restart from an advanced basis that is constructed automatically. This option is used to specify whether basis information (probably from an earlier solve) will be used. The use of this basis will be 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 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 has no effect for most MIP solvers because MIP presolve destroys a basis.

Default: 0.25

case (boolean): Output case option for LST file

Available: Command line

This option controls the case of the text in the listing file.

Default: 0

ValueMeaning
0 Write listing file in mixed case
1 Write listing file in upper case only

cErr (integer): Compile time error limit

Available: Command line

The compilation will be aborted after n errors have occurred. By default, there is no error limit and GAMS compiles the entire input file and collects all the compilation errors that occur. If the file is too long and the compilation process is time consuming, cerr could be used to set to a low value while debugging the input file.

Default: 0

ValueMeaning
0 No error limit (default)
n Stop after n errors

charSet (boolean): Character set flag

Available: Command line

This option specifies whether foreign language characters are permitted in comments and text items. For a list of standard GAMS characters, see table Legal Characters.

Default: 1

ValueMeaning
0 Use limited GAMS characters set
1 Accept any character in comments and text items (foreign language characters)

cheat (real): Cheat value, i.e. minimum solution improvement threshold

Available: Attribute statement (use before solve)

For a branch-and-bound based solver, each new feasible solution must be at least the value of cheat better than the current best feasible solution. Note that this may speed up the search, but may cause some solutions, including optimal ones, to be missed. If a model has been solved with a nonzero cheat value, then the optimal solution will be within the cheat value or less of the found solution. Observe that the option cheat is specified in absolute terms (like the option optCA), therefore non-negative values are appropriate for both minimization and maximization models. Note that using this option will invalidate any reporting of the dual bound or optimality gaps. Further, certain solver options can override the cheat setting, e.g., the Cplex option objDif, and some solvers may ignore the cheat option.

Default: 0

CNS (string): Constrained Nonlinear Systems - default solver

Available: Command line, Option statement

The default solver for models of the type Constrained Nonlinear Systems is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

curDir (string): Current directory

Synonym: CDir

Available: Command line

This option sets the current working directory. It is useful when GAMS is called from an external system like Visual Basic. If it is not specified, it will be set to the directory the GAMS module is called from.

cutOff (real): Cutoff value for branch and bound

Available: Attribute statement (use before solve, reset by solve statement)

Within a branch-and-bound based solver, the parts of the tree with an objective value worse than the cutoff value are ignored. Note that this may speed up the initial phase of the branch and bound algorithm (before the first integer solution is found). However, the true optimum may be beyond the cutoff value. In this case the true optimum will be missed and moreover, no solution will be found.

Observe that this option is specified in absolute terms (like the option optCA).

Default: 0

decimals (integer): Decimal places for display statements

Available: Option statement

This option specifies the number of decimals that will be printed for numeric values that do not have a specific print format attached. The range is [0,8].

Default: 3

defPoint (integer): Indicator for passing on default point

Available: Attribute statement (use before solve, reset by solve statement)

This option determines the point that is passed to the solver as a basis. By default, the levels and marginals from the current basis are passed to the solver. In some circumstances (mostly during debugging), it can be useful to pass a standard default input point, i.e. with all levels set to 0 or lower bound.

ValueMeaning
0 Pass user defined levels and marginals to solver
1 Pass default levels and marginals to solver
2 Pass default marginals to solver

dFormat (integer): Date format

Synonym: DF

Available: Command line

This option controls the date format in the listing file. The three date formats correspond to various conventions used around the world. For example, the date December 2, 1996 will be written as 12/02/96 with the default df value of 0, as 02.12.96 with df=1, and as 96-12-02 with df=2.

Default: 0

ValueMeaning
0 Date as mm/dd/yy
1 Date as dd.mm.yy
2 Date as yy-mm-dy

dictFile (real): Force writing of a dictionary file if dictfile > 0

Available: Attribute statement (use before solve, reset by solve statement)

If this option is set to a value that is larger than zero, it will instruct GAMS to make the GAMS names of variables and equations that have been generated by the solve statement available to the solver. In many solver links these names are registered with the solver and hence messages from the solver that involve variables and equations (e.g. an infeasible row or duplicate columns) can be easily interpreted by the user. Consider the following example:

Row 'demand(new-york)' infeasible, all entries at implied bounds.

Duplicate columns x(san-diego.new-york) and x(san-diego.chicago) make problem unbounded.

If we have modelname.dictfile=0 the same messages will read as follows:

Row 'c4' infeasible, all entries at implied bounds.

Duplicate columns x4 and x5 make problem unbounded.

Sometimes a dictionary is required for a successful run. Some solver option use the original GAMS names and need to be matched with the variables 1..n and equations 1..m in the solver. The dictionary file with its API allows to calculate such a mapping. Note that this is done automatically inside the solver links, so users do not need to be concerned with it.

For example, in the indicator constraints implementation a binary indicator variable is matched to a constraint. In the model [INDIC01] from the GAMS test library, this matching is done in the following GAMS/Cplex option file cplex.opt:

indic eq3(dice,f,fp)$comp(dice,f,fp) 1

Observe that if no dictionary is available, we will get an error:

**** Unable to read dictionary file required for indicator constraints

However, the dictionary comes at a price. Generating the names and calculating and storing the map takes time and space. In addition, GAMS names take up space in the solver. Thus, if the user needs very fast generation and does not need names, setting dictFile to zero is a good option.

Further, note that some solvers allow to suppress the loading of names (using the solver option names=no). Suppressing the loading of names facilitates to use the name mapping features required for models like INDIC01 above, but does not load the names into the solver name space for better reporting (and hence saves some space).

dispWidth (integer): Number of characters to be printed in the column labels of all subsequent display statements

Available: Option statement

This option controls the number of characters that are shown for a label in a column in the context of the display statement. Consider the following example:

 Set i / thislabelhas24characters /;
 Parameter p(i,i) / thislabelhas24characters.thislabelhas24characters 2/;
 display p;

 option dispWidth=24;
 display p;

The two display statements in this code will generate the following output:

----      3 PARAMETER p

                          thislabel~

thislabelhas24characters       2.000

----      6 PARAMETER p

                          thislabelhas24characters

thislabelhas24characters                     2.000

Observe that in the first display, the label in the column is cut off after 10 characters, while in the second display it is shown in full.

Note that the default value is 10 and the range is [10,31].

Default: 10

dmpOpt (no value): Debugging option: causes GAMS to echo the runtime option settings

Available: Option statement

This debugging option has the effect that all available option statements and their current values are listed in the listing file.

dmpSym (no value): Debugging option: causes GAMS to echo the symbol table to the listing file

Available: Option statement

This debugging option is especially useful for diagnosing memory problems. It has the effect that GAMS will report the number of elements that are stored for each identifier at the point in the program where this option is inserted. The report that is generated in this way is called a memory dump. For details, see section Finding the Causes for Excessive Memory Use.

DNLP (string): Non-Linear Programming with Discontinuous Derivatives - default solver

Available: Command line, Option statement

The default solver for models of the type Nonlinear Programs with Discontinuous Derivatives is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

domLim (integer): Domain violation limit solver default

Available: Command line, Option statement, Attribute statement (use before solve)

This option 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 and returns solver status 5 EVALUATION ERROR LIMIT. Nonlinear solvers have difficulties recovering after attempting an undefined operation. Note that some solvers operate in a mode where trial function evaluations are performed. These solvers will not move to points at which evaluation errors occur, thus the evaluation errors at trial points are not counted against the limit.

Default: ∞

domUsd (integer): Number of domain violations

Available: Attribute statement (use after solve)

This model attribute returns the number of domain violations after a solve.

dualCheck (integer): Output on the reduced cost condition

Available: Option statement

If this option is set to 1, the reduced cost condition for each variable in the column listing will be evaluated using the equation marginals. The default value is zero, which means that the calculation will be omitted.

Default: 0

dumpOpt (integer): Writes preprocessed input to the file input.dmp

Available: Command line

This option with value larger than 9 creates a GAMS input file of that will reproduce results encapsulating all include files into one GAMS file. If activated, a file will be written containing GAMS source code for the entire problem. The file name is the input file name with the extension dmp. For values smaller than 10, this option tries to encapsulate all the items from a restart file that are needed to execute a solve.

For the values smaller than 10, consider the following example. We will split the transportation model [TRNSPORT] into two files and run them with the save and restart feature. Then we will illustrate the option dumpOpt. The first file called trans1.gms contains the first part of the model up to and including the model statement:

Sets
       i   canning plants   / seattle, san-diego /
       j   markets          / new-york, chicago, topeka / ;

Parameters
       a(i)  capacity of plant i in cases
         /    seattle     350
              san-diego   600  /

       b(j)  demand at market j in cases
         /    new-york    325
              chicago     300
              topeka      275  / ;

Table d(i,j)  distance in thousands of miles
                    new-york       chicago      topeka
      seattle          2.5           1.7          1.8
      san-diego        2.5           1.8          1.4  ;

Scalar f  freight in dollars per case per thousand miles  /90/ ;

Parameter c(i,j) transport cost in thousands of dollars per case ;
c(i,j) = f * d(i,j) / 1000 ;

Variables
    x(i,j)  shipment quantities in cases
    z       total transportation costs in thousands of dollars ;
Positive Variable x ;

Equations
    cost        define objective function
    supply(i)   observe supply limit at plant i
    demand(j)   satisfy demand at market j ;

cost ..        z  =e=  sum((i,j), c(i,j)*x(i,j)) ;
supply(i) ..   sum(j, x(i,j))  =l=  a(i) ;
demand(j) ..   sum(i, x(i,j))  =g=  b(j) ;

model transport /all/ ;

Note that we removed all comments for brevity. The second file called trans2.gms contains the solve statement and the display statement:

solve transport using lp minimizing z ;
display x.l, x.m ;

We run the first file with the command line parameter save and thus generate eight work files. For details on work files, see chapter The Save and Restart Feature. Then we run trans2.gms restarting from the saved work files. The result will be equivalent to running the original model [TRNSPORT].

Note
The option dumpOpt can only be used effectively, if the first line in the second file, trans2.gms, is the solve statement.

Now, we will illustrate the use of the option dumpopt, by running he second file with the following command:

   > gams trans2 r=trans dumpopt=1

Here trans is the name of the saved files generated from the file trans1.gms. As a result of this call, a new file will be created. It is called trans2.dmp and has the following content:

* This file was written with DUMPOPT=1 at 11/30/11 08:43:06

* INPUT = C:\Fred\GAMS options\test\trnsport2.gms
* DUMP = C:\Fred\GAMS options\test\trnsport2.dmp
* RESTART = C:\Fred\GAMS options\test\trans1.g0?

*           with time stamp of 11/30/11 08:40:41

* You may have to edit this file and the input file.

*  There are 5 labels

Set WorkFileLabelOrder dummy set to establish the proper order /
    seattle,san-diego,new-york,chicago,topeka /;

Model transport;

Variable z total transportation costs in thousands of dollars;

Set i(*) canning plants /
    seattle,san-diego /

Set j(*) markets /
    new-york,chicago,topeka /

Parameter c(i,j) transport cost in thousands of dollars per case /
    seattle.new-york 0.225,seattle.chicago 0.153,seattle.topeka 0.162,
    san-diego.new-york 0.225,san-diego.chicago 0.162,san-diego.topeka 0.126 /

Positive Variable x(i,j) shipment quantities in cases;

Parameter a(i) capacity of plant i in cases /
    seattle 350,san-diego 600 /

Parameter b(j) demand at market j in cases /
    new-york 325,chicago 300,topeka 275 /

Equation demand(j) satisfy demand at market j;

Equation supply(i) observe supply limit at plant i;

Equation cost define objective function;

*      *** EDITS FOR INPUT FILE ***

 *** END OF DUMP ***

Note that all the data that enters the model in the solve statement has been regenerated. Observe that the parameter d has not been regenerated since it does not appear in the model. Changing the value of the parameter dumpopt will have the effect that other names are used for the identifiers in the regenerated file, see table below.

Default: 0

ValueMeaning
0 No dumpfile
1 Extract referenced data from the restart file using original set element names
2 Extract referenced data from the restart file using new set element names
3 Extract referenced data from the restart file using new set element names and drop symbol text
4 Extract referenced symbol declarations from the restart file
11 Write processed input file without comments
21 Write processed input file with all comments

dumpParms (integer): GAMS parameter logging

Synonym: DP

Available: Command line

This option lists the settings of all command line parameters that were changed or set by the user, GAMS or the IDE during the current run. Note that with dp=2 all file operations are listed, including the full path of each file on which any operation is performed.

Default: 0

ValueMeaning
0 No logging
1 Lists accepted/set parameters
2 Log of file operations plus list of accepted/set parameters

dumpParmsLogPrefix (string): Prefix of lines triggered by DumpParms>1

Synonym: DPLP

Available: Command line

This option prefixes in the log file the list of all command line parameters that were changed or set by the user, GAMS or the IDE during the current run. Note that the option dumpParms must be greater than 1 for dumpParmsLogPrefix to have an effect.

Default: stars

eject (no value): Inject a page break into the LST file

Available: Option statement

This option has the effect that a page break is inserted in the listing file.

EMP (string): Extended Mathematical Programs - default solver

Available: Command line, Option statement

The default solver for models of the type Extended Mathematical Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

eolOnly (integer): Single key-value pairs (immediate switch)

Synonym: EY

Available: Command line

This option controls formatting of parameters on the command line and is useful in conjunction with the option parmFile.

This option acts as an immediate switch that forces only one option-value pair to be read on a line. Note that by default, any number of option-value pairs may be present on the same line and termination characters and quoting is necessary to determine the end of key/value pair. With this option active the remainder after the key is used as the value independent of quoting or termination characters.

Default: 0

ValueMeaning
0 Any number of keys or values
1 Only one key-value pair on a line

errMsg (integer): Placing of compilation error messages

Available: Command line

This option controls the position of the compilation error messages in the listing file. To illustrate the option, consider the following slice of GAMS code:

Set       i     / 1*10 / ;
Set       j(i)  / 10*11 /;
Parameter a(jj) / 12 25.0 / ;

After running this code, the listing file will contain the following lines:

   1  Set       i     / 1*10 / ;
   2  Set       j(i)  / 10*11 /;
****                        $170
   3  Parameter a(jj) / 12 25.0 / ;
****               $120
   4

120  Unknown identifier entered as set
170  Domain violation for element

**** 2 ERROR(S)   0 WARNING(S)

Note that numbers $170 and $120 flag the two errors as they occur, but the errors are explained only at the end of the compilation output. However, if the code is run using the option errmsg=1, the resulting listing file will contains the following:

   1  Set       i     / 1*10 / ;
   2  Set       j(i)  / 10*11 /;
****                        $170
**** 170  Domain violation for element
   3  Parameter a(jj) / 12 25.0 / ;
****               $120
**** 120  Unknown identifier entered as set
   4
**** 2 ERROR(S)   0 WARNING(S)

Observe that the explanation for each error is provided immediately following the error marker.

Default: 0

ValueMeaning
0 Place error messages at the end of compiler listing
1 Place error messages immediately following the line with the error
2 Suppress error messages

errNam (string): Name of error message file

Available: Command line

This option specifies the name of a file defining the internally used compiler error messages. It is used to change the name from the default name gamserrs.txt.

error (string): Force a compilation error with message

Available: Command line

This option forces a parameter error with a specified message. It is useful in the context of incorporating a GAMS file within another batch file where the user needs to have control over the conditions when GAMS is called. See also section Conditional Compilation.

To illustrate, the default GAMS log file from running a model with the option error=Hallo will look as follows:

gams: **** Error: Parameter error(s)
    :             Reading parameter(s) from "command line"
    :             *** Error Hallo
    :             Finished reading from "command line"

errorLog (integer): Max error message lines written to the log for each error

Synonym: ER

Available: Command line

This option controls the number of error message lines that are written to the log file.

Under the IDE, the default is reset to 99.

Default: 0

ValueMeaning
0 No error messages to LOG file
n Number of lines for each error that will be written to LOG file

etAlg (real): Elapsed time it took to execute the solve algorithm

Available: Attribute statement (use after solve)

This model attribute returns the elapsed time it took to execute the solve algorithm. The time does not include the time to generate the model, the time to read and write files etc. The time is expressed in seconds of wall-clock time.

etLim (real): Elapsed time limit in seconds

Synonym: ETL

Available: Command line

This option controls the time limit for a GAMS job. The system will terminate with a compilation or execution error if the limit is reached. A GAMS job will terminate if the elapsed time in seconds exceeds the value of etLim.

Default: ∞

etSolve (real): Elapsed time it took to execute a solve statement in total

Available: Attribute statement (use after solve)

This model attribute returns the elapsed time it took to execute a solve statement in total. This time includes the model generation time, the time to read and write files, the 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 (real): Elapsed time taken by the solver only

Available: Attribute statement (use after solve)

This model attribute returns the elapsed time taken by the solver only. This does not include the GAMS model generation time and the time taken to report and load the solution back into the GAMS database. The time is expressed in seconds of wall-clock time.

execErr (integer): Execution time error limit

Available: Command line

This option puts an upper limit on the number of errors that may be found during execution or preprocessing associated with a solve statement. If more than execErr errors have been found GAMS will abort.

Default: 0

ValueMeaning
0 No errors allowed limit
n Max number allowed

execMode (integer): Limits on external programs that are allowed to be executed

Available: Command line

A higher value denotes a more restrictive alternative. If the restriction level n is chosen, then the restriction levels less than n will also be active. For example, if restriction level 3 is chosen, then restrictions 2 and 1 will apply too.

Default: 0

ValueMeaning
0 Everything allowed
1 Interactive shells in $call and execute commands are prohibited
2 Embedded Code and all $call and execute commands are prohibited
3 $echo or put commands can only write to directories in or below the working or scratchdir
4 $echo and put commands are not allowed

expand (string): Expanded (include) input file name

Synonym: EF

Available: Command line

This option generates a file that contains information about all the input files processed during a particular compilation. By default, the names of the input files are composed by completing the name with the current directory.

Consider the following exmaple:

$call rm expfile.txt
$onecho > file1.inc
a = a*2; display a;
$include file2.inc
$offecho
$onecho > file2.inc
a = a+1; display a;
$include file3.inc
$offecho
$onecho > file3.inc
a = a**2; display a ;
$offecho
parameter a / 1 /;
$include file3.inc
$include file2.inc
$include file1.inc

If the model is run with the command line parameter ef=expfile.txt, a file called expfile.txt will be generated. This file will contain the following lines:

     1 INPUT       0     0        0        1       29  C:\GAMS\Examples\expand.gms
     2 CALL        0     1        1        1        1  rm expfile.txt
     3 INCLUDE     1     1       14       14       15  C:\GAMS\Examples\file3.inc
     4 INCLUDE     1     1       15       16       19  C:\GAMS\Examples\file2.inc
     5 INCLUDE     2     4        2       18       19  C:\GAMS\Examples\file3.inc
     6 INCLUDE     1     1       16       20       25  C:\GAMS\Examples\file1.inc
     7 INCLUDE     2     6        2       22       25  C:\GAMS\Examples\file2.inc
     8 INCLUDE     3     7        2       24       25  C:\GAMS\Examples\file3.inc
     9 EXIT        0     1       20       29       29  C:\GAMS\Examples\expand.gms

Note that the first row always refers to the parent file, in this case the file expand.gms. The first column gives the sequence number of the input files that were encountered. The second column refers to the type of file that is referenced. The following file types are possible:

0    INPUT
1    INCLUDE
2    BATINCLUDE
3    LIBINCLUDE
4    SYSINCLUDE

Observe that $call is also listed. The third column describes the depth for nested include files. The fourth column provides the sequence number of the parent file for the file being referenced. The fifth column gives the local line number in the parent file where the dollar control option $include appeared. The sixth column gives the global (expanded) line number which contained $include. The seventh column provides the total number of lines in the file after it is processed. The last column provides the name of the file.

Note that the listing in the expand file is similar to the include file summary in the listing file of the model.

fdDelta (real): Step size for finite differences

Available: Command line, Option statement, Attribute statement (use before solve)

This option allows users to control the step size while the numerical Hessian and numerical derivatives are computed in the context of the function suffixes .hessn and .gradn. For functions with one argument, GAMS evaluates the function at f(x-d) and f(x+d) for the numerical gradient. If function values are used for the numerical Hessian, GAMS will evaluate at f(x-2d), f(x) and f(x+2d). For functions with multiple arguments, the same calculations are performed for the components of the input argument vector.

Default: 1.0E-05

fdOpt (integer): Options for finite differences

Available: Command line, Option statement, Attribute statement (use before solve)

This option allows users to control how numerical derivatives are computed. The values provide choice regarding the scaling of steps, Hessian calculation method and the use of numerical first derivatives.

Default: 0

ValueMeaning
0 All derivatives analytically, for numerical Hessian use gradient values, scale delta
1 All derivatives analytically, for numerical Hessian use function values, scale delta
2 Gradient analytically, force Hessian numerically using gradient values, scale delta
3 Gradient analytically, force Hessian numerically using function values, scale delta
4 Force gradient and Hessian numerically, scale delta
10 Same as 0, but no scale of delta
11 Same as 1, but no scale of delta
12 Same as 2, but no scale of delta
13 Same as 3, but no scale of delta
14 Same as 4, but no scale of delta

fErr (string): Alternative error message file

Available: Command line

This option redirects the compilation error messages to a file and names the file. By default, the file name is composed by completing the name with the scratch directory and the scratch extension. Note that under default settings such a file with compilation error messages is not generated. This option can be used when GAMS is being integrated into other environments like Visual Basic. The error messages that are reported in the listing file may be extracted with this option and their display may be controlled from the environment that is calling GAMS.

To illustrate, consider the slice of GAMS code that we used to explain the option errMsg. If we call this code with the command line parameter ferr=myfile.err, a file called myfile.err will be created in the scratch directory. This file will contain the following lines:

    0     0      0      0 D:\GAMS\NEW.LST
    1     1    170     31 D:\GAMS\NEW.GMS
    2     2    120     14 D:\GAMS\NEW.GMS

Note that the first column refers to the global row number of the error in the listing file. The second column refers to the row number of the error in the individual file where the problem occured. This will be different from the first column only if the error occured in an include file. In this case, the second column will contain the line number in the include file where the error occurred, while the first number will contain the global line number (as reported in the listing file) where the error occured. The number in the third column refers to the error number of the compilation error. The fourth number refers to the column number of the error in the source file. The last column contains the individual file in which the error occurred.

fileCase (integer): Casing of new file names (put, gdx, ref etc.)

Available: Command line

This option facilitates modifying the case of file names for files like put files, GDX files, reference files. It only works with new file names. However, note that it won't create trnsport.REF if TRNSPORT.ref already exists.

Default: 0

ValueMeaning
0 Causes GAMS to use default casing
1 Causes GAMS to upper case file names
2 Causes GAMS to lower case file names

fileStem (string): Sets the file stem for output files which use the input file name as stem by default

Available: Command line

By default, some output files use the input file name as base. If the names of these output files were not set explicitly, then this option may be used to set another name than the input file name as base for these output files. In particular, the names for the following files may be set with fileStem: dump files (see option dumpOpt), GDX files (if the option GDX was set to default), log files (see option logFile), lst files (see option output), reference files (if the option reference was set to default) and trace summary files (see option trace).

forceOptFile (integer): Overwrites other option file section mechanism

Available: Command line

Default: 0

forceWork (boolean): Force GAMS systems to process save files for example with an execution error

Synonym: FW

Available: Command line

Most of the work files generated by GAMS using the command line parameter save are saved in binary format. The information inside these files will change from one GAMS version to another GAMS version. GAMS makes every attempt to be backward compatible and ensure that all new GAMS systems are able to read save files generated by older GAMS systems. However, at certain versions, we are forced to concede default incompatibility (regarding save files, not source files) in order to protect efficiency. The option forceWork may be used to force newer GAMS systems into translating and reading save files generated by older systems.

Default: 0

ValueMeaning
0 No translation
1 Try translation

forLim (integer): GAMS looping limit

Available: Command line, Option statement

This option specifies the maximum number of permitted executions of control structures with a for statement, a while statement or a repeat statement before GAMS signals an execution error and terminates the control structure.

Default: ∞

fSave (boolean): Creates a forced work file, i.e., the file is saved even if execution errors or other errors occured

Available: Command line

This option allows to save a file even in the face of execution or other errors. How it works depends on the command line parameter save.

Note that the option value of 1 is mainly used by solvers that can be interrupted from the terminal.

Default: 0

ValueMeaning
0 Workfile only written to file specified by SAVE if no errors occur
1 Workfile always written to file specified by SAVE or if SAVE is not present to a name made up by GAMS

G205 (integer): Use GAMS version 2.05 syntax

Available: Command line

This option sets the level of the GAMS syntax and is mainly used to ensure backward compatibility. New keywords have been introduced in the GAMS language since Release 2.05. Models developed earlier that use identifiers that have since become keywords will cause errors when they are run with the latest version of GAMS. This option enables users to run such old models.

For example, the word "if" is a keyword in GAMS that was introduced with the first version of Release 2.25. Setting the option g205=1 allows the word "if" to be used as an identifier since it was not a keyword in Release 2.05. As another example, the word "for" is a keyword in GAMS that was introduced with the later versions of Release 2.25. Setting the option g205=2 allows "for" to be used as an identifier since it was not a keyword in the first version of Release 2.25.

Note
If the values 1 or 2 are specified for option g205, then it will not be permitted to use enhancements of the GAMS language that were introduced in later versions.

Default: 0

ValueMeaning
0 Use only latest syntax
1 Allow version 2.05 syntax only
2 Allow version 2.25 syntax only

GDX (string): GAMS data exchange file name

Available: Command line

This option specifies the name of the GAMS data exchange file and causes a GDX file to be written hat contains all data in the model at the end of the job. Setting gdx to the string 'default' causes GAMS to create a GDX file with the gms file root name and a gdx extension. Thus gams the call

   > gams trnsport gdx=default

will cause GAMS to write the GDX file trnsport.gdx.

gdxCompress (boolean): Compression of generated GDX file

Available: Command line

This option specifies whether the GDX files are compressed or not.

Default: 0

ValueMeaning
0 Do not compress GDX files
1 Compress GDX files

gdxConvert (string): Version of GDX files generated (for backward compatibility)

Available: Command line

This option specifies in which format the GDX files will be written.

Default: v7

ValueMeaning
v5 Version 5 GDX file, does not support compression
v6 Version 6 GDX file
v7 Version 7 GDX file

gdxUels (string): Unload labels or UELs to GDX either squeezed or full

Available: Command line, Option statement

This option specifies the UEL export mode. The UEL table may be written to a GDX file in two different modes. In squeezed mode, only the UELs that are required by the exported symbols are exported. In full mode, all UELs are exported. The following code snippet illustrates the difference:

Set       i    / i1*i5 /;
Parameter p(i) / i3 3 /;

option gdxuels = squeezed;
execute_unload 'squeezed' p;
execute 'gdxdump squeezed UelTable=i';

option gdxuels = full;
execute_unload 'full' p;
execute 'gdxdump full UelTable=i';

The file squeezed.gdx will contain the following lines:

Set i /
  'i3' /;

Parameter p(*) /
'i3' 3 /;

The file full.gdx on the other hand, will contain the following lines:

Set i /
  'i1' ,
  'i2' ,
  'i3' ,
  'i4' ,
  'i5' /;

Parameter p(*) /
'i3' 3 /;

Default: squeezed

ValueMeaning
Squeezed Write only the UELs to Universe, that are used by the exported symbols
Full Write all UELs to Universe

gridDir (string): Grid file directory

Synonym: GDir

Available: Command line

This option sets the grid file directory. Note that each GAMS job has only one grid file directory.

gridScript (string): Grid submission script

Synonym: GScript

Available: Command line

This option provides the name of a script file that is used to submit grid computing jobs. If only the file name is given the file is assumed to be located in the system directory. A fully qualified name can be given as well. The script needs to be similar to the file gmsgrid.cmd on Windows machines with arguments that give name and location of the solver executable, the solver control file name and the name of the scratch directory. For an example of such a script, see section The Grid Facility: Architecture and Customization. However, note that advanced knowledge of how GAMS sets up and calls solvers is needed for successful use.

Default: gmsgrid

handle (real): Unique handle number of SOLVE statement

Available: Attribute statement (use after solve)

The model attribute handle contains a unique identification of each submitted solution request and is typically stored in a parameter defined over a set that covers all model instances. The handle number may be used by the functions handleCollect, handleStatus, handleDelete, handleSubmit and readyCollect. For details see chapter The Grid and Multi-Threading Solve Facility.

heapLimit (real): Maximum Heap size allowed in MB

Synonym: HL

Available: Command line

This option allows to limit the amount of memory a GAMS job may use during compilation and execution. If the needed data storage exceeds this limit, the job will be terminated.

Default: ∞

holdFixed (boolean): Treat fixed variables as constants

Available: Command line, Attribute statement (use before solve)

This option facilitates treating fixed variables as constants. Thus the problems size may be reduced.

Default: 0

ValueMeaning
0 Fixed variables are not treated as constants
1 Fixed variables are treated as constants

IDE (boolean): Integrated Development Environment flag

Available: Command line

This option instructs GAMS to write special instructions to the log file that are in turn read by the IDE.

Default: 0

ValueMeaning
0 Unknown environment
1 Runs under GAMS IDE

input (string): Input file

Synonym: I

Available: Command line

Completing the input file name with the current directory composes the final name. If such a file does not exist and the extension was not specified, the standard input extension will be attached and a second attempt will be made to open an input file.

inputDir, inputDir1..40 (string): Input file directories

Synonym: IDIR

Available: Command line

In general, GAMS searches for input and include files in the current working directory only. This option allows the user to specify additional directories for GAMS to search for include and batinclude files. A maximum of 40 separate directories may be included. The directories are separated by Operating System specific symbols. For example, on a PC the separator is a semicolon (;) character and under Unix it is the colon (:) character. Note that libinclude and sysinclude files are handled differently. Their paths are specified with the command line parameters libIncDir and sysIncDir respectively.

Consider the following illustration:

   > gams myfile idir \mydir;\mydir2

Note that the search order for the file myfile.gms and all included files in PC systems will be as follows: (1) the current directory, (2) the directories specified by inputdir in their respective order (here the directories: \mydir and \mydir2). Under Unix, the corresponding GAMS call will be:

   > gams myfile idir \mydir:\mydir2

Note that the information in the option inputDir may be also transferred to GAMS by entering the individual directories separately. A maximum of 40 directories may be passed on in this manner. The number appended to InputDir is important since the earlier InputDir directories will be searched first.

The example above may alternatively be formulated in the following way:

   > gams myfile idir1 mydir1 idir2 mydir2

Note that in this case the search order will be as follows:

  1. current directory
  2. mydir1
  3. mydir2

Observe that we could modify the command in the following way:

   > gams myfile idir3 \mydir1 idir2 \mydir2

Note that in this case the search order will be as follows:

  1. current directory
  2. mydir2
  3. mydir1

Thus it is not the order in which the directories are specified that matters, but the number of the option inputDir that they have been assigned to.

integer1..5 (integer): Integer communication cell N

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies an integer communication cell that may contain any integer number.

interactiveSolver (boolean): Allow solver to interact via command line input

Available: Command line

Default: 0

ValueMeaning
0 Interaction with solvelink 0 is not supported
1 Interaction with solvelink 0 is supported

intVarUp (integer): Set default upper bound on integer variables

Available: Command line, Option statement

Default: 1

ValueMeaning
0 Set default upper bound for integer variables to +INF
1 Pass a value of 100 instead of +INF to the solver as upper bound for integer variables
2 Same as 0 but writes a message to the log if the level of an integer variable is greater than 100
3 Same as 2 but issues an execution error if the level of an integer variable is greater than 100

iterLim (integer): Iteration limit of solver

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies the maximum number of permitted solver iterations, before the solver terminates the run. If this limit is reached, the solver will terminate and will return solver status 2 ITERATION INTERRUPT. Note that the definition of what constitutes an interation depends on the solver. For LP solvers, iterlim often refers to the number of simplex iterations (i.e., pivots). For MIP solvers, iterlim often refers to the cumulative number of simplex iterations over all solves of LP relaxations. Observe that iterlim does not apply to all iterations. For example, it does not apply to barrier iterations and major iterations in nonlinear solvers. For these iterations solver-specific options need to be set.

Default: 2000000000

iterUsd (integer): Number of iterations used

Available: Attribute statement (use after solve)

This model attribute returns the number of iterations used after a solve.

jobTrace (string): Job trace string to be written to the trace file at the end of a GAMS job

Synonym: JT

Available: Command line

This option specifies a string that is written to the trace file at the end of a GAMS job.

keep (boolean): Controls keeping or deletion of process directory and scratch files

Available: Command line

This option controls whether to keep the process directory. In the process directory the temporary/scratch files are located, unless the options scrDir or procDir were used.

Default: 0

ValueMeaning
0 Delete process directory
1 Keep process directory

libIncDir (string): LibInclude directory

Synonym: LDIR

Available: Command line

This option specifies the name of the directory to be used by GAMS for libinclude files that do not have a full path specification. An absolute or relative path may be specified. If the option lDir is not set, it will be set to the subdirectory inclib of the GAMS system directory. A relative path is relative to the GAMS system directory.

Note that if the option ldir parameter is set, the default library include directory will not not searched.

Attention
Only one directory may be set with the option lDir. Thus the string specified will be treated as one directory. If additional directories are added, errors will be reported.

Consider the following example:

   > gams myfile ldir mydir

Note that GAMS will search for any referenced libinclude file in the directory <GAMS System Directory>/mydir.

license (string): Use alternative license file

Available: Command line

This option specifies the name the file that contains the GAMS license. It may be used to change the name from the default gamslice.txt that is located in the system directory. This option should only be used by advanced users attempting to override internal license information.

limCol (integer): Maximum number of columns listed in one variable block

Available: Command line, Option statement, Attribute statement (use before solve)

This option controls the number of columns that are listed for each variable in the column listing in the listing file. Note that the value of zero will suppress the column listing.

Default: 3

limRow (integer): Maximum number of rows listed in one equation block

Available: Command line, Option statement, Attribute statement (use before solve)

This option controls the number of rows that are listed for each equation in the equation listing in the listing file. Note that the value of zero will suppress the equation listing.

Default: 3

line (integer): Line number of last solve of the corresponding model

Available: Attribute statement (use after solve)

This model attribute returns the line number of the last solve of the respective model.

linkUsed (integer): Integer number that indicates the value of SolveLink used for the last solve

Available: Attribute statement (use after solve)

logFile (string): Log file name

Synonym: LF

Available: Command line

logLine (integer): Amount of line tracing to the log file

Synonym: LL

Available: Command line

This option may be used to limit the number of line tracing sent out to the log file during the compilation phase of a GAMS run. Note that setting this option to zero will cause the line tracing to be suppressed for all phases of the GAMS processing.

The log file that results from running the model [TRNSPORT] with the option ll=0 is shown below.

--- Starting compilation
--- Starting execution: elapsed 0:00:00.018
--- Generating LP model transport
---   6 rows  7 columns  19 non-zeroes
--- Executing CPLEX: elapsed 0:00:00.060

IBM ILOG CPLEX   24.8.2 r59988 Released Jan  3, 2017 DEG x86 64bit/Mac OS X
Cplex 12.7.0.0

Reading data...
Starting Cplex...
Space for names approximately 0.00 Mb
Use option 'names no' to turn use of names off
Tried aggregator 1 time.
LP Presolve eliminated 1 rows and 1 columns.
Reduced LP has 5 rows, 6 columns, and 12 nonzeros.
Presolve time = 0.01 sec. (0.00 ticks)

Iteration      Dual Objective            In Variable           Out Variable
     1              73.125000    x(Seattle.New-York) demand(New-York) slack
     2             119.025000     x(Seattle.Chicago)  demand(Chicago) slack
     3             153.675000    x(San-Diego.Topeka)   demand(Topeka) slack
     4             153.675000  x(San-Diego.New-York)  supply(Seattle) slack
LP status(1): optimal
Cplex Time: 0.03sec (det. 0.01 ticks)

Optimal solution found.
Objective :         153.675000

--- Restarting execution
--- Reading solution for model transport
instructions that will go to the log file
more instructions that will go to the log file
*** Status: Normal completion
--- Job trnsport.gms Stop 02/09/17 15:43:43 elapsed 0:00:00.275

If we compare this output to the output shown in the example of option logFile, we will observe that the line numbers are missing from this log file.

Default: 2

ValueMeaning
0 No line tracing
1 Minimum line tracing
2 Automatic and visually pleasing

logOption (integer): Log option

Synonym: LO

Available: Command line

This option controls the location of the output log of a GAMS run. By default, GAMS directs the log of the run to the screen/console. If logOption is set to 2, the log will be redirected to a file. With logOption=3 all the output goes to the standard output. Note that if no file name is provided for the log through the option logFile, the file name will be the input file name with the extension .log. Observe that the settings zero and 2 may be used to permit jobs to run in the background.

To illustrate, consider the following call:

   > gams trnsport lo=2

Note that the rhe resulting log file, trnsport.log, will be identical to the file myfile.log that is shown as part of the description of the option logFile.

Default: 1

ValueMeaning
0 No log output
1 Log output to screen (console)
2 Log output to logfile
3 Log output to standard output
4 Log output to logfile and standard output

LP (string): Linear Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Linear Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

marginals (integer): Indicator for marginals present

Available: Attribute statement (use after solve)

maxInfes (real): Maximum of infeasibilities

Available: Attribute statement (use after solve)

This model attribute returns the maximum number of infeasibilities after a solve.

maxProcDir (integer): Maximum number of 225* process directories

Available: Command line

This option controls the maximum number of work file directories that may be generated by GAMS. By default they are called 225a, 225b, ..., 225aa, 225ab ... Note that the label 225 may be changed with the option procDir.

Default: 700

MCP (string): Mixed Complementarity Problems - default solver

Available: Command line, Option statement

The default solver for models of the type Mixed Complementarity Problems is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

MCPRHoldFx (boolean): Print list of rows that are perpendicular to variables removed due to the holdfixed setting

Available: Command line, Option statement, Attribute statement (use before solve)

Default: 0

meanInfes (real): Mean of infeasibilities

Available: Attribute statement (use after solve)

This model attribute returns the mean of the infeasibilities after a solve.

measure (no value): Output of time and memory use since the last measure statement or the program beginning

Available: Option statement

This option has the effect that three measurements will be displayed: the memory and time usage since the last option statement measure and the total time used. See also the related option profile.

memoryStat (no value): Show memory statistics in the LST file

Available: Option statement

This option has the effect that memory statistics will be shown in the listing file.

MINLP (string): Mixed-Integer Non-Linear Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Mixed Integer Nonlinear Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

MIP (string): Mixed-Integer Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Mixed Integer Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

MIQCP (string): Mixed Integer Quadratically Constrained Programs - default solver

Available: Command line, Option statement

The default solver for models of the type Mixed Integer Quadratically Constrained Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

modelStat (integer): Integer number that indicates the model status

Available: Attribute statement (use after solve)

This model attribute returns the model status after a solve. Observe that there are compile-time constants that are related to modelStat. Note that additional information to the values given in the table below is provided in section Model Status.

ValueMeaning
1 Optimal
2 Locally Optimal
3 Unbounded
4 Infeasible
5 Locally Infeasible
6 Intermediate Infeasible
7 Intermediate Nonoptimal
8 Integer Solution
9 Intermediate Non-Integer
10 Integer Infeasible
11 Licensing Problem
12 Error Unknown
13 Error No Solution
14 No Solution Returned
15 Solved Unique
16 Solved
17 Solved Singular
18 Unbounded - No Solution
19 Infeasible - No Solution

MPEC (string): Mathematical Programs with Equilibrium Constraints - default solver

Available: Command line, Option statement

The default solver for models of the type Mathematical Program with Equilibrium Constraints is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

multiPass (boolean): Multipass facility

Synonym: MP

Available: Command line

This option may be used to instruct GAMS to use a quick syntax checking compilation facility which does not require all items to be declared. This alternative is useful when a large model is assembled from smaller pieces. It allows slices of GAMS code to be independently checked for syntax errors.

Consider the following example:

a(i) = b(i)*5 ;
b(i) = c(j) ;

By default, running a file containing just these two statements will generate the following listing file:

   1  a(i) = b(i)*5 ;
****  $140,120,140
   2  b(i) = c(j) ;
****         $140,120,149

120  Unknown identifier entered as set
140  Unknown symbol
149  Uncontrolled set entered as constant

**** 6 ERROR(S)   0 WARNING(S)

Note that both sets i and j have not been defined or initialized. In addition, the identifiers a, b and c have not been defined either. Further, an assignment cannot be made without the right-hand side of the assignment being known. However, in both assignments there is no data available for the right-hand side. If we run the same two lines with the option mp=1, we will get the following listing file:

   1  a(i) = b(i)*5 ;
   2  b(i) = c(j) ;
****            $149

149  Uncontrolled set entered as constant

**** 1 ERROR(S)   0 WARNING(S)

Observe that the statements have now been processed independently of their context. They are now checked only for consistency. GAMS now assumes that the sets i and j, as well as the identifiers a, b, and c have been defined and, if necessary, initialized elsewhere. The only error that is reported is the inconsistency of indices in the second statement.

Default: 0

ValueMeaning
0 Standard compilation
1 Check-out compilation
2 As 1, and skip $call and ignore missing file errors with $include and $gdxin

NLP (string): Non-Linear Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Nonlinear Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

nodLim (integer): Node limit in branch and bound tree

Available: Command line, Attribute statement (use before solve)

This option specifies the maximum number of nodes that are to be processed in the branch and bound tree search for a MIP problem. Note that setting nodLim can stop solutions that are exhibiting "excessive" iterations: if the limit is reached the algorithm will terminate, without obtaining optimality. In this case the solver status will be 4 TERMINATED BY SOLVER. Observe that a value of zero is interpreted as 'not set'.

Default: 0

nodUsd (integer): Number of nodes used by the MIP solver

Available: Attribute statement (use after solve)

This model attribute returns the number of nodes used by the MIP solver after a solve.

noNewVarEqu (integer): Triggers a compilation error when new equations or variable symbols are introduced

Available: Command line

Default: 0

ValueMeaning
0 AllowNewVarEqu
1 DoNotAllowNewVarEqu

number (real): Model instance serial number

Available: Attribute statement (use after solve)

This model attribute returns the model instance serial number. Note that the first model solved is assigned number 1, the second number 2 etc. The user may also set a value n and the next model solved will be assigned the number n+1.

numDepnd (integer): Number of dependencies in a CNS model

Available: Attribute statement (use after solve)

This model attribute returns the number of dependencies identified in a CNS model after a solve.

numDVar (integer): Number of discrete variables

Available: Attribute statement (use after solve)

This model attribute returns the number of discrete variables after a solve.

numEqu (integer): Number of equations

Available: Attribute statement (use after solve)

This model attribute returns the number of equations after a solve.

numInfes (integer): Number of infeasibilities

Available: Attribute statement (use after solve)

This model attribute returns the number of infeasibilities after a solve.

numNLIns (integer): Number of nonlinear instructions

Available: Attribute statement (use after solve)

This model attribute returns the number of nonlinear instructions after a solve.

numNLNZ (integer): Number of nonlinear nonzeros

Available: Attribute statement (use after solve)

This model attribute returns the number of nonlinear nonzeros after a solve.

numNOpt (integer): Number of nonoptimalities

Available: Attribute statement (use after solve)

This model attribute returns the number of nonoptimalities after a solve.

numNZ (integer): Number of nonzero entries in the model coefficient matrix

Available: Attribute statement (use after solve)

This model attribute returns the number of nonzero entries in the model coefficient matrix after a solve.

numRedef (integer): Number of MCP redefinitions

Available: Attribute statement (use after solve)

This model attribute returns the number of MCP equation-type redefinitions after a solve.

numVar (integer): Number of variables

Available: Attribute statement (use after solve)

This model attribute returns the number of variables after a solve.

numVarProj (integer): Number of bound projections during model generation

Available: Attribute statement (use after solve)

This model attribute returns the number of bound projections during model generation.

objEst (real): Estimate of the best possible solution for a mixed-integer model

Available: Attribute statement (use after solve)

This model attribute returns the estimate of the best possible solution for a MIP or other models with discrete variables. The model attribute is mainly used after solve.

Some GAMS solvers implement algorithms (e.g. branch-and-bound) that generate a bound on the objective function value for the best possible solution. Users may access this bound by using the model attribute objEst. Note that this is mainly used for models with discrete variables (e.g. MIP and MINLP), but some global solvers implement spatial branch-and-bound algorithms that also provide such a bound for purely continuous problems. In case the solver does not set the attribute, its value is na.

objVal (real): Objective function value

Available: Attribute statement (use after solve)

This model attribute returns the objective function value after a solve.

on115 (boolean): Generate errors for unknown unique element in an equation

Available: Command line

This option generates errors for unknown unique elements in an equation.

Default: 0

ValueMeaning
0 No error messages
1 Issue error messages

optCA (real): Absolute Optimality criterion solver default

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies an absolute termination tolerance for a global solver. General problems are often extremely difficult to solve and proving that a solution that was found for a nonconvex problem is indeed the best possible solution can use enormous amounts of resources. The absolute gap is defined to be |PB-DB|. Here the primal bound PB is the objective function value of the best feasible solution found thus far and the dual bound DB is the current bound on the optimal value of the problem (i.e., lower bound in case of minimization and upper bound in case of maximization).

If the absolute gap is not greater than optCA, the solver will terminate and return solver status 1 NORMAL COMPLETION and model status 8 INTEGER SOLUTION (for a problem with discrete variables) or 2 LOCAL OPTIMAL or 7 FEASIBLE SOLUTION (for a problem without discrete variables). Note that this is a termination test only; setting this option should not change the global search.

Note
As this is an absolute criterion, setting the value to 100 means that the objective value will be within the 100 units of the true objective value.

Observe that a nonzero value for optCA will reduce solution time. However, it may cause the true integer optimum to be missed. This will be the case if at the time the solution algorithm stops, the value of the true integer optimum is within the tolerance specified by optCA of the best current solution. Therefore the reported solution could be the best, but it is guaranteed only to be within the tolerance of the true optimal solution.

Default: 0

optCR (real): Relative Optimality criterion solver default

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies a relative termination tolerance for a global solver. General problems are often extremely difficult to solve and proving that a solution that was found for a nonconvex problem is indeed the best possible solution can use enormous amounts of resources. The precise definition of optCR depends on the solver. GAMS and some solvers use the following formula to compute the optimality gap:

|PB-DB| / max(|PB|,|DB|)

Here the primal bound PB is the objective function value of the best feasible solution found thus far and the dual bound DB is the current bound on the optimal value of the problem (i.e., lower bound in case of minimization and upper bound in case of maximization). However, two other formulas are also widely used, namely

|PB-DB| / |PB|

and

|PB-DB| / |DB|

Different adjustments when the denominator approaches zero or bounds are of different signs will be applied. The solver will stop as soon as it has found a feasible solution proven to be within optCR of optimal, that is, the optimality gap falls below optCR.

Note
As optCR is specified in proportional terms relative to the objective value, a value of 0.1 means that the objective value will be within 10% of the true objective value.

Observe that the solver will stop after finding a solution proven to be optimal within the tolerance specified with optCR and thus the solution time may be reduced. However, setting this option may cause the true integer optimum to be missed. This will be the case if at the time the solution algorithm stops, the value of the true integer optimum is within the tolerance specified by optCR of the best current solution. Therefore the reported solution could be the best, but it is guaranteed only to be within the tolerance of the true optimal solution.

Default: 0.10

optDir (string): Option file directory

Available: Command line

This option may be used to specify the name of the directory for solver option files. By default, the directory will be set to the current working directory.

optFile (integer): Default option file

Available: Command line, Attribute statement (use before solve)

This option instructs the solver to read an option file. The value of optFile determines which option file is used (see table below). Solver options allow users to manipulate the way solvers work. This may affect various solver functions including the choice of the branch and bound tree handling strategies. Please consult the solver manuals for options for each solver.

Note that this option is availabe as model attribute and command line parameter. Consider the following GAMS call:

   > gams myfile optfile=1

Observe that the value of 1 for optFile means that the option file with the name solverName.opt will be used. Here solverName is the name of the respective solver. For example, if the solver CONOPT is used, the name of the respective option file is conopt.opt.

Note
If optFile is set with the model attribute in the GAMS input file, the value of the model attribute will override any optFile specifications on the command line.

Different values for optFile allow access to different option files for the same solver. Note that the following rule is used: if we specify optfile = n, then solvername.opt will be used for n=1, otherwise solvername.opX, solvername.oXX or solvername.XXX will be used, where X's are the characters representing the value of n, for n > 1. Observe that no option file will be used if the value of optFile is zero.

Default: 0

ValueMeaning
0 No option file will be used
1 The option file solvername.opt will be used
2 The option file solvername.op2 will be used
3 The option file solvername.op3 will be used
15 The option file solvername.o15 will be used
222 The option file solvername.222 will be used
1234 The option file solvername.1234 will be used

output (string): Listing file name

Synonym: OO

Available: Command line

By default, the name of the output file (or listing file) is automatically created by combining the name of the input file with the current directory and applying the standard output file extension .lst. This option may be used to specify an alternative name for the output file. If the value is a file name without an absolute path, the current directory will compose the final name. If the absolute path is included in the file name, then the name is used as specified.

Consider the following examples:

gams trnsport
gams trnsport o=trnsport.out
gams trnsport o=c:\test\trnsport.out

Note that the first call will create an output file called trnsport.lst (for PC and Unix platforms) in the current directory. The second call will create a file called trnsport.out in the current directory. The last call will create the file as listed. If the directory c:\test does not exist, GAMS will exit with a parameter error.

pageContr (integer): Output file page control option

Synonym: PC

Available: Command line

This option affects the page control in the listing file.

Default: 3

ValueMeaning
0 No page control, with padding
1 FORTRAN style line printer format
2 No page control, no padding
3 Formfeed character for new page

pageSize (integer): Output file page size (=0 no paging)

Synonym: PS

Available: Command line

This option specifies the number of lines that are used on a page for printing the listing file. The lower bound is zero, which is interpreted as +inf. That means that everything is printed to one page.

Default: 58

pageWidth (integer): Output file page width

Synonym: PW

Available: Command line

This option sets the print width on a page in the listing file with a possible range from 72 to 32767. Note that under the IDE, the default is set to 80. If the value is outside the allowed range, the default value will be used.

Note that .pw is also a put file attribute. In the context of the put writing facility, it may be used to set the page width of a put file. See page width for further details.

Default: 255

parmFile (string): Command Line Parameter include file

Synonym: PF

Available: Command line

This option specifies the name of a secondary customization parameter file to use. It is used to augment the command line adding more command line parameters from a file. It is read from the current directory unless a path is specified. For an example, see section Specifying Options Through a Secondary Parameter File.

pLicense (string): Privacy license file name

Available: Command line

This option gives the name of a privacy license file that contains file encryption codes. A full path should be used. For more information, see Encrypting Files.

prefixLoadPath (boolean): Prepend GAMS system directory to library load path

Available: Command line

The OS environment variable to locate shared libraries used to be prefixed with the GAMS system directory. The option controls if this done or not. For the platforms Windows and AIX setting of this option has no impact.

Default: 0

ValueMeaning
0 Do not set GAMS system directory at beginning of library load path
1 Set GAMS system directory at beginning of library load path

priorOpt (real): Priority option for variable attribute .prior

Available: Attribute statement (use before solve)

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.

Default: 0

procDir (string): Process Directory

Available: Command line

This option specifies the name of the process directory. If specified, the directory must already exist and it will not be deleted when GAMS cleans up. By default, the process directory name is chosen automatically from the list 225a, 225b, ..., 225aa, 225ab ..., by skipping over existing entries, and the directory will be deleted during cleanup if the option keep is not used. Very little is written to the process directory, but the scratch directory is used more, and the option scrDir takes its default from the process directory.

procDirPath (string): Directory to create process directory in

Available: Command line

This option specifies the directory where the process directory should be created. If specified, the directory must already exist. While the process directory does not get cleaned automatically if the option procDir is set, this is not the case if the option procDirPath is used instead. Thus it allows to conveniently change the location of the process directory without changing the GAMS cleanup behavior. Note that if the location of the process directory is changed, the location of the default scratch directory will be changed accordingly (see option scrDir).

procUsed (integer): Integer number that indicates the used model type

Available: Attribute statement (use after solve)

ValueMeaning
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

profile (integer): Execution profiling

Available: Command line, Option statement

The execution profile of a GAMS run contains the individual and cumulative time required to execute the sections of the GAMS model, as well as information on memory use. The option profile controls whether an execution profile will be generated in the listing file. Observe that profile is available as command line parameter and option statement.

Note
The value for profile that is specified with an option statement in the GAMS input file overrides the value of profile that is passed through the command line.

Observe that an execution profile will be generated if the option profile is assigned a value larger than zero (zero is the default). Setting profile to 1 has the effect that execution times for each statement and the number of set elements over which the particular statement is executed will be reported. However, statements in programming flow control structures like loops will be omitted. Information on the execution of these statements will be included in the profile if the value is n, with n > 1. Note that an overview of the values for profile is given in the table at the end of this description.

Consider the following GAMS call:

   > gams trnsport profile=1

This call causes the following additional lines to appear in the listing file:

----      1 InitE                    0.000     0.000 SECS      3 MB
----      1 ExecInit                 0.000     0.000 SECS      3 MB
----     44 Assignment c             0.011     0.011 SECS      4 MB      6
----     63 Assignment transport     0.000     0.011 SECS      4 MB      3
----     65 Solve Init transport     0.000     0.012 SECS      4 MB
----     57 Equation   cost          0.001     0.013 SECS      4 MB      1
----     58 Equation   supply        0.000     0.013 SECS      4 MB      2
----     59 Equation   demand        0.000     0.013 SECS      4 MB      3
----     65 Solve Fini transport     0.009     0.022 SECS      4 MB     19
----     65 GAMS Fini                0.001     0.001 SECS      4 MB
----      1 InitE                    0.000     0.000 SECS      2 MB
----      1 ExecInit                 0.000     0.000 SECS      2 MB
----     65 Solve Alg  transport     0.000     0.000 SECS      2 MB
----     65 Solve Read transport     0.002     0.002 SECS      2 MB
---     67 Display                  0.000     0.002 SECS      3 MB
----     69 Display                  0.000     0.002 SECS      3 MB
----     69 GAMS Fini                0.001     0.001 SECS      3 MB

Observe that the first column provides the line number in the input file of the statement that is executed.

The second column reports the type of the respective statement. For an overview of all GAMS statements, see section Classification of GAMS Statements. In addition, ExecInit denotes the beginning of the execution phase of the GAMS input file and GAMS Fini denotes the end of this phase. Note that as soon as a solve statement is processed, GAMS will pass control to the solver system. Once the solver has completed its task, GAMS will restart. Thus we have two ExecInit/ GAMS Fini pairs in our example. Note that only equations are listed, and not variables. This reflects the fact that GAMS uses an equation based scheme to generate a model.

The third and fourth columns show the individual time needed to execute the statement and the cumulative time taken by the GAMS system so far.

The last column gives the number of assignments that were generated in the specified line.

In addition to the lines above, a profile summary is created at the end of the listing file. This summary contains (up to) ten of the slowest execution steps. The profile summary from trnsport.lst follows:

---- Profile Summary (17 records processed)
     0.011   0.004GB        44 Assignment c (6)
     0.009   0.004GB        65 Solve Fini transport (19)
     0.002   0.002GB        65 Solve Read transport
     0.001   0.004GB        65 GAMS Fini
     0.001   0.004GB        57 Equation   cost (1)
     0.001   0.003GB        69 GAMS Fini

Note that execution profiles and profile summaries are particularly useful for detecting the sources of performance problems. For further details, see section Finding the Causes for Slow Program Execution.

Default: 0

ValueMeaning
0 No profiling
1 Minimum profiling
n Profiling depth for nested control structures

profileFile (string): Write profile information to this file

Synonym: PFILE

Available: Command line

This option causes profiling information to be written to a file. Note that profiling information is only created with the setting profile=1 or profile=2. For example such a file may have the following conten:

          1         -1        0.000    0.003 ExecInit
         45          6        0.000    0.004 Assignment c
         66         -1        0.000    0.004 Solve Init transport
         58          1        0.000    0.004 Equation   cost
         60          2        0.000    0.004 Equation   supply
         62          3        0.000    0.004 Equation   demand
         66         19        0.015    0.004 Solve Fini transport
         66         -1        0.000    0.004 GAMS Fini
          1         -1        0.000    0.002 ExecInit
         66         -1        0.000    0.002 Solve Read transport
         68         -1        0.000    0.003 Display
         68         -1        0.000    0.003 GAMS Fini

profileTol (real): Minimum time a statement must use to appear in profile generated output

Synonym: PTOL

Available: Command line, Option statement

This option sets the profile tolerance in seconds. All statements that take less time to execute than this tolerance are not reported in the listing file. Note that this option is only effective if the value of the option profile is larger than zero.

Default: 0

putDir (string): Put file directory

Synonym: PDir

Available: Command line

By default, put files are generated and saved in the current working directory. This option may be used to specify an alternative directory. Note that this option does not work if an absolute file name is provided through the file statement.

pyMultInst (integer): GAMS/Python Multiple Instance Interpreter

Available: Command line

This options controls the setup of the Python interpreter for use in embedded Python code sections. If this option is set to 1 the embedded Python code can work with multiple independent Python sessions. If pyMultInst is set to 0 there is a single interpreter even with multiple parallel embedded Python sessions that all share the same data space. With pyMultInst set to 0 or 1, the environment variable GMSPYTHONMULTINST is set by GAMS to this value. If the option is not set the value will be taken from the user environment variable GMSPYTHONMULTINST. Note that setting this to 1 might cause problems when using third party modules and packages (e.g. numpy or modules that make use of it) and might also impact the performance.

Default: 0

ValueMeaning
0 Use a single-session Python interpreter
1 Use a multi-session Python interpreter

pySetup (integer): GAMS/Python Setup

Available: Command line

This options controls the setup of Python for use in embedded Python code sections. If this option is set to 1 GAMS will use the Python installation that comes with the GAMS installation (sysdir/GMSPython). If pySetup is set to 0 the user needs to setup the environment (e.g. PATH and PYTHONHOME environment variables) so that the user Python installation is found. With pySetup set to 1, the environment variable GMSPYTHONHOME which is set by GAMS communicated the location to the embedded Python code facility. So even with pySetup set to 0 but an environment variable GMSPYTHONHOME present in the environment, the Python installation the GMSPYTHONHOME variable points to is used (independent of where the environment variable PYTHONHOME points to).

Default: 1

ValueMeaning
0 Rely on user setup of Python
1 Use Python installation provided in GAMS system directory

QCP (string): Quadratically Constrained Programs - default solver

Available: Command line, Option statement

The default solver for models of the type Quadratically Constrained Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

real1..5 (real): Real communication cell N

Available: Option statement, Attribute statement (use before solve)

This option specifies a real communication cell that may contain any real number.

reference (string): Symbol reference file

Synonym: RF

Available: Command line

If this option is specified, all symbol references will be written to the specified file. Setting rf or Reference to the string 'default' will cause GAMS to create a reference file with the file root name of the GAMS input file and the extension ref. Thus the call

   > gams trnsport rf=default

will generate the reference file trnsport.ref.

reform (integer): Reformulation level

Available: Option statement, Attribute statement (use before solve)

This option triggers an objective function reformulation. The interpretation depends on the solver. The solvers MINOS and SNOPT support this option. Note that the default value is zero and the range is [-2147483647,2147483647 ].

resCalc (real): Time spent in function and derivative calculations (deprecated)

Available: Attribute statement (use after solve)

resDeriv (real): Time spent in derivative calculations (deprecated)

Available: Attribute statement (use after solve)

resGen (real): Time GAMS took to generate the model in CPU seconds(deprecated)

Available: Attribute statement (use after solve)

This model attribute returns the time GAMS took to generate the model in CPU seconds.

resIn (real): Time to import model (deprecated)

Available: Attribute statement (use after solve)

resLim (real): Wall-clock time limit for solver

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies the maximum time in seconds that the solver may run before it terminates and returns the solver status 3 RESOURCE INTERRUPT. The solver should start the clock fairly early, tehrefore the time required to read in the problem and do any reformulatiosn, preprocessing or presolving is included in the time limit. For a multi-threaded solve, the time limit applies to the wall clock time.

Default: 1000

resOut (real): Time to export solution (deprecated)

Available: Attribute statement (use after solve)

restart (string): Name of a restart file, see The Save and Restart Feature

Synonym: R

Available: Command line

This option specifies the name of a work file that was written with the option save that will be used to restart the GAMS program. The work file is also called restart file. For more information including examples, see chapter The Save and Restart Feature.

restartNamed (string): Name of another matching restart file, see Obfuscated Work Files

Synonym: RN

Available: Command line

resUsd (real): Time the solver used to solve the model in CPU seconds

Available: Attribute statement (use after solve)

This model attribute returns the time the solver used to solve the model in CPU seconds.

RMINLP (string): Relaxed Mixed-Integer Non-Linear Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Relaxed Mixed Integer Nonlinear Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

RMIP (string): Relaxed Mixed-Integer Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Relaxed Mixed Integer Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

RMIQCP (string): Relaxed Mixed Integer Quadratically Constrained Programs - default solver

Available: Command line, Option statement

The default solver for models of the type Relaxed Mixed Integer Quadratically Constrained Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

RMPEC (string): Relaxed Mathematical Programs with Equilibrium Constraints - default solver

Available: Command line, Option statement

The default solver for models of the type Relaxed Mathematical Program with Equilibrium Constraints is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

rObj (real): Objective function value from the relaxed solve of a mixed-integer model when the integer solver did not finish

Available: Attribute statement (use after solve)

This model attribute returns the objective function value from the relaxed solve of a MIP when the integer solver did not finish.

save (string): Creates a work file, see The Save and Restart Feature

Synonym: S

Available: Command line

This option specifies the name of a work file to be written. The work file is intended to be used later to restart the GAMS program and it is also called save file. Note that save files are platform-independent.

The final name is composed by completing the specified save file name with the current directory and the standard work file extension. By default, GAMS will generated eight save files. Therefore the name of the save file should be such that GAMS can generate eight names from it. GAMS distinguishes file names from their extensions. If no extension is provided by the user, GAMS will add the extensions g01 through g08 to name the eight saved work files. Note that the character ? in the name of the save file will be replaced by GAMS with the numbers 1 to 8.

The following table illustrates which names GAMS will generate given the name provided by the user with the option save.

myfile: myfile.g01myfile.g02...myfile.g08
myfile?myfile1.g01:myfile2.g02...myfile8.g08
myfile.00?:myfile.001myfile.002...myfile.008
myfile?.wrk:myfile1.wrkmyfile2.wrk...myfile8.wrk
myfile?.???:myfile1.111myfile2.222...myfile8.888
Note
On Unix platforms the character ? is a special character and may require a backslash character \ before it in order to be interpreted correctly. For example, the name myfile? should be written as myfile\? on this platform.

For further information including examples, see chapter The Save and Restart Feature.

saveObfuscate (string): Creates an obfuscated work file, see Obfuscated Work Files

Synonym: SO

Available: Command line

savePoint (integer): Save solver point in GDX file

Synonym: SP

Available: Command line, Option statement, Attribute statement (use before solve)

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

Default: 0

ValueMeaning
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

scaleOpt (boolean): Employ user specified variable and equation scaling factors

Available: Attribute statement (use before solve)

This option determines whether GAMS will employ user-specified variable and equation scaling factors. It must be set to a nonzero value if scaling factors are to be used. For more details on scaling, see section Model Scaling - The Scale Option.

Default: 0

scrDir (string): Scratch directory

Synonym: SD

Available: Command line

This option specifies the name of the scratch directory. The scratch directory is used by GAMS for intermediate files that are generated during execution. The scratch directory and all its contents are usually deleted at the end of the GAMS run. By default, the scratch directory takes its value from the process directory that is specified with the option procDir. If neither the scratch directory nor the process directory are specified, the scratch directory will be set to a subdirectory of the current working directory with an internally generated name. If the scratch directory is specified, the respective directory must already exist and will not be deleted by GAMS at the end of the run.

Note that the option solveLink may be used to reduce or eliminate the need for intermediate files.

scrExt (string): Scratch file extension to be used with temporary files

Synonym: SE

Available: Command line

This option specifies the name of the extension for the temporary files that GAMS is generating during execution.

Default: dat

scriptExit (string): Program or script to be executed at the end of a GAMS run

Available: Command line

By default, GAMS does not call an exit script anymore. If this is required, the option scriptExit has to be set explicitly to the script that should be called after GAMS terminates. Note that an empty template of an exit script is in the GAMS system directory: it is called gmsxitnt.cmd for Windows and gmsxitus.run for Unix.

scriptFrst (string): First line to be written to GAMSNEXT file.

Synonym: SF

Available: Command line

This option specifies the first line written to gamsnext. The default is an empty string and the first line is not written.

scriptNext (string): Script mailbox file name (GAMSNEXT)

Synonym: SCRIPT

Available: Command line

scrNam (string): Work file names stem

Synonym: SN

Available: Command line

This option specifies the name stem that is used to complete the names of intermediate work files. Note that the name stem must have at least one '?'. The name will be completed with the scratch directory and the standard scratch name extension.

seed (integer): Random number seed

Available: Command line, Option statement

This option specifies the seed that is used for the pseudo random number generator.

Default: 3141

solPrint (int or string): Solution report print option

Available: Command line, Option statement, Attribute statement (use before solve)

This option controls the printing of the solution listing to the listing file.

Note that the numeric values are deprecated, they are only relevant for backwards compatibility. Note further, that there are compile-time constants that are associated with this option. The first of the two tables below offers an overview of how the different types of values are related and the second table gives the values in numerical terms and a description of the associated meaning. Observe that the compile-time constants in the last column are deprecated and only relevant for backwards compatibility.

Numeric Value String ValueCompile-Time Constant Decprecated Compile-Time Constant
0 off solprint.Off solprint.Summary
1 on solprint.On solprint.Report
2 silent solprint.Silent solprint.Quiet

Default: 1

ValueMeaning
0 Remove solution listings following solves
1 Include solution listings following solves
2 Suppress all solution information

solSlack (boolean): Causes the equation output in the listing file to contain slack variable values instead of level values

Available: Option statement

If the value of this option is set to 1, the equation output in the listing file will contain slack variable values instead of level values.

Default: 0

ValueMeaning
0 includes equation levels in the solution part of the LST file following solves
1 includes equation slacks in the solution part of the LST file following solves

solveLink (integer): Solver link option

Synonym: SL

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies the solver linking conventions. Note that values 3, 4, 6 and 7 are relevant for grid computing. Observe that there are compile-time constants that are associated with this option.

Default: 0

ValueMeaning
0 GAMS operates as it has for years
1 Solver is called from a shell and GAMS remains open
2 Solver is called with a spawn (if possible) or a shell (if 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 wait (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

solveOpt (int or string): Multiple solve management

Available: Option statement, Attribute statement (use before solve)

This option will instruct GAMS how to manage the model solution if only part of the variables and equations in the particular problem are solved.

Observe that this option is available as model attribute and option statement. The values for model attributes are numeric, while the values for option statements are text strings. In addition, there are compile-time constants that are associated with this option. The first of the two tables below offers an overview of how the different types of values are related and the second table gives the values in numerical terms and a description of the associated meaning.

Numeric Value String ValueCompile-Time Constant
0 replace solveOpt.Replace
1 merge solveOpt.Merge
2 clear solveOpt.Clear

Default: 1

ValueMeaning
0 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 The solution information for all equations and variables is merged into the existing solution information
2 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

solver (string): Default solver for all model types that the solver is capable to process

Available: Command line, Option statement

The command line parameter solver=abc initializes the default solver for the model types the solver "abc" is capable of to abc. This initialization is done before the default solvers of individual model types are set via command line parameters. Consider the following example:

   > gams trnsport lp=conopt solver=bdmlp

Note that this GAMS call will first set the solver BDMLP as the solver for the model types LP, RMIP and MIP, since these are the model types that BDMLP can handle. Then Conopt will be reset as the default solver for LPs. Observe that the order of these parameters on the command line is irrelevant. If multiple occurrences of the option solver appear, the last entry will set value of the option.

In addition, the solver for multiple model types may be set in the GAMS model source code via the following statement:

option solver = abc;

This statement sets the solver for the model types the solver abc can handle to abc. Note that in such an option statement the order of other solver setting options is significant. Consider the following example:

option lp=conopt, solver=bdmlp;

This statement will first set the solver for LPs to Conopt and in the next step to BDMLP because BDMLP is capable of handling the model type LP. In some cases it makes sense to set a solver twice. Consideer the following example:

option solver=conopt, solver=cbc;

This option statement has the effect that models of the types CNS, DNLP, NLP, QCP, RMIQCP or RMINLP will be solved with Conopt and models of the types LP, RMIP or MIP will be solved with CBC.

Note that as usual, a specification of an option through the command line takes precedence over a specification with an option statement.

solverCntr (string): Solver control file name

Synonym: SCNTR

Available: Command line

This option specifies the solver control file name. Note that the name is completed with the scratch directory and the scratch extension.

solverDict (string): Solver dictionary file name

Synonym: SDICT

Available: Command line

This option specifies the solver dictionary file name. Note that the name completed with the scratch directory and the scratch extension.

solverInst (string): Solver instruction file name

Synonym: SINST

Available: Command line

This option specifies the solver instruction file name. Note that the name is completed with the scratch directory and the scratch extension.

solverMatr (string): Solver matrix file name

Synonym: SMATR

Available: Command line

This option specifies the solver matrix file name. Note that the name is completed with the scratch directory and the scratch extension.

solverSolu (string): Solver solution file name

Synonym: SSOLU

Available: Command line

This option specifies the solver solution file name. Note that the name is completed with the scratch directory and the scratch extension.

solverStat (string): Solver status file name

Synonym: SSTAT

Available: Command line

This option specifies the solver status file name. Note that the name is completed with the scratch directory and the scratch extension.

solveStat (integer): Indicates the solver termination condition

Available: Attribute statement (use after solve)

This model attribute indicates the solver termination condition. Observe that there are compile-time constants that are related to solveStat. Note that additional information to the values given in the table below is provided in section Solver Status.

ValueMeaning
1 Normal Completion
2 Iteration Interrupt
3 Resource Interrupt
4 Terminated By Solver
5 Evaluation Interrupt
6 Capability Problems
7 Licensing Problems
8 User Interrupt
9 Setup Failure
10 Solver Failure
11 Internal Solver Failure
12 Solve Processing Skipped
13 System Failure

stepSum (boolean): Summary of computing resources used by job steps

Available: Command line

This option controls the generation of a step summary of the processing times taken by GAMS during a given run.

For example, the call

   > gams trnsport stepsum=1

will generate the following step summaries in the listing file:

STEP SUMMARY:     0.016       0.016 STARTUP
                  0.005       0.005 COMPILATION
                  0.065       0.065 EXECUTION
                  0.001       0.001 CLOSEDOWN
                  0.087       0.087 TOTAL SECONDS
                  0.089       0.089 ELAPSED SECONDS
                  3.942       3.942 MAX HEAP SIZE (MB)

Note that this step summary will be printed before the model is sent to the solver, thus it may be found before the solve summary. The second step summary will be printed after solution, it will appear at the very end of the listing file:

STEP SUMMARY:     0.004       0.020 STARTUP
                  0.000       0.005 COMPILATION
                  0.003       0.068 EXECUTION
                  0.000       0.001 CLOSEDOWN
                  0.007       0.094 TOTAL SECONDS
                  0.239       0.328 ELAPSED SECONDS
                  2.899       3.942 MAX HEAP SIZE (MB)

Observe that the first column reports the time for the individual section of the run, while the second column reports accumulated times including previous sections.

Default: 0

ValueMeaning
0 No step summary
1 Step summary printed

strictSingleton (boolean): Error if assignment to singleton set has multiple elements

Available: Command line, Option statement

This option affects the behavior of a membership assignment to a singleton set. If the value is set to zero, GAMS will not complain about a singleton set with more than one element, but will take only the first element. However, if the value is set to 1, a singleton set definition with more than one element will cause an error.

Default: 1

ValueMeaning
0 Take first record if assignment to singleton set has multiple elements
1 Error if assignment to singleton set has multiple elements

stringChk (integer): String substitution options

Available: Command line

This option affects the result of the check for %xxx% symbols. Note that %xxx% symbols may be environment variables or compile-time variables.

Default: 0

ValueMeaning
0 No substitution if symbol undefined and no error
1 Error if symbol undefined
2 Remove entire symbol reference if undefined and no error

subSys (string): Name of subsystem configuration file

Available: Command line

This option specifies the name of the configuration file that contains solver defaults and other information. This option should be used only by advanced users who attempt to override internal subsystem information.

subSystems (no value): Lists all solvers available as well as the current default and active solvers in the LST file

Available: Option statement

This option has the effect that all available subsystems will be displayed in the listing file. Note that a solver is considered a subsystem.

sumInfes (real): Sum of infeasibilities

Available: Attribute statement (use after solve)

This model attribute returns the sum of infeasibilities after a solve.

suppress (boolean): Compiler listing option

Available: Command line

If set to 1, this option will suppress the echoing of the contents of the input file(s) to the listing file. Note that this option is similar in functionality to the dollar control option $offlisting.

Note
The dollar control options $on/offlisting will affect the echo print in the listing file only if suppress is set to zero. If suppress is set to 1, the input file(s) will not be echoed to the listing file and the dollar control options will not have any effect on the listing file.

Default: 0

ValueMeaning
0 Standard compiler listing
1 Suppress compiler listing

symbol (string): Symbol table file

Available: Command line

This option specifies the name of a partial symbol table that may be written in conjunction with reference files.

symPrefix (string): Prefix all symbols encountered during compilation by the specified string in work file

Available: Command line

sys10 (boolean): Changes rpower to ipower when the exponent is constant and within 1e-12 of an integer

Available: Command line, Option statement

Default: 0

ValueMeaning
0 Disable conversion
1 Enable conversion

sys11 (integer): Dynamic resorting if indices in assignment/data statements are not in natural order

Available: Command line, Option statement

Speed-up for expressions containing constant indices or indices that are not in the natural order at the cost of increased memory use.

Default: 0

ValueMeaning
0 Automatic optimization/restructuring of data
1 No optimization
2 Always optimize/restructure

sys12 (integer): Pass model with generation errors to solver

Synonym: noSolveSkip

Available: Command line, Option statement

sys15 (integer): Automatic switching of data structures used in search records

Available: Command line

Default: 0

ValueMeaning
0 Automatic switching to dense data structures
1 No switching
2 Always switch
1x Print additional information in lst file

sys16 (integer): Disable search record memory (aka execute this as pre-GAMS 24.5)

Available: Command line

Default: 0

sys17 (integer): Disable sparsity trees growing with permutation (aka execute this as pre-GAMS 24.5)

Available: Command line

Default: 0

sysDir (string): GAMS system directory where GAMS executables reside

Available: Command line

This option sets the GAMS system directory. It is useful if there are multiple systems installed on the machine or when GAMS is called from an external system like Visual Basic.

sysIdent (real): Solver identification number

Available: Attribute statement (use after solve)

sysIncDir (string): SysInclude directory

Synonym: SDIR

Available: Command line

This option specifies the name of the directory to be used by GAMS for sysinclude files that do not have a full path specification. An absolute or relative path may be specified. If this option is not set, it will be set to the GAMS system directory.

Note that if this option is set, the default system include directory will not be searched.

Attention
Only one directory may be set with the option sDir. Thus the string specified will be treated as one directory. If additional directories are added, errors will be reported.

Consider the following example:

   > gams myfile sdir mydir

Note that GAMS will search for any referenced sysinclude file in the directory mydir.

sysOut (bool or string): Solver Status file reporting option

Available: Command line, Option statement, Attribute statement (use before solve)

This option controls whether additional solver generated output (the solver status file) is included in the listing file. Note that the contents of the solver status file are useful for debugging or to get additional information about a solver run. Normally, only those messages flagged by the solver as destined for the listing file will be listed. If the solver crashes or encounters any unexpected difficulties, the contents of the solver status file will be automatically sent to the listing file.

Note that the boolean values are deprecated, they are only relevant for backwards compatibility. The first of the two tables below offers an overview of how the boolean values and string values are related and the second table gives the boolean values and a description of the associated meaning.

Numeric Value String Value
0 off
1 on

Default: 0

ValueMeaning
0 Suppress additional solver generated output
1 Include additional solver generated output

sysVer (real): Solver version

Available: Attribute statement (use after solve)

tabIn (integer): Tab spacing

Available: Command line

This option sets the tab spacing. By default, tabs are not allowed in GAMS. However, the most common setting is 8. As a result, the tabs are at columns 1, 9, 17, ... and the intermediate columns are replaced by blanks.

Default: 8

ValueMeaning
0 Tabs are not allowed
1 Tabs are replaced by blanks
n Tabs are 1, n+1, 2n+1,.. (default: n=8)

tFormat (boolean): Time format

Synonym: TF

Available: Command line

This option controls the time format in the listing file. The three date formats correspond to the various conventions used around the world. For example, the time 7:45~PM will be written as 19:45:00 with the default tf value of zero and as 19.45.00 with tf=1.

Default: 0

ValueMeaning
0 Time as hh:mm:ss
1 Time as hh.mm.ss

threads (integer): Number of threads to be used by a solver

Available: Command line, Option statement, Attribute statement (use before solve)

This option controls the number of threads or CPU cores to be used by a solver. If the number is greater than the number of available CPU cores, it will be reduced to the number of cores available. Note that the value of zero means that all available cores will be used.

Default: 1

ValueMeaning
0 Use number of available cores
n Use n threads
minus_n Number of cores to leave free for other tasks

threadsAsync (integer): Number of threads to be used for asynchronous solve (solveLink=6)

Available: Command line, Option statement

Default: -1

ValueMeaning
0 Use number of available cores
n Use n threads
minus_n Number of cores to leave free for other tasks

timer (integer): Instruction timer threshold in milli seconds

Available: Command line

This option specifies an instruction timer threshold in milli seconds. That means that only details about internal GAMS intructions that took more than n milli seconds are echoed to the log.

Default: 0

ValueMeaning
0 Interpreted as +inf, no details echoed
n Echo all details about internal GAMS instructions that took more than n milli seconds to the log

tolInfeas (real): Infeasibility tolerance for an empty row of the form a.. 0*x =e= 0.0001;

Available: Attribute statement (use before solve)

This option specifies the infeasibility tolerance for an empty row of the following form:

a.. 0*x =e= 0.0001;

If the option is not set, a tolerance of 10 times the machine precision will be used. Empty rows that fail this infeasibility check will be flagged with the listing file message Equation infeasible due to rhs value.

tolInfRep (real): This attribute sets the tolerance for marking infeasible in the equation listing

Available: Attribute statement (use before solve)

This option sets the tolerance for marking an equation infeasible in the equation listing. Note that the default value is 1.0e-6.

Default: 1.0E-06

tolProj (real): Tolerance for setting a variable level to its bound and filtering marginals when reading a solution

Available: Attribute statement (use before solve)

This option controls the tolerance for filtering marginals (i.e. setting marginals within the tolerance to zero) and projecting levels to the lower or upper bound that are within the tolerance when reading a solution. Note that the default value is 1e-8.

Default: 1.0E-08

trace (string): Trace file name

Available: Command line

This option specifies the trace file name and causes a trace file to be written. Note that if a previous trace file of the same name already exists, then all new data output will be appended. Therefore, users should be careful to delete all old versions of the trace file if the a file name is reused and they do wish the new data to be appended.

traceLevel (integer): Solvestat threshold used in conjunction with action=GT

Synonym: TL

Available: Command line

Default: 0

traceOpt (integer): Trace file format option

Available: Command line

This option specifies the fromat of the trace file. Note that several different types of trace files may be created, depending on what output information is desired.

Default: 0

ValueMeaning
0 Solver and GAMS step trace without headers
1 Solver and GAMS step trace
2 Solver step trace only
3 Trace file format used for GAMS performance world
5 Trace file with all available trace fields

tryInt (real): Whether solver should make use of a partial integer-feasible solution

Available: Attribute statement (use before solve, reset by solve statement)

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. The exact form of implementation depends on the solver and may be partly controlled by solver settings or options. See the solver manuals for details.

tryLinear (real): Examine empirical NLP model to see if there are any NLP terms active. If there are none the default LP solver will be used

Available: Attribute statement (use before solve)

If this option is set to 1, empirical NLP models will be examined to determine if there are any active NLP terms. If there are none, the default LP solver will be used. The procedure also checks to see if QCP and DNLP models can be reduced to an LP; MIQCP and MINLP can be solved as a MIP; RMIQCP and RMINLP can be solved as an RMIP. Note that the default value is zero.

user1..5 (string): User string N

Synonym: U1

Available: Command line

This option permits users to enter a text for up to 5 user-defined options. The double dash parameters supersede these parameters.

warnings (integer): Number of warnings permitted before a run terminates

Available: Command line

This option specifies the maximum number of allowable warnings, before the run terminates.

Default: ∞

workDir (string): Working directory

Synonym: WDir

Available: Command line

This option sets the working directory. This option is useful when GAMS is called from an external system like Visual Basic. If it is not specified, the working directory will be set to the directory curDir.

workFactor (real): Memory Estimate multiplier for some solvers

Available: Command line, Attribute statement (use before solve)

This option instructs the solver how much workspace to allocate for problem solution relative to the solver-computed estimate. For example, setting the value to 2 will double the memory estimate. In cases where a solver allocates memory dynamically as it is needed, this option will have no effect. Note that in cases where both options workfactor and workSpace are specified, the value for workSpace will take precedence.

Default: 1

workSpace (real): Work space for some solvers in MB

Available: Command line, Attribute statement (use before solve)

This option instructs the solver how much workspace in Megabytes to allocate. If it is not speicified by the user, the solver will estimate the size. In cases where a solver allocates memory dynamically as it is needed, this option will have no effect, or it may be used as a memory limit.

xSave (string): Creates a compressed work file

Synonym: XS

Available: Command line

This option specifies the name of a save file written in ASCII format in older GAMS systems (versions older than 21.7), in order for the save file to be platform dependent and may be moved to machines with different operating systems.

In GAMS systems from release 22.3 and newer this option has the effect that compressed save files are written.

xSaveObfuscate (string): Creates a compressed obfuscated work file

Synonym: XSO

Available: Command line

zeroRes (real): The results of certain operations will be set to zero if abs(result) LE ZeroRes

Available: Command line

This option specifies the threshold value for internal rounding to zero in certain operations.

Default: 0

zeroResRep (boolean): Report underflow as a warning when abs(results) LE ZeroRes and result set to zero

Available: Command line

This option causes GAMS to issue warnings whenever a rounding occurs because of the setting of the option zeroRes.

Default: 0

ValueMeaning
0 No warning when a rounding occurs because of ZeroRes
1 Issue warnings whenever a rounding occurs because of ZeroRes

Executing an External Program

External programs may be run during a GAMS job either using the $call, Execute or Put_utility syntax. The $call procedure is executed at the moment that is encountered during compilation. The Execute and Put_utility commands causes the external program to be run during GAMS program execution. The contrast between these statements is important in two ways.

  • Influence on results that can be included in a GAMS program – Anything run with $Call can generate files that can be included in the subsequent compilation. On the other hand files generated with Execute and Put_utility cannot be included because $Include operates only at compile time (unless you use Save and Restart).
  • Influence on results that can be fed into the external program – Obviously when one is running an external program there is the desire to pass it data depicting results of the GAMS execution. $Call cannot do this as the data passed have to exist at compile time and cannot use the result of any GAMS calculations and solves in the current program. Execute commands on the other hand can use any data generated during a run which arise before the Execute and Put_utility command's position in the file through passage via put files or other mechanisms.

The big difference between the $call and execute is

  • $call
    • can generate results to be immediately incorporated back into GAMS
    • cannot use GAMS results generated within this run because the $Call is executed at compile time.
  • execute and put_utility
    • can cause a program to be started using results generated by the GAMS program (note such results do have to have been saved in an external file using a command like put)
    • cannot generate results which can be immediately reincluded into the GAMS program because new material can only be added compile time.

Execute

This command uses the syntax

execute[.async[NC]] "[=]command_to_execute"

to execute a program specified by command_to_execute. The execution occurs during the GAMS execution phase.

  • The = will call the program directly, while without the = GAMS calls a shell that executes the program. When a program is executed in a shell, mechanisms like redirection (>) and pipe (|) will work.
  • The .async suffix makes GAMS go ahead without waiting.
  • The .asyncNC option tells the operating system to start the run a new console rather than sharing the console of the parent process allowing use of multiple processors. This is available under Windows only.
  • Since this occurs during execution one cannot use the compile time $Include to incorporate the results of that external run into the GAMS code except through a GAMS from GAMS approach as discussed below or through save and restart use (see the Save Restart chapter).

Asynchronous Execution

The .async variant of $call and execute start a job without waiting for the result. One can continue in the GAMS program and collect the return code of the job later. There are three ways to start a job asynchronously:

  • $call.async ... (compile phase)
  • execute.async '...'; (execution phase)
  • `put_utility fx 'exec.async' / '...'; / put_utility fx 'shell.async' / '...';` (execution phase)

After each of those the function JobHandle can be used to get the Process ID (pid) of the last job started. With jobStatus(pid) one could check for the status of a job. Possible return values are:

  • 0: error (input is not a valid PID or access is denied)
  • 1: process is still running
  • 2: process is finished with return code which could be accessed by errorLevel
  • 3: process not running anymore or was never running, no return code available

With jobTerminate(pid) a interrupt signal can be sent to a running job. If this was successful the return value is one, otherwise it is zero.

With jobKill(pid) a kill signal can be sent to a running job. If this was successful the return value is one, otherwise it is zero.

The model [ASYNCEXEC] from the GAMS Test Library demonstrates the use of this feature.