• ex0.gms

  Plotting a one-dimensional array

• ex1.gms

  Generic output to the screen (default invocation)

• ex2.gms

  Directing GNUPLOT output to file

• ex3.gms

  Graphs with labels and titles

• ex4.gms

  Changes the graph size, y range and location of key.

• ex5.gms

  Missing data

• ex6.gms

  Dealing with zero rows and zero columns

• ex7.gms

  Plotting multiple independent series

• ex8.gms

  Plotting two-dimensional series

• ex9.gms

  Contour plotting example

• ex10.gms

  Generating EPS plots for LaTeX documents.

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

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:

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.

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:

domain	Specifies 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.)
series	Specifies 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.)
labels	Subset of X axis labels to be displayed on graph.
xvalue	Specifies 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.)
batch	Specifying $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.

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

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

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 

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

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: