Plot_3D_File_Reader
Hwu, Tzong-Yow
April 8, 1992

Summary: Description of Plot-3D file reader

Beginning with version 0.7 of SciAn, there is a partial implementation of
a reader for Plot-3D format files.  A more complete implementation is 
under development.

A set of plot 3d files is composed of a meta file and several data files, which 
must include at least one grid XYZ file and one solution Q file or FUNCTION 
file.  

The meta file is an ASCII text file used to specify to the file reader the 
format of the data files. The data files contain data for visulization.  
The file reader is capable of reading files stored in
ASCII text format (FORTRAN list-directed format), fortran unformatted
file and binary format.

The meta file contains one or more Plot 3D READ commands.  A Plot 3D READ
command is of the syntax:  READ/qualifier1/qualifier2....where the qualifier
may be one or more of the following:

/1D
/2D
/3D (default)
   specification of the dimensionality of the data set

/XYZ=filename
   specification of the abolute path name of the XYZ file, the filename
   must be enclosed in double quotes

/Q=filename
   specification of the abolute path name of the Q file, the filename
   must be enclosed in double quotes

/FUNCTION=filename
   specification of the abolute path name of the FUNCTION file, the filename
   must be enclosed in double quotes

/MDATASET (defaut is a single dataset)
   specification of multiple datasets in one file (for time-varying datasets)
   This option is mainly designed for supporting time-varying solutions.

/MGRID (default is a single grid)
   specification of multiple grid datasets in one file

/FORMATTED
/UNFORMATTED      
/BINARY (default)
   specification of the file format

/PLANES
/WHOLE (default)
   specification of the data arrangement format in the data file

/CHECK (default)
/NOCHECK
   specification of whether checking of Q data for zero or negative density
   or pressure is to be performed

/JACOBIAN (not implemented)
/NOJACOBIAN (default)
   specification of whether Q varialbes are scaled by the determinant of the
   metric Jacobian

/BLANK
/NOBLANK (default)
   specification of whether the XYZ file contains an integer array IBLANK as
   a fourth variable.  The data with a 0 IBLANK value is treated as missing
   in SciAn.

The main purpose of qualifiers is to specify the path of data files, data 
format and operations to be done on the data.  To avoid ambiquity, qualifiers 
describing a file must precede the qualifier that specifies the file path name.
At most one of the qualifier in its group may be used for any data file.  
If certain qualifier is not specified for a file, then it inherits the
attributes of the previous file.  If this happens to the first file, then
the default is assumed.

It is illegal to specify inconsistent qualifiers for a Q or FUNCTION file and 
its corresponding XYZ file.  For example, if a Q file is described as 3D
then it is an error to have its corresponding XYZ file qualified as 1D or 2D.
It is suggested that all the Q or FUNCTION files using the same XYZ
file as grid be placed in the same READ command and the qualifiers common to 
the data files be placed only once at the beginning of the READ command.

A READ command must consist of at least one complete specification of a dataset
for visualization.  A complete specification of a dataset contains at least one 
XYZ file and one Q or FUNCTION file.  An XYZ file may be used for more than
one Q or FUNCTION files in a single READ command, in which case the XYZ file
is used as the grid for the Q and FUNCTION datasets.  A READ command may also
contain specification of more than one XYZ files.  All the Q and FUNCTION
files preceding the second XYZ file are considered using the grid speficied by
the first XYZ file and the XYZ files thereafter are used as grids for the Q
and FUNCTION files before the next specification of XYZ file.  It is illegal
to specify a XYZ file without supplying any Q or FUNCTION file for it.

If a READ command is to be separated into two or more lines, a hyphen '-'
must follow the end of the previous line to indicate the continuation of the
command at the next line.

The reader is case-insensitive and recongnize abbreviations for each
qualifier.

The default extension name of p3d meta file in SciAn is .p3d.

Example1:

read/unformatted/mdataset/mgrid/xyz="/user/hwu/xyz.dat"/q="/user/hwu/q.dat"/-
function="/user/hwu/function.dat"

This read command specifies a Q dataset and a FUNCTION dataset with both of
them using the same XYZ grid.  For attributes not specified, defaults are
assumed, thses include:
/3D
/WHOLE
/CHECK
/NOJACOBIAN
/NOBLANK


Notes on MDATASET option:

The purpose of the MDATASET option is for supporting time-varying solutions.  
The time field in the SOLUTION file is used when this option is turned on.
All the solution time slices in a SOLUTION file will use the grid specified 
in the corresponding XYZ file coupled with the SOLUTION file.  The implication
of this is that all the time-varying solutions in a MDATASET SOLUTION file 
will share the same grid.  However, it is still pretty easy to do a time-
varying grid for time-varying solutions by storing different time dataset of 
solutions and grids in different SOLUTION files and XYZ files as shown in the 
example2.  The only requirement is that the prefix part (before the first 
period) of the name of the files of the time-varying solutions must be the 
same.  

Example2:
read/3d/formatted/MDATASET/x="/user/hwu/newxyz.1"/q="/user/hwu/newsol.1"
read/3d/formatted/MDATASET/x="/user/hwu/newxyz.2"/q="/user/hwu/newsol.2"
read/3d/formatted/MDATASET/x="/user/hwu/newxyz.3"/q="/user/hwu/newsol.3"

These read commands specify time-varying solutions with time-varying grids in
different SOLUTION and XYZ files.  Time-varying solutions sharing the same
grid may be stored in the same SOLUTION file and the grid in its corresponding
XYZ file.