Index: trunk/doc/pslib/psLibSDRS.tex =================================================================== --- trunk/doc/pslib/psLibSDRS.tex (revision 3424) +++ trunk/doc/pslib/psLibSDRS.tex (revision 3447) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.187 2005-03-15 20:57:48 price Exp $ +%%% $Id: psLibSDRS.tex,v 1.188 2005-03-18 04:04:09 jhoblitt Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -3469,34 +3469,44 @@ \subsubsection{Overview} -We require a collection of functions to manipulate time data. These -operations primarily consist of conversions between specific time -formats. Internally, PSLib handles times as a structure similar to -the POSIX \code{timeval} which has been extended to track the time -system being represented. +We require a collection of functions to manipulate time data. These operations +primarily consist of conversions between specific time formats. Internally, +PSLib handles times as a structure similar to the POSIX \code{timeval} struct +which has been extended to track the time system being represented. + +\subsubsection{Data Types} \begin{verbatim} typedef enum { - PS_TIME_TAI, ///< seconds since 1970-01-01T00:00:00Z (Gregorian) - PS_TIME_UTC, ///< seconds since 1970-01-01T00:00:00Z (Gregorian) + PS_TIME_TAI, ///< seconds since 1970-01-01T00:00:00Z (Gregorian), SI seconds + PS_TIME_UTC, ///< seconds since 1970-01-01T00:00:00Z (Gregorian), SI seconds + leapseconds + PS_TIME_UT1, ///< seconds since 1970-01-01T00:00:00Z (Gregorian), variable length seconds + PS_TIME_TT, ///< seconds since 1970-01-01T00:00:00Z (Gregorian), SI seconds } psTimeType; + +typedef enum { + PS_IERS_A, ///< IERS Bulliten A + PS_IERS_B, ///< IERS Bulliten B +} psTimeBulliten; typedef struct { psS64 sec; ///< seconds, negative values represent dates before 1970 - psU32 usec; ///< microseconds + psU32 nsec; ///< nanseconds + bool leapsecond; ///< if time falls on a UTC leapsecond psTimeType type; ///< type of time } psTime; \end{verbatim} -The corresponding constructor shall be: +\subsubsection{Constructors} + +To allocate a new, initalized to zero, \code{psTime}: + \begin{verbatim} psTime *psTimeAlloc(psTimeType type); \end{verbatim} -\subsubsection{Current Date and Time} - -Get the current time (in given system): - -\begin{verbatim} -psTime *psTimeGetTime(psTimeType type); +To allocate a new \code{psTime} set to the current time (in the given system): + +\begin{verbatim} +psTime *psTimeGetNow(psTimeType type); \end{verbatim} @@ -3504,50 +3514,72 @@ Converting between the \code{psTime} time systems is done with: + \begin{verbatim} psTime *psTimeConvert(psTime *time, psTimeType type); \end{verbatim} -This function may be used to convert between \code{PS_TIME_TAI} and -\code{PS_TIME_UTC} time representations. The \code{time} is modified -and returned. - -To convert to Local Mean Sidereal Time, it is necessary to provide the -local longitude (specified in radians, positive East of Greenwich) as -well: -% -\begin{verbatim} -psF64 *psTimeToLST(psTime *time, psF64 longitude); -\end{verbatim} -% -The functions may accept either \code{psTimeType}. The \code{time} is -modified and returned. Note that this function must supply the value -UT1-UTC, which is available externally (see \code{psTimeGetUT1Delta}). -The following utility function encapsulates the PSLib mechanism to -extract the value of UT1-UTC: -\begin{verbatim} -double psTimeGetUT1Delta(const psTime *time); -psSphere *psTimeGetPoleCoords(const psTime *time); -\end{verbatim} - -Leap seconds are added to UTC in order to keep it within 0.9s of UT1 -(which is defined relative to the Earth's rotation, and hence is -useful for astronomical purposes). The following function, -\code{psTimeLeapSeconds}, shall calculate the number of leap seconds -added between two times: -% -\begin{verbatim} -long psTimeLeapSeconds(const psTime *time1, const psTime *time2); -\end{verbatim} + +This function may be used to convert between the various \code{psTimeType} time +representations. The \code{time} is modified and returned. Conversion between +all of the \emph{SI} length second systems should be implimented as first +converting to TAI and then to the destination system. UT1 is a special case +for conversion as it uses variable length secounds. Conversation to UT1, via +TAI, is allowed but conversion \emph{from} UT1 is currently forbidden. + +To convert to Local Mean Sidereal Time, it is necessary to provide the local +longitude (specified in radians, positive East of Greenwich) as well: + +\begin{verbatim} +psF64 *psTimeToLMST(psTime *time, psF64 longitude); +\end{verbatim} + +The function may accept any of the \code{psTimeType} types with \emph{SI} +length seconds. The \code{time} is modified and returned. Note that this +function must supply the value $UT1-UTC$, which is available externally (see +\code{psTimeGetUT1Delta()}) and should use the UT1 values interpolated from +IERS bulliten B. The following utility function encapsulates the PSLib +mechanism to extract the value of $UT1-UTC$: + +\begin{verbatim} +double psTimeGetUT1Delta(const psTime *time, psTimeBulliten bulliten); +psSphere *psTimeGetPoleCoords(const psTime *time, psTimeBulliten bulliten); +\end{verbatim} + +Leap seconds are added to UTC in order to keep it within $0.9s$ of UT1 (which +is defined relative to the Earth's rotation, and hence is useful for +astronomical purposes). + +\begin{verbatim} +long psTimeLeapSecondDelta(const psTime *time1, const psTime *time2); +\end{verbatim} + +This function calculates the absolute number of leap seconds different between +two times. + +\begin{verbatim} +bool psTimeIsLeapSecond(const psTime *utc); +\end{verbatim} + +This function only accepts \code{PS_TIME_UTC} objects and determines if the +time is potentaly a leapsecond. \subsubsection{External Date and Time Formats} A collection of functions convert from the \code{psTime} types to various -external formats. Note that ISO8601 format is "YYYY-MM-DDThh:mm:ss,sZ" +external formats. The ISO8601 format\footnote{ISO8601:2000(E) - +http://www.pvv.ntnu.no/~nsaa/8601v2000.pdf} we will be using is +"YYYY-MM-DDThh:mm:ss,sZ". \emph{Note that the ISO8601 format is only valid for +the years $0000 .. 9999$. Values out side that range should cause a +\code{NULL} pointer to be returned.} \begin{verbatim} psF64 psTimeToJD(const psTime *time); psF64 psTimeToMJD(const psTime *time); -char *psTimeToISOTime(const psTime *time); +char *psTimeToISO(const psTime *time); timeval *psTimeToTimeval(const psTime *time); \end{verbatim} + +The \code{psTimeToISO()} function will convertion \code{PS_TIME_UTC} objects +with the \code{leapsecond} flag set to represent the number of seconds as +``:60''. \subsubsection{Date and Time Parsing} @@ -3561,5 +3593,11 @@ psTime *psTimeFromISO(const char *input); psTime *psTimeFromTimeval(const timeval *input); -\end{verbatim} +psTime *psTimeFromUTC(psS64 sec, psU32 nsec, bool leapsecond); +psTime *psTimeFromTT(psS64 sec, psU32 nsec); +\end{verbatim} + +Where \code{psTimeFromUTC()} will validate that it is possible for the input +time to land on a UTC leapsecond (using \code{psTimeIsLeapSecond()}) if +\code{leapsecond} is set to \code{true}. \subsubsection{Date and Time Math} @@ -3569,40 +3607,63 @@ psF64 psTimeDelta(const psTime *time1, const psTime *time2); \end{verbatim} -\code{psTimeMath} adds the \code{delta} (in seconds; may be negative) -to a \code{psTime}. \code{psTimeDelta} gives -the difference between times \code{time1} and \code{time2} (which may -be negative). - -Note that in both these, the difference between two times is to be -expressed in \textit{SI} seconds, and not inclusive of leap seconds. -For example, if we add 30 seconds to 1998-12-31T23:59:45Z, the result -is 1999-01-01T00:00:14Z, since a leap second was introduced at -1999-01-01T00:00:00Z. - -Time math may only be done on the \code{psTime} TAI type, and so the -functions shall internally convert the \code{psTime} inputs to TAI -before performing the math; this is in order that leap seconds are -accounted for. - -The type of the time returned by \code{psTimeMath} shall be the same -as that of the input \code{time}. + +\code{psTimeMath} adds the \code{delta} (in seconds; may be negative) to a +\code{psTime}. \code{PS_TIME_UTC} objects will be converted to +\code{PS_TIME_TAI}, before applying the delta, and then back to +\code{PS_TIME_UTC}. \code{psTimeDelta} gives the difference between times +\code{time1} and \code{time2} (which may be negative). + +The API documentation should note that when handling UT1, date math is allowed +on the UT1 system but that the seconds are not of \emph{SI} length (this is why +conversion from UT1 is correctly forbidden). It should also be noted that with +\code{psTimeDelta()} it is possible to overflow the dynamic range of a +\code{psS64} (the type of \code{psTime.sec}). + +Note that in both these functions, when handling UTC, that the difference +between two times is not inclusive of leap seconds. For example, if we add 30 +seconds to 1998-12-31T23:59:45Z, the result is 1999-01-01T00:00:14Z, since a +leap second was introduced at 1999-01-01T00:00:00Z. + +Time math may only be done on the of \code{psTime} objects of the same type, +and in the case of UT1, the functions shall internally convert the +\code{psTime} inputs to TAI before performing the math; this is in order that +leap seconds are accounted for. + +The type of the time returned by \code{psTimeMath} shall be the same as that of +the input \code{time}. \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: +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 IERS Bulliten A \& B (1 year ago $\rightarrow$ now + $\sim$3 months) +\begin{itemize} +\item \code{ftp://maia.usno.navy.mil/ser7/finals.daily} +\end{itemize} + +\item IERS Bulliten A \& B (1973-1-2 $\rightarrow$ now + $\sim$1 year) +\begin{itemize} +\item \code{ftp://maia.usno.navy.mil/ser7/finals.all} +\end{itemize} + +\item $TAI - UTC$ +\begin{itemize} +\item \code{ftp://maia.usno.navy.mil/ser7/tai-utc.dat} +\end{itemize} + +\item $TAI -UTC$ (contains estimates prior to 1972) +\begin{itemize} \item \code{http://hpiers.obspm.fr/eoppc/eop/eopc01/eopc01.1900-2004} - (contains estimates prior to 1972). \end{itemize} +\end{itemize} + +The format of \code{finals.daily} and \code{finals.all} is documented at +\code{ftp://maia.usno.navy.mil/ser7/readme.finals}. The tables shall reside on local disk in known locations (i.e., there @@ -3614,12 +3675,12 @@ \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 +# finals.daily, 2005-03-17 +# ftp://maia.usno.navy.mil/ser7/finals.daily +# MJD PM-IP PM-X" PM-Y" UT1-YP UT1-UTCs PM-X" PM-Y" UT1-UTCs +# A A A A A B B B +53403.00 I .089198 .207785 I -.5218847 .089220 .207360 -.5219040 +53404.00 I .086549 .206873 I -.5224164 .086670 .206850 -.5224260 +53405.00 I .083589 .206143 I -.5227681 +53406.00 I .081541 .205865 I -.5229582 \end{verbatim}