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