Table of Contents
Introduction
System attributes give access to string constants in the GAMS system environment. We will refer to these string constants as system suffixes. Moreover, there are attributes that can be used as data elements for user symbols. This way one can get access e.g. to the solvers (as set elements) in the system. We will refer to these data elements as system data. Two special system data attributes, namely powerSetLeft
and powerSetRight
, for a three dimensional set setName(n,s,b)
create data which can be interpreted as a numbering system with base b and s digits. Finally, a system attribute can provide access to a system function that was hidden by the compiler because of a name conflict with a user symbol.
System Suffixes
System suffixes contain information about the GAMS system environment during a run. There are two ways to reference them: system.suffix
and %system.suffix%
. Here system
is a keyword and .suffix
is the name of the system suffix. A full list is given in section List of all System Suffixes below. Note that system.suffix
references the execution-time version of the system suffix and %system.suffix%
references the compile-time version resulting in a textual replacement. The execution-time system suffix can only be used in the context of put files. Consider the following example where both versions are used:
file fx;
put fx 'lp:' system.LP;
option lp=gurobi;
put / 'lp:' system.LP
put / 'lp:%system.LP%';
Observe that the compile-time string %system.LP%
is evaluated at compile time and does not change. However, the execution-time system suffix system.LP
is evaluated at execution time and it does change. It is first CPLEX
, since CPLEX is the default LP solver. Then it changes to GUROBI
as a result of the execution-time command option LP=gurobi;
. The resulting put
file fx.put
follows:
lp:CPLEX lp:GUROBI lp:CPLEX
In the following two subsection we will discuss execution-time suffix in more detail.
Execution-Time System Suffixes
Execution-time system suffixes are only used in the context of the put writing facility with commands like put , putclose and put_utility. Consider the following simple example. We have the files x.gms
and dummy.gms
, where x.gms
contains just the following line:
file fx; put fx system.version;
The file dummy.gms
contains the following:
$exit;
We run these files with the following calls:
> c:\gams\win64\24.7\gams x.gms action=c s=putVersion
Note that the value c
for the command-line parameter action causes the first input file to be compiled only. The result is saved in the work file putVersion
. Then we restart and execute dummy.gms
. Now, depending on the GAMS release version, the put
file fx
will have a different content:
c:\gams\win64\24.7\gams dummy.gms r=putVersion // this produces a put file with content "GAMS Rev 247" c:\gams\win64\24.8\gams dummy.gms r=putVersion // this produces a put file with content "GAMS Rev 248"
In contrast, the value of the compile-time system suffix %system.version%
is determined at compile time. Suppose we change the file x.gms
to contain the following line:
file fx; put fx "%system.version%";
The file dummy.gms
is not changed and we use the same calls as above. Note that the put
file will have the same content for both versions of GAMS:
c:\gams\win64\24.7\gams dummy.gms r=putVersion // this produces a put file with content "GAMS Rev 247" c:\gams\win64\24.8\gams dummy.gms r=putVersion // this produces a put file with content "GAMS Rev 247"
Compile-Time System Suffixes
Compile-time system suffixes may be placed anywhere a compile-time variables makes sense, including code for conditional compilation. The quoting of these compile-time system suffixes depends on their use in the code. Consider the following example:
$set systemDATE %system.date%
display "system.date", "%system.date%";
$ifi %system.LP% == Xpress $log "LP solver is Xpress."
The resulting output generated by the display statement follows:
---- 3 system.DATE 11/07/16
List of all System Suffixes
In the following table all system suffixes are listed.
System Suffix | Description |
---|---|
BuildCode | System build code |
CNS | CNS solver that is active for CNS model type |
ComputerName | Operating system computer name |
Date | Job date |
Date1 | Job date format |
DirSep | File or directory separator in file names |
DNLP | DNLP solver that is active for DNLP model type |
Elapsed | Elasped time in seconds since start of job |
EMP | EMP solver that is active for EMP model type |
Error | Used to indicate unknown suffix |
ErrorLevel | System Errorlevel |
FE | File extension |
FileSys | Name of the operating system (MSNT for Windows, UNIX for Linux and macOS) |
FN | File name |
FP | File path |
GamsRelease | GAMS Release number |
GamsReleaseMaint | GAMS Release number with maintenance number suffix |
GamsVersion | GAMS version number |
GdxFileNameIn | GDX file name for input, set by put_utility command gdxin |
GdxFileNameOut | GDX file name for output, set by put_utility command gdxout |
GString | GAMS system audit string (exact GAMS version being used) |
HostPlatform | Host platform |
IFile | Input file |
ILine | Current source line number beeing executed |
IncLine | Include file line |
IncName | Include file name |
IncParent | Include file parent |
IncParentL | Include file parent line number |
IsAlphaBeta | Indicates an Alpha or Beta bulid |
JobHandle | Job handle of last async call |
LicenseFileName | The file name of the license file currently used |
LicenseLevel | GAMS license level |
Line | Line number in source code |
ListLine | Line number on listing file |
LP | LP solver that is active for LP model type |
MACAddress | MAC address of the first network adapter |
MaxInput | Max input line length that can be processed |
MCP | MCP solver that is active for MCP model type |
Memory | Memory (in Mb) in use |
MINLP | MINLP solver that is active for MINLP model type |
MIP | MIP solver that is active for MIP model type |
MIQCP | MIQCP solver that is active for MIQCP model type |
MPEC | MPEC solver that is active for MPEC model type |
NLP | NLP solver that is active for NLP model type |
NullFile | The null filename |
OFile | Output (Listing) file |
OPage | Current page number in output (listing) file |
Page | Current page number |
PFile | Current put file |
Platform | Job platform (DAX for macOS on ARM64, DEX for macOS on x86_64, LEX for Linux, WEX for Windows) |
PrLine | Line on listing page |
Procname | Model types LP MIP etc |
PrPage | Listing page number |
PutFileName | The filename of the currently active PUT file |
QCP | QCP solver that is active for QCP model type |
RDate | Restart file date |
ReDirLog | Append redirection string into the logfile |
RFile | Restart file name |
RMINLP | RMINLP solver that is active for RMINLP model type |
RMIP | RMIP solver that is active for RMIP model type |
RMIQCP | RMIQCP solver that is active for RMIQCP model type |
RMPEC | RMPEC solver that is active for RMPEC model type |
RTime | Restart file time |
SFile | Save file name |
SString | Subsystem (Solver) audit (last solver used) |
Tab | Tab character |
TClose | Time to save GAMS |
TComp | Time to compile |
TExec | Time to execute |
Time | Job time |
Title | Current listing title |
TStart | Time to restart GAMS |
UserConfigDir | User writable directory that is searched for gamsconfig.yaml |
UserDataDir | User writable directory that is searched for gamslice.txt and others |
UserName | Operating system user name |
VerID | GAMS version ID |
Version | GAMS compiler version |
A model that prints all system suffixes with its current values to a put file can be found in model [SSUFFIX].
System Data
Some of the system relevant information does not fit into a single string. Such system data can be stored in GAMS symbols. The system data for this symbol can be accessed in the data statement of the symbol, e.g. set allSolvers / system.solverNames /;
. Now you can work with the solver names as you can work with any set. The system data can be viewed as an internal set, so it can be used to create more complex GAMS symbols with this information. For example:
set seq / 1*1000 /;
set solvermap(seq,*) / set.seq:system.solverNames /;
parameter solverpar(*) / system.solverNames 1 /;
Here is the list and dimensionality of the system data:
System Data | Dimension | Description |
---|---|---|
dollarOptions | 1 | Dollar control options |
empty | 1 | Empty label |
gamsFunctions | 1 | Intrinsic functions |
gamsParameters | 1 | Command line parameters |
gamsParameterSynonymMap | 2 | Map between command line parameters and their synonyms |
gamsParameterSynonyms | 1 | Synonyms for command line parameters |
GUSSModelAttributes | 1 | Model attributes stored for GUSS scenarios |
modelTypes | 1 | Model types, e.g. LP, MIP, ... |
platforms | 1 | Platform code |
powerSetLeft | 3 | Numbering system with base b and s digits |
powerSetRight | 3 | Numbering system with base b and s digits |
predefinedSymbols | 1 | Predefined symbols, e.g. SameAs , Diag , ... |
setConstants | 1 | System data names (this list) |
solverNames | 1 | Names of solvers and tools |
solverPlatformMap | 2 | Map between solvers and platforms |
solverTypePlatformMap | 3 | Map between solvers, model types and platforms |
systemSuffixes | 1 | System suffixes |
Power Set
The very special system attribute powerSetLeft
and powerSetRight
do not provide access to static data relevant to the system but produce data based on existing sets b
and s
. This system data produced can be interpreted as a numbering system with base b and s digits. The total number of tuples created is power(card(b),card(s))
. The first index of the resulting set has to have at least this size. The following small example demonstrates the functionality of powerSetRight
:
$set digits 3
set s / s1*s%digits% /, b / 0,1 /;
$eval nMax power(card(b),card(s))
set n / n1*n%nMax% /
x(n,s,b) / system.powerSetRight /;
option x:0:0:%digits%; display x;
With 3 digits the display results in the following output:
---- 6 SET x n1.s1.0, n1.s2.0, n1.s3.0 n2.s1.0, n2.s2.0, n2.s3.1 n3.s1.0, n3.s2.1, n3.s3.0 n4.s1.0, n4.s2.1, n4.s3.1 n5.s1.1, n5.s2.0, n5.s3.0 n6.s1.1, n6.s2.0, n6.s3.1 n7.s1.1, n7.s2.1, n7.s3.0 n8.s1.1, n8.s2.1, n8.s3.1
Changing powerSetRight
to powerSetLeft
reassigns the order of the digits. So the lowest digit is on the left:
---- 6 SET x n1.s1.0, n1.s2.0, n1.s3.0 n2.s1.1, n2.s2.0, n2.s3.0 n3.s1.0, n3.s2.1, n3.s3.0 n4.s1.1, n4.s2.1, n4.s3.0 n5.s1.0, n5.s2.0, n5.s3.1 n6.s1.1, n6.s2.0, n6.s3.1 n7.s1.0, n7.s2.1, n7.s3.1 n8.s1.1, n8.s2.1, n8.s3.1
Access to Hidden Functions
Intrinsic functions are not keywords but they are stored in a list of predefined names. If a user program uses such a predefined name of a function for a user symbol, GAMS will hide the original function. For example,
set uniform 'School Uniform' / skirt, blouse, blazer, socks, shoes /;
scalar randomNumber;
randomNumber = uniform(0,1);
will result in a compilation error in the second line because GAMS expects uniform
to be a set. The function uniform
is hidden for this GAMS program. Renaming the user symbol that hides a function is often the best solution for this, but there are a few cases (including GAMS code already compiled and stored in a restart file) where renaming is not an option. A hidden function can be accessed via the system attribute system.functionName
. So the following will successfully compile and execute:
set uniform 'School Uniform' / skirt, blouse, blazer, socks, shoes /;
scalar randomNumber;
randomNumber = system.uniform(0,1);