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

PGPLOT NEWS


2018
The April update to Windows10 shows up some problems with high resolution screens where graphical symbols, + o etc were displaced from their intended placement.. The /GW (Windows screen driver) has been modified to avoid using system graphical markers, using instead Hershey vector characters.

2006
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. The necessary X-window software is available from https://www.xquartz.org
Running programs usually leads to the system requesting the download and installation.

A new PC-Windows version of PGPLOT offers a much improved facility to programs compiled with Visual Fortran or MinGW-g77/gfortran
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

Template plotting program

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. 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 PC-Windows, Linux, and Macintosh OS X using the GNU gcc compiler suite. The characters and marker symbols (Hershey Fonts) are stored in binary in a separate file grfont.dat which is read when programs are launched. The font file and graphics server programs (GRWND.EXE or pgxwin_server) are with the libraries and build instructions.

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

(linux)                                         

% setenv PGPLOT_DIR ../LibsLgf      
(This defines the location of the font files and Xwindow server programs)                                             

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

2. ILL Extensions

PGNOPN, PGNSEL, PGNEND, PGQNOP, for compatibility PGOPN3, PGSEL3, PGEND3

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 version 4 extensions, PGOPN3, PGSLCT, PGEND3 (limited to three devices), a number of different output devices can be opened simultaneously. PGNOPN reads environment variables PGPLOT_ILL_DEV_1 and PGPLOT_ILL_DEV_2 which can be set to valid PGplot device names. Typically these would be one screen and one PostScript output file for printing. This routine will generate a systematic filename pgxxx.ps for the output file, and the number of pictures per page may be chosen. Closing th PostScript file deletes the header if no graphics have been written. When only a single plot is written the header is modified to allow the file to be an EPS format.

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 compiled libraries 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 gfortran -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
	  xr(i)=0.1*i
	  yr(i)=xr(i)**2
10	continue
	call pgline(100,xr,yr)
	call pgend
	end

% gfortran -o simple simple.f libpgplot.a /usr/X11R6/libX11.a
% simple

produces:

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 ../libsLgf/libpgplot.a.a libpgplot.a
% gfortran  -o simple simple.f libpgplot.a /usr/X11R6/libX11.a

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

4. PGPLOT on PC-WINDOWS

. 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 MinGW - 

Console applications:
g77 -o toto toto.f -mconsole libpggw520.a -mwindows
Windows (GUI) applications
g77 -o totog totog.f tres.o  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 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 psfile.ps/PS	PostScript output
                        			file psfile.ps 

	% 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. pgpx#.ps becomes pgpx004.ps. 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.

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.

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.
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.