Colorado GAMS

A LIBINCLUDE Interface to GNUPLOT from GAMS


NB: This page describes tools developed for GNUPLOT version 3.6. A new set of routines have been developed for GNUPLOT version 3.7.

Thomas F. Rutherford*

Department of Economics
University of Colorado

February 1996

Revised, March, 1998

* This research supported by the GAMS Applied General Equilibrium Research Fund. The software described here operates only with GAMS 2.25.087 or later on the PC, shipped in December, 1995. 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.

In the future, it would be nice if someone were to extend the gnuplot.gms tools to provide a clean GAMS call to generate more exotic plots. In principle, it should be possible to generate any of these images using data passed from a GAMS program, but it will require some effort to get everything set up properly.

Cheers,

Thomas F. Rutherford
University of Colorado


Contents:

  • Notes from 3/98 bug fix

  • Notes from 1/98 update

  • Frequently asked questions about using GNUPLOT with GAMS

  • Hardware and software requirements

  • Installation

  • Environment variables

  • All output formats

  • Some examples


    Notes from 3/98 bug fix:

    GNUPLOT 3.5 had some problems locating a key outside the plot, and I had programmed a work-around for this which located the key on the basis of the x-axis range. A problem arose in my workaround when missing values were assigned as "NA". With the "set key outside" command in GNUPLOT 3.6, the key location workaround is no longer needed. I know use this as the default location for GNUPLOT under NT/95. You can change the key location from within a GAMS program using a statement like:

    
    $setglobal gp_key 'top left'
    
    


    Notes from 1/98 update:

    Installation of GNUPLOT now requires that you download inclib.pck into your GAMS system directory, and run GAMSINST.

    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.


    Frequently asked questions about using GNUPLOT with GAMS:

    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.
    
    


    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 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)
    
    
    Contents of gpdos.pck, executables for use with DOS/Windows 3.1:

    
    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
    
    


    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:

    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_xlSubset of X axis labels to be displayed on graph.
    gp_keyKey location (e.g. '1,2' or - (under Windows 95 or NT) 'bottom right')
    gp_rowSpecifies the data rows (X axis indices) which are to be displayed. (Can be used to assure that zero rows are displayed.)
    gp_colSpecifies the data colums (individual output plots) which are to be displayed. (Can be used to assure that zero columns are displayed.)
    gp_titleTitle for the graph
    gp_xlabelTitle for the X axis
    gp_ylabelTitle for the Y axis
    gp_sizePlot size (default value '0.8/1.0')
    gp_xrangeExplicit X axis range (e.g. '[0:3]')
    gp_yrangeExplicit Y axis range (e.g. '[0:3]')
    gp_xlabelX axis label (identification text for x axis)
    gp_ylabelY axis label (identification text for y axis)
    gp_gridGrid (yes or no)
    gp_labelLabel (yes or no)
    gp_ticsAxis tics (yes or no)
    gp_xticsX axis tics (yes or no)
    gp_borderGraph border (yes or no)
    gp_zeroaxisZero axis (yes or no)
    gp_xzeroaxisX zero axis (yes or no)
    gp_yzeroaxY zero axis (yes or no)


    Complete set of output formats:

    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:

    NameDescription
    tableDump ASCII table of X Y [Z] values to output
    svgaIBM PC/Clone with Super VGA graphics board ["fontname"]
    aifmAdobe Illustrator 3.0 Format
    cgmComputer Graphics Metafile
    corelEPS format for CorelDRAW
    dumbprinter or glass dumb terminal
    dxfdxf-file for AutoCad (default size 120x80)
    dxy800aRoland DXY800A plotter
    exclTalaris EXCL Laser printer (also Talaris 1590 and others)
    figFIG 3.1 graphics language: X graphics editor
    hp2623AHP2623A and maybe others
    hp2648HP2648 and HP2647
    hp500cHP DeskJet 500c, [75 100 150 300] [rle tiff]
    hpglHP7475 and (hopefully) lots of others [number of pens] [eject]
    pcl5HP LaserJet III [mode] [font] [point]
    hpljiiHP Laserjet series II, [75 100 150 300]
    hpdjHP DeskJet 500, [75 100 150 300]
    hppjHP PaintJet and HP3630 [FNT5X9 FNT9X17 FNT13X25]
    imagenImagen laser printer
    prescribePrescribe - for the Kyocera Laser Printer
    kyoKyocera Laser Printer with Courier font
    mifFrame maker MIF 3.00 format
    pbmPortable bitmap [small medium large] [monochrome gray color]
    postscriptPostScript graphics language [mode "fontname" font_size]
    qmsQMS/QUIC Laser printer (also Talaris 1200 and others)
    tgifTGIF X11 [mode] [x,y] [dashed] ["font" [fontsize]]
    tkcanvasTk/Tcl canvas widget
    vx384Vectrix 384 and Tandy color printer
    epson_180dpiEpson LQ-style 180-dot per inch (24 pin) printers
    epson_60dpiEpson-style 60-dot per inch printers
    epson_lx800Epson LX-800, Star NL-10, NX-1000, PROPRINTER ...
    nec_cp6NEC printer CP6, Epson LQ-800 [monocrome color draft]
    okidataOKIDATA 320/321 Standard
    starcStar Color Printer
    tandy_60dpiTandy DMP-130 series 60-dot per inch graphics
    latexLaTeX picture environment
    emtexLaTeX picture environment with emTeX specials
    pslatexLaTeX picture environment with PostScript \specials
    pstexplain TeX with PostScript \specials
    eepicEEPIC -- extended LaTeX picture environment
    tpicTPIC -- LaTeX picture environment with tpic \specials
    pstricksLaTeX picture environment with PSTricks macros
    texdrawLaTeX texdraw environment
    mfMetafont plotting standard


    Some examples:

    (gplib.zip)

    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 
    
    GIF files generated by ex6.gms:


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