Changeset 3447

Timestamp:

Mar 17, 2005, 6:04:09 PM (21 years ago)

Author:

jhoblitt

Message:

changes to the Time section:
add psTimeBulliten enum
add leapsecond member to psTimeType
change psTime.usec -> psTime.nsec (nanoseconds)
minor reorganization and additional comments
rename psTimeGetTime() -> psTimeGetNow()
new rules for time system converstion
rename psTimeToLST() -> psTimeToLMST()
rename psTimeLeapSeconds()} -> psTimeLeapSecondDelta()
add psTimeIsLeapSecond()
iSO8601 format clarifications
rename psTimeToISOTime() -> psTimeToISO()
add psTimeFromUTC()
add psTimeFromTT()
change psTime math rules
change "Time Tables" to have IERS Bulliten A & B

Location:

trunk/doc/pslib

Files:

• ChangeLogSDRS.tex (modified) (2 diffs)
• psLibSDRS.tex (modified) (6 diffs)

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.74 2005-03-15 20:54:49 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.75 2005-03-18 04:04:09 jhoblitt Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -487 +487 @@
 \item Added \code{psPlaneTransformDeriv}.
 \item Added \code{psImageGrowMask}.
-\end{itemize}
+\item Changes to the Time section:
+\begin{itemize}
+\item Add \code{psTimeBulliten} enum
+\item Add \code{leapsecond} member to \code{psTimeType}
+\item Change \code{psTime.usec} $\rightarrow$ \code{psTime.nsec} (nanoseconds)
+\item Minor reorganization and additional comments
+\item Rename \code{psTimeGetTime()} $\rightarrow$ \code{psTimeGetNow()}
+\item New rules for time system converstion
+\item Rename \code{psTimeToLST()} $\rightarrow$ \code{psTimeToLMST()}
+\item Rename \code{psTimeLeapSeconds()} $\rightarrow$ \code{psTimeLeapSecondDelta()}
+\item Add \code{psTimeIsLeapSecond()}
+\item ISO8601 format clarifications
+\item Rename \code{psTimeToISOTime()} $\rightarrow$ \code{psTimeToISO()}
+\item Add \code{psTimeFromUTC()}
+\item Add \code{psTimeFromTT()}
+\item Change \code{psTime} math rules
+\item Change ``Time Tables'' to have IERS Bulliten A \& B
+\end{itemize}
+\end{itemize}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $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 +3469 @@
 \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 +3514 @@
 
 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 +3593 @@
 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 +3607 @@
 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 +3675 @@
 
 \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}