Changeset 1767 for trunk/doc/pslib/psLibSDRS.tex

Timestamp:

Sep 9, 2004, 2:17:59 PM (22 years ago)

Author:

Paul Price

Message:

Added psTimeTable stuff.

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (3 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.118 2004-09-09 23:48:55 jhoblitt Exp $
+%%% $Id: psLibSDRS.tex,v 1.119 2004-09-10 00:17:59 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -176 +176 @@
 \item Set the error codes for PSLib.
 \item Seed the random number generator.
+\item Read the \code{psTimeTable} configuration file and set up the
+  appropriate \code{psTimeTable}s and predictions.
 \end{itemize}
 
@@ -3231 +3233 @@
 Time math is only done on the \code{psTime} TAI type.
 
+\subsubsection{Time Tables}
+
+The offset of UTC from UT1, $\Delta$UT = UT1-UTC, as well as the polar
+motion, $x_p$ and $y_p$, may be determined from table lookups.  Tables
+are available covering different time periods and with different time
+resolution, and so it is important to be able to utilise multiple
+tables.  Some tables may be found at:
+
+\begin{itemize}
+\item \code{ftp://maia.usno.navy.mil/ser7/ser7.dat}
+\item \code{ftp://maia.usno.navy.mil/ser7/finals.all} with explanatory
+  guide at \code{ftp://maia.usno.navy.mil/ser7/readme.finals} . See also
+  the web page \code{http://maia.usno.navy.mil/}.
+\item \code{http://hpiers.obspm.fr/eoppc/eop/eopc01/eopc01.1900-2004}
+  (contains estimates prior to 1972).
+\end{itemize}
+
+The tables shall reside on local disk in known locations (i.e., there
+is no need that they are downloaded from the internet and parsed by
+PSLib).  The format of these files shall be simple, for speed in
+reading: Each line shall contain the MJD, $x_p$ (in arcseconds), $y_p$
+(in arcseconds) and $\Delta$UT (in seconds) separated by whitespace;
+blank lines and lines commencing with the comment character (the hash
+symbol, \code{#}) as the first character shall be ignored.  For
+example:
+
+\begin{verbatim}
+# Bulletin A, 9 September 2004.
+# ftp://maia.usno.navy.mil/ser7/ser7.dat
+# MJD       XP(")   YP(")   UT1-UTC(s)
+53258       0.1715  0.4774  -0.45092              
+53259       0.1734  0.4757  -0.45039              
+53260       0.1753  0.4741  -0.45012              
+53261       0.1770  0.4724  -0.45015              
+53262       0.1787  0.4708  -0.45045              
+\end{verbatim}
+
+The location of these files, their priority order, and the ``from''
+and ``to'' dates of applicability will be specified through metadata
+(\S\ref{sec:timeMetadata}).
+
+When a value is required, the tables shall shall be checked in
+priority order to see if the date is within the range of applicability
+for the table.  If a table is found that is applicable, then the
+appropriate value shall be derived from linear interpolation between
+the nearest entries in the table.  If no table is found that is
+applicable, and the required date is later than those covered in the
+tables, a warning shall be generated, and a pre-determined formula
+shall be applied (\S\ref{sec:timeMetadata}).  For dates prior to those
+covered in the tables, the function shall generate a warning and use
+pre-determined values (\S\ref{sec:timeMetadata}).
+
+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
+    bool loaded;                        // Has the table been loaded?
+    psVector *mjd;                      // MJD data, type is psF64
+    psVector *dut;                      // delta UT = UT1 - UTC data
+    psVector *xp, *yp;                  // Polar motion data
+} psTimeTable;
+\end{verbatim}
+
+The tables shall be read in only when required by the user (hence the
+\code{loaded} member); once loaded, the table shall remain in memory
+until the termination of the program.  The corresponding constructor
+shall be:
+\begin{verbatim}
+psTimeTable *psTimeTableAlloc(const char *filename, psF64 validFrom, psF64 validTo);
+\end{verbatim}
+which simply constructs a \code{psTimeTable} with the appropriate
+\code{filename}, \code{validFrom} and \code{validTo}.  Upon
+construction, the \code{loaded} member shall be set to \code{false},
+and the vectors containing the data shall be set to \code{NULL}.
+
+The function \code{psTimeTableLoad} shall load a specified time
+\code{table}, returning \code{true} for success, and \code{false} if
+the table failed to load.  If the \code{table} has already been
+loaded, then it shall be re-loaded.
+\begin{verbatim}
+bool psTimeTableLoad(psTimeTable *table);
+\end{verbatim}
+
+Given a time \code{table} and a Modified Julian Date, \code{mjd}, at
+which to interpolate values, \code{psTimeTableInterpolate} shall
+calculate the appropriate UT1-UTC (\code{dut}; if non-\code{NULL}),
+and polar motion (\code{xp,yp}; if non-\code{NULL}) by interpolation
+on the table.  If the \code{mjd} is outside the range of the table or
+the interpolation was for some other reason unsuccessful, then the
+function shall return \code{false}; otherwise the function shall set
+those parameters which are non-\code{NULL} (\code{dut,xp,yp}) and
+return \code{true}.  If the requested \code{mjd} lies in the range of
+the \code{table}, but the \code{table} has not been \code{loaded},
+then the function shall call \code{psTimeTableLoad}.
+\begin{verbatim}
+bool psTimeTableInterpolate(const psTimeTable *table, double *xp,
+                            double *yp, double *dut, psF64 mjd);
+\end{verbatim}
+
+\paragraph{Time Metadata}
+\label{sec:timeMetadata}
+
+The following metadata keys will be used in time calculations:
+
+\begin{tabular}{l|l} \hline
+Metadata key & Purpose \\ \hline
+psLib.time.tables.files & Time table file names (space-delimited)                          \\
+psLib.time.tables.from  & Time tables are valid from these MJDs (vector)                   \\
+psLib.time.tables.to    & Time tables are valid to these MJDs (vector)                     \\
+psLib.time.before.xp    & Value of XP for before the earliest MJD                          \\
+psLib.time.before.yp    & Value of YP for before the earliest MJD                          \\
+psLib.time.before.dut   & Value of UT1-UTC for before the earliest MJD                     \\
+pslib.time.predict.xp   & A vector containing the $x_p$ prediction formula coefficients    \\
+pslib.time.predict.yp   & A vector containing the $y_p$ prediction formula coefficients    \\
+pslib.time.predict.mjd  & A value containing the MJD offset for temporary variables        \\
+pslib.time.predict.dut  & A vector containing the UT1-UTC prediction formula coefficients  \\
+\hline
+\end{tabular}
+
+These metadata keys shall reside in a configuration file
+(\S\ref{sec:configspec}), \code{psTime.config}, which shall be loaded
+into a \code{psMetadata} structure private to \code{psTime}, as part
+of \code{psLibInit}.  An example of \code{psTime.config} follows:
+
+\begin{verbatim}
+# This configuration file specifies values required for time calculations by psLib.
+psLib.time.tables.n     U8      2                                               # Number of time tables
+psLib.time.tables.files STR     bulletinA_09Sep2004.dat eopc01_1900_2004.40.dat # These are the file names
+@psLib.time.tables.from F64     53258.0, 15020.0                                # Valid from these MJDs
+@psLib.time.tables.to   F64     53622.0, 53258.0                                # Valid to these MJDs
+psLib.time.before.xp    F64     0.0                     # Value of XP for before the earliest MJD
+psLib.time.before.yp    F64     0.0                     # Value of YP for before the earliest MJD
+psLib.time.before.dut   F64     0.0                     # Value of UT1-UTC for before the earliest MJD
+                                                        
+# Now follows formulae for predicting ahead of the most recent available table entry.
+# xp = [0] + [1]*cos A + [2]*sin A + [3]*cos C + [4]*sin C
+# yp = [0] + [1]*cos A + [2]*sin A + [3]*cos C + [4]*sin C
+# A = 2*pi*(MJD - pslib.time.predict.mjd)/365.25
+# C = 2*pi*(MJD - pslib.time.predict.mjd)/435.0
+# dut = ut1-utc = [0] + [1]*(MJD - [2]) - (UT2-UT1)
+# ut2-ut1 = 0.022 sin(2*pi*T) - 0.012 cos(2*pi*T) - 0.006 sin(4*pi*T) + 0.007 cos(4*pi*T)
+# T = 2000.0 + (MJD - 51544.03)/365.2422
+@psLib.time.predict.xp  F64     0.0569, 0.0555, -0.0200, 0.0513, 0.1483
+@psLib.time.predict.yp  F64     0.3498, -0.0176, -0.0498, 0.1483, -0.0513
+psLib.time.predict.mjd  F64     53257.0
+@psLib.time.predict.dut F64     -0.4944, -0.00023, 53262.0
+\end{verbatim}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%