FFIO Library

Description:

The FFIO library routines that determine file type return a fltype variable. The values in the parenthesis correspond to the value of fltype for that file type.

The intent of the library is as follows:

• Provide a common interface for I/O.
• Make the I/O endian-blind (can detect as well as read or write files in either endian).
• Make the I/O precision-blind (can detect as well as read or write files in single and double precision). Ascii I/O is provided for most grid and triangulation formats.

Prior to FFIO: Behavior of CGT programs using standard I/O:

• Controlled by compiler flags such as -byteswapio for pgf90 or -fconvert for gfortran (executables locked in to a particular endian setting).
• Controlled at runtime by environment variables such as F_UFMTENDIAN for ifort or GFORTRAN_CONVERT_UNIT for gfortran.

• CGT has two binary trees (single precision and double precision).
• The executable must match the precision of the file being read and can only write that precision.

FFIO-enabled CGT programs behavior:

• FFIO is intended to be backwards compatible.
• Endian: It can read either endian and completely disregards compiler related byteswapping flags and environment variables such as F_UFMTENDIAN or GFORTRAN_CONVERT_UNIT.
• Precision: It can read either single or double precision data irrespective of the precision specified for compiling the executables. Note that FFIO converts data to the precision expected by the executable, so computations will be performed in executable precision.
• File attributes: output file attributes follow the input file attributes whenever possible. When the input file attributes do not provide clear guidance on the output file attributes (e.g., input file is ASCII, output file is unformatted), or when there are no input files (e.g., boxgr), the default rules given in the tables below are used.
• If user desire does not match output attributes, please use overConvert to obtain desired attributes.

Input File Endian	Output File Endian
little	little
big	big
no input file or ASCII	machine native

Code Precision	Input File Precision	Output File Precision
single	single	single
single *	double	double
single	no input file or ASCII	single
double **	single	single
double	double	double
double	no input file or ASCII	double

* A single precision code will convert double precision data to single precision internally and perform all computations in single precision. The user should avoid this demotion of the data.

** A double precision code will convert single precision data to double precision internally and perform all computations in double precision. The data is converted back to single precision in the output file. Such conversion is considered 'safe'.

There are situations where a code is reading more than one file. For example, one can use the combinex code to append a grid in file B.dat to a grid in file A.dat. To do this, file A is read first and all attributes are set by that file. If the attributes of file B are different from file A (e.g. file A is little-endian, while file B is big-endian), then the output file follows the endian of the first file (file A). This choice was made with the idea that file A is being worked on or append to, so file A's attributes should be retained in the output.

Note that all ASCII output follows the precision of the code; except for triangulations. All triangulations are assumed to be single precision for both input and output.

Set output endian and/or precision using environment variables:

Code Precision	CGT_OUTPUT_PRECISION	Output Precision
single	SP (or SINGLE)	single
double	SP (or SINGLE)	single
single *	DP (or DOUBLE)	double
double **	DP (or DOUBLE)	double
single	EXEC	single
double	EXEC	double
single	INPUT	precision of the first file ***
double	INPUT	precision of the first file ***

*** Default behavior as described above.

Usage:

Codes converted to use FFIO:

• autoBC
• boxgr
• combinemx
• combinemq
• compx
• conmug
• curvar
• cva
• diffxq
• gen_x
• gencore
• genpipe
• grided
• gridinf
• hypgen
• lsect
• minmax
• mixsur
• movegrd
• overConvert
• overint
• p3dtrans
• parsec
• pip
• progrd
• qed
• qinfo
• reord
• seamcr
• setzeta
• smooth
• splitmx
• splitmq
• srap
• str2tri
• surflobc
• surgrd
• triged
• triloadCmd
• xrayed

Code development with FFIO:

A code developer attempting to use the FFIO library has a large amount of capability at his/her fingertips. However, such a large capabiity also means a large number of callable API routines.

Imlementation details:

For implementation details please see the FFIO.pdf file.