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