#include <math.h>
#include <time.h>
#include <string.h>
#include <lal/LALStdlib.h>
#include <lal/Date.h>
#include "XLALLeapSeconds.h"
#include <lal/LALRCSID.h>
Include dependency graph for XLALCivilTime.c:
Go to the source code of this file.
Functions | |
| NRCSID (XLALCIVILTIMEC,"$Id: XLALCivilTime.c,v 1.7 2008/04/29 20:12:19 kipp Exp $") | |
| tm * | gmtime_r (const time_t *, struct tm *) |
| int | XLALLeapSeconds (INT4 gpssec) |
| Returns the leap seconds TAI-UTC at a given GPS second. | |
| int | XLALLeapSecondsUTC (const struct tm *utc) |
| Returns the leap seconds TAI-UTC for a given UTC broken down time. | |
| INT4 | XLALUTCToGPS (const struct tm *utc) |
| Returns the GPS seconds since the GPS epoch for a specified UTC time structure. | |
| tm * | XLALGPSToUTC (struct tm *utc, INT4 gpssec) |
| Returns a pointer to a tm structure representing the time specified in seconds since the GPS epoch. | |
| REAL8 | XLALJulianDay (const struct tm *utc) |
| Returns the Julian Day (JD) corresponding to the date given in a broken down time structure. | |
| INT4 | XLALModifiedJulianDay (const struct tm *utc) |
| Returns the Modified Julian Day (MJD) corresponding to the date given in a broken down time structure. | |
W. and Creighton, J. D. E.
Civil time structures, represented in the C library by the struct tm structure, known as a broken down time structure, gives the time by normal measures (hours, minutes, seconds since midnight, day of the month, month of the year, and year). LAL uses seconds since the the GPS epoch as its reference. The GPS epoch is defined to be 0h UTC 6 Jan 1980 in civil time. The process of converting between a civil time and a GPS time is almost done by standard C library functions, though the C library functions use a different reference epoch, which is called the UNIX epoch.
The tricky bits are:
This code does not deal with time zones at all. All civil time structures are taken to be in Coordinated Universal Time or UTC. The user must convert local times into UTC before using these routines.
Leap seconds are accounted for. But since the addition and subtraction of leap seconds is not deterministic, a leap second table needs to be maintained to account for the number of leap seconds in effect at a particular time.
Leap seconds are defined as the difference between UTC and a (yet another) standard of time called the International Atomic Time or TAI. UTC is ultimately determined by the position of the stars, so it is occationally altered by a second to keep the location of fixed points on the celestial sphere correct to within plus or minus 0.9 seconds. TAI, like the GPS time used in LAL, is just the number of seconds since some epoch and is not affected by leap seconds. The difference between TAI and UTC, TAI-UTC, is the number of leap seconds.
Note that UTC is fixed to atomic time, though there are an integer number of leap seconds. The real civil time, as measured in terms of points on the celestial sphere, is UT1. UTC and UT1 are kept within 0.9 seconds of each other by the introduction of leap seconds. But if what you want is UT1 note that UTC can be off by up to about a seconds. For this reason, we assume that accuracy at the second scale is sufficient, so the routines have only second precision. If you need more accuracy, you'll need to be monitoring UT1.
Another way of representing the civil time in in terms of Julian days. There is a routine for converting a UTC time into Julian days. The inverse conversion is not attempted.
Definition in file XLALCivilTime.c.
| NRCSID | ( | XLALCIVILTIMEC | , | |
| "$Id: XLALCivilTime. | c, | |||
| v 1.7 2008/04/29 20:12:19 kipp Exp $" | ||||
| ) |
| struct tm* gmtime_r | ( | const time_t * | , | |
| struct tm * | ||||
| ) | [read] |
| int XLALLeapSeconds | ( | INT4 | gpssec | ) |
Returns the leap seconds TAI-UTC at a given GPS second.
| gpssec | [In] Seconds relative to GPS epoch. |
Definition at line 121 of file XLALCivilTime.c.
| int XLALLeapSecondsUTC | ( | const struct tm * | utc | ) |
Returns the leap seconds TAI-UTC for a given UTC broken down time.
| utc | [In] UTC as a broken down time. |
Definition at line 142 of file XLALCivilTime.c.
| INT4 XLALUTCToGPS | ( | const struct tm * | utc | ) |
Returns the GPS seconds since the GPS epoch for a specified UTC time structure.
| utc | [In] UTC time in a broken down time structure. |
Definition at line 169 of file XLALCivilTime.c.
| struct tm* XLALGPSToUTC | ( | struct tm * | utc, | |
| INT4 | gpssec | |||
| ) | [read] |
Returns a pointer to a tm structure representing the time specified in seconds since the GPS epoch.
| utc | [Out] Pointer to tm struct where result is stored. |
| gpssec | [In] Seconds since the GPS epoch. |
Definition at line 198 of file XLALCivilTime.c.
| REAL8 XLALJulianDay | ( | const struct tm * | utc | ) |
Returns the Julian Day (JD) corresponding to the date given in a broken down time structure.
See {esaa:1992} and {green:1985} for details. First, some definitions:
Mean Julian Year = 365.25 days Julian Epoch = 1 Jan 4713BCE, 12:00 GMT (4713 BC Jan 01d.5 GMT) Fundamental Epoch J2000.0 = 2001-01-01.5 TDB
Julian Date is the amount of time elapsed since the Julian Epoch, measured in days and fractions of a day. There are a couple of complications arising from the length of a year: the Tropical Year is 365.2422 days. First, the Gregorian correction where 10 days (1582-10-05 through 1582-10-14) were eliminated. Second, leap years: years ending with two zeroes (e.g., 1700, 1800) are leap only if divisible by 400; so, 400 civil years contain 400 * 365.25 - 3 = 146097 days. So, the Julian Date of J2000.0 is JD 2451545.0, and thus the Julian Epoch = J2000.0 + (JD - 2451545) / 365.25, i.e., number of years elapsed since J2000.0.
One algorithm for computing the Julian Day is from {vfp:1979} based on a formula in {esaa:1992} where the algorithm is due to {fvf:1968} and ``compactified'' by P. M. Muller and R. N. Wimberly. The formula is
jd = 367 y - 7 (y + (m + 9)/12)/4 - 3 ((y + (m - 9)/7)/100 + 1)/4 + 275 m/9 + d + 1721029
where jd is the Julian day number, y is the year, m is the month (1-12), and d is the day (1-31). This formula is valid only for JD > 0, i.e., after -4713 Nov 23 = 4712 BCE Nov 23.
A shorter formula from the same reference, but which only works for dates since 1900 March is:
jd = 367 y - 7 (y + (m + 9)/12)/4 + 275 m/9 + d + 1721014
We will use this shorter formula since there is unlikely to be any analyzable data from before 1900 March.
References:
{esaa:1992} {Explanatory Supplement to the Astronomical Almanac}, P.~K. Seidelmann, {ed.} (University Science Books, Mill Valley, 1992)
{green:1985} R.~M. Green, {Spherical Astronomy} (Cambridge University Press, Cambridge, 1985)
{vfp:1979} T.~C. Van Flandern, and K.~F. Pulkkinen, {Astrophysical Journal Supplement Series}, {41}, 391-411, 1979 Nov.
{fvf:1968} Fliegen, and Van~Flandern, {Communications of the ACM}, {11}, 657, 1968
| utc | [In] UTC time in a broken down time structure. |
Definition at line 282 of file XLALCivilTime.c.
| INT4 XLALModifiedJulianDay | ( | const struct tm * | utc | ) |
Returns the Modified Julian Day (MJD) corresponding to the date given in a broken down time structure.
Note:
If you want a Modified Julian Day that has a fractional part, simply use the macro:
define XLAL_MODIFIED_JULIAN_DAY(utc) (XLALJulianDay(utc)-XLAL_MJD_REF)
| utc | [In] UTC time in a broken down time structure. |
Definition at line 320 of file XLALCivilTime.c.
1.5.2