CCL Home Page
Up Directory CCL STF_File_Reader
STF File Reader
Eric Pepke, Tzong-Yow Hwu
September 22, 1992

Summary: Description of file format read by STF file reader

1.0  Introduction

This document describes the STF format as used in SciAn versions 0.64 or 
later.

The STF (Simple Text File) provides a file format to store a variety of
datasets defined over structured grids.  Someday it will be able to do
nonstructured grids as well.

An STF file is a text file containing statements separated by newlines.
Each statement begins with a single word token at the beginning of the
line which gives the purpose of the statement.  The statement may have
arguments, which appear after the statement token.  For most statements,
all the arguments must appear on the same line as the statement.
Exceptions are noted later.  Normally, all of the statements in a single
file put= together a single dataset or timestep of a dataset.  However,
you can use the END statement to separate several datasets or timesteps
within a single file.

Any line that begins with a hash mark (#) is assumed to be a comment and
is ignored.  Currently, lines CANNOT be extended using the backslash (\).

The STF file stores scalar or vector data defined over regular or
curvilinear grids.  Data may be time-dependent or eternal.  There may
be missing data.

STF files should have a file extension of .stf to be recognized by SciAn.

2.0  Some background concepts

In order to understand how the STF reader works, it is important to
understand some background concepts about grids and datasets.  Most of
this information is described in the SciAn user manual, but it is
summarized here.

The kind of datasets that STF can read are made up of data defined over
grids.  The grid gives the location of the data points and connectivity
between them.

For the purposes of STF, there are two types of grids: regular and
curvilinear.  In a regular grid, all the cells are the same shape, and 
the axes of the grid are aligned with the principal axes of the 
Cartesian space.  In a curvilinear grid, each cell can be a different
shape, and the axes in a grid can bend in space any way desired.

Grids (or lattices) have two kinds of dimensions: topological and
spatial.  Some people call topological dimensions "computational"
dimensions instead.  The topological dimensionality of a grid is
given by how many numbers are needed to represent a unique point 
on the grid.  The spatial dimensionality of a grid is given by 
how many numbers are needed to represent the position of the points
in space.

In regular grids, the topological dimensionality is always the same 
as the spatial dimensionality.  In curvilinear grids, it need not be.
For example, a grid over a flat sheet of rubber which locates points
on the surface of the paper has two topological dimensions and two
spatial dimensions.  However, if you wrapped that sheet of rubber 
around a sphere to locate points on the surface of the sphere, you
would have a grid still with two topological dimensions but three
spatial dimensions.

The data defined over the grid can be scalar or vector.  For scalar
datasets, there is just a single real number at each grid point.
(E.g., temperature over an area of terrain)  For scalar datasets, 
there are several numbers at each grid point.  (E.g., wind velocity
within a cell of air)  Individual data points can be missing.

3.0  Writing an STF file

Because I need to get this out as fast as possible, I'll write this
section later.  It should be possible to figure out how to write an
STF file just from the reference section.  Basically, you just write
to the file all the statements you need.

4.0  Reference

Here is a list of all the statements in the STF file format:

RANK 
    This gives the rank or topological dimensionality of the grid.
     should be a single real number.  For example, a two-dimensional
    grid should have RANK 2.

DIMENSIONS   ...
    This gives the dimensions of the grid.  There should be as many
    dimensions as the number given by RANK.  For example, a 20 by 50
    grid should have DIMENSIONS 20 50.

BOUNDS     ...
    This gives the bounds, or the extent within the Cartesian space,
    of the grid.  This can also be thought of as the smallest box with
    the same spatial dimension of the grid that can fit around the grid.
    There must be as many pairs as the spatial dimensionality of the grid.
    If GRID (described later) is specified, this is the number of components
    of the grid.  Also, if GRID is specified, the BOUNDS may be omitted, in
    which case they will be calculated automatically.  If GRID is not
    specified, this is assumed to be the same as RANK and a regular grid is
    constructed from BOUNDS, DIMENSIONS, and RANK. 

NAME 
    This gives the name of the dataset.  If it is not present, the name of
    the file is used.

SCALAR
    This specifies that the DATA to follow is scalar data.  See VECTOR.

VECTOR 
    This specifies that the DATA to follow is vector data, with a number of
    components given by the real number .  VECTOR is also used
    before a GRID to specify the number of components, and thus the number
    of spatial dimensions in the grid.

ORDER COLUMN
ORDER ROW
    These specify column- or row-major ordering for data in subsequent 
    DATA or GRID statements.  The default is column-major ordering.

INTERLACED
NONINTERLACED
    These specify whether subsequent vector data in a DATA or VECTOR statement
    is interlaced or not.  In non-interlaced data, all the first components
    in the dataset appear, then all the second components, and so on.  In 
    interlaced data, all components for the first grid point appear, then
    all components for the second, and so on.

TIME 
Modified: Sun Nov 17 17:00:00 1996 GMT
Page accessed 7222 times since Sat Apr 17 21:29:08 1999 GMT