GDXMRW: Reading and Writing GDX files from
Matlab
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:
- Platform independence - GDX files are platform independent
- Efficiency - the GDX format takes advantage of sparsity in the
data, and uses various other forms of compression as well.
- Standards compliance - the GDX format is well-established and
well-supported by GAMS, with a large and growing set of utilities
written to read, write, or manipulate data in this format.
- Flexibility - GDX data can be read or written from a GAMS model at
compile time or execution time.
- Ease of maintainance - An application built using GDXMRW will be
easier to debug and maintain than one built using the earlier tools.
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:
- Create a directory.
- Unzip the gdxmrw.zip file you download into this
directory.
- Add this directory to your Matlab path.
- (Unix only)Add this directory to your LD_LIBRARY_PATH environment
variable.
A note on GDX 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.
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.
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.