Subject: Proposed TNDIMnnn convention

From: thompson at stars.gsfc.nasa.gov (Bill Thompson)
Date: 1 Oct 91 15:38:43 GMT

"Variable Dimensions" Convention

This convention describes how columns in a binary table not only can contain
multidimensional arrays as its elements, but also how the number and size of
the dimensions can be different for each row of the table.  The convention
works by storing the dimensions of an array stored in one column (nnn) in
another array stored in a second column (mmm).  The format of this second
description array is discussed below.  The interrelationship between the data
arrays (column nnn) and the description arrays (column mmm) is indicated by the
use of the optional keyword "TNDIMnnn=mmm".  Adherence to this convention will
be indicated by the presence of the TNDIMnnn keyword.

The description array used by this convention is a 16 bit integer array with
the following format: the first element contains the number of dimensions in
the data array being described; the second element contains the size of the
most rapidly varying dimension of the data array; the third the size of the
next most rapidly varying dimension; and so forth up to the total number of
dimensions.  Any extra elements in the description array after the final
dimension parameter will be ignored, and should be padded with zeros.  The
product of the dimension sizes must be less than or equal to the size of the
data array as given by the keyword TFORMnnn.  The number of dimensions can be
zero to signal that no data is stored in the data array for that row in the
binary table.

If multiple columns in the binary table represent arrays with the same
dimensional structure, then they can all refer to the same description array.

The "Variable length array" facility could also be used with this convention.
Either the data array or description array, or both, could be defined as
variable length arrays.

As an example, suppose that both columns 3 and 4 contain a series of
multidimensional data arrays of different sizes, and that the associated array
sizes are in column 5.  The header could contain the following keywords and
values:

        TFORM3  = '100I    '            /  16 bit integers
        TNDIM3  =                    5  /  Dimensions contained in column 5
        TFORM4  = '100I'                /  16 bit integers
        TNDIM4  =                    5  /  Dimensions contained in column 5
        TFORM5  = '4I      '            /  Dims. stored as 16 bit integers

The data arrays in columns 3 and 4 could then contain up to three dimensions,
one less than the size of the array in column 5.  Valid values of the array
stored in column 5 can be represented symbolically as

        (1,100)
        (2,10,10)
        (2,20,5)
        (3,5,5,2)
        (3,4,4,4)

even though the last example adds up to only 64 points and not 100.  However,
the description array

        (3,5,5,5)

would not be valid because this requires 5 x 5 x 5 = 125 elements, which is
bigger than the 100 elements allocated to the arrays in columns 3 and 4.