Colorado GAMS

A LIBINCLUDE Interface to GNUPLOT 3.7 from GAMS


NB: This page describes tools developed for GNUPLOT version 3.71. See here for documentation of routines developed earlier for GNUPLOT version 3.6.
NB: When upgrading to GNUPLOT version 3.7, make sure that you:
  1. Upgrade to the latest version of inclib.pck.
  2. Use the call $libinclude plot rather than $libinclude gnuplot

Thomas F. Rutherford*

Department of Economics
University of Colorado

February 1996

Revised, March, 1999

* This research supported by the GAMS Applied General Equilibrium Research Fund. The software described here operates only with GAMS 2.50. I would like to thank Michael Ferris and Miles Light for their suggestions. It would be misleading if I did not acknowledge that Ferris prefers to use MATLAB for visualization. The author remains responsible for any bugs which exist in this software. This software is not officially supported by GAMS Corporation.

This is unsupported software developed for my own use which I am distributing freely to GAMS users. The motivation for this package is that computational work often involves calculations followed by plotting of results. GNUPLOT provides a quick and easy way to produce graphical images from a GAMS program. This program is relatively new, so I would be very pleased to receive a bug report or two. Of course, there are no warranties.

In the GNU spirit, I am regarding the GNUPLOT stuff as public domain. In the same vein, I would be most grateful if users would post improvements or bug fixes as they are made.

Cheers,

Thomas F. Rutherford
University of Colorado


Contents:

  • Notes from 3/99 upgrade to GNUPLOT 3.7

  • Frequently asked questions about using GNUPLOT with GAMS

  • Hardware and software requirements

  • Installation

  • Environment variables

  • Some examples


    Notes from 3/99 upgrade:

    A new GNUPLOT version has just been released, and this has lead to my decision to make some extensive changes in the GAMS link to GNUPLOT. The key idea in this revision is to move all possible plotting options to "native GNUPLOT instructions". This revision significantly reduces the number of setglobals in my libinclude package, and it leaves the user the task of reading the GNUPLOT manual or the other documentation. The package now includes a routine for three-dimensional contour plots -- see example 9.

    The libinclude routine for GNUPLOT 3.7 is now called PLOT rather than GNUPLOT.


    Frequently asked questions about using GNUPLOT with GAMS:

    Where do I find out about GNUPLOT?

    You can find a fairly complete set of GNUPLOT 3.7 source files, executables and documentation at the GNUPLOT 3.7 web page (using Netscape) or from the FTP site. There are some other related sites.

    What version of GNUPLOT is used with GAMS?

    This version includes GNUPLOT 3.7. I have only tested under Windows 95 and NT. A different set of routines were developed for use with GNUPLOT 3.6.

    My GNUPLOT graph did not appear. How do I debug?

    The libinclude routine writes two files in the local directory, GNUPLOT.PLT and GNUPLOT.DAT. These contain a GNUPLOT program and data. You need to load GNUPLOT as a separate process and load GNUPLOT.PLT in order to see the GNUPLOT error message. Due to an apparent bug, I am unable to retrieve the return code from within the libinclude routine.

    My GAMS program hangs when I output a graph to a file.

    It is essential to include the statement $setglobal batch yes before plotting to disk.

    How can I move GNUPLOT output into a paper or presentation?

    Here is some sample output from GNUPLOT and formatted with Corel Presentations. Figures may be copied to the Windows clipboard (use the right button!). This provides a Windows-compatible image which can be pasted into any number of applications. It is then relatively easy to produce a publication-quality plot in black-and-white or an overhead transparency in color.

    Alternative, you can produce publication-quality figures by loading GNUPLOT output into LaTeX. (Here is a web page on how to use GNUPLOT with LaTeX.)

    How do I represent missing values?

    GNUPLOT.GMS uses use the special GAMS numeric value "NA" to represent missing data.

    Can I regenerate a plot using GNUPLOT independent of GAMS?

    Yes. If you look at files GNUPLOT.PLT and GNUPLOT.DAT after GAMS has exited, you will find that these contain all the GNUPLOT commands and data required to generate the last plot from your GAMS code. To reproduce the graph, open the GNUPLOT.PLT within WGNUPLOT.

    Hardware and software requirements:

    1. A PC (perhaps Unix?)
    2. GAMS version 2.25.089 or later (released in October, 1996), available from:

    GAMS Development Corp., 1217 Potomac Street NW, Washington DC 20007
    Phone: (202) 342 0180, Fax: (202) 342 0181
    email:steve@gams.com


    Installation:

    1. Copy inclib.pck and gp371w32.pck into your GAMS system directory and run GAMSINST.
    2. Download the GNUPLOT manual and the other documentation for reference.


    Environment variables:

    In GAMS, an environment variable is set with a statement such as:

    $setglobal variable  value
    

    This passes a variable with a specified value to GNUPLOT. The following variables are understood:

    domainSpecifies the domain on the x-axis of data which are to be displayed. (Note: this parameter may be specified as the second argument on the $libinclude call.)
    seriesSpecifies the data series (individual output plots) which are to be displayed. (Note: this parameter may be specified as the third argument on the $libinclude call.)
    labelsSubset of X axis labels to be displayed on graph.
    xvalueSpecifies a parameter or column containing the x-axis values -- included to permit generating graphs with unequal intervals. (The package first looks to see if there is a parameter named %xvalue%. If there is no parameter with that name, it then looks for a datacolumn with that name.)
    batchSpecifying $setglobal batch yes indicates that GNUPLOT should be called in batch mode. When this switch is omitted, GNUPLOT awaits the user's click before closing the graph window. This switch must be specified whenever output is directed to a file.


    Some examples:

    (gplib37.zip)

    ex0.gms

    $title  Example 0: Plot a one dimensional vector to the screen
    
    set t /1990*2030/;
    
    parameter a(t)  Example 0: Generic output to the screen (default invocation);
    a("1990") = 1;
    loop(t,  a(t+1) = a(t) * (1 + 0.04 * uniform(0.2,1.8)); );
    
    *        I know that a() is defined over set t.  The plotting package
    *       knows that the argument has one dimension, but it does not know
    *       what set defines those entry.  Three ways to pass the domain:
    
    *       (i) Let GAMS figure out which elements of A are nonzero (not a problem
    *       here because the parameter is dense:
    
    $libinclude plot A 
    
    *       (ii) Pass GAMS the domain on the call:
    
    $libinclude plot A t
    
    *       (iii) Pass GAMS the domain in an environment vaiable:
    
    $setglobal domain t
    
    $libinclude plot A 
    

    ex1.gms

    $title  Example 1: Generic Invocation of GNUPLOT
    
    
    set t /1990*2030/, j /a,b,c,d/;
    
    parameter a(t,j)  Example 1: Generic output to the screen (default invocation);
    a("1990",j) = 1;
    loop(t,  a(t+1,j) = a(t,j) * (1 + 0.04 * uniform(0.2,1.8)); );
    
    $setglobal gp_opt1 'set key top left'
    $libinclude plot A
    

    ex2.gms

    $title  Example 2: Directing GNUPLOT Output to File
    
    set t /1990*2030/, j /a,b,c,d/;
    
    parameter a(t,j)  Random time series with a trend; 
    a("1990",j) = 1;
    loop(t,  a(t+1,j) = a(t,j) * (1 + 0.04 * uniform(0.2,1.8)); );
    
    $setglobal gp_opt1 'set key bottom right'
    $setglobal gp_opt2
    $setglobal gp_opt3
    $libinclude plot A
    
    $setglobal batch yes
    
    $setglobal gp_opt2 "set term pslatex"
    $setglobal gp_opt3 "set output 'a.ps'"
    $libinclude plot A
    
    $setglobal gp_opt2 'set term gif'
    $setglobal gp_opt3 "set output 'ex2_37.gif'"
    $setglobal gp_opt7 "set size 0.8,0.8"
    $libinclude plot A
    
    

    The GIF file generated by ex2.gms:

    ex3.gms

    $title  Example 3: Graphs with Labels and Titles
    
    set t /0*40/, j /a,b,c,d/;
    
    *       Note: where we specify descriptive text for subset elements,
    *       it is then displayed in place of the subset index on the 
    *       graph -- i.e. 1990,2000 etc. are displayed, not 0,10,...
    
    set decade(*) / 0 1990, 10 2000, 20 2010, 30 2020, 40 2030/;
    
    parameter a(t,j)  Example 3: Labels and Titles; 
    a("0",j) = 1;
    loop(t,  a(t+1,j) = a(t,j) * (1 + 0.04 * uniform(0.2,1.8)); );
    
    *       ---------------------------
    *       Generic plotting commands:
    
    $setglobal labels decade
    
    
    $setglobal gp_opt5 "set xlabel 'Year -- time step annual'"
    $setglobal gp_opt6 "set ylabel 'Value'"
    
    
    *       ---------------------------
    *       GNUPLOT commands:
    
    $setglobal gp_opt1 "set key 5,3"
    $setglobal gp_opt2 "set title 'Graph of Random Time Series'"
    $libinclude plot A
    
    $setglobal batch yes
    $setglobal gp_opt3 "set output 'ex3_37.gif'"
    $setglobal gp_opt4 "set term gif"
    $setglobal gp_opt7 "set size 0.8,0.8"
    $libinclude plot A
    
    

    The GIF file generated by ex3.gms:

    ex4.gms

    $title  Example 4: Changes the graph size, y range and location of key:
    
    set t /1990*2030/, j /a,b,c,d/;
    
    set decade(*) / 1990, 2000, 2010, 2020, 2030/;
    
    parameter a(t,j)  Example 4: Changing graph size and scaling ;
    a("1990",j) = 1;
    loop(t,  a(t+1,j) = a(t,j) * (1 + 0.04 * uniform(0.2,1.8)); );
    
    $setglobal labels decade
    
    $setglobal gp_opt5 "set xlabel 'Year -- time step annual'"
    $setglobal gp_opt6 "set ylabel 'Value'"
    
    $setglobal gp_opt1 "set size 0.8,0.8"
    $setglobal gp_opt2 "set key  5,2"
    $setglobal gp_opt3 "set grid"
    $setglobal gp_opt4 "set yrange [0:3]"
    $libinclude plot A
    
    $setglobal batch yes
    $setglobal  gp_opt5 "set output 'ex4_37.gif'"
    $setglobal  gp_opt6 "set term gif"
    $libinclude plot A
    
    
    

    The GIF file generated by ex4.gms:

    ex5.gms

    $title  Example 5: Unequally spaced data
    
    set t /1990*2030/, j /a,b,c,d/; 
    parameter a(t,j)  Example 5: Missing data represented by NA;
    a("1990",j) = 1;
    loop(t,  a(t+1,j) = a(t,j) * (1 + 0.04 * uniform(0.2,1.8)); );
    
    set decade(*) / 1990, 2000, 2010, 2020, 2030/;
    parameter year(*); year(t) = 1989 + ord(t);
    
    * Omit some data points randomly, indicating these as missing
    * by assigning values equal to na:
    
    a(t,j)$(uniform(0,1) le 0.25) = na;
    
    $setglobal labels decade
    $setglobal xvalue year
    
    $setglobal gp_opt1 "set key    1995,2"
    $setglobal gp_opt2 "set data style linespoints"
    $setglobal gp_opt3 "set xlabel 'Year -- time step annual'"
    $setglobal gp_opt4 "set ylabel 'Value'"
    $libinclude plot A
    
    
    $setglobal batch yes
    
    $setglobal gp_opt5 "set size 0.7,0.6"
    $setglobal gp_opt6 "set output 'ex5_37.gif'"
    $setglobal gp_opt7 "set term gif"
    $libinclude plot A
    

    The GIF file generated by ex5.gms:

    ex6.gms

    $title  Example 6: Dealing with Zero Rows and Zero Columns
    
    set     i       evaluation points       /1990*2000/
            j       various time seris      /a, b, c, d/;
    
    $setglobal labels i
    
    table  time_path(i,j)  Time series with holes
    
            a       b       c       d
    1990    0       2       0       0
    1991    1       2       1       0
    1992    2       3       4       0
    1993    3       4       0       0
    1994    4       0       2       0
    1995    0       0       0       0
    1996    1       2       3       0
    1997    2       3       4       0
    1998    3       4       5       0
    1999    4       5       6       0
    2000    5       1       7       0;
    
    *       Note that time series d is all zeros, and 
    *       all of the time series equals zero in 1995.
    
    *       Problem:        Get gnuplot.gms to pass zero files
    *                       through to the plotting package.
    
    
    $setglobal gp_opt1 "set size 0.7,0.6"
    $setglobal gp_opt2 "set key top left"
    
    $setglobal gp_opt3 "set title 'Problem: 1995 and series D are both zero.'"
    $libinclude plot time_path
    
    $setglobal batch yes
    $setglobal gp_opt4 "set term gif"
    $setglobal gp_opt5 "set output 'ex6a_37.gif'"
    $libinclude plot time_path
    $setglobal gp_opt4
    $setglobal gp_opt5
    $setglobal batch no
    
    *       Define an explicit domain and series:
    
    $setglobal domain i
    $setglobal series j
    
    $setglobal gp_opt3 "set title 'One solution: define domain and series'"
    $libinclude plot time_path
    
    $setglobal batch yes
    $setglobal gp_opt4 "set term gif"
    $setglobal gp_opt5 "set output 'ex6b_37.gif'"
    $libinclude plot time_path
    $setglobal gp_opt4
    $setglobal gp_opt5
    $setglobal batch no
    
    *       Drop the domain and series definition:
    
    $setglobal domain
    $setglobal series 
    
    *       Method 2: replace zero by eps
    
    time_path(i,j)$(not time_path(i,j)) = eps;
    
    $setglobal gp_opt3 "set title 'Another solution: replace zero by eps.'"
    $libinclude plot time_path
    
    $setglobal batch yes
    $setglobal gp_opt4 "set term gif"
    $setglobal gp_opt5 "set output 'ex6c_37.gif'"
    $libinclude plot time_path
    $setglobal gp_opt4
    $setglobal gp_opt5
    $setglobal batch no
    
    GIF files generated by ex6.gms:

    ex7.gms

    $title Example 7: Plotting Multiple Independent Series 
    
    set             i       observation counts /1*4/,
                    g       graphs /a, b, c/;
    
    table data(i,*,g)
    
            x.a     y.a     x.b     y.b     x.c     y.c
    1       1       1       0       2       1       6
    2       2       2       3       2       2       4
    3       4       3       5       5       3       3
    4       10      4       7       6       4       1;
    
    *       First define a set which can hold 4 observations x 
    *       3 plot series:
    
    set     p       plot points /1*12/
    
    set pp(p);
    
    pp("1") = yes;
    
    parameter       x       X coordinate for a given point,
                    y       Series values for points;
    
    
    *       The next statement is crucial -- initialize
    *       all plot points to NA (missing).  The package
    *       will then only plot those items which are 
    *       specified.
    
    y(p,g) = na;
    loop(g,
            loop(i,
              x(pp)   = data(i,"x",g);
              y(pp,g) = data(i,"y",g);
              pp(p+1)$pp(p) = yes;
              pp(p)$pp(p+1) = no;
            );
    );
    display x, y;
    
    $setglobal domain p
    $setglobal xvalue x
    
    $setglobal gp_opt1 "set grid"
    $setglobal gp_opt2 "set tics"
    
    $libinclude plot y
    
    
    *       The X coordinates may also be passed as a column in the matrix:
    
    y(p,"xv") = x(p);
    
    $setglobal xvalue xv
    $libinclude plot y
    
    $setglobal batch yes
    $setglobal gp_opt3 "set size 0.7,0.6"
    $setglobal gp_opt4 "set term gif"
    $setglobal gp_opt5 "set output 'ex7_37.gif'"
    $libinclude plot y
    
    GIF file generated by ex7.gms:

    ex8.gms

    $title Example 8: Plotting Two-Dimensional Series 
    
    set     i       Commodities     /i1*i3/,
            r       Regions         /r1*r3/,
            t       Time periods    /2000*2100/
            s(i,r)  Plot series;
    
    *       Whenever generating a plot with multi-dimensional
    *       series, the user must define a tuple identifying all
    *       the series:
    
    s(i,r) = yes;
    $setglobal series s
    
    
    parameter       prices(t,i,r)   Commodity prices;
    
    
    prices(t,i,r) = 1;
    loop(t,  prices(t+1,i,r) = prices(t,i,r) * (1 + 0.04 * uniform(0.2,1.8)); );
    
    $setglobal gp_opt1 'set key top left'
    $libinclude plot prices 
    
    
    $setglobal batch yes
    $setglobal gp_opt2 "set size 0.7,0.6"
    $setglobal gp_opt3 "set term gif"
    $setglobal gp_opt4 "set output 'ex8_37.gif'"
    $libinclude plot prices 
    
    
    GIF file generated by ex8.gms:

    ex9.gms

    
    $title Example 9: Contour Plotting Example
    
    set     i /1*20/;
    alias (i,j);
    
    parameter       a(i,j)  Evaluation of xy
                    x(i)    Ages of individuals
                    y(j)    Number of individuals;
    
    x(i) = ord(i) - 10;
    y(j) = ord(j) - 10;
    
    
    loop((i,j), a(i,j) = x(i) * y(j); );
    
    $setglobal gp_opt1 "set xlabel 'value of X'"
    $setglobal gp_opt2 "set ylabel 'value of Y'"
    $setglobal gp_opt3 "set key top left"
    $setglobal gp_opt4 "set cntrparam levels discrete 1,10,-1,-10"
    $setglobal gp_opt5 "set title 'Evaluation of xy'"
    $setglobal gp_opt6 "set contour base"
    
    $libinclude contour a i j
    
    $setglobal gp_opt7 "set output 'ex9_37.gif'"
    $setglobal gp_opt8 'set term gif'
    
    $setglobal batch yes
    $libinclude contour a i j
    
    
    GIF file generated by ex9.gms:

    ex10.gms

    
    $title Example 10: Generating EPS Output (provided by Jared Carbone)
    
    set	t /t1*t20/,
    	tl(t)	/t1	0,
    		 t11	pi
    		 t20	2 pi /;
    
    parameter	f(t)		Sine Function
    		theta(t)	Angle in radians;
    
    theta(t) = 2 * 3.141592 * (ord(t)-1)/(card(t)-1);
    f(t) = sin(theta(t));
    
    $setglobal domain t
    $setglobal labels tl
    $setglobal xvalue theta
    
    *	If you want to preview, make the call first:
    
    *.$libinclude plot f
    
    $setglobal batch yes
    $setglobal gp_opt1 "set term postscript eps monochrome 'Times-Roman' 30"
    $setglobal gp_opt2 "set output 'sine.ps'"
    $libinclude plot f
    

    ex10.tex: Using graphicx to insert the figure in a LaTeX document:

    \documentclass{article}
    \usepackage[dvips]{graphicx}
    \begin{document}
    \pagestyle{empty}
    \begin{figure}
    \includegraphics[scale=1.0]{sine}
    \end{figure}
    \end{document}
    

    The resulting LaTeX image appears as follows:


    Economics Department, University of Colorado, Boulder CO 80309-0256
    Phone: (303) 492-5169, Fax: (303) 492-8969
    email:rutherford@colorado.edu
    Last modified March, 1999 by TR