Changeset 1554

Timestamp:

Aug 16, 2004, 3:56:41 PM (22 years ago)

Author:

eugene

Message:

cleaned up time handling

Location:

trunk/doc/pslib

Files:

• psLibADD.tex (modified) (10 diffs)
• psLibSDRS.tex (modified) (6 diffs)

trunk/doc/pslib/psLibADD.tex

@@ -1 @@
-%%% $Id: psLibADD.tex,v 1.24 2004-08-16 19:12:54 eugene Exp $
+%%% $Id: psLibADD.tex,v 1.25 2004-08-17 01:56:41 eugene Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -644 +644 @@
 
 Correct time representation is critical in astronomical software.
-PSLib uses the \code{psTime} structure to represent all time
-values.  This structure represents a time which is equivalent to TAI
-(International Atomic Time) and has the following properties:
-\begin{itemize}
-\item it represents both seconds and microseconds
-\item the seconds are continuous (no leap seconds)
-\item the zero reference point is \tbd{1970/01/01,00:00:10} UTC.
-\end{itemize}
+PSLib uses the \code{psTime} structure to represent all time values.
+This structure represents a time which is consists of seconds and
+fractions of seconds in a time system defined by the \code{psTimeType}
+element \code{type}.  Two possible time systems are currently
+available: TAI and UTC.  Both are defined in terms of the reference
+epoch 1970-01-01T00:00:00Z, but with minor modifications for
+leap-seconds as needed.  The first represenatation, TAI (International
+Atomic Time), has seconds of uniform length and no leap seconds.  The
+exact zero reference is 1970/01/01,00:00:10 UTC.  The second
+representations is UTC, which has seconds of uniform length and
+leap-seconds as needed to adjust it to remain within 0.9 seconds of
+the Earth's rotation.  It has a zero-point of exactly
+1970/01/01,00:00:00 UTC.
 
 Julian Day (JD) and Modified Julian Day (MJD) are both continuous time
@@ -708 +713 @@
 \end{verbatim}
 
+The conversion from a time and longitude to local mean sidereal time
+is performed using the SLA Lib function \code{sla_GMST}.  This
+function requires the value $\Delta$ UT1 = UTC - UT1.  The value of
+$\Delta$ UT1 may be determined from the following site in real time:
+
+\code{ftp://maia.usno.navy.mil/ser7/ser7.dat}
+
+In addition, the long-term values may be determined from the table
+found at: \code{ftp://maia.usno.navy.mil/ser7/finals.all}.  See also
+the web page \code{http://maia.usno.navy.mil/}.  The most significant
+accuracy requirements are for the current value when calculating the
+LST.  For this purpose, the table above (\code{ser7.dat}), which
+provides predictions over a 2 month period, must be made available
+locally to PSLib and updated regularly. 
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -842 +862 @@
 \subsubsection{Projections}
 
-We implement three types of projections, {\em zenithal} and {\em
-cylindrical} and {\em pseudocylindrical} projections.  These three
-require slightly different handling.  Our representations are based on
-the treatment of projections presented by
+We implement three types of projections: {\em zenithal}, {\em
+cylindrical} and {\em pseudocylindrical}, each requiring slightly
+different handling.  Our representations are based on the treatment of
+projections presented by
 \href{http://www.cv.nrao.edu/fits/documents/wcs/wcs.all.ps}{Greisen \&
-Calabretta (1995, ADASS, 4, 233)}.
+Calabretta (1995, ADASS, 4, 233)}.  In all of these projections, we
+are converting from a spherical coordinate $\alpha,\delta$ to a linear
+(2-D) coordinate $x_p,y_p$.  The projection is defined by the
+projection type, the projection center ($\alpha_p, \delta_p$) and the
+the plate scales in the $x_p$ and $y_p$ directions ($\rho_x,\rho_y$).
+
+In the structure, \code{psProjection}, the projection type is defined
+by the element \code{type}, the projection center $\alpha_p,\delta_p$
+is defined by the elements \code{R,D}, and the plate scales,
+$\rho_x,\rho_y$, are defined by the elements \code{Xs,Ys}.  The plate
+scales are applied independently to the $x$ and $y$ coordinates to
+convert them to the corresponding linear units (ie, pixels):
+%
+\begin{eqnarray}
+x_p & = & \rho_x x \\
+y_p & = & \rho_y y \\
+\end{eqnarray}
+% 
+In the discussions below, we ignore this last step (or first step,
+depending on the direction of the conversion).
 
 \paragraph{Zenithal Projections}
 
 The {\em zenithal} projections are defined relative to a set of
-spherical coordinates whose pole is the center of the projection
-($\alpha_p, \delta_p$, or \code{psProjection.R, psProjection.D}).  In
+spherical coordinates with pole at the center of the projection
+($\alpha_p, \delta_p$), and which thus represents a coordinate system
+rotated relative to the coordinate system of $\alpha, \delta$.  In
 this spherical coordinate system, the coordinate of longitude is
 labeled $\phi$, and has domain of $-\pi < \phi \le \pi$, while the
@@ -859 +899 @@
 $0 \le \theta \le \pi$.
 
-For zenithal projections (e.g.\ Gnomonic and Orthographic) the
-following hold:
-%
-\begin{eqnarray}
-x & = & R_\theta \sin \phi \\
-y & = & -R_\theta \cos \phi
-\end{eqnarray}
-%
-and
-%
-\begin{eqnarray}
-R_\theta & = & \sqrt{x^2 + y^2} \\
-\phi     & = & {\rm arg} (-y,x)
-\end{eqnarray}
-%
-The coordinates $x,y$ above are defined to be in angular units (ie,
-radians).  The plate scales ($\rho_x, \rho_y$ = \code{psProjection.Xs,
-psProjection.Ys}) are applied independently to the $x$ and $y$
-coordinates to convert them to the corresponding linear units (ie,
-pixels):
-%
-\begin{eqnarray}
-x_p & = & \rho_x x \\
-y_p & = & \rho_y y \\
-\end{eqnarray}
-
 For an arbitrary projection center, it is necessary to convert the
 spherical coordinates to be projected ($\alpha,\delta$) to the
-projection spherical coordinate system coordinates ($\phi, \theta$)
-from which $x,y$ may be calculated using the relationships above,
-given a prescription for $R_\theta$.  In practice, we construct the
-following useful trigonometric relationships between $\phi$ and
-$\theta$ which may be employed in the equations of $x,y$ above:
+projection spherical coordinate system coordinates ($\phi, \theta$).
+In practice, we construct the following useful trigonometric
+relationships between $\phi$ and $\theta$ which may be employed in the
+equations of $x,y$ below:
 %
 \begin{eqnarray}
@@ -907 +920 @@
 \end{eqnarray}
 %
+For zenithal projections, the linear coordinates are related to
+$\phi,\theta$ by:
+%
+\begin{eqnarray}
+x & = & R_\theta \sin \phi \\
+y & = & -R_\theta \cos \phi
+\end{eqnarray}
+%
+and the inverse:
+%
+\begin{eqnarray}
+R_\theta & = & \sqrt{x^2 + y^2} \\
+\phi     & = & {\rm arg} (-y,x)
+\end{eqnarray}
+%
+The coordinates $x,y$ above are defined to be in angular units (ie,
+radians).  
+
 From these relationships, we can calculate $\alpha, \delta$ as:
 %
 \begin{eqnarray}
-\alpha - \alpha_p & = & arg (\sin \alpha, \cos \alpha) \\
-\delta            & = & arcsin (sin \delta) \\
-\end{eqnarray}
-%
-The necessary relationships for $\phi$ are equivalent for all zenithal projections:
-%
-\begin{eqnarray}
-R_\theta  & = & \sqrt{x^2 + y^2} \\
-\sin \phi & = & x / R_\theta \\
-\cos \phi & = & -y / R_\theta \\
+\alpha - \alpha_p & = & \arctan (\sin \alpha, \cos \alpha) \\
+\delta            & = & \arcsin (\sin \delta) \\
 \end{eqnarray}
 %
@@ -933 +956 @@
 x           & = & \frac{\cos \theta \sin \phi}{\sin \theta} \\
 y           & = & \frac{-\cos \theta \cos \phi}{\sin \theta} \\
-\sin \theta & = & \zeta / \sqrt (1 + \zeta^2) \\
-\cos \theta & = & 1 / \sqrt (1 + \zeta^2) \\
+\sin \theta & = & \zeta / \sqrt{1 + \zeta^2} \\
+\cos \theta & = & 1 / \sqrt{1 + \zeta^2} \\
 \end{eqnarray}
 
@@ -958 +981 @@
 coincident with the pole of the spherical coordinates.  These
 projections are particularly used for full-sky representations, and
-are only defined for projection centers with $\delta_c = 0$.  In this
+are only defined for projection centers with $\delta_p = 0$.  In this
 spherical coordinate system, the coordinate of longitude is labeled
 $\phi$, and has domain of $-\pi < \phi \le \pi$, while the latitude,
 measured from the pole, is labeled $\theta$ and has domain $0 \le
-\theta \le \pi$.  The projection center longitude, $\alpha_c$
+\theta \le \pi$.  The projection center longitude, $\alpha_p$
 corresponds to $\phi = 0$, thus the value of $\phi$ is determined as
-$\alpha - \alpha_c$ for all such projections.  The terms
-$\alpha_c,\delta_c$ are equivalent to the elements
-\code{psProjection.R} and \code{psProjection.D}.
+$\alpha - \alpha_p$ for all such projections.
 
 \subparagraph{Cartesian}
 
-The Cartesian projection (``CAR'') is a very simple cylindrical with
-the following relationships between $x,y$ and $\phi,\theta$:
+The Cartesian projection (``CAR'') is a very simple cylindrical
+projection with the following relationships between $x,y$ and
+$\phi,\theta$:
 
 \begin{eqnarray}
@@ -985 +1007 @@
 x & = & \phi \\
 y & = & \ln \left( \tan (\pi/4 + \theta/2) \right) \\
-{\rm and}\hspace{1cm} \theta & = & 2 \arctan \left( e^y \right) - \pi/2^\circ
+{\rm and}\hspace{1cm} \theta & = & 2 \arctan \left( e^y \right) - \pi/2
 \end{eqnarray}
 
 \subparagraph{Hammer-Aitoff}
 
-The Hammer-Aitoff projection is a pseudocylindrical projection, and is defined:
-
-\begin{eqnarray}
-x & = & 2 \alpha \cos \theta \sin \frac{\phi}{2} \\
-y & = & \alpha \sin \theta \\
-{\rm where}\hspace{1cm} \alpha^{-1} & \equiv & \sqrt{\frac{1}{2}\left(1 + \cos \theta \cos \frac{\phi}{2} \right)}
+The Hammer-Aitoff projection(``AIT'') is a pseudocylindrical projection, and is defined:
+
+\begin{eqnarray}
+x & = & 2 \zeta \cos \theta \sin \frac{\phi}{2} \\
+y & = & \zeta \sin \theta \\
+{\rm where}\hspace{1cm} \zeta^{-1} & \equiv & \sqrt{\frac{1}{2}\left(1 + \cos \theta \cos \frac{\phi}{2} \right)}
 \end{eqnarray}
 
@@ -1001 +1023 @@
 
 \begin{eqnarray}
-\phi & = & 2 {\rm arg} (2z^2 - 1, x z) \\
+\phi & = & 2 {\rm \arctan} (2z^2 - 1, x z) \\
 \theta & = & \arcsin (yz) \\
 {\rm where}\hspace{1cm} z & \equiv & \sqrt{1 - (x/2)^2 - y^2}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.72 2004-08-14 00:58:46 jhoblitt Exp $
+%%% $Id: psLibSDRS.tex,v 1.73 2004-08-17 01:56:41 eugene Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -3031 +3031 @@
 \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 struct similar to the POSIX \code{struct timeval} which
-has been extended to track the time system being represented.
-
-Conversion from one time system to another is achived by converting first to
-TAI and then to the destination type.  This allows arbitarily many time system
-to be supported by merely add functions to convert to and from TAI.
-
-\subsubsection{Generic Data Structures}
+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.  
 
 \begin{verbatim}
@@ -3046 +3041 @@
     PS_TIME_TAI,                    ///< seconds since 1970-01-01T00:00:00Z (Gregorian)
     PS_TIME_UTC,                    ///< seconds since 1970-01-01T00:00:00Z (Gregorian)
-    PS_TIME_UT1,                    ///< seconds since 1970-01-01T00:00:00Z (Gregorian)
-    PS_TIME_LST,                    ///< seconds since 1970-01-01T00:00:00Z (Gregorian)
 } psTimeType;
 
 typedef struct {
     psU64            sec;           ///< seconds
-    psU32            nsec;          ///< nanoseconds
+    psU32            usec;          ///< microseconds
     psTimeType       type;          ///< type of time
 } psTime;
@@ -3059 +3052 @@
 \subsubsection{Current Date and Time}
 
-A number of functions are provided to get the current time in a particular time
-system.
-
-\begin{verbatim}
-psTime *psGetTAI(void);
-psTime *psGetUTC(void);
-psTime *psGetUT1(void);
-psTime *psGetLST(psF64 longitude);
-psF64 *psGetJD(void);
-psF64 *psGetMJD(void);
-\end{verbatim}
-
-\subsubsection{Automatic Date and Time Type Conversion}
-
-When converting to a time system the source time system is automaticaly
-converted to TAI and then from TAI to the destination type.
-
-\begin{verbatim}
-bool psTimeToTAI(psTimeType type, psTime *time);
-bool psTimeToUTC(psTimeType type, psTime *time);
-bool psTimeToUT1(psTimeType type, psTime *time);
-bool psTimeToLST(psTimeType type, psTime *time);
+Get the current time (in given system):
+
+\begin{verbatim}
+psTime *psTimeGetTime(psTimeType);
+\end{verbatim}
+
+\subsubsection{Time Conversion}
+
+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.  
+
+To convert to or from Local Mean Sidereal Time, it is necessary to
+provide the local longitude as well:
+%
+\begin{verbatim}
+psTime *psTimeToLST(psTime *time, double longitude);
+psTime *psLSTToTime(psTime *time, double longitude);
+\end{verbatim}
+%
+The functions may accept either \code{psTimeType}.  Note that this
+function must supply the value UT1-UTC, which is available externally
+The value UT1-UTC is necessary for this an various other SLALIB
+functions.  The following utility function encapsulates the PSLib
+mechanism to extract the value of UT1-UTC:
+\begin{verbatim}
+double psGetUT1Delta(psTime *time);
+\end{verbatim}
+
+\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"
+
+\begin{verbatim}
 psF64 psTimeToJD(psTime *time);
 psF64 psTimeToMJD(psTime *time);
-\end{verbatim}
-
-\subsubsection{Date and Time Formatting}
-
-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"
-
-\begin{verbatim}
-char *psFormatISO8601(psTime *time);
-struct timeval *psFormatTimeval(psTime *time);
+char *psTimeToISOTime(psTime *time);
+struct timeval *psTimeToTimeval(psTime *time);
 \end{verbatim}
 
@@ -3101 +3102 @@
 
 \begin{verbatim}
-psTime *psParseISO8601(psTimeType type, char *input);
-psTime *psParseTimeval(psTimeType type, struct timeval *input);
-\end{verbatim}
-
-\subsubsection{Date and Time System Support}
-
-All \code{psTime} types must be able to be converted to to the TAI type.
-Conversion from one \code{psTime} type to another is achieved by first
-converting to TAI and then to the target type.
-
-\begin{verbatim}
-psTime *psTAIToUTC(psTime *time);
-psTime *psUTCToTAI(psTime *time);
-\end{verbatim}
-
-A utility function provides the current time from the system clock, in correct TAI units:
-
-\begin{verbatim}
-psTime *psTAIToUT1(psTime *time);
-psTime *psUT1ToTAI(psTime *time);
-\end{verbatim}
-
-\begin{verbatim}
-psTime *psTAIToLST(psTime *time, double longitude);
-psTime *psLSTToTAI(psTime *time, double longitude);
-\end{verbatim}
-
-\subsubsection{Utility Functions}
-
-A number of utility functions is needed for type conversion.
-
-\begin{verbatim}
-psTime *psUT1ToGMST00(psTime *time);
-psTime *psGMST00ToUT1(psTime *time);
-\end{verbatim}
-
-\begin{verbatim}
-psTime *psGMST00ToLST(psTime *time, double longitude);
-psTime *psLSTToGMST00(psTime *time, double longitude);
-\end{verbatim}
-
-Conversions to/from Julian Centuries.
-
-\begin{verbatim}
-psF64 psJDToJC(psF64 time);
-psF64 psJCToJD(psF64 time);
-\end{verbatim}
-
-\begin{verbatim}
-psF64 psMJDToJC(psF64 time);
-psF64 psJCToMJD(psF64 time);
-\end{verbatim}
-
-\begin{verbatim}
-unsigned int psGetLeapSeconds(psTime *utc);
-\end{verbatim}
-
-\begin{verbatim}
-double psGetUT1Delta(psTime *tai);
+psTime *psJDToTime(psF64 input);
+psTime *psMJDToTime(psF64 input);
+psTime *psISOTimeToTime(char *input);
+psTime *psTimevalToTime(struct timeval *input);
 \end{verbatim}
 
@@ -3710 +3656 @@
     PS_PROJ_AIT,                        ///< Aitoff projection
     PS_PROJ_PAR,                        ///< Par projection
-    PS_PROJ_GLS,                        ///< GLS projection
     PS_PROJ_NTYPE                       ///< Number of types; must be last
 } psProjectionType;