Suggested Updates to psTimeTable

[calvin.harman@…]

I'd like to change the psTimeTable struct and supporting functions to make them
more generic. The new name prefix would be just "psTable". I'd also like to
remove all the psVector members from the psTimeTable struct and replace them
with a single psImage member. With a single psImage, the number of columns
would no longer be fixed and tables with multiple dependencies could be
created.

Note also the following:

• I'm not sure how useful it will be to pass the validFrom and validTo

arguments into the psTimeTableAlloc() function. I think that most would rather
have these set automatically when the table is read in base on the first and
last entries. If the user does need to set these, then he could do it by simple
member assignment, providing we remove the const. The SDRS might also be
updated to define what happens when a user loads a table but uses a valid range
less than or greater than that of the table.

• Provided there is interest in creating a generic psTable, the current

interpolate function argument list should be changed: There would be only one
interpolation result, rather than 3 as currently designed (the user would have
to call the function two more times to get everything). The desired column to
be interpolated would also need to be passed. The return should also be changed
to an int to indicate if the interpolation was successful in terms being off
the the table (in which direction) or a generic failure.

[Paul Price]

I like the idea of generalising the psTimeTable.

Since the values in the table may have different types (e.g., one may be an
integer, another a float), an array of vectors would be more suitable than an image:

typedef struct {

psVector *index; Index values
psArray *values; Corresponding values: an array of vectors

} psLookupTable;

And APIs:

Return a particular value given an index and column
psF64 psLookupTableInterpolate(psLookupTable *table, psF64 index, int column);
Return values in all columns given an index
psVector *psLookupTableInterpolateAll(psLookupTable *table, psF64 index);

The latter saves on the extra math of doing several calls to get multiple columns.

I'll look up the valid{From,To} stuff and get back to you.

[Paul Price]

Added a section on psLookupTable to the SDRS (below). Changed the psTimeTable
section to use psLookupTables, removing psTimeTableInterpolate which is now
redundant. The validFrom and validTo are kept in the psTimeTable, since they
are required.

\subsection{Lookup Tables}

Lookup tables store a variety of values indexed on a certain column.
An example is for storing the difference between UT1 and UTC, and the
polar motion vector as a function of date.

\begin{verbatim}
typedef struct {

psVector *index; /< Index values
psArray *values; /< Corresponding values: an array of

vectors
} psLookupTable;
\end{verbatim}

\code{index} shall contain the index values, which shall be sorted in
increasing order. The \code{values} shall consist of an array of
vectors, each of the same length as the \code{index} vector. The
vectors (including the \code{index} and all vectors in the
\code{values} array) may be any numerical type except complex types.

The constructor shall be:
\begin{verbatim}
psLookupTable *psLookupTableAlloc(int numValues);
\end{verbatim}
Here the \code{numValues} indicates the number of vectors in the
\code{values} array.

The destructor shall also free the components.

\begin{verbatim}
psLookupTable *psLookupTableRead(const char *filename, int numValues);
\end{verbatim}
\code{psLookupTableRead} shall read the file specified by
\code{filename} and import the data into a \code{psLookupTable}. The
file shall be plain text, with index and values on separate lines,
separated by whitespace. Lines commencing with a comment character
(the pound sign, \code{#}) shall be ignored. \code{numValues} in
addition to the index shall be read on each line. If the \code{index}
vector is not sorted in the file, the lookup table shall be sorted
prior to the function returning, but no sort shall be performed if the
indices were sorted in the file.

Interpolation on a lookup table is performed by the following
functions:
\begin{verbatim}
psF64 psLookupTableInterpolate(psLookupTable *table, psF64 index, int column);
psVector *psLookupTableInterpolateAll(psLookupTable *table, psF64 index);
\end{verbatim}
Both functions shall interpolate the \code{table} at the provided
\code{index}. For \code{psLookupTableInterpolate}, only the value in
the specified \code{column} shall be calculated and returned. For
\code{psLookupTableInterpolateAll}, all the values shall be calculated
and returned as a \code{psVector}, the type of which shall be
\code{PS_TYPE_F64}. If the \code{index} is beyond the range of the
\code{table}, \code{psLookupTableInterpolate} shall return \code{NaN},
and \code{psLookupTableInterpolateAll} shall return \code{NULL} ---
that is, no attempt is made at extrapolation.

[... on to psTimeTable...]

We define a structure, \code{psTimeTable} to hold a single time table:
\begin{verbatim}
typedef struct {

const char *filename; Filename of time table
const psF64 validFrom, validTo; MJDs of validity of time table
psLookupTable *table; Lookup table indexed on MJD, with UT1-UTC,

xp and yp
} psTimeTable;
\end{verbatim}

[calvin.harman@…]

I'm not sure we still need a psTimeTable struct. As it is, this struct has
items that would be useful to other types of tables (file name and limits). I'd
like to just move everything to the psLookupTable struct if possible.

The psLookupTableAlloc(int numValues) function only specifies the number of
columns (numValues). What about the number of rows? Perhaps numRows and numCols
should both should be passed as allocator arguments and also added as members
of the psLookupTable struct?

[eugene]

paul: please come to a conclusion on this one.

[Paul Price]

OK, moving the psTimeTable into psLookupTable. Pity... I liked the name
"psTimeTable".... (;
psTimeTable has disappeared, and the definition of psLookupTable now reads:

Lookup tables store a variety of values indexed on a certain column.
An example is for storing the difference between UT1 and UTC, and the
polar motion vector as a function of date.

\begin{verbatim}
typedef struct {

psVector *index; /< Index values
psArray *values; /< Corresponding values: an array of

vectors

const char *filename; /< File from which table was read
const psF64 validFrom, validTo; /< Range of validity

} psLookupTable;
\end{verbatim}

\code{index} shall contain the index values, which shall be sorted in
increasing order. The \code{values} shall consist of an array of
vectors, each of the same length as the \code{index} vector. The
vectors (including the \code{index} and all vectors in the
\code{values} array) may be any numerical type except complex types.
The \code{filename} shall specify the file from which the table is to
be read. The \code{validFrom} and \code{validTo} shall specify the
range of valid values for the index; in most cases, these will simply
be the first and last indices.

The constructor shall be:
\begin{verbatim}
psLookupTable *psLookupTableAlloc(const char *filename, int numValues);
\end{verbatim}
Here the \const{filename} indicates the file from which the table
shall be read when \code{psLookupTableRead} is
called. \code{numValues} indicates the number of vectors in the
\code{values} array.

The destructor shall also free the components.

\begin{verbatim}
int psLookupTableRead(psLookupTable *table);
\end{verbatim}
\code{psLookupTableRead} shall read the \code{table} from the
appropriate file and import the data into the \code{table}.
Sufficient memory shall be allocated to hold all the data in the
specified file. The file shall be plain text, with index and values
on separate lines, separated by whitespace. Lines commencing with a
comment character (the pound sign, \code{#}) and blank lines shall be
ignored. \code{table->values->n} in addition to the index shall be
read on each line. If the \code{index} vector is not sorted in the
file, the lookup table shall be sorted prior to the function
returning, but no sort shall be performed if the indices were sorted
in the file. It shall be an error to call \code{psLookupTableRead} on
a \code{table} that has already been read. The function shall return
the number of lines read (not including ignored lines).

Interpolation on a lookup table is performed by the following
functions:
\begin{verbatim}
psF64 psLookupTableInterpolate(psLookupTable *table, psF64 index, int column);
psVector *psLookupTableInterpolateAll(psLookupTable *table, psF64 index);
\end{verbatim}
Both functions shall interpolate the \code{table} at the provided
\code{index}. For \code{psLookupTableInterpolate}, only the value in
the specified \code{column} shall be calculated and returned. For
\code{psLookupTableInterpolateAll}, all the values shall be calculated
and returned as a \code{psVector}, the type of which shall be
\code{PS_TYPE_F64}. If the \code{index} is beyond the range of the
\code{table}, \code{psLookupTableInterpolate} shall return \code{NaN},
and \code{psLookupTableInterpolateAll} shall return \code{NULL} ---
that is, no attempt is made at extrapolation.

[Paul Price]

Closing subsequent to release of SDRS-08, ADD-07.