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.

• Installation

• Syntax for GAMS2HAR

• Syntax for HAR2GAMS

• Example 1: Generic Invocation.

• Example 2: Transferring Multiple Items

• GAMS2HAR Update, May 2002

  GAMS2HAR writes the elements of all relevant sets on the output HAR file and writes GEMPACK TAB files to read the data.

• 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.

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.

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.

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

(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.

$LIBINCLUDE har2gams file 

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;

set i /i1*i3/;

alias (i,j);

$libinclude har2gams ex1

display a;

----    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

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;

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

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

• declare and read the sets,
• declare and read the Coefficients from the HAR file written,
• write the Coefficients to the terminal.

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.

EX2_S.TAB

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

EX2_C.TAB

! 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" ;

EX2_W.TAB

Write a to terminal ;
Write b to terminal ;

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.

Example

Consider the following GAMS file HAR1.GMS.

SET
Powerset      / cap, inv, dep/
Misc  miscellaneous data in DATA /sx, sh, cap, wb/ ;
PARAMETER
param1(powerset)
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.