          Chapter 4: Plotting Axis Systems and Titles

4.1 Plotting Axis Systems

An  axis system  defines  an area  on the page  for plotting
data.  Various axis systems  can be  plotted  to accommodate
different applications. For two-dimensional graphics, a max-
imum of two parallel  X- and Y-axes  can be drawn.  The axis
system is scaled  to fit the range of data points and can be
labeled with values, names and ticks.  Two-dimensional  axis
systems  are plotted  with a call  to the routines  GRAF  or 
GRAFP.

                              G R A F

GRAF plots a two-dimensional axis system.

The call is:  CALL GRAF (XA, XE, XOR, XSTEP, 
                         YA, YE, YOR, YSTEP)         level 1

XA, XE        are the lower and upper limits  of the X-axis.
XOR, XSTEP    are the first  X-axis label  and the  step be-
              tween labels.
YA, YE  are   the lower and upper limits of the Y-axis.
YOR, YSTEP    are the first  Y-axis label  and the  step be-
              tween labels.

Notes:     -  GRAF must be called  in level 1  and automati-
              cally sets the level to 2.  When plotting more
              than  1 axis system  on a page, ENDGRF must be
              called  in between each new set of axes in or-
              der to set the level back to 1.
           -  The position  of the lower left corner and the
              size of an axis system can be changed with the
              routines AXSPOS and AXSLEN.
           -  The axis scaling is linear by default  and can
              be changed with AXSSCL.  For logarithmic  sca-
              ling,  the corresponding  parameters  in  GRAF
              must be exponents of base 10.
           -  One of several label types can be chosen  with
              the routine LABELS or user-defined with MYLAB.
              Single  labels  can be  suppressed  by calling
              AXENDS.
           -  The routine NAME defines axis titles.
           -  The number of ticks between axis labels can be
              changed with the routine TICKS.
           -  SETGRF  can be  used  to remove  a piece of or
              complete axis from an axis system.
           -  If the numerical value  of the lower  limit of
              an axis is larger than the upper limit and the
              label step is negative,  axis scaling  will be
              in descending order.
           -  The routine  FRAME  defines the thickness of a
              frame plotted  around an axis system.  A frame
              can also be plotted outside of  GRAF  with the
              statement CALL BOX2D.

                              G R A F P

The routine GRAFP plots a two-dimensional polar axis system.

The call is:  CALL GRAFP (XE, XOR, XSTEP, YOR, YSTEP)
                                                     level 1

XE            is upper limit  of the  X-axis (radius coordi-
              nate).
XOR, XSTEP    are the first  X-axis label  and the  step be-
              tween labels.
YOR, YSTEP    are the first  Y-axis label  and the  step be-
              tween labels specified in degrees.  The Y-axis
              is scaled from 0 to 360 degrees.

Notes:      - The direction and position of the angle labels
              can be modified with the routine POLMOD.
            - GRAFP is a new name for the old routine POLAR,
              since  polar  is also a C99 function.  The old 
              routine POLAR  is still in the  DISLIN librar-
              ies.  

                              G R A F R

The routine GRAFR plots a two-dimensional  axis system for a
Smith chart, where the non negative impedance or  admittance
plane is projected to a complex reflexion coefficient plane,
which is displayed in the unity radius region. The projecti-
on is done by the formula r = (z - 1) / (z + 1), where z and
r are complex numbers. For admittance,  1 / z is used in the
formula.
 
The call is:  CALL GRAFR (XRAY, N, YRAY, M)          level 1

XRAY          is an array  of non  negative  real values  of 
              complex impedance or admittance data. The val-
              ues are plotted as labels at the X-axis.

N             is the dimension of XRAY.            

YRAY          is an array of imaginary values of complex im-
              pedance  or  admittance data.  The values  are
              plotted as labels at the Y-axis (unity circle).

M             is the dimension of YRAY.            

Notes:      - The type of the Smith  axis system,  impedance
              or admittance, can be defined with the routine
              AXSTYP. 

            - The conversion routine  GETRCO  calculates the
              reflection factor  r  for a impedance z by the
              formula  r = (z - 1) / (z + 1).   The  reverse
              transformation  z = (1 + r) / (1 - r)  is done 
              by GETICO.  For admittance,  1 / z is used for
              the conversions above.

            - Additional grid lines in a Smith chart can be
              plotted with the routines GRIDRE and GRIDIM.

            - A similar axis system for a Smith chart can be
              created  with the normal GRAF  routine,  where
              the scaling  is defined from  -1.0 to 1.0  for
              both axes. For that case,  values must be con-
              verted by GETRCO to reflection factors  before
              passing them to plot routines. For GRAFR, this
              is done automatically in plot routines.
               
4.2 Termination of Axis Systems

                         E N D G R F

The routine  ENDGRF  terminates  an axis system and sets the
level back to 1.

The call is:  CALL ENDGRF                         level 2, 3

Note:         ENDGRF  contains  a call of the routine SENDBF
              that can be disabled with the routine BUFMOD.

4.3 Plotting Titles

                         T I T L E

This routine plots  a title  over an axis system.  The title
may contain up to four lines of text designated with TITLIN.

The call is:  CALL TITLE                          level 2, 3

Note:         All lines  are centred  by default  but can be
              left- or right-justified using TITJUS.

4.4 Plotting Grid Lines

                         G R I D

The routine GRID overlays a grid on an axis system.

The call is:      CALL GRID (IXGRID, IYGRID)      level 2, 3

IXGRID, IYGRID    are the numbers  of grid lines between la-
                  bels.

Note:             GRID uses automatically GRDPOL for a polar 
                  axis system.

                         G R D P O L

The routine GRDPOL plots a polar grid.

The call is:      CALL GRDPOL (IXGRID, IYGRID)    level 2, 3

IXGRID            is the numbers of circles between labels.
IYGRID            is the numbers of sector lines between 360
                  degrees.

                         A X G I T

The  routine  AXGIT  plots  vertical  and  horizontal  lines
through X = 0 and Y = 0.
The call is:  CALL AXGIT                          level 2, 3

Note:         The statement  CALL XAXGIT plots only the line
              Y = 0 while CALL YAXGIT plots only X = 0.

                         C R O S S

The routine  CROSS plots vertical  and horizontal lines with
additional ticks through X = 0 and Y = 0.

The call is:  CALL CROSS                          level 2, 3

Note:         The statement  CALL XCROSS plots only the line
              Y = 0 while CALL YCROSS plots only X = 0.


                        G R I D R E

GRIDRE plots a grid line of a constant real part  in a Smith
chart. 

The call is:  CALL GRIDRE (ZRE, ZIMG1, ZIMG2, N)     level 2

ZRE           is the constant  real  value  of the grid line
              (>= 0.0).

ZIMG1, ZIMG2  are the start and  end imaginary parts  of the 
              gird line. 

N             is the resolution  of the curve,  which  means
              the number of  generated  points between ZIMG1
              and ZIMG2.

                        G R I D I M

GRIDIM plots a grid line  of a constant imaginary part  in a
Smith chart. 

The call is:  CALL GRIDIM (ZIMG, ZRE1, ZRE2, N)      level 2

ZIMG          is the  constant  imaginary value  of the grid
              line.

ZRE1, ZRE2    are the start and  end real parts of the  gird
              line (>= 0.0). 

N             is the resolution  of the curve.
 
4.5 Plotting Additional Labels

                         A D D L A B

Additional  single labels  can be plotted  on an axis system
with the routine ADDLAB.

The call is:  CALL ADDLAB (CSTR, V, ITIC, CAX)    level 2, 3

CSTR          is a character string containing a label.
V             is an  user coordinate  that  defines the axis
              position of the label.
ITIC          is an integer option  that  defines  if a tick
              mark is plotted.  ITIC = 0 means  that no tick
              is plotted,  ITIC = 1 defines a minor tick and
              ITICK = 2 defines a major tick.
CAX           is a character string that defines the axis.
              CAX can have the values  'X', 'Y', 'Z', 'XTOP'
              and 'YRIGHT'.

4.6 Secondary Axes

The following routines  plot single  X- and Y-axes; they are
called secondary axes  because they do not define  or change
any of the  axis scaling parameters.  Secondary axes  can be
used to add additional labels to the axis systems.

The secondary axis routines  for a  rectangular  axis system
are:

    XAXIS  plots a linear X-axis.              level 1, 2, 3
    YAXIS  plots a linear Y-axis.              level 1, 2, 3
    XAXLG  plots a logarithmic X-axis.         level 1, 2, 3
    YAXLG  plots a logarithmic Y-axis.         level 1, 2, 3

The call is:  CALL XAXIS (A, B, OR, STEP, NL, CSTR, IT,
                                                     NX, NY)

A, B          are the lower and upper limits of the axis.
OR, STEP      are the first  label and the step  between la-
              bels.
NL            is the length of the axis in plot coordinates.
CSTR          is a  character  string  containing  the  axis
              name.
IT            indicates how ticks,  labels and the axis name
              are plotted. If IT = 0,  they are plotted in a
              clockwise direction. If IT = 1, they are plot-
              ted  in an  counter-clockwise direction.
NX, NY        are  the  plot  coordinates  of the axis start
              point.  The X-axis  will be plotted  from left
              to right  and the Y-axis from bottom to top.

Analogue:     YAXIS, XAXLG, YAXLG

Notes:     -  Secondary axes can be called  from level  1, 2
              or 3.  Note again  that  secondary axes do not
              change  the scaling of  an axis system defined
              by GRAF.  Similarly,  curves cannot be plotted
              with only secondary axes,  they require a call
              to GRAF.
           -  As in GRAF, the parameters of logarithmic axes
              must be exponents of base 10.
           -  User-defined  labels  may also  be plotted  on
              secondary axes  with  MYLAB  and the  argument
              'MYLAB' in the routine LABELS. 
           -  The number of ticks  can be changed by calling
              TICKS.

The secondary axis routine  for a polar or Smith axis system
is:

    YPOLAR  plots a polar Y-axis.              level    2, 3

The call is:  CALL YPOLAR (A, B, OR, STEP, CSTR, NDIST)

NDIST         is the distance  to the polar  or Smith circle 
              in plot coordinates. The other parameters have
              the same meaning as above.
                                                    

4.7 Calculating Axis Parameters

                         G A X P A R

The routine  GAXPAR  calculates parameters  for  GRAF from a 
minimum and maximum of data values.

The call is:  CALL GAXPAR (V1,V2,COPT,CAX,A,B,OR,STEP,NDIG)
                                               level 1, 2, 3

V1, V2        are the lower and upper limits of the axis. If
              V1 > V2, the calculated parameters  will be in
              descending order.
COPT          is a character string that can have the values
              'NOEXTEND' and 'EXTEND'.  For COPT = 'EXTEND',
              the calculated  axis  limits are extended to a
              full axis step.  Otherwise, V1 and V2 are used
              as axis limits.
CAX           is a character string that defines the axis. 
              CAX can have the values 'X', 'Y', and 'Z'.
A, B          are the calculated limits of the axis.
OR, STP       are the first axis label  and the step between
              labels.
NDIG          is the  calculated number of digits  after the
              decimal point that should be set with the rou-
              tine LABDIG for the labels.
    
Notes:      - The  same  algorithm as in  SETSCL for setting 
              automatic axis scaling is applied to GAXPAR.  
            - The  current  axis  settings such as linear or
              logarithmic scaling  are used by  GAXPAR.  For 
              logarithmic scaling,  the parameters V1 and V2
              must be exponents of base 10.

