The GDXDIFF tool compares the data of symbols with identical name, type and dimension in two GDX files and writes the differences to a third GDX file. A summary report will be written to standard output.

Usage

gdxdiff file1 file2 {diffile} {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. GDXDIFF requires two parameters, the file names of two GDX files. An optional third parameter is the name of the GDX difference file. Without the third parameter, the difference file will be diffile.gdx in the current directory.

diffile = fileName (default = diffile.gdx)

An optional name of the GDX difference file.

Options

The following options can be used when calling GDXDIFF:

Some more detailed remarks on the options:

Eps = value (default = 0.0)

Absolute difference for comparisons; see also Comparing numeric values. If the difference between two values exceeds Eps, a difference will be reported.

RelEps = value (default = 0.0)

Relative difference for comparisons; see also Comparing numeric values. If the value of RelEps is exceeded, a difference will be reported.

Field = fieldName (default = all)

The specified subfield is the only field used for deciding if a variable or equation is different. FieldName is one of the following: l, m, up, lo, prior, scale or all.

FldOnly (disabled by default)

Used in combination with the Field option; The variables and equations will be written as parameters for the selected subfield. This option cannot be used in combination with DiffOnly and requires Field being set to an actual field name but not to all.

ID = identifier (default = all)

Limits the comparison to one or more symbols; symbols not specified will be ignored. Multiple identifiers can be specified as: ID=id1 ID=id2 or as ID="id1 id2". When using GDXDIFF from the menu bar in the GAMS IDE (Utilities), this option is not available.

SkipID = identifier (default = none)

Limits the comparison to one or more symbols; symbols specified will be ignored. Multiple identifiers can be specified as: SkipID=id1 SkipID=id2 or as SkipID="id1 id2". When using GDXDIFF from the menu bar in the GAMS IDE (Utilities), this option is not available.

DiffOnly (disabled by default)

Differences for variables and equations will be written as parameters; each parameter will have an additional index which is used to store the field name. Only fields that are different will be written. This option cannot be used in combination with FldOnly.

CmpDefaults

Enables the comparison of default values. When using GDXDIFF from the menu bar in the GAMS IDE (Utilities), this option is not available.

CmpDomains (disabled by default)

Enable the comparison of symbol domains. Note that the difference are not listed in particular in the diffile. When using GDXDIFF from the menu bar in the GAMS IDE (Utilities), this option is not available.

MatrixFile

This activates a special mode to compare GAMS matrix files in GDX format. This is mostly done for internal use. When using GDXDIFF from the menu bar in the GAMS IDE (Utilities), this option is not available.

IgnoreOrder

By default, GDXDiff preserves the UEL order of the input files. If this is set, this is disabled so that records in the output file could show up in a different order than in the input files. Doing this, the output file can be reduced in size.

SetDesc = boolean (default = Y)

Enable or disable the comparison of associated texts for set elements.

Criterion for comparing numeric Values
The use of Eps and RelEps is best described by the code fragment below.

AbsDiff := Abs(V1 - V2);
if  AbsDiff <= EpsAbsolute
then
  Result := true
else
  if EpsRelative > 0.0
  then
     Result := AbsDiff / (1.0 + DMin(Abs(V1), Abs(V2))) <= EpsRelative
  else
     Result := false;

Interpreting the Labels in the diffile
Only symbols with the same name, type and dimension will be compared. Tuples with different values are written to the GDX difference file, and a dimension is added to describe the difference using the following labels:

• ins1 indicates that the tuple only occurs in the first file.
• ins2 indicates that the tuple only occurs in the second file.
• dif1 indicates that the tuple occurs in both files; contains the value from the first file.
• dif2 indicates that the tuple occurs in both files; contains the value from the second file.

Examples

Compares two GDX Files and writes the Differences to a third GDX File

In the following example, the [trnsport] model is solved twice with different capacity data. GDX files are saved for each run, and compared afterwards using GDXDIFF. The shipments variable is loaded into a new variable used for a display statement. We introduce four new unique elements that are used in the difference file.

* solve and write to unmodified.gdx before manipulating the data
solve transport using lp minimizing z;
execute_unload 'unmodified.gdx', a, x;

* manipulate the data and solve again, write to modified.gdx
a('seattle') = 1.2*a('seattle');
solve transport using lp minimizing z;
execute_unload 'modified.gdx', a, x;

execute 'gdxdiff unmodified modified diffile > %system.nullfile%';

* Declare symbols to hold the data for differences
Set difftags / dif1, dif2, ins1, ins2 /;
Variable xdif(i,j,difftags);
Parameter adif(i,difftags);

execute_load 'diffile' adif=a, xdif=x;
display a, xdif.l;

The display statement generates the following output in the listing file:

----    101 PARAMETER a  capacity of plant i in cases

seattle   420.000,    san-diego 600.000


----    101 VARIABLE xdif.L

                          dif1        dif2

seattle  .new-york      50.000     120.000
san-diego.new-york     275.000     205.000

Alternatively, one can open the diffile in GAMS Studio to display the differences.

This example is also part of the GAMS Data Utilities Library, see model [GDXDIFFExample16] for reference.