• 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

$setglobal gp_key 'top left'

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 data file management (GAMS2TXT), report writing (GAMS2TBL), spreadsheet interface , and interactive modeling (GAMSCGI). Henceforth I will be keeping libinclude source files for all of these applications in a single archive in order to simplify maintenance. You will need to download additional batch and executable files in order to install these other packages.

Where do I find out about GNUPLOT?

You can find a fairly complete set of GNUPLOT source files, executables and documentation at different points on the net. There is a newsgroup devoted to GNUPLOT (Something like comp.graphics.applications.gnuplot, I seem to recall.). Most of the files I have included here come from ftp://cmpc1.phys.soton.ac.uk/incoming (using Netscape).

What version of GNUPLOT is used with GAMS?

This version includes both GNUPLOT 3.5 and 3.6. The libinclude file determines which to use on the basis of your operating system. The 3.6 version runs under Windows 95 and NT, the 3.5 version runs under DOS or Windows 3.1. (Under 95 or NT you can revert to version 3.5 if you specify $setglobal gp_version 3.5.)

There are only a few substantive differences between 3.5 and 3.6. One useful improvement with 3.6 is that you can specify the key location with words rather than with coordinates. The syntax under 3.6 is, for example, $setglobal gp_key 'top right'.

How do I invoke the Windows Version of GNUPLOT?

If you want to use the Windows version of GNUPLOT to display output, then you specify "$setglobal gp_term windows". (There is now only one $libinclude call for the command-line and windows versions of GNUPLOT.) As with the standard invocation, you obtain WGNUPLOT version 3.6 under 95 and NT, and you get version 3.5 under DOS or Windows 3.1. Note that you can only run WGNUPLOT when Windows is operating.

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 generated using WGNUPLOT ($setglobal gp_term windows) and then 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.

The latest release also provides syntax to generate output files for any of the printers and file formats supported by GNUPLOT (see below). These include Postscript, a number of TeX/Latex-readable file formats and HPGL (which can be subsequently processed using hp2xx.exe).

How do I represent missing values?

GNUPLOT.GMS now uses use the special GAMS numeric value "NA" to represent missing data. I have determined that version 3.5 had a bug in its sscanf implementation which created problems in the representation of plots with missing data. I have found a work-around for this problem with version 3.6.

You may find that graphs generated under the earlier version are now flawed due to the revised treatment of zero. If you want to revert to the ealier interpretation (i.e., zero=missing data), specify "$setglobal gp_na 0". If want to adapt your plots to the new default, you need to assign a value of NA to missing data points.

Can I regenerate a plot using GNUPLOT independent of GAMS?

Yes. If you look at files GNUPLOT.INP 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, load GNUPLOT (run "gnuplot" under DOS, "gp36" under Win95/NT), then type "load 'gnuplot.inp'".

Where can I find further documentation on the GAMS interface to GNUPLOT?

The best way to find out how GAMS is passing data to gnuplot is to execute a plot and then examine the GNUPLOT input file (GNUPLOT.INP) and the GNUPLOT data file (GNUPLOT.DAT). An interested user may also find the libinclude file, inclib/gnuplot.gms, to provide some information on how flags are processed.

What are the common output formats from GNUPLOT?

        screen          Default
        WINDOWS         Loads WGNUPLOT with the program and plot in a separate window.
        GIF             Web-compatible graphic image
        lots more!      See table below.

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

1. Copy inclib.pck into your GAMS system directory.
2. Copy gp32.pck (for 95/NT) or gpdos.pck (for DOS/Win3.1) into your GAMS system directory.
3. Run GAMSINST.EXE.

Contents of gp32.pck, executables for use with Windows 95/NT:

gp36.exe                DOS executable for GNUPLOT 3.6
gnuplot.gih             Help file for GNUPLOT.
wgnupl32.exe            Windows 95 executable for WGNUPLOT 3.6
wgnuplot.mnu            Menu configuration file for WGNUPLOT
wgnuplot.hlp            Help file for the WGNUPLOT
gnugif.exe              Windows 95 executable for GNUPLOT 3.6 (gif driver)

gnuplot.exe             DOS executable for GNUPLOT 3.5 (DOS)
gnuplot.gih             Help file for GNUPLOT.
wgnuplot.exe            Windows executable for WGNUPLOT 3.5 
wgnuplot.mnu            Menu configuration file for WGNUPLOT
wgnuplot.hlp            Help file for the WGNUPLOT

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:

gp_term name [options]	Default terminal output is to the screen in the DOS window running GAMS. "windows" invokes the WGNUPLOT program (available only under Windows 3.1, 95), in which the plot is produced in a separate window. "gif" is available only under Windows 95 or NT, and produces output in GIF format in a file. When you specify a value other than "svga" or "windows" for gp_term, output is directed to a file. GNUPLOT supports lots of different output formats (see the table below).
gp_output name	File name for output. This item is optional. When no output file name is specified, graphics images are written to a file with a prefix matching the calling parameter and a suffix defined by gp_suffix. Once a graph is generated, the value gp_output is erased to avoid overwriting in a subsequent call to GNUPLOT.
gp_suffix name	Default file name suffix for output. This item is optional, with a default of "bin" (or "gif" when gp_term is "gif").
gp_xl	Subset of X axis labels to be displayed on graph.
gp_key	Key location (e.g. '1,2' or - (under Windows 95 or NT) 'bottom right')
gp_row	Specifies the data rows (X axis indices) which are to be displayed. (Can be used to assure that zero rows are displayed.)
gp_col	Specifies the data colums (individual output plots) which are to be displayed. (Can be used to assure that zero columns are displayed.)
gp_title	Title for the graph
gp_xlabel	Title for the X axis
gp_ylabel	Title for the Y axis
gp_size	Plot size (default value '0.8/1.0')
gp_xrange	Explicit X axis range (e.g. '[0:3]')
gp_yrange	Explicit Y axis range (e.g. '[0:3]')
gp_xlabel	X axis label (identification text for x axis)
gp_ylabel	Y axis label (identification text for y axis)
gp_grid	Grid (yes or no)
gp_label	Label (yes or no)
gp_tics	Axis tics (yes or no)
gp_xtics	X axis tics (yes or no)
gp_border	Graph border (yes or no)
gp_zeroaxis	Zero axis (yes or no)
gp_xzeroaxis	X zero axis (yes or no)
gp_yzeroax	Y zero axis (yes or no)

In GNUPLOT the graphics output format is specified by "set term" command. This command indicates a file format or printer for which the plot is to be generated. The compiled version of gnuplot included here includes drivers for the following terminals:

Name	Description
table	Dump ASCII table of X Y [Z] values to output
svga	IBM PC/Clone with Super VGA graphics board ["fontname"]
aifm	Adobe Illustrator 3.0 Format
cgm	Computer Graphics Metafile
corel	EPS format for CorelDRAW
dumb	printer or glass dumb terminal
dxf	dxf-file for AutoCad (default size 120x80)
dxy800a	Roland DXY800A plotter
excl	Talaris EXCL Laser printer (also Talaris 1590 and others)
fig	FIG 3.1 graphics language: X graphics editor
hp2623A	HP2623A and maybe others
hp2648	HP2648 and HP2647
hp500c	HP DeskJet 500c, [75 100 150 300] [rle tiff]
hpgl	HP7475 and (hopefully) lots of others [number of pens] [eject]
pcl5	HP LaserJet III [mode] [font] [point]
hpljii	HP Laserjet series II, [75 100 150 300]
hpdj	HP DeskJet 500, [75 100 150 300]
hppj	HP PaintJet and HP3630 [FNT5X9 FNT9X17 FNT13X25]
imagen	Imagen laser printer
prescribe	Prescribe - for the Kyocera Laser Printer
kyo	Kyocera Laser Printer with Courier font
mif	Frame maker MIF 3.00 format
pbm	Portable bitmap [small medium large] [monochrome gray color]
postscript	PostScript graphics language [mode "fontname" font_size]
qms	QMS/QUIC Laser printer (also Talaris 1200 and others)
tgif	TGIF X11 [mode] [x,y] [dashed] ["font" [fontsize]]
tkcanvas	Tk/Tcl canvas widget
vx384	Vectrix 384 and Tandy color printer
epson_180dpi	Epson LQ-style 180-dot per inch (24 pin) printers
epson_60dpi	Epson-style 60-dot per inch printers
epson_lx800	Epson LX-800, Star NL-10, NX-1000, PROPRINTER ...
nec_cp6	NEC printer CP6, Epson LQ-800 [monocrome color draft]
okidata	OKIDATA 320/321 Standard
starc	Star Color Printer
tandy_60dpi	Tandy DMP-130 series 60-dot per inch graphics
latex	LaTeX picture environment
emtex	LaTeX picture environment with emTeX specials
pslatex	LaTeX picture environment with PostScript \specials
pstex	plain TeX with PostScript \specials
eepic	EEPIC -- extended LaTeX picture environment
tpic	TPIC -- LaTeX picture environment with tpic \specials
pstricks	LaTeX picture environment with PSTricks macros
texdraw	LaTeX texdraw environment
mf	Metafont plotting standard

ex1.gms

$title  Example 1: Generic output to the screen (default invocation)

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

$libinclude gnuplot 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_key 'bottom right'
$libinclude gnuplot A

$setglobal gp_output 'ex2.gif'
$setglobal gp_term 'gif'
$libinclude gnuplot A

$setglobal gp_suffix 'hpg'
$setglobal gp_term 'hpgl'
$libinclude gnuplot A

$setglobal gp_suffix 'tex'
$setglobal gp_term 'tex'
$libinclude gnuplot A

The GIF file generated by ex2.gms:

The TEX image generated by ex2.gms (translated to GIF by textogif:

The HPGL image generated by ex2.gms (translated to PCX using hp2xx.exe and then from PCX to GIF using cvtgif.exe):

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

$setglobal gp_key '5,3'
$setglobal gp_xl     decade
$setglobal gp_title  "Graph of Random Time Series"
$setglobal gp_xlabel "Year -- time step annual"
$setglobal gp_ylabel "Value"
$libinclude gnuplot A

$setglobal  gp_output 'ex3.gif'
$setglobal  gp_term 'gif'
$libinclude gnuplot A

The GIF file generated by ex3.gms:

ex4.gms

$title  Example 4: Changes the graph size, y range and location of the 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 gp_size '0.8,0.8'
$setglobal gp_key    '5,2'
$setglobal gp_grid   'yes'
$setglobal gp_yrange '[0:3]'
$setglobal gp_xl     decade
$setglobal gp_xlabel "Year -- time step annual"
$setglobal gp_ylabel "Value"
$libinclude gnuplot A

$setglobal  gp_output 'ex4.gif'
$setglobal  gp_term 'gif'
$libinclude gnuplot A

The GIF file generated by ex4.gms (the border was cropped using Paintshop Pro):

ex5.gms

$title  Example 5: Missing 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.1) = na;

$setglobal gp_key    '1995,2'
$setglobal gp_style 'linespoints'
$setglobal gp_x      year
$setglobal gp_xl     decade
$setglobal gp_xlabel "Year -- time step annual"
$setglobal gp_ylabel "Value"
$libinclude gnuplot A

$setglobal  gp_output 'ex5.gif'
$setglobal  gp_term 'gif'
$libinclude gnuplot 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 gp_xl 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 process zero rows and columns.


$setglobal gp_title "Problem: zero row 1995 and zero column D are omitted."
$libinclude gnuplot time_path

$setglobal gp_term gif
$setglobal gp_output 'ex6a.gif'
$libinclude gnuplot time_path
$setglobal gp_term 


$setglobal gp_title "One solution: define gp_row and gp_col"
$setglobal gp_row i
$setglobal gp_col j

$libinclude gnuplot time_path

$setglobal gp_term gif
$setglobal gp_output 'ex6b.gif'
$libinclude gnuplot time_path

$setglobal gp_term 
$setglobal gp_row 
$setglobal gp_col 

*       Method 2: replace zero by eps

$setglobal gp_title "Another solution: replace zero by eps."
time_path(i,j)$(not time_path(i,j)) = eps;
$libinclude gnuplot time_path

$setglobal gp_term gif
$setglobal gp_output 'ex6c.gif'
$libinclude gnuplot time_path
$setglobal gp_term