Table of Contents
GDXDUMP is a tool to write scalars, sets, parameters (tables), variables and equations from a GDX file formatted as a GAMS program with data statements to standard output, GMS or CSV files. To write to a file, use the output redirection '>' provided by the operating system or the output option of GDXDUMP.
Usage
gdxdump filename {options}
The .gdx file extension can be omitted. Files without a full path name are assumed to be in the current directory when using a command prompt. When using the GAMS IDE, these files are assumed to be in the current project directory.
Options
The table summarizes the options of GDXDUMP. Running GDXDUMP without any arguments will write the sets, parameters, scalars etc. to standard output formatted as a GAMS program with data statements.
| Option | Default | Description |
|---|---|---|
| output | none | Specify the output filename. |
| version | disabled | Writing version information only. |
| symb | none | Specify a single identifier to be written from the GDX. |
| UelTable | none | Write all unique elements in the GDX to a single set. |
| delim | if format=normal: period if format=csv: comma | Specify a delimiter to separate elements in the output. |
| decimalSep | period | Specify a decimal separator. |
| noHeader | disabled | Suppress writing the header information. |
| header | none | Specify a new header when writing to CSV. |
| noData | disabled | Only write the headers of the symbols. |
| CSVAllFields | disabled | Controls the writing of subfields of a variable or equation to CSV. |
| CSVSetText | disabled | Controls the writing of set element text to CSV. |
| symbols | disabled | Generate an alphabetical list of all symbols in the GDX file. |
| symbolsAsSet | disabled | Write some basic information for all symbols in the GDX as set. |
| symbolsAsSetDI | disabled | Write some basic information including domain information for all symbols in the GDX as set. |
| domainInfo | disabled | Generate an alphabetical list of all symbols in the GDX file that includes domain information. |
| setText | disabled | Show the set text (aka the associated text) in the GDX file. |
| format | normal | Specify the output file format. |
| dFormat | normal | Specify the numerical format in the output file. |
| cDim | N | Controls the writing of the column header when using the CSV format. |
| filterDef | Y | Controls the writing of default values. |
| EpsOut | EPS | String to be used when writing the value for 'Epsilon'. |
| NaOut | NA | String to be used when writing the value for 'Not Available'. |
| pInfOut | +Inf | String to be used when writing the value for 'Positive Infinity'. |
| mInfOut | -Inf | String to be used when writing the value for 'Negative Infinity'. |
| UndfOut | Undf | String to be used when writing the value for 'Undefined'. |
| ZeroOut | 0 | String to be used when writing the value for 'Zero'. |
Some more detailed remarks on the options:
output = fileName (default=none)
Write the output to a file. The .gms resp. the .csv file extension must be added when writing to GMS resp. CSV.
This option is demonstrated in Writing GDX to CSV.
-version (disabled by default)
Synonym: -v
Write version information only and terminate; all other options will be ignored.
symb = identifier (default=none)
Specify a single identifier in the GDX file to be written to standard output, GMS or CSV. When writing to CSV, one must specify the
symboption.This option is demonstrated in Writing GDX to standard output and to GMS.
UelTable = identifier (default=none)
Write all unique elements found in the GDX file to a set using the identifier specified as the name for the set.
This option is demonstrated in Writing GDX to standard output and to GMS.
delim = [period, comma, tab, blank, semiColon] (if format=normal: default=period, if format=csv: default=comma)
Selects a different delimiter to separate unique elements; period is the default when writing to standard output or GMS, while comma is the default when writing to CSV.
This option is demonstrated in Writing GDX to CSV.
decimalSep = [period, comma] (default=period)
Specify a decimal separator.
This option is demonstrated in Writing GDX to CSV.
noHeader (disabled by default)
Suppress the header information when writing a single symbol; only the data for the symbol will be written, not its declaration. The option is ignored when writing all symbols. When writing to CSV, the header row can be suppressed by enabling
noHeader.This option is demonstrated in Adding double Quotes to an user defined Header when writing to CSV.
header = string (default=none)
The string supplied replaces the default header written by the program to a CSV file. If an empty header is desired, the string can be empty; such a string can be written using two single quotes (header=''), while in general it is best to enclose the string with double quotes.
This option is demonstrated in Writing GDX to CSV and Adding double Quotes to an user defined Header when writing to CSV.
Only write the headers for the symbols; no data is written. The option is ignored when writing to CSV.
CSVAllFields (disabled by default)
When writing a variable or equation to CSV, all fields (level, marginal, lower, upper, and scale) will be written. Without this option, only the level will be written. When writing a set the option control the writing of the element text.
This option is demonstrated in Writing GDX to CSV.
CSVSetText (disabled by default)
When writing a set to CSV, the set element text will be written as the last column in the CSV file in addition to the set elements. Without this option, only the set elements will be written.
This option is demonstrated in Writing GDX to CSV.
Generate an alphabetical list of all symbols in the GDX file (not valid when writing to CSV).
This option is demonstrated in Writing GDX to standard output and to GMS.
symbolsAsSet (disabled by default)
Generate a set declaration where the data represents basic information (symbol identifier, dimension, type, explanatory text) of all symbols in the GDX file (not valid when writing to CSV).
This option is demonstrated in Writing GDX to standard output and to GMS.
symbolsAsSetDI (disabled by default)
Generate a set declaration where the data represents basic information (symbol identifier, dimension, type, domain information) of all symbols in the GDX file (not valid when writing to CSV).
domainInfo (disabled by default)
Generate an alphabetical list of all symbols in the GDX file that includes domain information (not valid when writing to CSV). The column
DomInfcan have the following values:
N/A- The function to get the type of domain information is not available
None- No domain was specified (domain is the universe)
Relaxed- The domain is relaxed, i.e. the identifiers shown do not necessarily represent one dimensional sets
Regular- Regular domain; the identifiers shown are one dimensional sets
This option is demonstrated in Writing GDX to standard output and to GMS.
Show the set text (aka the associated set text or the set element text) in the GDX file (not valid when writing to CSV).
GDX allows a string of text to be associated with each element of a set. The universe of such strings stored for use in any particular GDX file (i.e. the set text list) can be shown with this option.
format = [normal, gamsbas, CSV] (default=normal)
Change the output format and the symbols written.
When using the gamsbas format, the program will not write the declarations for the symbols and only write the Level and Marginal assignment statements for the variables, and the Marginal assignment statements for equations.
The CSV format adds column headers to the output. By enabling the cDim option the unique elements of the last dimension of the symbol will be used as column headers for the values. If domain information is available, the column headers will be made unique if overlapping names have been used for the names of the index positions. If no domain information is available, the index names used will be of the form
dim1,dim2, ...In order to run
GDXDUMP, one must specify a single symbol using the symb option when writing to CSV.The gamsbas and CSV format is demonstrated in Writing GDX to standard output and to GMS resp. Writing GDX to CSV.
dFormat = [normal, hexponential, hexBytes] (default=normal)
Specify the numerical format in the output file.
Can be used when writing a CSV file; when enabled, the unique elements of the last dimension will be used as column headers for the values.
This option is demonstrated in Writing GDX to CSV.
filterDef = [
Y,N] (default =Y)When enabled, default values will be filtered and not written. This option is enabled by default. For example, if the Level field (
.L) of a variable is zero, the value will not be written.EpsOut = string (default =
EPS)String to be used when writing the value for 'Epsilon'.
String to be used when writing the value for 'Not Available'.
pInfOut = string (default =
+Inf)String to be used when writing the value for 'Positive Infinity'.
This option is demonstrated in Writing GDX to CSV.
mInfOut = string (default =
-Inf)String to be used when writing the value for 'Negative Infinity'.
UndfOut = string (default =
Undf)String to be used when writing the value for 'Undefined'.
zeroOut = string (default = 0)
String to be used when writing the value for 'Zero'.
Note that GDX files can also be viewed using the GAMS IDE or GAMS Studio.
Examples
To demonstrate the features of GDXDUMP in the Writing GDX to standard output and to GMS and Writing GDX to CSV examples, we execute the model trnsport.gms ([TRNSPORT] from GAMS Model Library) initially to create the GDX file trnsport.gdx by using the GDX command line option. Afterwards, some important features of GDXDUMP are demonstrated.
gams trnsport gdx=trnsport
The figure shows the symbol listing of the GDX file in total and the variable x in particular, since those data is used quite often in the following examples:
All subfields of the variable x are shown in the next figure:
Writing GDX to standard output and to GMS
In this example, we will demonstrate the effect of some basic features of GDXDUMP.
While we write to standard output in the most sections of this example, one can also write the GDX file contents into a GAMS file using the following command to redirect the output:
gdxdump trnsport.gdx > GDXContents.gms
Alternatively, the output option can be used to specify an output filename.
Option symbols
This listing shown above can also be written to standard output by using the symbols option of GDXDUMP:
gdxdump trnsport symbols
The GDXDUMP program writes the following output (except for the numbering and the records column, the content is identical compared to the figure):
Symbol Dim Type Records Explanatory text 1 a 1 Par 2 capacity of plant i in cases 2 b 1 Par 3 demand at market j in cases 3 c 2 Par 6 transport cost in thousands of dollars per case 4 cost 0 Equ 1 define objective function 5 d 2 Par 6 distance in thousands of miles 6 demand 1 Equ 3 satisfy demand at market j 7 f 0 Par 1 freight in dollars per case per thousand miles 8 i 1 Set 2 canning plants 9 j 1 Set 3 markets 10 supply 1 Equ 2 observe supply limit at plant i 11 x 2 Var 6 shipment quantities in cases 12 z 0 Var 1 total transportation costs in thousands of dollars
Option domainInfo
We use the domainInfo option to write some basic information including domain information (column DomInf) to standard output:
gdxdump trnsport domainInfo
The GDXDUMP program writes the following output:
SyNr Type DomInf Symbol 3 Par Regular a(i) 4 Par Regular b(j) 7 Par Regular c(i, j) 10 Equ None cost 5 Par Regular d(i, j) 12 Equ Regular demand(j) 6 Par None f 1 Set None i(*) 2 Set None j(*) 11 Equ Regular supply(i) 8 Var Regular x(i, j) 9 Var None z
Check the domainInfo option explanation linked above to get a full list of possible values for DomInf and their interpretation. In this example, the symbol dimensions were not specified (none) or they are defined on the one dimensional sets i and j (regular).
Option symbolsAsSet
Using the symbolsAsSet option one can write the information displayed by enabling the symbols option to a set declaration:
gdxdump trnsport symbolsAsSet
The GDXDUMP program writes the following:
alias (Symbol, Dim, Type, *)
set gdxitems(Symbol,Dim,Type) Items in the GDX file /
"i".1."Set" "canning plants",
"j".1."Set" "markets",
"a".1."Par" "capacity of plant i in cases",
"b".1."Par" "demand at market j in cases",
"d".2."Par" "distance in thousands of miles",
"f".0."Par" "freight in dollars per case per thousand miles",
"c".2."Par" "transport cost in thousands of dollars per case",
"x".2."Var" "shipment quantities in cases",
"z".0."Var" "total transportation costs in thousands of dollars",
"cost".0."Equ" "define objective function",
"supply".1."Equ" "observe supply limit at plant i",
"demand".1."Equ" "satisfy demand at market j"
/;
Option symb
One can write a single identifier from the GDX using the symb option:
gdxdump trnsport.gdx symb=x
The default output includes the declaration header and a data statement when writing a set or parameter. When writing a variable, the output includes the level and marginal subfields:
positive Variable x(i,j) shipment quantities in cases /
'seattle'.'new-york'.L 50,
'seattle'.'chicago'.L 300,
'seattle'.'topeka'.M 0.036,
'san-diego'.'new-york'.L 275,
'san-diego'.'chicago'.M 0.00900000000000001,
'san-diego'.'topeka'.L 275 /;
Note the default values are not written (for instance, zero values of the level or lower bound subfields are missing).
Option UelTable
Using the UelTable option one can write a set (named allUELs in this example) containing all unique elements of the GDX file:
gdxdump trnsport output=allUELs.gms UelTable=allUELs
The following set declaration will be part of the output file allUELs.gms:
Set allUELs /
'seattle' ,
'san-diego' ,
'new-york' ,
'chicago' ,
'topeka' /;
Format gamsbas
Using the format option one can write a variable or equation in the gamsbas format, i.e. there will be no declaration of the symbol and the level and marginal subfields will be written as assignments.
gdxdump trnsport format=gamsbas
GDXDUMP writes the following to standard output:
x.L ('seattle'.'new-york') = 50 ;
x.L ('seattle'.'chicago') = 300 ;
x.M ('seattle'.'topeka') = 0.036 ;
x.L ('san-diego'.'new-york') = 275 ;
x.M ('san-diego'.'chicago') = 0.00900000000000001 ;
x.L ('san-diego'.'topeka') = 275 ;
z.L = 153.675 ;
cost.M = 1 ;
supply.M ('seattle') = Eps ;
demand.M ('new-york') = 0.225 ;
demand.M ('chicago') = 0.153 ;
demand.M ('topeka') = 0.126 ;
Writing GDX to CSV
Next we specify CSV as the output format and demonstrate some simple features available when writing to CSV.
Writing to CSV
One can write to a CSV file by running the following command:
gdxdump trnsport.gdx output=varX.csv symb=x format=csv
By doing this, the level subfield of the variable x is written as a list to the file varX.csv specified in the output statement. The header row contains the domain set identifiers i and j of x and the field "Val":
"i","j","Val" "seattle","new-york",50 "seattle","chicago",300 "seattle","topeka",0 "san-diego","new-york",275 "san-diego","chicago",0 "san-diego","topeka",275
Option cDim
Using the cDim option one can write the data as a table since the right most dimension is used as the column header:
gdxdump trnsport.gdx symb=x format=csv cDim=y
We did not specify an output file in this case, so the data will be written to standard output formatted as CSV:
The GDXDUMP program writes the following:
"i","new-york","chicago","topeka" "seattle",50,300,0 "san-diego",275,0,275
Note the elements new-work, chicago and topeka are written to the header row, since they are elements of the most right dimension j.
Customizing the output: CSVAllFields, header, decimalSep, delim, pInfOut etc.
In this section, all subfields of the variable x are written to CSV and the representation is customized. The writing of subfields is enabled by CSVAllFields. In addition, the header option is used to overwrite the default header (as seen in the two previous paragraphs). For instance, we want to replace i with the term 'canning plants', j with the term 'markets' and "Val" with the term 'shipment quantities in cases', while we are fine with the default column labels for the level, marginal etc. subfields, but they will be overwritten, too. Therefore, we must specify them again manually in the header option. For some reason, the field separator is changed from comma (default) to semicolon and the decimal separator from period (default) to comma using the delim and decimalSep options. One can define the string written to CSV for special values of GAMS like +INF by using the corresponding option pInfOut, which might be useful for further processing of the CSV file.
gdxdump trnsport format=csv output=varX.csv symb=x CSVAllFields header="canning plants;markets;shipment quantities in cases;Level;Marginal;Lower;Upper;Scale" delim=semiColon decimalSep=comma pInfOut=1E+100
GDXDUMP creates the following output:
canning plants;markets;shipment quantities in cases;Level;Marginal;Lower;Upper;Scale "seattle";"new-york";50;0;0;1E+100;1 "seattle";"chicago";300;0;0;1E+100;1 "seattle";"topeka";0;0,036;0;1E+100;1 "san-diego";"new-york";275;0;0;1E+100;1 "san-diego";"chicago";0;0,00900000000000001;0;1E+100;1 "san-diego";"topeka";275;0;0;1E+100;1
Note that the fields in the header are not enclosed by double quotes. This problem is addressed in the next section Adding double Quotes to an user defined Header when writing to CSV.
Customizing the output: CSVSetText
The set element text is the value of a set element. Often this is left out when defining sets, but for descriptive models often set element text is provided. When dumping a set to a CSV file the set element text is not written to the CSV file by default. The option CSVSetText enables the writing of the text. The model mexss.gms ([MEXSS] from GAMS Model Library) has a set i of steel plants with set element text
Set i 'steel plants' / ahmsa 'altos hornos - monclova'
fundidora 'monterrey'
sicartsa 'lazaro cardenas'
hylsa 'monterrey'
hylsap 'puebla' /;
When we create a GDX file and dump set i as CSV with defaults via the following commands
gamslib mexss gams mexss a=c gdx=mexss gdxdump mexss format=csv output=setI.csv symb=i header="steel_plants"
GDXDUMP creates the following output:
steel_plants "ahmsa" "fundidora" "sicartsa" "hylsa" "hylsap"
If we add CSVSetText
gamslib mexss gams mexss a=c gdx=mexss gdxdump mexss format=csv output=setI.csv symb=i CSVSetText header="steel_plants,real_name"
GDXDUMP creates the following output:
steel_plants,real_name "ahmsa","altos hornos - monclova" "fundidora","monterrey" "sicartsa","lazaro cardenas" "hylsa","monterrey" "hylsap","puebla"
Adding double Quotes to an user defined Header when writing to CSV
This sections describes a possible workaround for the following problem: Suppose one wish to write a parameter or variable from GDX to CSV, but with a non default header containing double quotes. For this purpose, one might try to use the header option of GDXDUMP to specify an user defined header. Though, there is no way to add double quotes enclosing the single fields using the header option, but this is a quite common standard in CSV files (for instance, if the fields contain reserved characters).
Initially, define the header you want to write to the CSV file and redirect the line to your final CSV file (which will be created at this point, an already existing file will be overwritten!). Note the double quotes enclosing the field content. Adding the single quotes is necessary in order to run the following statement from GAMS IDE (however, they will not be written to the file), while they must be omitted when using the command prompt.
$echo '"canning plants","markets","shipment quantities in cases"' > quotedHeader.csv
Afterwards, call GDXDUMP by specifying the GDX file, the single symbol x we want to write, the output format CSV and redirect the output to the file quotedHeader.csv:
$call gdxdump trnsport.gdx symb=x format=csv noHeader >> quotedHeader.csv
Appending the output of the recent GDXDUMP call to the already existing file quotedHeader.csv adds the data of x to the file and creates the following CSV file (note that one must prevent GDXDUMP to write the default header by using the command noHeader):
"canning plants","markets","shipment quantities in cases" "seattle","new-york",50 "seattle","chicago",300 "seattle","topeka",0 "san-diego","new-york",275 "san-diego","chicago",0 "san-diego","topeka",275