AUTOPLOT

---- Autoplot Help ----

GENERAL INFORMATION

AUTOPLOT is an interactive-graphics computer program which produces labelled plots of numerical data in the form of graphs showing the variation of one or more variables against another variable.

The interactive capability of AUTOPLOT permits adjustment of the scaling, position and annotation of the plots for maximum clarity and impact.

Although designed to be especially convenient for PHOENICS users, AUTOPLOT can be used to plot any appropriately formatted data.

The following notes explain how it is used.

Notes on how to use AUTOPLOT

Contents

1. About autoplot
2. Data files accessed by autoplot
3. Starting the run
4. Data elements
5. Creating and scaling the plot
6. Data manipulation
7. Picture management
8. Additional facilities
9. Increasing the array size
10. Tutorials
11. File formats

1. ABOUT AUTOPLOT

• AUTOPLOT is the second graphics program of the PHOENICS suite, the first being PHOTON . It is an interactive program, but has a batch facility which allows commands to be read from a file.
• AUTOPLOT provides X-Y graphs, made up of straight line segments joining the data points.
• The data can be manipulated in a number of ways during plotting, specifically by:
  • adding or subtracting a constant
  • multiplying or dividing by a constant
  • raising to a power
  • taking base 10 or natural logarithms
  • constructing new data elements can be constructed by operating on existing elements.
• AUTOPLOT can access data from PHOENICS PHIDA and XYZDA files, and also from user-created files. It can plot data from many files simultaneously, allowing easy comparison of PHOENICS results with experimental or analytical results.

2. DATA FILES ACCESSED BY AUTOPLOT

• AUTOPLOT can access data from PHOENICS PHIDA (or PHI) files, to create graphs of phi vs. distance, where phi is any of the STOREd or SOLVEd variables, and distance is measured along one of the cartesian coordinates. In BFC cases, AUTOPLOT will read the BFC grid file, XYZDA, to obtain the corner coordinates.
• AUTOPLOT can plot BFC grid files directly, to give 2D or 3D views of the grid. However, although PHOTON is much more sophisticated in many respects, AUTOPLOT provides the only way to:
  • Draw grids with calibrated axes.
  • Directly compare two or more grids.
• AUTOPLOT can also read data from files in 'plot' or 'table' format. These are both free format ascii files, which can be created by the user in any convenient way. The formats of these files are given in section 11 below. The convergence-monitoring tables in the RESULT file are in 'table' format, and can be read by AUTOPLOT if they are first written to disc file with an editor.

3. STARTING THE RUN

• AUTOPLOT is started at the system command prompt by typing RUNAUT. The next move is to type: file , followed by the name of the file and its type number. The available numbers are:
  1. PLOT FILE
  2. TABLE FILE
  3. PHIDA
  4. XYZDA
  5. PHI
  6. XYZ
  7. DF09
  8. DF12

  If the user does not specify the type number after each file name, the type of the previous file will be used.

• At this point, as many files as required can be attached. They can be in any order and any combination of types.
• Help:
  • General help is available at the command level by typing a question mark (?).
  • Help on a particular command can be obtained by typing command ?. The command REDRAW will refresh the screen after the help message.

4. DATA ELEMENTS

• AUTOPLOT pictures are made up of 'data elements'. Each data element consists of a set of x-y data points, making up a particular curve.
• Usually, several data elements are combined to make the final picture. The data can come from any of the supported file types. Once a data element has been created, it is treated identically, wherever it came from.
• Once created, data elements can be switched on or off, using the ELEMENT ON/OFF command.
• The command used to create new data elements is:
  DATA
  where
  is the sequence number of the file to be read
  specify the actual data to be read. This field
  changes according to the file type.

Data are introduced into the program by means of the 'DATA n' command, where 'n'denotes the number of the file containing the data.

This can then be displayed on the screen by using the 'PLOT', 'DOTn', 'BLBn' or 'COLh' commands, which will cause the line to be drawn

• solid,
• dashed,
• 'symboled' or
• coloured.

Subsequent 'DATA' commands may introduce points which lie outside the current range; then the 'SCALE' command can be used to re-scale both axes to encompass the new data. It may thus be better to enter several 'DATA' commands before plotting, as fewer redraws will be required.

The plot can be labelled using the 'TEXT' and 'KEY' commands.

At any time, a clean picture can be recovered by the 'REDRAW' command.

The finished plot can be stored to a PHOTON-format 'save' file by the 'SAVE' command.

Data elements can be cleared away for the next plot by means of the 'CLEAR' command.

At any point, entering '/' will return control to the 'Command?' level. Many commands can be entered on one line, by use ';' as a delimiter.

More detailed help may be obtained on : DATA, PLOT, DOT, BLB, COLOUR, SCALE, TEXT, KEY, CLEAR

5. CREATING THE PLOT

• Once several data elements have been created, they can be plotted using solid lines with the command PLOT where is the first element to be plotted is the last element to be plotted.
• If are omitted, all data elements in memory but not on the screen will be drawn using solid lines.
• If parts of the data lie outside the plotting 'window', the window can be rescaled with the SCALE command. This will scale the axes to fit all data in memory.
• The SCALE X and SCALE Y commands allow the user to specify the minimum and maximum values on the X and Y axes.
• The SCALE ELEMENT will force the axes to fit the data in data elements to .

6. DATA MANIPULATION

• AUTOPLOT provides several commands which allow the user to manipulate the data, once it is in memory.
• SHIFT X and SHIFT Y allow the user to add a (positive or negative) constant to the X or Y coordinate of a range of data elements.
• MULTIPLY X, MULTIPLY Y, DIVIDE X and DIVIDE Y allow the user to multiply or divide the X or Y coordinates of a range of data elements by a constant.
• POWER X and POWER Y raise the X or Y coordinates of a range of elements to a power.
• ELEMENT ADD, ELEMENT SUBTRACT, ELEMENT MULTIPLY and ELEMENT DIVIDE allow the user to create new data elements, by performing the stated operations on the X or Y coordinates of existing data elements.
• LOG X, LOG Y, LN X and LN Y act as toggles to change the X or Y axes to base 10 or natural logarithms. All data elements in memory are transformed, as are all subsequently created elements. The reverse transforms are performed by ALOG X/Y and ALN X/Y.

NOTE:

All AUTOPLOT commands can be abbreviated as much as possible whilst still maintaining uniqueness. Thus, for example:

ELEMENT ADD Y can be shortened to EL A Y

7. PICTURE MANAGEMENT

• This section lists a number of commands used to modify the appearance of the picture on the screen.
• REDRAW causes the screen to be redrawn. Any data elements which have been switched off will not be redrawn.
• CLEAR deletes all data elements and clears the screen.
• DOT and BLB act in the same way as PLOT, but use different line styles or symbols to join or denote the data points.
  • DOT1, DOT2, DOT3, DOT4 and DOT5 denote different dashed lines.
  • BLB1, BLB2, BLB3, BLB4 and BLB5 use various symbols to mark the actual data points, which are not joined.
• COLOUR is used to draw data elements in one of the available colours. If the data element is not on the screen yet, it will be drawn with a solid line in the specified colour, otherwise it will be redrawn with the current line/symbol style.
• TEXT allows the user to annotate the plot, using different character sizes and colours.
• KEY allows the user to draw line sections in any of the line or symbol styles. It also allows the creation of filled polygons.
• GROUP MAKE allows the user to create groupings of TEXT and KEY items. These can then be moved about the screen with a single cursor location using GROUP MOVE.
• LEVEL X and LEVEL Y draws lines parallel to the X or Y coordinates at the specified locations.
• TEXT, KEYs and LEVELs are normally deleted on CLEAR. This can be unwanted if a complicated annotation has been created. TEXT/KEY/LEVEL KEEP will prevent these items from being cleared until explicit TEXT/KEY/LEVEL CLEAR commands are issued.
• AXES, FRAME and TICK control the appearance of the axes.
• GRID and GRID DEFINE draw dashed grid lines at the axis tick marks, or at user specified intervals.
• MAGNIFY can be used to expand selected regions of the plot.

8. ADDITIONAL FACILITIES

• Program status The command SHOW will give information on the program status:
  • SHOW n will give information on file n
  • SHOW FILES will list currently attached files
  • SHOW TEXT/KEYS will list current TEXT and KEY items
  • SHOW ELEMENTS will list current data elements
• Equally scaled axes
  • The command EQUAL will force equally scaled axes. UNEQUAL reverts to normal scaling. For XYZ files, EQUAL is the default.
• Changing data files
  • FILE allows the user to change all currently attached data files. It has the same effect as starting the session afresh.
  • FILE ADD allows the user to attach more data files
  • FILE REPLACE n allows the user to replace the n'th data file with another one.
• Use of batch files
  • Sequences of commands normally typed interactively can be read from a file. The command USE causes commands to be read from the file .
• Saving pictures
  • The SAVE command will cause the current picture to be saved to a file. The format of the command is; SAVE [title]
  • If is omitted, the picture is appended to the current file as the next frame.
  • The option title will cause AUTOPLOT to prompt for a title for the picture.
• Replaying saved pictures
  • SAVEd pictures can be redrawn by using the REPLAY command in PHOTON. AUTOPLOT does not have a REPLAY facility of its own.

Hard copies

• The command SENDP will redraw the current picture to a plotting device, or into a file to be sent to a plotting device, if any such devices are available.
• The command DUMP will activate a screen dump to a local printer, if this is supported by the device driver.

9. INCREASING THE ARRAY SIZE

• The data points are held consecutively in a single storage array. If very large data sets are created, there may be insufficient space in this array to store all the data.

  If this situation arises, AUTOPLOT issues a warning message, and advises how large the array should be. The user can obtain a copy of the AUTOPLOT main program from d-phoe20/d_autopl. He can then change the parameter setting as advised, compile the Fortran file autplt.f, and finally rebuild AUTOPLOT by issuing the command: bldaut .This creates a new executable called autexe.exe. Use of the PHOENICS Commander environment program makes them especially easy to perform.

• There is a limit of 40 to the number of files attached at one time, and also of 40 data elements in memory at one time. These limits cannot be changed. The number of data points within a data element is limited only by the size of the main storage array, which can be expanded as outlined above.

10. TUTORIALS

AUTOPLOT for PHOENICS-2 is supplied with on-line tutorials. All that is necessary in order to activate these is to run AUTOPLOT and to type the word: tutorial

Appropriate instructions will then appear on the screen.

These tutorials make unconventional use of the command-file method of running autplot.

11. FILE FORMATS

PLOT-format data files

Any number of data elements may be contained in one file. Suppose that a file contains N data elements, so that there are N dependent variables y1.....yN to be plotted against the independent variable x (say).

The layout for each number within a line is free-format.

The layout of the file is as follows:

Line number Contents

    1                              the integer N
    2                              title for y1
    3                              title for y2
    ...                            ...
    N+1                            title for yN
    (N+1)+1                        x1 first value of x
    (N+1)+2                        value of y1 at x1
    ...                            ...
    2*(N+1)                        value of yN at x1
    ...                            ...
    2*(N+1)+1                      x2 second value of x
    2*(N+1)+2                      value of y1 at x2

3*(N+1) value of yN at x2 ... ...

The titles in lines 2 to (N+1) may each contain up to 16 characters; their purpose is solely to identify individual elements when they are plotted. Embedded blank lines are not allowed.

TABLE-format files

These are also formatted indexed files, which contain columns of data. For example, the convergence-monitoring tables to be found in the PHOENICS RESULT file can be cut out and used as AUTOPLOT TABLE files.

Each TABLE file may contain up to 20 columns, and may be as long as required. The first line of the file should contain a heading for each column, up to 6 characters long. The subsequent lines will contain the values for each column in free format. Null entries in a particular column are allowed, and must be denoted by the character 'X'. Embedded blank lines are ignored.

PHI, PHIDA, XYZ, XYZDA, DF09 and DF12 files

The following files are produced by the PHOENICS program: PHI, PHIDA, XYZ and XYZDA by Versions 1.4 and above; DF09 and DF12 by Version 1.3.

In PHOENICS 1.4 and above, the choice between PHI & PHIDA and XYZ and XYZDA is controlled by the parameters PHIDA=T or F and XYZDA=T or F in the PREFIX file.

AUTOPLOT permits plotting of PHI and PHIDA files simultaneously. If any of the cases involve Body-Fitted-Coordinate grids (BFC=T), the name of the grid file will be requested. However, there is one limitation the restart file and grid file must be either both sequential-formatted (PHI/XYZ), or both direct-access (PHIDA/XYZDA). Mismatched pairs, eg (PHI/XYZDA) or (PHIDA/XYZ), are not allowed.

wbs