Use of PGPLOT Graphics Library and extensions at ILL

ILL Version 2.2, May 2005, R.E. Ghosh

PGPLOT On-line Manual
Summary of the function of each subroutine

Author T.J Pearson, California Institute of Technology, 1997

Summary of the function of each subroutine


A new Macintosh OS-X version of PGPLOT adds a native Aqua interface allowing pictures to be easily cut and pasted into other applications. The X-window routines are still include however, but require the X-server to be running (default) with the program started in xterm.

A new PC-Windows version of PGPLOT offers a much improved facility to programs compiled with Visual Fortran or MinGW-g77. Graphics are now in a separate, resizeable and printable window, which is shared by tasks.

Extensions added at the ILL

Compiling and linking with PGPLOT

Windows programming and usage

Environment (LOGICAL) variables controlling Output


Error messages

Template plotting program

Sequence of developments at the ILL

Scientific graphics embedded within calculation programs under VAX-VMS used primarily Tektronix-PLOT10, DISSPLA or NAG-Graphics plus GKS libraries, the last two being commercially licensed products. Recognising that new programs will want to use modern window systems to the maximum, while retaining a simplified calling structure, we have spent some effort on finding and testing a graphics package which will function on Unix systems and PCs as well as OpenVMS. The PGPLOT library is now being recommended for new programming projects. This note, describing use in the context of ILL, is intended to complement the manual written by T.J. Pearson (1989), (copies available from R. Ghosh). A summary of the function of each subroutine, listed alphabetically, is also available.

1. Introduction

The PGPLOT library includes routines for most basic scientific needs, including interactivity, with output devices including X-window, Tektronix(emulations), and PostScript. The library is in the public domain for education and research, and offers, especially with the ILL extensions, equivalent performance and possibilities to other licensed packages for which the resulting applications are less easily exported.

The library has been compiled for HP-UX, SGI-Irix, Linux, PC-Windows, VAX-OpenVMS and AXP- OpenVMS systems at ILL. The unix libraries are stored on the server serpub in directories appropriate to each machine type /usr/ill/lib; this renders usage transparent to each type of machine for the user if not the system administrator. The characters and marker symbols (Hershey Fonts) are stored in binary in a separate file grfont.dat which is read when programs are launched. Some notes on use on OpenVMS systems too have been conserved.

To get some flavour of the library, assuming it is installed on a standard system, type the following commands:


% setenv PGPLOT_DIR /usr/ill/lib	      
(This defines the location of the font files and Xwindow server programs)                                             

% /usr/ill/bin/pgdemo1                    run program    
Give /xserv as reply to the question concerning choice of output device.

2. ILL Extensions


The main function of the original ILL extensions was to allow multiple devices to remain open simultaneously. This function is now in the main library. The other useful aspect of the ILL extensions was to use several environmental variables to define output options. This is useful, for example, to avoid repeating questions concerning user's preferences. The present routines PGNOPN, PGNSEL and PGNEND , now offer a more flexible and uniform means of naming the output files from the different drivers.

As with PGOPN3, PGSLCT, PGEND3 (limited to three devices), a number of different output devices simultaneously. PGNOPN reads environment (or on OpenVMS LOGICAL names) opens selected devices, often these would be one screen and one PostScript output file for printing. This routine will generate a systematic filename for the output file, and the number of pictures per page may be chosen.

An X display window handler is spawned automatically if the /xserv, /xwin or /xdisp output option is chosen; the /xwin window handler may have the initial window size set by an environment variable.

Note: the device dependent routines are not in general re-entrant; only different device types can be selected this way. It is possible, however, to address multiple screen windows using the xdisp handler (see below). The xwin server may also be called to oopen more than one window.

PGNSEL, and PGSEL3 selects the output device for the following sequence of plotting commands.

PGNEND and PGEND3 close one or all the output devices. In addition they can send a file to be printed if the command is defined in an environment variable.

In the ILL library only the most common devices have been included:

Some small modifications have been made to these drivers: for example, if a PostScript file is closed before any drawings have been made, then the file is automatically deleted. The default paper size at ILL is A4. Common block values allow GIF images to be created with a specific size, controlled within a program. The filenames generated by the PGN* routines are consistent across the different hardcopy devices, and screen graphics are usually set to black on white background.

3. Compiling and linking with PGPLOT

Compiling and linking a simple program:

	program simple
c f77 -o simple simple.f libpgplot.a -lX11
	real xr(100), yr(100)
	call pgbegin(0,'?',1,1)
	call pgenv(0.,10.,0.,40.,0,1)
	call pglabel('x-axis','y-axis','A simple example')
	do 10 i=1,100
10	continue
	call pgline(100,xr,yr)
	call pgend

% f77 -o simple simple.f libpgplot.a -lX11
% simple


For SGI-Irix the additional library path for libpgplot.a is given with the -L option (here shown as the directory /usr/ill/lib).

% f77 -backslash -O0 -o simple simple.f -L /usr/ill/lib \
-lpgplot520_n32 -lX11

(the -backslash ensures the code will compile escaped characters as text, rather than their C-language equivalents. This is used in fancy text output options possible in the PGPLOT library)

For HP-UX the environment variable LPATH can designate search paths for libraries

% setenv LPATH /usr/lib:/usr/ill/lib/:/usr/lib/X11R5
% f77 -K -O +z -o simple simple.f -lpgplot -lX11

For Unix systems in general it is simpler to create a link to the library in the same directory as the program source then load the program as follows. One advantage is that newer copies of the library will only be used after the link is deleted (% rm libpgplot.a) and re-etablished by the programmer, since each library version at ILL has a distinct name.

% ln -s /usr/ill/lib/libpgplot520_n32.a.a libpgplot.a
% f77 -backslash -o simple simple.f libpgplot.a -lX11   (SGI)
% f77 -o simple simple.f libpgplot.a -lX11   (OSF1-DEC-COMPAQ)

Necessary files  (fonts, library, display)    grfont.dat, libpgplot.a, figdisp


The Quickwin library of PGPLOT6.LIB compiled with Visual Fortran has been superseded by two libraries,PGPLOTGW6.LIB and libpgplotgw.a for Visual Fortran and MinGW-g77 respectively. The PGPLOT_DIR directory is expected to be defined in the environment and should contain grwnd.exe, grfont6.dat and PGPLOT_window.exe For convenience the library files are also stored here. In PGNOPN the default driver option for the screen graphics is device /GW and hardcopy is /VCPS.

linking with Visual Fortran

The link flags pose a problem of exceeding the normal command line
Use a makefile with nmake containing:
LINK32FLAGS=kernel32.lib user32.lib gdi32.lib winspool32.lib \
advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib \
odbc32.lib odbccp32.lib /subsystem:console /incremental:no /machine=I386

linking with MinGW -
Console applications:
g77 -o toto toto.f -Wl,--subsystem,console libpggw520.a -mwindows
Windows (GUI) applications
g77 -o totog totog.f tres.o -Wl,--subsystem,windows libpggw520.a -mwindows
(noting that there is a MinGW resource compiler windres
windres -o tres.o tres.rc
tres.o which contains ICON and other information is then linked as above.)

Other devices included: /GW /CGW /NULL /VPS /VCPS /PS /GIF /VGIF

5. Controlling output from programs containing the PGPLOT library

Each graphical device has characeristics which can be modified by environment variables. These are shown on a separate page.

Here is a summary of some environment variables (Unix), and logical names (VMS) which can be passed to programs using the PGPLOT library to define standard attributes and plotting devices. Examples shown below designate non-standard location of the font file necessary for writing characters. Others control PostScript output etc. New variables defined at ILL have _ILL_ as part of the name. Use of environment variables, typically set at login time, avoids unnecessary repetition of questions each time a program is initiated. For IRIX and HP-UX use the setenv command) and VMS systems the DEFINE command. For example, the following have equivalent results when a copy of the font file is in the current directory:

	% setenv PGPLOT_FONT grfont.dat	             

Specification of plotting device

The default output device is given by /NULL if no environment variable is set. The device and type can be combined into one string for the different devices as shown in some examples beneath.

	% setenv PGPLOT_DEV	PostScript output

	% setenv PGPLOT_DEV /xserv	X- display handler

	% setenv PGPLOT_DEV /tek	Tektronix 4010 emulator, useful for
                                        telephone connections, and external
					networks. (Note X does not work through
                                        networks protected by fire-wall computers.)
In the ILL library if the filename includes a # this is converted into an identifying number e.g. becomes GIF files, which have been "paged", are stored as separate images, again with additional numbers to identify frames.

PGNOPN provides a way to name files directly within the program. If any filename is set in the environment variable this overrides the programmed name

If PGOPN3 is used, up to 3 devices may be preset; PGNOPN allows more, but not all devices can be opened for multiple use. Most commonly, device 1 should be attributed to a screen device, and device 2 to a file or hardcopy device. This practice should be used systematically within a set of programs to maximise use of the environment variables.
	% setenv PGPLOT_ILL_DEV_1  /xserv
        % setenv PGPLOT_ILL_DEV_2  /vcps
If PGEND3 is used then closing after a PostScript device is closed the file can be printed directly if the printing command variable has been set: e.g.
	% setenv PGPLOT_ILL_PRINT_CMD "lp -dlj1_04121"
This allows a page to be printed during the continued execution of a program - see example in the templote plotting program.

Xwindow Displays (Workstations, X-window terminals, Mac-X...)

The X11 system uses the environment variable DISPLAY to locate the screen in use. On a workstation this is usually set on logging in, otherwise it may need to be set manually giving the IP address:

	% setenv DISPLAY xxxxx:0.0    (xxxxx is replaced by the local IP 
number, or using a known system name:
	% setenv DISPLAY scabbard:0.0

/XSERV, /XWIN (re-sizable window display)

The window is created automatically, and in the case of XSERV is retained after the termination of the program. The window is then ready in this case for re-use by a succeeding program, simplifying the need for contiaully adjustng the screen layout.

The initial size may be set by the environment variable

  % setenv PGPLOT_XW_WIDTH 0.5
where the fraction of the width of the screen is given as the initial size of the window.

/XDISP - (re-sizable window display with active cursor) Device type /xdisp

This, the original X-display window driver uses considerably more resources than the XSERV and XWIN server above. It should only be used when there is a strong need to have an active cursor continuously available. The location of the figdisp or xdisp display program may be given either by including the directory (/usr/ill/bin) in the current path or by setting the environment variable:
% setenv PGPLOT_ILL_RUNFIGDISP /usr/ill/bin/figdisp

The display window is created before the graphics program, and may be positioned and reproportioned to a convenient size. The command:

Silicon Graphics:	% pgdisp &
HP                      % pgdisp 1> pgdisp.tmp &

creates a display window with a default identifier 0 and up to 16 colours before the plotting program is started. The window remains after the program terminates, and is available for other programs to re-use. The main advantage is that the window can be re-sized and located in a convenient space on the display. Each time, before drawing, the library checks the current window size. Other X-display device windows (e.g. /xwin), are created on demand, have fixed dimensions, and tend to require moving away from the main text window each time a program is initiated.

Using the command:
	% pgdisp -lineColors 64 -id 3 &

a window capable of showing up to 64 colours (e.g. for use with a pixelmap: see pgdemo9) is created. In this case it has an identifier 3, and output is directed to it by telling the program to use the device


Using different identifiers id allows several windows to be addressed individually on the same display.

Other useful environment variables with examples:

   % setenv PGPLOT_ILL_PPAGE 2	   
the number of pictures (vertically) on PostScript output is set to 2 here

   % setenv PGPLOT_XW_WIDTH 0.4
sets the picture size for the /xwin display to 0.4 times the full screen width.

   % setenv PGPLOT_ILL_PRINT_CMD "lp -dlj1_04121"
will print the PostScript file automatically using the quoted print command
when the file is closed.  If not defined a separate print command must be
given after the program terminates.  

6.1 Examples - Tasting the possibilities

The demonstration programs can be run and show the following characteristics:

	General (x,y) plots, linear/log scales, annotation, line drawing,
        scatter-plots, multiple windows, colour

	Text, markers, line and colour attributes

	Contours, contours on non cartesian grid, vector fields

	Grey scale, and contouring

	Interactive cursor defining polygon

	Interactive cursor returning coordinates

	Simple isometric display

	Wire-frame surface representation

	Coloured pixel map with superimposed contours.


        Use of ILL extensions PGOPN3, PGSEL3, PGEND3

6.2. The sources of these demonstration programs may then be perused, and appropriate features copied into the new applications, compiled, and linked as shown above.

Using Multiple Windows

Once the PGDISP display program has been started it continues to run on even after the application closes the connection (CALL PGEND). To create an application using several windows:

a)	start up the required windows
		call system('figdisp  -id=100 &')
		call system('figdisp  -id=200 &')
		call system('figdisp  -id=300 &')
b)	it is perhaps wise to then wait to ensure they are running
		call sleep(3)
c)	then the application opens and closes each window in turn:
		ier=pgbegin(0,'100/xdisp',1,1) calls....
		call pgend
		ier=pgbegin(0,'200/xdisp',1,1) calls for second window
		call pgend

	and so on.
Note: each window consumes considerable resources, and these are also proportional to the sizes of the windows. Making these smaller might enable a program to run where large windows fail.

7. Directories for PGPLOT components SGI-Irix, HP-UX

Source are in /home/cs/ghosh/pg520dis 

Library		/usr/ill/lib/libpgplotnnn.a

Fonts		/usr/ill/lib/grfont.dat

Doc (summary)	/usr/ill/doc/pgplot.doc

Demonstration	/usr/ill/bin/pgdemo1
Programs		:

Display handlers
		(/usr/ill/bin should be included in default path)

Note: the directory /usr/ill will normally refer to either the SGI routines
or the HP routines as appropriate on the file-server serpub

8. Directories for PGPLOT components for WINDOWS

Files (all associated with PGPLOT_DIR)
stored in
Font file	grfont6.dat
GW server	grwnd.exe
helper		PGPLOT_window.exe
MinGW library	libpggw520.a
Visual Fortran	PGPLOTGW6.LIB
MinGW environ	MinGWVARS.BAT
VF Environment	DVFVARS.BAT
To simplify linking with the MinGW g77 an environment variable PGFLAG can be used. This is set in the batch file.
> SET PGFLAG=libpggw520.a -Wl,--subsystem,console -mwindows
and the program linked:
> g77 -o prog prog %pgflag%

9. Files for Macintosh OS-X

The files for the standard X-window PGPLOT library and the Aquaterm components (libpgplotaq.a) may be found (with installation notes)
and an example of the compilation requires :
g77 -fno-backslash -o pgdemo3 pgdemo3.f libpgplotaq.a -L/usr/X11R6/lib \
-lX11 -laquaterm -Wl,-framework -Wl,Foundation

NOTE: if a library file is copied to another location and the date is consequently changed it is usually necessary to give the command "ranlib library_filename" so that the dates in the internal symbol table are updated.

10.. Error messages

If the programs are installed in the correct directories, but even the test programs do not appear to be found, check that the directory /usr/ill/bin is in the default PATH (printenv), adding it in the .cshrc file as necessary. Some other messages encountered when the programs run abnormally are shown below, with brief explanations.

/xwin output (Unix)

message: "XWDRIV: cannot connect to X-server"

The variable DISPLAY must be a valid screen identifier; the user must also have given permision to allow access to write on the screen. The security lock is controlled by the command xhost, giving the command:

	% xhost +

removes access controls, and allows anyone to write to the local screen named in the DISPLAY variable.

/xdisp output

message: "Can't find the selection atom" (/xdisp) The display handler figdisp must first be started: the basic command required is % figdisp & ( see section 3).

Sequence of developments at the ILL

Macintosh OsX - 2004
Basic X-window library taken from stable g77 version (as used on linux, MinGW etc). Aquaterm version built from this - advantages include remaining in the standard Macintosh environment, with easy cutting and pasting of graphics into Macintosh applications rather than the lossy process using the X-clipboard, similarly this avoids using X with a single button mouse. It is however necessary to install the Aquaterm software following the given recipe.

Windows improvements - 2003
The starting point was the GrWin Graphics Library of Tauguhiro TAMARIBUCH which includes an excellent graphics server program grwnd.exe and GWdriver routines for PGPLOT. These have been added to a Visual Fortran Library and a MinGW library after small modifications to allow a single graphics window to be shared amongst several processes. The resulting programs now run similarly to their Unix counterparts with XServe and pgxwin-server, and in addition resolve many of the problems of printing graphical results.

Year 2000

The default Fortran compiler installations on HP and SGI machines reflect the processors installed. For HP biceps this is a twin processor architecture, and the present library in the HP zone of /usr/ill/lib is of this type. For SGI there are a greater variety of processors. To build generic programs which run on most SGI systems use a link for local libpgplot.a in the build directory as follows, with an environment variable selecting the old 32 bit program format.

           % ln -s /usr/ill/lib/libpgplot520_o32.a libpgplot.a
           % setenv SGI_ABI -32
           % f77 -o myprog myprog.f libpgplot.a -lX11
To build programs to run on most SGI version 6.5 systems and more recent
           % ln -s /usr/ill/lib/libpgplot520_n32.a libpgplot.a
           % f77 -mips3 -o myprog myprog.f libpgplot.a -lX11
July 1997

Version 5.20 of PGPLOT is now available at ILL for Unix systems. In addition to PGNOPN, PGNSEL, PGNEND, a new routine PGQNOP allows the status of a device to obtained, showing whether it has already been opened. A C-callable library /usr/ill/lib/libcpgplot520.a is available for sgi, together with header file /usr/ill/lib/cpgplot520.h One new feature is the use of arrow keys to move the cursor precisely, with shift increasing the speed. Example programs are in /usr/ill/bin, and the source files in /usr/ill/doc/pgplot. The manual pages at ILL are local copies of the Author's pages at

December 1996

Version 5.11 of PGPLOT has now been installed at ILL. Multiple device features are now included in the basic library. For compatibility the ILL routines PGOPN3 and PGEND3 have been adapted to new library routines. Since this version uses PGSLCT in a different context users who have programmed PGSLCT into existing programs must change this to PGSEL3 for their programs to match this updated library. Three routines PGNOPN, PGNSEL, PGNEND, offering extra features are described below.

An addition, a GIF driver is now available, and is included in the library to make image files suitable for inclusion in www files.

January 1996

Version 5.03 of PGPLOT is available, containing primarily bug-fixes for a few functions. A completely new release is proposed shortly, which will include features as standard similar to those added at ILL for handling multiple open devices etc. June 1995

Version 5.02 of PGPLOT is now available and has been installed in addition to the version 49H. The examples have been updated, and so now refer to this version. The library files are accessed via:

The most important improvements are a new X-window server, /XWIN or /XSERV. The second leaves the window visible after the program terminates, ready for re-use. In this new version the window is fully resizeable. To ensure the window-server is found the environment variable PGPLOT_DIR should point to /usr/ill/lib, or ILLLIB:

A header file containing the prototypes of the subroutines allows easier integration with C main programs.

PGPLOT v5.20 Scientific Graphics Library, Author T.J. Pearson, Copyright 1997 California Institute of Technology The library is available for non-commercial use, but is not a public domain package.