Colorado GAMS

A GAMS Utility for Mapping Tuples to Linear Sets

Thomas F. Rutherford*

Department of Economics
University of Colorado

Antti Lehtila

VTT Technical Research Centre of Finland

November, 2003

* This research supported by the GAMS Applied General Equilibrium Research Fund. The authors remain responsible for any bugs which exist in this software. This software is not officially supported by GAMS Corporation.

This GAMS libinclude routine implements an efficient algorithm for mapping a sparse, multi-dimensional GAMS tuple onto a linear dimensional set. The routine uses the GDX facility to improve efficiency, hence the routine requires a version of recent version of GAMS.


This utility consists of two GAMS libinclude files, lmap.gms, and lmaprun.gms. Both files must reside either in the source directory of the calling program or in the GAMS library subdirectory. The routine must be in the libinclude directory if you want to have the tool as a standard component of your GAMS installation. The libinclude files are provided along with other libinclude utilities in inclib.pck. Installation involves copying inclib.pck into your GAMS system directory and running GAMSINST.

If you want to use lmap.gms in a model which may be run by someone who may not have installed the inclib.pck library, include copies of lmap.gms and lmaprun.gms in your model directory and replace "$libinclude" by "$batinclude".

The file inclib.pck contains all of the libinclude programs which have been developed at the University of Colorado. These include files for data management (GAMS2TXT), output of comma-delimited tables (GAMS2CSV), Excel file input and output (XLLINK), plotting (GNUPLOT), report writing ( GAMS2TBL), use of GEMPACK data files (GAMS2HAR), and scenario management (GAMSSM).

Syntax for lmap

$LIBINCLUDE lmap map hh h 

The three arguments are required. These are defined as following:
hhA one-dimensional set to be mapped onto h .
hMultidimensional set (tuple) to be mapped.
map(hh,h)A tuple which assigns each element of hh to an element of h.

General Comments

(i) LMAP only works for sets. You cannot map numeric arrays.

(ii) The cardinality of hh must be no smaller than the cardinality of h.

(ii) The first invocation must be outside of a loop or if block. This routine may be used within a loop or if block only if it is first initialized with blank invocations ("$LIBINCLUDE lmap" in a context where set and parameter declarations are permitted.

(iii) The GAMS file identifier lmapdim is used within this routines and may not be used in the calling program.

Example 1: Map elements of a two dimensional tuple onto a linear set.

set	t(*,*) / a.c, b.b, b.c, c.b, c.d/;

set	k	Linear addresses /1*5/;

set	map(k,*,*)	Mapping from t to k;

$libinclude lmap map k t 

*	Note that the sequencing of t is determined by the 
*	symbol table.  The display statement lists elements
*	of t in this sequence:

option t:0:0:1;
display t;

*	When k is mapped to t, the assignments are 
*	with the previous display statement:

option map:0:0:1;
display map;

Example 1 writes the following lines to ex1.lst:

----     68 SET t  


----     74 SET map  Mapping from t to k


Example 2: A Large Dimensional Example

set     hh              Households in a linear address /1*20000/,
        hid             Household ID /1*1000/,
        r               Regional ID /1*800/,
	c		County ID /1*20/,
        h(r,c,hid)        Surveyed households,
        hmap(hh,r,c,hid)  Mapping from hh to h;

*       Produce a random, sparse, three-dimenional set:

h(r,c,hid) = yes$(uniform(0,1) < 0.001);  

*	Map the single dimensional set h onto elements of 
*	the three-dimensional tuple:

$libinclude lmap hmap hh h 

parameter	cardchk	Check of the number of elements;

cardchk("h") = card(h);
cardchk("hmap") = card(hmap);
display cardchk

The display statement produces the following output:

----     73 PARAMETER cardchk  Check of the number of elements

h    15720,    hmap 15720

This example runs in less than 8 seconds on a 3GHz PC, and most of this time is involved in generating the random input data.

Economics Department, University of Colorado, Boulder CO 80309-0256
Phone: (303) 492-5169, Fax: (303) 492-8969
Last modified November, 2003 by TFR