TMAP'S GRID FILE LAYOUT The grid file is used to describe axes and grids to programs that use TMAP library of routines (e.g. FERRET). It can describe all manner of axes from regular to irregular; modulo and non-modulo; spatial and time; and grids that use these axes. This document will describe how to build a grid file that will correctly describe the grid arrangement you desire. The grid file has four (4) parts to it. Not all are required in any one grid file. We will go through each of the parts and describe them with examples, and talk about some of the inter-relationships. First, let's cover some important things about the grid files in general. The files are "FREE" format. This means on any one line (except for COORDS definition - see below) any of the items in a definition can be located anywhere on that line, as long as they are in the correct order, do not extend past one line, and are not longer than 132 characters. This allows you to "pretty up" the file anyway you like. LINE definitions have to come before any GRID, TIME, or COORDS definitions that reference them. GRID, TIME, and COORDS definitions can come in any order. The usual order for a grid file is LINE, GRID, TIME, COORDS. It is a good idea to leave the explanatory documentation in a grid file in there when you copy it (the section enclosed in *'s). These will be useful for quick reference should you ever forget what components belong in each definition. Lastly, before starting with a part by part break-down, all lines that begin with a * are considered comments (do not embed comments in COORDS definitions!). I. LINE - defining axes This part of the grid file is used to define an axis or axes. Here is an example: ******************************************************************************** * Line definitions first: name, number of points, ordering, and defined by * start,delta or coordinate values (given below) "ordering" may be "WE" * (longitude), "SN"(latitude), "UD"(depth), "TI"(time) or "NA"(non-standard * values) ******************************************************************************** LINE XAXIS 10 WE LONGITUDE START,DELTA: 250. 1. LINE YAXIS 5 SN LATITUDE GIVEN_BELOW: LINE ZAXIS 11 UD METERS GIVEN_BELOW: LINE TAXIS 120 TI HOURS START,DELTA: 17592. 73. MODULO First comes "LINE" that identifies this line as an axis definition, then comes the unique line name (e.g. XAXIS). The number of points in the axis is next, followed by the line orientation (e.g. WE="west to east"; SN="south to north"; UD="up to down, or depth - increasing downwards"; TI="forward time"). After this comes the units of the axis, LATITUDE, METERS, HOURS... The next component tells how the axis is defined. There are two (2) choices: regular axis are defined by "START,DELTA:" followed by the starting point in user units, and the distance between two points on the axis in user units; and "GIVEN_BELOW:" which indicates that the axis points are irregularly spaced and will be explicitly defined in a COORDS definition (defined below). The starting point and delta should be real numbers. The last item is optional. It is the MODULO flag, which indicates whether an axis is modulo (i.e. one which wraps around on itself, as in LONGITUDE defined around the globe). If the line is not modulo, this parameter is omitted. If an irregular axis (GIVEN_BELOW:) is MODULO, 2 "dummy" parameters need to be put between the "GIVEN_BELOW:" and the "MODULO". For example: GIVEN_BELOW: x x MODULO. The x's will be ignored. II. GRID - defining grids from axes. This part of the grid file is where grids are defined from >pre-existing This is an important point. If an axis name is not defined within a grid file and it is used in a grid definition it must have been already defined. There are 2 ways an axis could be already defined: i) it could be pre-defined by the application you are running (e.g. "FERRET"); or ii) by a separate grid file that has already been processed. Otherwise the program will generate an error. Here is an example of grid definitions: ******************************************************************************** * Next comes grid definitions: gridname and rotation, followed by lines they * contain (along with inner/outer product flag) ******************************************************************************** GRID G1 0.0 XAXIS OUTER YAXIS OUTER NORMAL OUTER UNKNOWN OUTER GRID G2 0.0 XAXIS OUTER YAXIS OUTER ZAXIS OUTER UNKNOWN OUTER GRID G3 0.0 XAXIS OUTER YAXIS OUTER ZAXIS OUTER TAXIS OUTER First comes "GRID" to indicate that this line is a grid definition, then the unique name for the grid you are going to define. Next is the grid rotation in the xy plane, a real number indicating the number of degrees the grid is rotated from a normal world-coordinate system (e.g. Latitude, Longitude on earth). Rotation is not currently supported, and should be 0.0. Next comes the four (4) axes used to define the grid paired with the type of "product" they are in relation to the other axes. These are in order x-axis, y-axis, z-axis, t-axis. Product can be either INNER or OUTER. OUTER products define a regular grid, where points can be located at any combination of valid points along the defined axis, independent of location on the other axes. INNER products are grids defined by ordered pairs/triplets/quadruplets. In effect they are discrete points located in time-space. Therefor, OUTER products define a regular, rectangular region in space-time, a cube for example, while INNER products define a scatter of points in a "fuzzy" but definable region (INNER are products are not currently supported as of 6/90). In our example above, three (3) grids are defined: a x-y grid with a NORMAL Z-axis, and time left to be determined by the data set descriptor (see documentation on descriptors); a x-y-z grid also with an UNKNOWN time axis; and a fully defined x-y-z-t grid. III. TIME - giving a time axis an initial date The TIME axis is the simplest of the four parts. It's only function is to locate the starting point of a time axis in "World" coordinates. Time axis are identified in two ways: time step values - which are defined in the LINE section, in our above example that is starting with 17592 with 73 unit increments; and "calender" time, for example 12-DEC-1989-10:35:15. Here is an example: ******************************************************************************** * Next time line definitions: timeaxis linename, followed by t0 ******************************************************************************** TIME TAXIS 14-JAN-1980:14:00:00 As you can see the only things in this definition are "TIME", the name of the time axis being defined, and the date for timestep 0. Notice this is not necessarily the first time step you defined in the LINE section. In our example the first time step is 17592, however the date given here is for time step 0. This is an important point. The t0 date must be in the above format. That is 2 digits for day (0 filled - e.g. 04), "-", a 3 character month, "-", a four digit year, ":", 2 digits for hour (0 filled), ":", 2 digits for minute (0 filled), ":", and 2 digits for second (again, 0 filled). IV. COORDS - defining locations on an irregular axis This is where the coordinates for irregular lines are explicitly defined. This is the most complicated part of a grid file, and requires extra care in preparation. It has two parts: the first is the COORDS definition line which describes the format of the irregular axis and the starting point of the first box; the second part is pairs of coordinates and box sizes. Some explanation of how an axis is set up is required here. When you define a regular axis ("START,DELTA:" in the LINE section) you are actually describing grid point locations and a box containing each grid point. Because the line is regular these boxes are all the same size and are symmetrical around the grid point. A picture will illustrate this: | x | x | x | x | x | x | x | Here the x's designate grid points you have defined on a regular axis and the |'s are the implicitly defined borders of boxes containing the grid points. This works great for regular axes, but in irregular axes there is not enough information given by just the locations of the grid points to determine where the box boundaries go. Again, a picture will help clarify this: | x | x | x | x | x | x |x|x| x | x | x | x | x | x | As you can see the boxes are all different size and the end boxes are not symmetrical around the grid points. This is a very simple irregular axis and for more complex cases it might be the rule rather than the exception that the grid boxes are not symmetrical around the grid points. Therefor, an irregular axis is defined with three (3) pieces of information. The locations of the grid points, the location of the starting point of the first grid box, and the size of each box. here is an example of a COORDS section: ******************************************************************************** * Lastly, coordinate/box size pairs for those lines not specified by * start,delta: line name followed by format for coordinates followed by start * location of first grid box ******************************************************************************** COORDS YAXIS (5(F8.0,F6.0)) -9.50 -7.90 3. -5.00 3. -2.00 3.5 2.00 3.5 5.00 3. COORDS ZAXIS (7(F5.0,F4.0)) 0.00 0.00 10. 20.00 20. 40.00 20. 60.00 20. 80.00 20. 100.00 20. 120.00 20. 140.00 30. 180.00 80. 300.00 90. 500.00 95. Only the YAXIS definition will be explained, since the ZAXIS definition is no different in concepts, just in detail. First comes the COORDS line which contains "COORDS", the name of the irregular axis to be defined, the format for the data (explained below), and the location of the first grid box (in the same units as the locations of the grid points). The lines below that (up to the next COORDS definition) are the lines containing the grid point locations matched one-to-one with the size of the grid box the grid point is located in. The format can be constructed in a number of ways. The only rules concerning it are that it must be enclosed in parenthesis, it should describe the data on one line only, and every line, except the last need to contain the same number of data pairs. The last line can contain either the same or less number of data pairs. The recommended way is to follow the form (n(Fq.0,Fr.0)) where n is the number of pairs per line, q is the number of spaces the grid point location is defined in, and r is the number of spaces the box size is defined in. In the YAXIS definition this is 5 pairs per line, there are 8 spaces reserved for the grid point location, and there are 6 points reserved for the box size. The full layout of the YAXIS line is: Grid Point Location Box size Box Start Location -7.90 3.0 - 9.50 -5.00 3.0 - 6.50 -2.00 3.5 - 3.50 2.00 3.5 0.00 5.00 3.0 3.50 With the last box ending at 6.50.