GDXMRW: Reading and Writing GDX files from Matlab


Authors: Steven P. Dirkse (sdirkse@gams.com) and Michael C. Ferris (ferris@cs.wisc.edu)

Note Well:

This document describes the older, unsupported GDXMRW. The newer utilities are part of the GAMS distribution and do not need to be downloaded. Use this page at your own risk!!

Abstract:

This document briefly describes GDXMRW (GDX-Matlab Read/Write), a tool for moving data between GAMS and Matlab. This data exchange gives MATLAB users the ability to use all the optimization capabilities of GAMS, and allows visualization of GAMS data directly within MATLAB. The tool is based on GDX (GAMS Data eXchange), a well-established and public API for exchanging data with GAMS.

N.B.: GDXMRW is distinct from the earlier MATGAMS tools developed to call GAMS from within Matlab. The focus here is narrowed to include only the reading and writing of GDX data files. This has a number of benefits:

Download and installation instructions

Downloads are available for a number of architectures and Matlab versions. Each download contains architecture-specific Mex-files and generic support scripts.

Before installing GDXMRW, first install Matlab and GAMS. A working installation of Matlab is required. A working installation of a recent distribution of GAMS is not required to run GDXMRW, but the tests do depend on GAMS.

The suggested installation procedure is this:

A note on GDX and Matlab versions

The GDX file format and the programming API used to access GDX files have been updated over the years. Throughout the course these updates, some things have remained constant: GDX tools can read any older GDX file, and they always write files at the current version. However, the newer GDX files may not be compatible with older versions of GDX tools. To be sure there are no issues with version incompatibilities, you can run GDXMRW with the same GAMS version it was built with. However, the GDX API and file format does not change with every GAMS distribution so there is a good chance that GDXMRW will be compatible with some other GAMS versions also. Run the tests below to check for compatibility with your installed GAMS system.

In a similar way, the Mex-files built to run with a particular Matlab version may also be compatible with other Matlab versions, especially newer versions of Matlab. Again, run the test below to check for compatibility with your installed Matlab system.

If you have issues with different GDX versions, you should be aware of the GDXCOPY utility distributed with GAMS. GDXCOPY copies or converts one or more GDX files to a different GDX format, and also displays the version information for a GDX file.

As of May 2009, the most recent versions of GDXMRW are built using Matlab 7.4 (2007a) and GAMS Distribution 22.7. There have been no changes to the GDX file format since GAMS 22.7. There are no known issues running with newer versions of Matlab either. Tests on Windows 32- and 64-bit systems with different combinations of GAMS and Matlab distributions, up to and including GAMS 23.0 and Matlab 7.8 (2009a), have been successful using these most recent versions of GDXMRW.

Testing your installation

Tests for the GDXMRW utilities are included in GAMS Distribution 22.3 and later. To run the tests, do
testlib gdxmrw01
testlib gdxmrw02
gams    gdxmrw01
gams    gdxmrw02
Prior to completion the tests will output a clear indication of success or failure to the GAMS log.

Documentation

Good Matlab functions include help text for the command window: the GDXMRW tools are no exception to this rule.

In addition, have a look at the GDXMRW tests to see how things work. They are written to illustrate functionality as well as to test it.