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
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.
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.
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:
(Unix) % 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.
PGNOPN, PGNSEL, PGNEND 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 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 pgxxx.ps 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:
/tek Tektronix 4010 compatible output
/tk4100 Tektronix 4100 (colour)
/krm Kermit Tektronix emulator
/ps PostScript, (portrait, landscape, +colour...)
/gif GIF image file /gif /vgif
/xserv X-window (persists after program termination
/xdisp X-window (with active cursor)
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.
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 xr(i)=0.1*i yr(i)=xr(i)**2 10 continue call pgline(100,xr,yr) call pgend end % f77 -o simple simple.f libpgplot.a -lX11 % simpleproduces:
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 -lX11For 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 pgxwin_server
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 length. 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 : LINK $(LINK32FLAGS) prog.obj PGPLOTGW6.LIBlinking 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
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 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 nameIf 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 /vcpsIf 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.5where 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:
pgdemo1 General (x,y) plots, linear/log scales, annotation, line drawing, scatter-plots, multiple windows, colour pgdemo2 Text, markers, line and colour attributes pgdemo3 Contours, contours on non cartesian grid, vector fields pgdemo4 Grey scale, and contouring pgdemo5 Interactive cursor defining polygon pgdemo6 Interactive cursor returning coordinates pgdemo7 Simple isometric display pgdemo8 Wire-frame surface representation pgdemo9 Coloured pixel map with superimposed contours. pgdemo10....etc pgdemill 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 e.g. 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) ....graphics calls.... call pgend ier=pgbegin(0,'200/xdisp',1,1) ....graphics 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.
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 /usr/ill/doc/pgplot/pgdemo1.f : /usr/ill/doc/pgplot/pgdemo17.f Demonstration /usr/ill/bin/pgdemo1 Programs : /usr/ill/bin/pgdemo17 Display handlers /usr/ill/bin/pgxwin_server /usr/ill/bin/figdisp (/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
Files (all associated with PGPLOT_DIR) stored in ftp://ftp.ill.fr/pub/cs/pcpgplot.zip 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.BATTo 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 -mwindowsand the program linked:
> g77 -o prog prog %pgflag%
ftp://ftp.ill.fr/pub/cs/osxpgplot.zipand an example of the compilation requires :
g77 -fno-backslash -o pgdemo3 pgdemo3.f libpgplotaq.a -L/usr/X11R6/lib \ -lX11 -laquaterm -Wl,-framework -Wl,FoundationNOTE: 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.
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.
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).
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.
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 -lX11To 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 -lX11July 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 http://astro.caltech.edu/~tjp/pgplot/
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.
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:
/usr/ill/lib/libpgplot502.a and ILLCOM:PGPLOT5_LOGICAL.COMThe 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.