Colorado GAMS

A LIBINCLUDE Tool for Reading and Writing
GEMPACK Header Array Files

Ken Pearson

Centre of Policy Studies and the Impact Project
Monash University

Thomas F. Rutherford*

Department of Economics
University of Colorado

January, 2000; Updated May, 2002

* This research supported by the GAMS Applied General Equilibrium Research Fund. The software described here operates only with GAMS 2.25.089 or later on the PC. The author remains responsible for any bugs which exist in this software. This software is not officially supported by GAMS Corporation.

On occasion it is necessary for GAMS programs to share data with GEMPACK programs. This document describes libinclude routines which facilitate the transfer of data to and from files in GEMPACK header array format, identified by the suffix ".HAR". Data transfers from GAMS into HAR files involve the GAMS2HAR libinclude routine and occur at execution time. Data transfers from HAR files into GAMS involve the HAR2GAMS libinclude routine and occur at compile time.


A number of libinclude routines must be installed in the GAMS include library subdirectory (LDIR) if you want to have these tools as a standard component of your GAMS installation.

Download the inclib.pck and harfile.pck files into your GAMS system directory, and run GAMSINST.

The file inclib.pck contains all of the libinclude programs which have been developed at the University of Colorado during the past couple of years. These include files for report writing (GAMS2TBL), spreadsheet interface (SSLINK), workbook interface (XLLINK), and plotting (GNUPLOT). Libinclude source files for all of these applications are kept in a single archive in order to simplify maintenance. You may need to download additional batch and executable files in order to install these other packages.

Syntax for gams2har

$LIBINCLUDE gams2har [ file_prefix param1 domain1 param2 domain2 ...[&] ]

Some additional information:

(i) gams2har only works for parameters.

(ii) The first invocation must be outside of a loop or if block.

(iii) In order to use the routine within a loop or if block, include a blank invocation (without arguments) to initialize.

(iv) Domain specifications are required, with a single set identifier for each dimension.

(v) Data is written to the header array file using the MODHAR. The data transfer occurs following each call to gams2har, provided that the call does not terminate with a continuation symbol, "&".

(vi) A continuation symbol indicates that additional parameters will be provided on a subsequent call.

Syntax for har2gams

$LIBINCLUDE har2gams file 

har2gams reads all parameters from a specified header array file. It is not possible to read individual parameters from a header array file.

Example 1: Generic Invocation

set i /i1*i3/;

alias (i,j);

parameter	a(i,j)	Parameter to write into HAR file;

a(i,j) = uniform(0,1);

$libinclude gams2har ex1 a i j

display a;

This code generates a file named ex1.har. The following program reads the resulting header array file:

set i /i1*i3/;

alias (i,j);

$libinclude har2gams ex1

display a;

Both programs generate identical output:

----    206 PARAMETER A             Parameter to write into HAR file

            i1          i2          i3

i1       0.172       0.843       0.550
i2       0.301       0.292       0.224
i3       0.350       0.856       0.067

Example 2: Writing Multiple Parameters

set i /i1*i3/;

alias (i,j);

parameter	a(i,j)	Matrix array to write into HAR file
		b(i)	Vector array to write into HAR file;

a(i,j) = uniform(0,1);
b(i) =  uniform(0,1);

*	Execute the data transfer with a continuation:

$libinclude gams2har ex2 a i j  b i

display a,b;

Alternatively, the second parameter could be transferred in a continuation line:

$libinclude gams2har ex2 a i j &
$libinclude gams2har b i

GAMS2HAR Update, May 2002

An updated version of the GAMS2HAR routines writes the elements of the sets involved to the output Header Array file.

This version also writes TABLO Input files which can be used (in conjunction with GEMPACK) to

These TAB files can be used to check that you can access the data on the HAR file produced by GAMS2HAR. In particular, if you create a single TAB file made up of these three TAB files (in the order above), you can run this TAB file to test that you can read the coefficients from the HAR file written by GAMS2HAR, and write their values elsewhere.

The TAB files produced have names which start with the name of the output HAR file, followed by an underscore "_" and then a single letter. The letter at the end is "s" (declares and read sets), "c" (declares and reads Coefficients) and "w" (writes Coefficients).

For Example 2 (see above), the TAB files produced are EX2_S.TAB, EX2_C.TAB and EX2_W.TAB. They are as follows.


File BaseData # Contains set and coefficient data # ;
Set i read elements from file Basedata header "s0001" ;


! Next is declared in SETS TAB file !
!File Basedata # Contains set and coefficient data # ;!
Coefficient (All,i1,i)(All,i2,i) a(i1,i2) ;
Read a from file Basedata header "h001" ;
Coefficient (All,i1,i) b(i1) ;
Read b from file Basedata header "h002" ;


Write a to terminal ;
Write b to terminal ;

Element order in GAMS2HAR output files

GEMPACK users should be careful about the order of the elements in the sets written on the output HAR file by GAMS2HAR. An example will make this clear.


Consider the following GAMS file HAR1.GMS.

Powerset      / cap, inv, dep/
Misc  miscellaneous data in DATA /sx, sh, cap, wb/ ;
param2(misc) ;
param1(powerset)=23 ;
param2(misc)=12 ;
param2("cap") = 11 ;
$LIBINCLUDE gams2har  ex1 param2 misc

You might expect that the elements of the set Misc on the output HAR file EX1.HAR would be as in the declaration of the set Misc in HAR1.GMS. However, the order will be

cap, sx, sh, wb

since GAMS stores the element names in the order they appear in the whole file HAR1.GMS. Since "cap" appears in set Powerset, it comes before the other elements of Misc when written to EX1.HAR by GAMS2HAR.

Since the order of the elements can be important in interpreting data on HAR files, you should look carefully at the output HAR file. For this reason, GEMPACK users should consider including statement

check-on-read all = yes ;

in their Command files when reading data translated via GAMS2HAR to check that they are associating data correctly.

Economics Department, University of Colorado, Boulder CO 80309-0256
Phone: (303) 492-5169, Fax: (303) 492-8969
Create January, 2000 by TFR
Updated May, 2002 by TFR and KRP