# 2. Simple Use of PGPLOT

## 2.1 Introduction

This chapter introduces the basic subroutines needed to create a graph using PGPLOT, by way of a concrete example. It does not describe all the capabilities of PGPLOT; these are presented in later chapters.

A graph is composed of several elements: a box or axes delineating the graph and indicating the scale, labels if required, and one or more points or lines. To draw a graph you need to call at least four of the PGPLOT functions and subroutines:

1. `PGBEG`, to start up PGPLOT and specify the device you want to plot on;
2. `PGENV`, to define the range and scale of the graph, and draw labels, axes etc;
3. one or more calls to `PGPT` or `PGLINE` or both, or other drawing routines, to draw points or lines.
4. `PGEND` to close the plot.
To draw more than one graph on the same device, repeat steps (2) and (3). It is only necessary to call `PGBEG` and `PGEND` once each, unless you want to plot on more than one device.

This chapter presents a very simple example program to demonstrate the above four steps.

## 2.2 An Example

A typical application of PGPLOT is to draw a set of measured data points and a theoretical curve for comparison. This chapter describes a simple program for drawing such a plot; in this case there are five data points and the theoretical curve is y = x². Here is the complete Fortran code for the program:
```      PROGRAM SIMPLE
INTEGER I, IER, PGBEG
REAL XR(100), YR(100)
REAL XS(5), YS(5)
DATA XS/1.,2.,3.,4.,5./
DATA YS/1.,4.,9.,16.,25./
IER = PGBEG(0,'?',1,1)
IF (IER.NE.1) STOP
CALL PGENV(0.,10.,0.,20.,0,1)
CALL PGLAB('(x)', '(y)', 'A Simple Graph')
CALL PGPT(5,XS,YS,9)
DO 10 I=1,60
XR(I) = 0.1*I
YR(I) = XR(I)**2
10 CONTINUE
CALL PGLINE(60,XR,YR)
CALL PGEND
END
```
The following sections of this chapter describe how the program works, and the resulting plot is shown in Figure 2.1.

## 2.3 Data Initialization

We shall store the x and y coordinates of the five data points in arrays `XS` and `YS`. For convenience, this program defines the values in `DATA` statements, but a more realistic program might read them from a file. Arrays `XR` and `YR` will be used later in the program for the theoretical curve.
```      REAL XR(100), YR(100)
REAL XS(5), YS(5)
DATA XS/1.,2.,3.,4.,5./
DATA YS/1.,4.,9.,16.,25./
```

## 2.4 Starting PGPLOT

The first thing the program must do is to start up PGPLOT and select the graphics device for output:
```      INTEGER PGBEG
IER = PGBEG(0,'?',1,1)
IF (IER.NE.1) STOP
```
Note that `PGBEG` is a Fortran function, not a subroutine, and must be declared `INTEGER`. It has four arguments, and returns an integer code which will have value 1 if the device was opened successfully.
• The first argument is present for historical reasons. It should always be set to zero (0).
• The second argument is a character string which gives a ``device specification'' for the interactive graphics device or disk file for hardcopy graphics (see Chapter 1 and Appendix D). This program makes use of a special shorthand feature of PGPLOT, however: if this argument is set to `'?'`, the program will ask the user to supply the device specification at run-time.
• The last two arguments are described in Section 3.2. Usually they are both set to 1, as in this example.

## 2.5 Defining Plot Scales and Drawing Axes

Subroutine `PGENV` starts a new picture and defines the range of variables and the scale of the plot. `PGENV` also draws and labels the enclosing box and the axes if requested. In this case, the x-axis of the plot will run from 0.0 to 10.0 and the y-axis will run from 0.0 to 20.0.
```      CALL PGENV(0.,10.,0.,20.,0,1)
```
`PGENV` has six arguments:
• the left and right limits for the x (horizontal) axis (real numbers, not integers).
• the bottom and top limits for the y (vertical) axis (also real numbers).
• An integer argument: if this is 1, the scales of the x-axis and y-axis (in units per inch) will be equal; otherwise the axes will be scaled independently. In this case we have not requested equal scales.
• Another integer argument, that controls whether an enclosing box, tick-marks, numeric labels, and/or a grid will be put on the graph. The recommended value is 0. Some of the allowed values are: -2: no annotation; -1: draw box only; 0: draw box, and label it with coordinate values around the edge;1: in addition to the box and labels, draw the two axes (lines x=0, y=0) with tick marks; 2: in addition to the box, labels, and axes, draw a grid at major increments of the x and y coordinates.

## 2.6 Labeling the Axes

Subroutine `PGLAB` may (optionally) be called after `PGENV` to write identifying labels on the x and y axes, and at the top of the picture:
```      CALL PGLAB('(x)', '(y)', 'A Simple Graph')
```
All three arguments are character variables or constants; any of them can be blank (`' '`).
• A label for the x-axis (bottom of picture).
• A label for the y-axis (left-hand edge).
• A label for the plot (top of picture).

## 2.7 Drawing Graph Markers

Subroutine `PGPT` draws graph markers at one or more points on the graph. Here we use it to mark the five data points:
```      CALL PGPT(5,XS,YS,9)
```
If any of the specified points fall outside the window defined in the call to `PGENV`, they will not be plotted. The arguments to `PGPT` are:
• The number of points to be marked (integer).
• The x and y coordinates of the points (real arrays).
• The number of the symbol to be used to mark the points. In this example, we use symbol number 9 which is a circle with a central dot. The available symbols are shown in Chapter 4.

## 2.8 Drawing Lines

The following code draws the ``theoretical curve'' through the data points:
```      DO 10 I=1,60
XR(I) = 0.1*I
YR(I) = XR(I)**2
10 CONTINUE
CALL PGLINE(60,XR,YR)
```
We compute the x and y coordinates at 60 points on the theoretical curve, and use subroutine `PGLINE` to draw a curve through them. `PGLINE` joins up the points with straight-line segments, so it is necessary to compute coordinates at fairly close intervals in order to get a smooth curve. Any lines which cross the boundary of the window defined in `PGENV` are ``clipped'' at the boundary, and lines which lie outside the boundary are not drawn. The arguments of `PGLINE` are like those of `PGPT`:
• The number of points defining the line (integer).
• The x and y coordinates of the points (real arrays).

## 2.9 Ending the Plot

Subroutine `PGEND` must be called to complete the graph properly, otherwise some pending output may not get sent to the device:
```      CALL PGEND
```

## 2.10 Compiling and Running the Program

To compile the program and link it with the PGPLOT library, see Chapter 1. For example, under Unix:
```emacs simple.f
...
f77 -o simple simple.f -lpgplot -lX11
```
Under VMS:
```\$ EDIT SIMPLE.FOR
...
\$ FORTRAN SIMPLE
When you run the program, it will ask you to supply the graphics device specification. Type in any allowed device specification, or type a question-mark (`?`) to get a list of the available device types. For example, if you are using an X Window display, type `/XWIN`: the graph will appear on the terminal screen.
If you want a hard copy, you can run the program again, and specify a different device type, e.g., `simple.ps/PS` to make a disk file in PostScript format. To obtain the hard copy, print the file (but first check with your system manager what the correct print command is; it is possible to waste a lot of paper by using the wrong command or sending a file to the wrong sort of printer!).