Changeset 3436 for trunk/doc/pslib/psLibADD.tex

Timestamp:

Mar 16, 2005, 3:36:07 PM (21 years ago)

Author:

jhoblitt

Message:

Changes to the Time section:
added references
updated definitions of UTC, UT1, JD, MJD
misc formatting
verbatim Perl code for YMD->sec and sec->YMD conversion

File:

• trunk/doc/pslib/psLibADD.tex (modified) (6 diffs)

trunk/doc/pslib/psLibADD.tex

@@ -1 @@
-%%% $Id: psLibADD.tex,v 1.66 2005-03-16 01:50:24 jhoblitt Exp $
+%%% $Id: psLibADD.tex,v 1.67 2005-03-17 01:36:07 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -786 +786 @@
 Correct time representation is \emph{critical} in astronomical software.  PSLib
 uses the \code{psTime} structure to represent 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 (SI seconds) and no leap seconds.
-The exact zero reference is ``1970-01-01T00:00:10Z'' UTC.  The second
-representation 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-01T00:00:00Z'' UTC.
+represents a time which consists of seconds and nanoseconds in a time
+system defined by the \code{psTimeType} element \code{type}.  All available
+time-systems are defined in terms of the reference epoch
+``1970-01-01T00:00:00Z'' (Gregorian\footnote{Gregorian Calendar -
+http://en.wikipedia.org/wiki/Gregorian\_calendar}), but with minor
+modifications, as needed, for for features such as leap-seconds.  The first
+represenatation, TAI (International Atomic Time), has seconds of uniform length
+(SI seconds) and no leap-seconds.  The exact zero reference is
+``1970-01-01T00:00:10Z'' UTC.  The second representation is UTC, which has
+seconds of uniform length and leap-seconds as needed to adjust it to remain
+within $0.9s$ of the Earth's rotation.  It has a zero-point of exactly
+``1970-01-01T00:00:00Z'' UTC.
 
 \paragraph{Coordinated Universal Time (UTC)}
 
-Coordinated Univeral Time (UTC) is a system of time with SI length
-seconds but attempts to stay within 1s of UT1.  This is done by the
-insertion of leap second whenever UTC-UT1 $\ge$ 0.9s.  By definition
-UTC-TAI is an integer number of seconds.  UTC went into effect on
-``1972-01-01T00:00:00Z'' and is defined as being TAI-UTC = 10s on that
-date.  For dates prior to 1972-01-01 a fixed offset of 10s relative
-to TAI will be assumed.
+Coordinated Univeral Time (UTC) is defined by the International
+Telecommunication Union (ITU)\footnote{ITU website -
+http://www.itu.int/home/index.html}.  It is a system of time with SI length
+seconds but attempts to stay within $1s$ of UT1.  This is done by the insertion
+of a ``leap-second'' whenever $\lvert UTC-UT1 \rvert \ge 0.9s$.  By
+definition\footnote{UTC definition -
+http://www.cl.cam.ac.uk/~mgk25/volatile/ITU-R-TF.460-4.pdf}, $UTC-TAI$ is an
+integer number of seconds.  UTC went into effect on ``1972-01-01T00:00:00Z''
+and is defined as being $TAI-UTC = 10s$ on that date.  For dates prior to
+``1972-01-01'' a fixed offset of 10s relative to TAI will be assumed.
 
 \begin{equation}
@@ -811 +816 @@
 \end{equation}
 
-Leapseconds are declared by the International Earth Rotation and Reference
-Systems Service (IERS).  Leapseconds only occur in the UTC time system and
-cannot be accurately predicted due to variations in the Earth's rotational
-period.  To determine the number of leapsecond in a given UTC date a table of
-leapseconds as annouced by the IERS must be consulted.  This table will have to
-be updated each time a new leapsecond occurs.
+Leap-seconds are declared by the International Earth Rotation and Reference
+Systems Service (IERS)\footnote{IERS website - http://www.iers.org/}.
+leap-seconds only occur in the UTC time system and cannot be accurately
+predicted due to variations in the Earth's rotational period.  To determine the
+number of leap-second in a given UTC date a table of leap-seconds as annouced by
+the IERS must be consulted.  This table will have to be updated each time a new
+leap-second occurs.
 
 For ease of conversion, UTC should be represented as the number of seconds
-since the UNIX epoch of ``1970-01-01T00:00:00Z''.  \emph{Times will always be
-expressed in the 'UTC' timezone.  Use of the local timezone is forbidden.}
+since the UNIX epoch of ``1970-01-01T00:00:00Z'', non-inclusive of leap-seconds.
+\emph{Times will always be expressed in the 'UTC timezone'.  Use of the local
+timezone is forbidden.}
 
 \paragraph{International Atomic Time (TAI)}
 
-International Atomic Time or Temps Atomique International (TAI) is a
-system of time defined by the Bureau International des Poids et
-Mesures (BIPM) with SI length seconds as measured at sea level.  To
-convert from UTC to TAI add the base delta of $10s$ and all of
-the accumulated leapsecons since 1972-01-01 up until the UTC date
-being converted.
-
-\begin{equation}
-{\rm TAI} = {\rm UTC} + 10{\rm s} + {\rm leapseconds}
+International Atomic Time or Temps Atomique International (TAI) is a system of
+time defined by the Bureau International des Poids et Mesures
+(BIPM)\footnote{BIPM website - http://www.bipm.fr/} with SI length seconds as
+measured at sea level.  To convert from UTC to TAI add the base delta of $10s$
+and all of the accumulated leap-seconds since ``1972-01-01'' up until the UTC
+date being converted.
+
+\begin{equation}
+{\rm TAI} = {\rm UTC} + 10{\rm s} + {\rm leap-seconds}
 \end{equation}
 
 For ease of conversion, TAI should be represented as the number of
-seconds since the UNIX epoch of "1970-01-01T00:00:00".
-
-\paragraph{Leap seconds}
+seconds since the UNIX epoch of ``1970-01-01T00:00:00Z''.
+
+\paragraph{Leap-seconds}
 
 Leap seconds keep UTC within 0.9s of UT1.  The offset between TAI and
@@ -874 +881 @@
 file will be made configurable.
 
-This data is available from
-\code{ftp://maia.usno.navy.mil/ser7/tai-utc.dat}
+This data is available from: \code{ftp://maia.usno.navy.mil/ser7/tai-utc.dat}
 
 \paragraph{Gregorian dates to seconds}
 
-The below algorithm converts from Gregorian-formatted dates to
-seconds since the UNIX epoch.
-
+The Perl code below, based on an algorithm described in the book ``Calendrical
+Calculations''\footnote{Calendrical Calculations -
+http://emr.cs.iit.edu/home/reingold/calendar-book/second-edition/} and modified
+to return seconds, converts from Gregorian-formatted dates to seconds since the
+UNIX epoch.
+
+Given year, month, day as \code{$y, $m, $d}.
 \begin{verbatim}
-    Given year, month, day.
-
-    ### Make month in range 3..14 (treat Jan & Feb as months 13..14 of prev year):
-    if ( month <= 2 )
+    use integer;
+
+    my $adj;
+
+    # make month in range 3..14 (treat Jan & Feb as months 13..14 of
+    # prev year)
+    if ( $m <= 2 )
     {
-        year -= ( temp = ( 14 - month ) / 12 )
-        month += 12 * temp
+        $y -= ( $adj = ( 14 - $m ) / 12 );
+        $m += 12 * $adj;
     }
-    else if ( month > 14 )
+    elsif ( $m > 14 )
     {
-        year += ( temp = ( month - 3 ) / 12 )
-        month -= 12 * temp
+        $y += ( $adj = ( $m - 3 ) / 12 );
+        $m -= 12 * $adj;
     }
+
+    # make year positive (oh, for a use integer 'sane_div'!)
+    if ( $y < 0 )
+    {
+        $d -= 146097 * ( $adj = ( 399 - $y ) / 400 );
+        $y += 400 * $adj;
+    }
+
+    # add: day of month, days of previous 0-11 month period that began
+    # w/March, days of previous 0-399 year period that began w/March
+    # of a 400-multiple year), days of any 400-year periods before
+    # that, and 306 days to adjust from Mar 1, year 0-relative to Jan
+    # 1, year 1-relative (whew)
+
+    $d += ( $m * 367 - 1094 ) / 12 + $y % 100 * 1461 / 4 +
+          ( $y / 100 * 36524 + $y / 400 ) - 306;
+
+    # convert from count of days to seconds since the UNIX epoch
+    $unix = ( ( $d - 1 ) * 86400 ) - 62135596800;
+    $utc = $unix - leapseconds($unix);
+\end{verbatim}
+Outputs seconds as \code{$utc}.
+
+To go the other way:
+
+Given the number of seconds since the UNIX epoch as \code{$utc}.
+\begin{verbatim}
+    use integer;
+
+    my $unix = $utc + leapseconds( $utc )
+    $d = ( unix + 62135596800 ) / 86400
  
-    ### make year positive
-    if ( year < 0 )
+    my $rd = $d;
+
+    my $yadj = 0;
+    my ( $c, $y, $m );
+
+    # add 306 days to make relative to Mar 1, 0; also adjust $d to be
+    # within a range (1..2**28-1) where our calculations will work
+    # with 32bit ints
+    if ( $d > 2**28 - 307 )
     {
-        day -= 146097 * ( temp = ( 399 - year ) / 400 )
-        year += 400 * temp
+        # avoid overflow if $d close to maxint
+        $yadj = ( $d - 146097 + 306 ) / 146097 + 1;
+        $d -= $yadj * 146097 - 306;
     }
- 
-    ### add: day of month, days of previous 0-11 month period that began
-    ### w/March, days of previous 0-399 year period that began w/March
-    ### of a 400-multiple year), days of any 400-year periods before
-    ### that, and 306 days to adjust from Mar 1, year 0-relative to Jan
-    ### 1, year 1-relative
-    day += ( month * 367 - 1094 ) / 12 + year % 100 * 1461 / 4 +
-          ( year / 100 * 36524 + year / 400 ) - 306
-
-    unix = ( ( day - 1 ) * 86400 ) - 62135596800
-    utc = unix - leapseconds(unix)
+    elsif ( ( $d += 306 ) <= 0 )
+    {
+        $yadj =
+          -( -$d / 146097 + 1 );    # avoid ambiguity in C division of negatives        $d -= $yadj * 146097;
+    }
+
+    $c = ( $d * 4 - 1 ) / 146097;   # calc # of centuries $d is after 29 Feb of yr 0
+    $d -= $c * 146097 / 4;          # (4 centuries = 146097 days)
+    $y = ( $d * 4 - 1 ) / 1461;     # calc number of years into the century,
+    $d -= $y * 1461 / 4;            # again March-based (4 yrs =~ 146[01] days)
+    $m = ( $d * 12 + 1093 ) / 367;  # get the month (3..14 represent March through
+    $d -= ( $m * 367 - 1094 ) / 12; # February of following year)
+    $y += $c * 100 + $yadj * 400;   # get the real year, which is off by
+    ++$y, $m -= 12 if $m > 12;      # one if month is January or February
+
+    if ( $_[0] )
+    {
+        my $dow;
+
+        if ( $rd < -6 )
+        {
+            $dow = ( $rd + 6 ) % 7;
+            $dow += $dow ? 8 : 1;
+        }
+        else
+        {
+            $dow = ( ( $rd + 6 ) % 7 ) + 1;
+        }
+
+        my $doy =
+            $class->_end_of_last_month_day_of_year( $y, $m );
+
+        $doy += $d;
+
+        my $quarter;
+        {
+            no integer;
+            $quarter = int( ( 1 / 3.1 ) * $m ) + 1;
+        }
+
+        my $qm = ( 3 * $quarter ) - 2;
+
+        my $doq =
+            ( $doy -
+              $class->_end_of_last_month_day_of_year( $y, $qm )
+            );
 \end{verbatim}
-
-To go the other way:
-
-\begin{verbatim}
-    unix = utc + leapseconds(utc)
-    day = ( unix + 62135596800 ) / 86400
-    temp = 0
- 
-    ### add 306 days to make relative to Mar 1, 0; also adjust day to be
-    ### within a range (1..2**28-1) where our calculations will work
-    ### with 32bit ints
-    if ( day > 2**28 - 307 )
-    {
-        ### avoid overflow if day close to maxint
-        temp = ( day - 146097 + 306 ) / 146097 + 1
-        day -= temp * 146097 - 306
-    }
-    else if ( ( day += 306 ) <= 0 )
-    {
-        temp = -( -day / 146097 + 1 )  ### avoid ambiguity in C division of negatives
-        day -= temp * 146097
-    }
- 
-    cent = ( day * 4 - 1 ) / 146097    ### calc number of centuries day is after 29 Feb of yr 0
-    day -= cent * 146097 / 4           ### (4 centuries = 146097 days)
-    year = ( day * 4 - 1 ) / 1461      ### calc number of years into the century,
-    day -= year * 1461 / 4             ### again March-based (4 yrs =~ 146[01] days)
-    month = ( day * 12 + 1093 ) / 367  ### get the month (3..14 represent March through
-    day -= ( month * 367 - 1094 ) / 12 ### February of following year)
-    year += cent * 100 + temp * 400    ### get the real year, which is off by
-    if ( month > 12 )                  ### one if month is January or February
-    {
-        year++
-        month -= 12
-    }
-
-
-    Output year, month, day.
-\end{verbatim}
-
-(Above taken from \code{DateTime.pm} (C) 2003 Dave Rolsky, available
-from \code{datetime.perl.org}.)
+Outputs year, month, day as \code{$y, $m, $d}.
+
+\emph{The above code was taken [and slightly altered] from
+\code{DateTime.pm}\footnote{DateTime.pm -
+http://search.cpan.org/~drolsky/DateTime/} (C)  2003 Dave Rolsky.
+Please see the DateTime project website\footnote{DateTime project -
+http://datetime.perl.org} for further details.}
 
 
@@ -978 +1030 @@
 post-2003 definition.
 
-UT1 is continuously measured by the International Earth Rotation
-Service\footnote{IERS - http://maia.usno.navy.mil/}, and tabulated values of the
-offset of UT1 from UTC are published at regular intervals, along with predicted
-future values.  IERS Bulletin A gives "rapid response" values necessary for
-real-time and near real-time data analysis (such as Pan-STARRS Otis and IPP
-subsystems). Bulletin B gives the results of a final, definitive data
-reduction.  An amalgam of Bulletin A and B values is published daily on the
-IERS website\footnote{IERS Bulletin A \& B -
+UT1 is continuously measured by the International Earth Rotation Service, and
+tabulated values of the offset of UT1 from UTC are published at regular
+intervals, along with predicted future values.  IERS Bulletin A gives ``rapid
+response'' values necessary for real-time and near real-time data analysis
+(such as Pan-STARRS Otis and IPP subsystems). Bulletin B gives the results of a
+final, definitive data reduction.  An amalgam of Bulletin A and B values is
+published daily on the IERS website\footnote{IERS Bulletin A \& B -
 http://maia.usno.navy.mil/ser7/finals2000A.daily} along with a desciption of
 the format\footnote{IERS finals2000A.daily table format -
@@ -1003 +1054 @@
 IERS publications references above, and should be interpolated in the same way.
 
-\paragraph{Julian Day and Modified Julian Day}
-
-Julian Day (JD) and Modified Julian Day (MJD) are both continuous time
-representations, with one julian day interval having a length of 86400
-TAI seconds.  MJD is equal to JD - 2400000.5 and has a zero point
-equal to that of TAI, while JD has a zero point 0.5 off of TAI.
+\paragraph{Julian Date and Modified Julian Date}
+
+The follow definitions of Julian Date (JD) and Modified Julian Date (MJD) was
+taken from, ``RESOLUTION B1: ON THE USE OF JULIAN DATES'' of ``The XXIIIrd
+International Astronomical Union General Assembly''\footnote{RESOLUTION B1: ON
+THE USE OF JULIAN DATES -
+http://www.iers.org/iers/earth/resolutions/UAI\_b1.html}.
+
+\subparagraph{Julian Date}
+
+\begin{verbatim}
+1. Julian day number (JDN)
+
+The Julian day number associated with the solar day is the number assigned to a
+day in a continuous count of days beginning with the Julian day number 0
+assigned to the day starting at Greenwich mean noon on 1 January 4713 BC,
+Julian proleptic calendar -4712.
+
+2. Julian Date (JD)
+
+The Julian Date (JD) of any instant is the Julian day number for the preceding
+noon plus the fraction of the day since that instant. A Julian Date begins at
+12h 0m 0s and is composed of 86400 seconds. To determine time intervals in a
+uniform time system it is necessary to express the JD in a uniform time scale.
+For that purpose it is recommended that JD be specified as SI seconds in
+Terrestrial Time (TT) where the length of day is 86,400 SI seconds.
+
+In some cases it may be necessary to specify Julian Date using a different time
+scale. (See Seidelmann, 1992, for an explanation of the various time scales in
+use). The time scale used should be indicated when required such as JD(UT1). It
+should be noted that time intervals calculated from differences of Julian Dates
+specified in non-uniform time scales, such as UTC, may need to be corrected for
+changes in time scales (e.g. leap seconds).
+\end{verbatim}
+
+\subparagraph{Modified Julian Date}
+
+\begin{verbatim}
+"that for those cases where it is convenient to employ a day beginning at
+midnight, the Modified Julian Date (equivalent to the Julian Date minus 2 400
+000.5) be used"
+\end{verbatim}
+
+\subparagraph{JD and MJD conversion}
+
 Conversion between \code{psTime} values and MJD and JD are determined
 from:
 
+Where \code{psTime} is a \code{PS_TIME_TAI}.
 \begin{verbatim}
-mjd = psTime.sec/86400.0 + psTime.usec/86400000000.0 + 40587.0;
- jd = psTime.sec/86400.0 + psTime.usec/86400000000.0 + 2440587.5;
+mjd = psTime.sec/86400.0 + psTime.nsec/86400000000000.0 + 40587.0;
+ jd = psTime.sec/86400.0 + psTime.nsec/86400000000000.0 + 2440587.5;
 \end{verbatim}
 
-$2451545.0$ JD $= 51544.5$ MJD is equivalent to ``2000-01-01T00:00:00Z''.
+For reference $2451545.0$ JD $= 51544.5$ MJD is equivalent to
+``2000-01-01T00:00:00Z''.
 
 \begin{equation}