Table of Contents
Time Routines in Icy Abstract References Introduction Intended Audience Detection of Non-native Text Files Overview If You're in a Hurry The J2000 Epoch Leapseconds Converting Time Strings to Numeric Representations Converting Numeric Representations to Time Strings Converting between Different Numeric Formats Initialization Leapseconds Kernel SPK and PCK kernels Input String Conversion Parsing Time Strings cspice_str2et Labels (A.M. and P.M.) For the Record Labels (Time Zones) For the Record Labels ( TDT, TDT, and UTC ) cspice_utc2et cspice_tparse Changing Default Behavior Abbreviated Years Default Time Systems and Time Zone Changing the Time System Time Zones Calendars Output Conversion cspice_timout cspice_et2utc cspice_etcal Converting Between Uniform Time Scales Local Solar Time Utility Routines Example Appendix A. Background Material Coordinated Universal Time (UTC) International Atomic Time (TAI) Naming the seconds of TAI --- UTC Tying UTC to the Earth's Rotation Leapseconds The Leapseconds Kernel (LSK) Ephemeris Time (ET) Barycentric Dynamical Time (TDB) Terrestrial Dynamical Time (TDT) The Relationship between TDT and TDB In the Toolkit ET Means TDB Naming the Seconds of Ephemeris Time Some Consequences of Leapseconds Computing UTC from TDB (cspice_deltet) Problems With the Formulation of DeltaET Spacecraft Clock (SCLK) Julian Date The abbreviation JD Appendix B. Parsing Time Strings An Outline of the Parser Tokenizing the Input String Combining and Removing Tokens Initial Token Processing Julian Dates Calendar Dates ISO Formats Other Calendar Formats Built in Representations Last Resort Production Rules Conclusion Appendix C: Document Revision History September 9, 2015 April 9, 2009 December 23, 2004 22 July 1997 15 October 1996 2012 JUN 14, EDW (JPL) 2009 APR 09, BVS (JPL) 30 June 1994 13 April 1992
Time Routines in Icy
For a general and very accessible discussion of time we recommend:
In addition to the discussion of time software, there are two appendices to this document. The first provides basic background material on various time systems. The second discusses the details of how time strings are parsed in the Icy system.
The Toolkit also supports conversion between spacecraft clock (SCLK) and Barycentric Dynamical Time (TDB). However, spacecraft clock conversion is mentioned only in the context of background information in Appendix A. Icy routines dealing with spacecraft clock are discussed in SCLK Required Reading (sclk.req).
Detection of Non-native Text Files
A brief description of the various time systems is given in Appendix A.
If You're in a Hurry
Loading a Leapseconds Kernel
cspice_furnsh, fileConverting strings to ET
cspice_str2et, string, et cspice_utc2et, utcstr, et cspice_tparse, tim_string, et, error_msgConverting ET to a string
cspice_timout, et, pictur, lenout, output cspice_et2utc, et, format, prec, utcstr cspice_etcal, et, stringConverting between numeric representations of time
double = cspice_unitim( epoch, insys, outsys )Runtime modification of behavior
cspice_timdef, action, item, value cspice_tsetyr, yearFormatting aid
cspice_tpictr, sample, lenout, pictur, ok, errorConverting ET to local solar time on the surface of an object.
cspice_et2lst, et, body, lon, type, hr, mn, sc, time, ampmUtilities
cspice_deltet, epoch, eptype, deltaTime constants
double = cspice_b1900() double = cspice_b1950() double = cspice_j1900() double = cspice_j1950() double = cspice_j2000() double = cspice_j2100() double = cspice_jyear() double = cspice_spd() double = cspice_tyear()
The J2000 Epoch
(As we've just seen ``J2000'' is used to name the fundamental inertial frame and a particular epoch. This can sometimes be confusing if you are not careful to distinguish the context in which the term ``J2000'' is used.)
cspice_furnsh, '<file name of leapseconds kernel>'The leapseconds kernel is discussed in more detail later in this document.
Converting Time Strings to Numeric Representations
cspice_str2et, string, etcspice_str2et computes the ephemeris epoch corresponding to an input string. The ephemeris epoch is represented as seconds past the epoch of the J2000 reference frame in the time system known as Barycentric Dynamical Time (TDB). This time system is also referred to as Ephemeris Time (ET) throughout the Icy Toolkit.
The variety of ways people have developed for representing times is enormous. It is unlikely that any single subroutine can accommodate all of the custom time formats that have arisen in various computing contexts. However, we believe that cspice_str2et correctly interprets most time formats used throughout the planetary science community. For example cspice_str2et supports ISO time formats, UNIX `date` output formats. VMS time formats, MS-DOS formats, epochs in both the A.D. and B.C. eras, time zones, etc.
If you've been using the Toolkit for a while you are probably familiar with the routine cspice_utc2et.
cspice_utc2et, string, etcspice_utc2et provides a subset of the capabilities contained in cspice_str2et. It does not recognize time zones or time systems other than the UTC system. However, it has been the work horse for time conversion within the Toolkit for many years. In version N0046 of the Toolkit it was upgraded to support ISO time formats.
If you are writing new code, we recommend that you use the routine cspice_str2et. There is no need to upgrade any of your existing code that calls cspice_utc2et. However, you may want to replace calls to cspice_utc2et with calls to cspice_str2et due to the greater flexibility of cspice_str2et.
Converting Numeric Representations to Time Strings
cspice_timout, et, pictur, lenout, outputGiven an epoch ET expressed as double precision seconds past J2000 and a format picture pictur that you would like to use as a model for the output time strings, cspice_timout produces a string representing the input ET in a format that matches the one specified by pictur with the length of the string lenout. Using cspice_timout you can produce a time string in almost any format you desire (including many that cannot be recognized by any of the Icy software). To assist in creating a format picture the routine cspice_tpictr is provided. cspice_tpictr takes a sample time string and produces the format picture that corresponds to the sample. By using cspice_tpictr and cspice_timout together you can easily produce strings in the format you are used to seeing.
Less flexible, but slightly easier to use, cspice_et2utc has been the standard Icy time formatting routine for many years.
cspice_et2utc, et, format, prec, utcstrThis routine supports several fixed formats: calendar, Julian Date (UTC), day-of-year, ISO year/month/day, and ISO year/day-of-year. You may adjust the number of digits that follow the decimal point in the seconds component (or day in the Julian Date format).
Converting between Different Numeric Formats
double = cspice_unitim( epoch, insys, outsys )
cspice_furnsh, kernel`kernel' is the name of a ``leapseconds kernel.'' Leapseconds kernels are text based kernels containing the epochs of leap seconds and other constants required by the time conversion routines.
The leapseconds kernel needs to be loaded just once per program run; normally, the leapseconds kernel is loaded in a program's initialization section.
The precise contents of the leapseconds kernel are discussed in the section ``Computing Delta ET'' below. Text kernels and the routine cspice_furnsh are discussed in more detail in KERNEL Required Reading, kernel.req.
SPK and PCK kernels
SPK files are loaded using the routine cspice_furnsh.
cspice_furnsh, '<spk file name>'PCK files are usually text based. Text based kernels are loaded by calling cspice_furnsh.
cspice_furnsh, kernelOccasionally, PCK, files are binary (DAF based) files that contain the orientation of an object with respect to an inertial frame. Binary PCK files are loaded with the routine cspice_furnsh.
cspice_furnsh, '<binary pck file name>'As with the leapseconds kernel, SPK and PCK files need to be loaded just once per program run---usually at program initialization.
Input String Conversion
string = 'Oct 1, 1996 09:12:32'However, arithmetic is most easily performed with numeric representations of time. In Icy we represent epochs as some number of double precision seconds past the J2000 epoch.
Icy contains three routines for converting strings directly to ``seconds past 2000.'' They are cspice_str2et, cspice_utc2et, and cspice_tparse. All of these routines take a string as input and produce a double precision number that gives the number of seconds past the J2000 epoch corresponding to the input string. The method of analyzing the input string and assigning meaning to its various components is identical for all three routines. This analysis is called ``parsing'' the string. All three routines, cspice_str2et, cspice_utc2et and cspice_tparse, use the CSPICE's ``foundation'' function tpartv_ to parse the input string. Each then interprets the results of tpartv_ to assign meaning to the string. Below are a number of examples of strings and the interpretation assigned to the various components.
ISO (T) Formats.
String Year Mon DOY DOM HR Min Sec ---------------------------- ---- --- --- --- -- --- ------ 1996-12-18T12:28:28 1996 Dec na 18 12 28 28 1986-01-18T12 1986 Jan na 18 12 00 00 1986-01-18T12:19 1986 Jan na 18 12 19 00 1986-01-18T12:19:52.18 1986 Jan na 18 12 19 52.18 1995-08T18:28:12 1995 na 008 na 18 28 12 1995-18T 1995 na 018 na 00 00 00Calendar Formats.
String Year Mon DOM HR Min Sec ---------------------------- ---- --- --- -- --- ------ Tue Aug 6 11:10:57 1996 1996 Aug 06 11 10 57 1 DEC 1997 12:28:29.192 1997 Dec 01 12 28 29.192 2/3/1996 17:18:12.002 1996 Feb 03 17 18 12.002 Mar 2 12:18:17.287 1993 1993 Mar 02 12 18 17.287 1992 11:18:28 3 Jul 1992 Jul 03 11 18 28 June 12, 1989 01:21 1989 Jun 12 01 21 00 1978/3/12 23:28:59.29 1978 Mar 12 23 28 59.29 17JUN1982 18:28:28 1982 Jun 17 18 28 28 13:28:28.128 1992 27 Jun 1992 Jun 27 13 28 28.128 1972 27 jun 12:29 1972 Jun 27 12 29 00 '93 Jan 23 12:29:47.289 1993* Jan 23 12 29 47.289 27 Jan 3, 19:12:28.182 2027* Jan 03 19 12 28.182 23 A.D. APR 4, 18:28:29.29 0023 Apr 04 18 28 29.29 18 B.C. Jun 3, 12:29:28.291 -017 Jun 03 12 29 28.291 29 Jun 30 12:29:29.298 2029+ Jun 30 12 29 29.298 29 Jun '30 12:29:29.298 2030* Jun 29 12 29 29.298Day of Year Formats
String Year DOY HR Min Sec ---------------------------- ---- --- -- --- ------ 1997-162::12:18:28.827 1997 162 12 18 28.827 162-1996/12:28:28.287 1996 162 12 28 28.287 1993-321/12:28:28.287 1993 231 12 28 28.287 1992 183// 12 18 19 1992 183 12 18 19 17:28:01.287 1992-272// 1992 272 17 28 01.287 17:28:01.282 272-1994// 1994 272 17 28 01.282 '92-271/ 12:28:30.291 1992* 271 12 28 30.291 92-182/ 18:28:28.281 1992* 182 18 28 28.281 182-92/ 12:29:29.192 0182+ 092 12 29 29.192 182-'92/ 12:28:29.182 1992 182 12 28 29.182Julian Date Strings
jd 28272.291 Julian Date 28272.291 2451515.2981 (JD) Julian Date 2451515.2981 2451515.2981 JD Julian Date 2451515.2981Abbreviations Used in Tables
na --- Not Applicable Mon --- Month DOY --- Day of Year DOM --- Day of Month Wkday --- Weekday Hr --- Hour Min --- Minutes Sec --- Seconds
Parsing Time Strings
The following substrings are immediately recognizable.
The case of the letters in these substrings does not matter. For example all of the various ways of writing 'TDB' ( 'TDB', 'tDB', ... 'tdb') are recognized as 'TDB'.
It is not necessary to leave space between the various substrings. For example JDTDT and JDUTC are recognized as 'JD' followed by 'TDT' and 'JD' followed by 'UTC' respectively.
To determine the meaning of the numeric tokens in the input string, a set of transformation rules are applied to the full set of tokens in the string. These transformations are repeated until the meaning of every token has been determined or until further transformations yield no new clues into the meaning of the numeric tokens. Here is an overview of the rules that are applied to the various tokens in the string.
Year Month Day Month Day Year Year Day Month
1988 June 13, 3:29:48There is nothing in this string to indicate what time system the date and time belong to. Moreover, there is nothing to indicate whether the time is based on a 24-hour clock or twelve hour clock.
In the absence of such indicators, the default interpretation of this string is to regard the time of day to be a time on a 24-hour clock in the UTC time system. The date is a date on the Gregorian Calendar (this is the calendar used in nearly all western societies).
Labels (A.M. and P.M.)
1988 June 13, 3:29:48 P.M.is still regarded as a UTC epoch. However, with the addition of the ``P.M.'' label it is now interpreted as the same epoch as the unlabeled epoch 1988 June 13, 15:29:48. Similarly
1988 June 13, 12:29:48 A.M.is interpreted as
1988 June 13, 00:29:48on the 24-hour clock.
For the Record
Labels (Time Zones)
1988 June 13, 3:29:48 P.M. PSTis interpreted as an epoch in the Pacific Standard Time system. This is equivalent to
1988 June 13, 23:29:48 UTCAll of the standard abbreviations for U.S. time zones are recognized by the time parser.
EST --- Eastern Standard Time ( UTC-5:00 ) CST --- Central Standard Time ( UTC-6:00 ) MST --- Mountain Standard Time ( UTC-7:00 ) PST --- Pacific Standard Time ( UTC-8:00 ) EDT --- Eastern Daylight Time ( UTC-4:00 ) CDT --- Central Daylight Time ( UTC-5:00 ) MDT --- Mountain Daylight Time ( UTC-6:00 ) PDT --- Pacific Daylight Time ( UTC-7:00 )In addition, any other time zone may be specified by representing its offset from UTC.
To specify an offset from UTC you need to create an offset label. The label starts with the letters `UTC' followed by a `+' for time zones east of Greenwich and `-' for time zones west of Greenwich. This is followed by the number of hours to add or subtract from UTC. This is optionally followed by a colon `:' and the number of minutes to add or subtract to get the local time zone. Thus to specify the time zone of Calcutta (which is 5 and 1/2 hours ahead of UTC) you would specify the time zone to be UTC+5:30. To specify the time zone of Newfoundland (which is 3 and 1/2 hours behind UTC) use the offset notation UTC-3:30.
For the Record
1995 December 31 23:59:60.5 (UTC) 1996 January 1, 05:29:60.5 (UTC+5:30 --- Calcutta Time) 1995 December 31, 20:29:60.5 (UTC-3:30 --- Newfoundland) 1995 December 31 18:59:60.5 (EST) 1995 December 31 17:59:60.5 (CST) 1995 December 31 16:59:60.5 (MST) 1995 December 31 15:59:60.5 (PST)
Labels ( TDT, TDT, and UTC )
In these systems there are no leapseconds; every day has exactly 86400 seconds. TDB times are written as
1988 June 13, 12:29:48 TDBTDT times are written as:
1988 June 13, 12:29:48 TDTTo add clarity or to override any changes you happen to make to the default behavior of ET2STR (see below) you may add the label ``UTC'' to any time string.
1998 Jun 13, 12:29:48 UTCNote that the system label may be placed anywhere in the time string. All of the following will be understood by the time parsing software:
TDB 1988 June 13, 12:29:48 1988 June 13, 12:29:48 TDB 1988 June 13, TDB 12:29:48
1983 June 13, 9:00:00 A.M.are treated as erroneous by cspice_utc2et.
Unlike cspice_str2et and cspice_utc2et, cspice_tparse does not make use of the Icy exception handling subsystem. Erroneous strings are diagnosed via a string---`error'. If the string `error' is returned empty (blank) no problems were detected in the input string. If `error' is returned by cspice_tparse non-blank, it contains a diagnostic message that indicates problems with the input time string.
Changing Default Behavior
cspice_tsetyr, 1972Note that this change affects the behavior of all three string conversion routines.
Default Time Systems and Time Zone
(Keep in mind that if you specify a time zone or time system label in the input time string the default time zone or system is not used. The label in the string is used to determine the time zone or time system.)
Changing the Time System
cspice_timdef, 'SET', 'SYSTEM', 'UTC' cspice_timdef, 'SET', 'SYSTEM', 'TDB' cspice_timdef, 'SET', 'SYSTEM', 'TDT'Note that setting a time system turns off any default time zone you may have set using cspice_timdef.
cspice_timdef, 'SET', 'ZONE', 'PST'Note that setting a time zone turns off any default time system you may have set via cspice_timdef.
Both the Gregorian and Julian calendars can be extended forward and backward in time indefinitely. The default behavior of cspice_str2et is to use the Gregorian calendar for all epochs. However, using cspice_timdef you can set the default calendar to one of three: GREGORIAN, JULIAN, or MIXED:
cspice_timdef, 'SET', 'CALENDAR', 'GREGORIAN' cspice_timdef, 'SET', 'CALENDAR', 'JULIAN' cspice_timdef, 'SET', 'CALENDAR', 'MIXED'The ``MIXED'' calendar assumes that calendar strings for epochs prior to October 5, 1582 belong to the Julian Calendar; strings for later epochs are assumed to belong to the Gregorian Calendar. The specification of a calendar, does not affect a previous setting of a time system or time zone. You can change the calendar used by cspice_str2et only through the routine cspice_timdef; there are no labels recognized by cspice_str2et for the various calendars.
cspice_timout, et, pictur, lenout, outputwhere
04:29:29.292 Jan 13, 1996The value of `pictur' to use to create time strings that are similar in appearance to the example string is:
pictur = 'HR:MN:SC.### Mon DD, YYYY ::RND'Most of this components in `pictur' are fairly obvious. The exception is the substring
'::RND'.This substring tells cspice_timout to round the seconds portion of the output string instead of simply truncating. (Note that the case of the letters is significant in pictur.) cspice_timout can produce strings representing epochs in the time systems (UTC, TDB, TDT) or any time zone, and on either the Julian, Gregorian Calendar or Mixed Calendar. You may round or truncate numeric components.
The rules for constructing pictur are spelled out in the header to cspice_timout. However, you may very well never need to learn these rules. Icy contains the routine cspice_tpictr that can construct a time format picture for you from a sample time string. Returning to the example above, if the following block of code is executed, pictur will contain the format picture that will yield output strings similar to our example string.
exampl = '04:29:29.292 Jan 13, 1996' cspice_tpictr, exampl, lenout, pictur, ok, errmsgThe arguments ok and error are outputs from cspice_tpictr. They are present because some strings are not recognized as time strings. cspice_tpictr recognizes the same set of time strings as do cspice_str2et, cspice_utc2et and cspice_tparse. However, if you want your output string to be in a system other than UTC you must supply the label for that system in your example string. cspice_tpictr can construct format pictures for strings that are not accepted by the string conversion routines. For example, if you would like to suppress the year in a calendar output format, you could use the following example string:
exampl = 'Jan 12, 02:28:29.### A.M. (PDT)'Even though this string is ambiguous as an epoch (there's no year specified), it is sufficient for determining a picture that describes its format. If you decide to use cspice_tpictr with inputs like this, be sure to check the output flag OK. Even though you know what is intended, cspice_tpictr may have problems with some ambiguous time strings.
Format Name Example ------ ----------- -------------------------- 'C' Calendar '1979 JUL 04 14:19:57.184' 'D' Day of Year '1979-114 // 14:19:57.184' 'J' Julian Date 'JD 2433282.529' 'ISOC' ISO Calendar '1987-04-12T16:31:12.814' 'ISOD' ISO Day of Year '1987-102T16:31:12.814'In addition, you may specify the number of decimal places in the fractional part of the seconds token or the Julian Date (three, in the examples above). Note that Julian Dates are prefaced with the character string `JD' (and are UTC Julian Dates). This allows strings generated by cspice_et2utc to be used later as inputs to cspice_utc2et or cspice_str2et.
Converting Between Uniform Time Scales
Conversion between uniform time scales can be carried out via the double precision function cspice_unitim. The uniform time scales that are supported by this routine are:
'TAI' International Atomic Time. 'TDB' Barycentric Dynamical Time. 'TDT' Terrestrial Dynamical Time. 'ET' Ephemeris time 'JDTDB' Julian Date relative to TDB. 'JDTDT' Julian Date relative to TDT. 'JED' Julian Ephemeris date. * In the @SPICE system ET is synonymous to TDB. ** In the @SPICE system JED is synonymous to JDTDB.
Local Solar Time
Formally, the local solar time at a site on a body is the difference between the planetocentric longitude of the site and the planetocentric longitude of the Sun as seen from the center of the body. The angular difference in these two longitudes is measured in hours, minutes, and seconds in the same sense that hours, minutes and seconds are used to measure right ascension--- 24 hours in 360 degrees; 60 minutes in an hour; 60 seconds in a minute. When the sun in on the zenith meridian the hour is defined to be 12. Finally, the hours increase from sunrise to sunset.
Because of these conventions, an hour of local solar time will not be of the same duration as a UTC hour. In the case of a site on Mars, a solar hour will be approximately 62 UTC minutes.
Local solar time for a specific site can be computed using the routine cspice_et2lst (ET to Local Solar Time).
Note that the data necessary to convert between UTC and ET are loaded into the kernel pool just once---typically during program initialization--- after which the conversion may be performed at any level within the program.
PRO example ;; ;; Convert between UTC and ET interactively, and convert ET ;; back to UTC in calendar format, DOY format, and as a ;; Julian date. ;; ;; Requires a leapseconds kernel. ;; SPICETRUE = 1B SPICEFALSE = 0B lenout = 80 str = '' leap = '' cont = SPICETRUE answer = '' ;; ;; Get the name of the leapseconds kernel file. ;; print, 'We need to load a leapseconds kernel.' read, leap, PROMPT = 'Kernel Name: ' ;; ;; Load the leapseconds kernel into the kernel pool. ;; cspice_furnsh, leap ;; ;; Create pictures for producing strings similar to ;; those below. ;; examp1 = 'Fri Oct 04, 08:57:28.000 (UTC) 1996' examp2 = 'Fri Oct 04, 08:57:28.000 (PST) 1996' cspice_tpictr, examp1, lenout, pictr1, ok, error cspice_tpictr, examp2, lenout, pictr2, ok, error ;; ;; Compute result for each new UTC epoch. ;; while ( cont ) do begin print, ' ' read, str, PROMPT = 'Enter a time: ' cspice_str2et, str, et print, ' ' print, FORMAT = $ '("Input time converts to ET (sec past J2000) ",F18.6)',$ et cspice_timout, et, pictr1, lenout, utc cspice_timout, et, pictr2, lenout, pst cspice_et2utc, et, 'ISOC', 3, doy cspice_et2utc, et, 'J', 7, jdutc print, ' ' print, 'ET converts back to' print, ' ' print, utc print, pst print, ' ' print, doy print, jdutc print, ' ' cont = SPICEFALSE read, answer, PROMPT = 'Do you wish to continue? ' if ( cspice_eqstr( answer, 'Y' ) ) then cont = SPICETRUE endwhile END
Appendix A. Background Material
Coordinated Universal Time (UTC)
International Atomic Time (TAI)
Naming the seconds of TAI --- UTC
'00:00:00'is midnight and is the first instant of the calendar day specified by the first three components of the UTC time.
In the Icy system UTC times are represented by character strings. These strings contain: year, month, day, hour, minute and second separated by delimiters (spaces or punctuation marks). The various delimiters and substrings between the delimiters are called the tokens of the string. A typical time string looks like
'5 OCTOBER 1986 7:20:16.122 (UTC)'The tokens of the string and the associated UTC time components are
'5' --- day 'OCTOBER' --- month '1986' --- year '7' --- hours '20' --- minutes '16.122' --- secondsThe link between any token and its corresponding UTC component is determined by examining the values of the tokens and comparing them to the other tokens. The precise rules used are spelled out in great detail in Appendix B. For now, simply be assured that the following five strings all mean the same thing and are interpreted in the same way by Icy Toolkit software.
'5 OCTOBER 1986' '1986 OCTOBER 5' '1986 5 OCTOBER' '1986 10 5' '10 5 1986'
Tying UTC to the Earth's Rotation
... DECEMBER 31 23:59:57 ... DECEMBER 31 23:59:58 ... DECEMBER 31 23:59:59 ... DECEMBER 31 23:59:60 ... JANUARY 1 00:00:00instead of the usual progression
... DECEMBER 31 23:59:57 ... DECEMBER 31 23:59:58 ... DECEMBER 31 23:59:59 ... JANUARY 1 00:00:00Should Greenwich UT1 midnight run ahead of UTC midnight by more than 0.9 seconds the IERS will announce a negative leap second. In this case one of the usual UTC hours-minutes-seconds triples will be missing from the list of UTC names. In this case the progression will be:
... DECEMBER 31 23:59:57 ... DECEMBER 31 23:59:58 ... JANUARY 1 00:00:00Since 1972 when leap seconds and the UTC system were introduced, a negative leap second has not occurred.
The Leapseconds Kernel (LSK)
LSK files conform to a flexible format called ``NAIF text kernel'' format. The SPICE file identification word provided by itself on the first line of an LSK file is ``KPL/LSK''. Both the NAIF text kernel format and SPICE file identification word are described in detail in the Kernel Required Reading document, kernel.req.
Ephemeris Time (ET)
Barycentric Dynamical Time (TDB)
Terrestrial Dynamical Time (TDT)
The Relationship between TDT and TDB
At some times in the year the TDT clock appears to run fast when compared to the TDB clock, at other times of the year it appears to run slow. Let TDB0 be some fixed epoch on the TDB clock and TDT0 be a fixed epoch on the TDT clock (TDB0 and TDT0 do not necessarily have to be the same epoch). Any epoch, EPOCH, can be represented in the following ways: as the number of seconds TDB(EPOCH), that have elapsed since TDB0 on the TDB clock; or as the number of seconds, TDT(EPOCH), that have elapsed since TDT0 on the TDT clock. If we plot the differences TDB(EPOCH) - TDT(EPOCH) against TDB(EPOCH) over all epochs, we will find that the graph is very close to a periodic function.
In Icy the difference between TDT and TDB is computed as follows:
 TDB - TDT = K * sin (E)where K is a constant, and E is the eccentric anomaly of the heliocentric orbit of the Earth-Moon barycenter. This difference, which ignores small-period fluctuations, is accurate to about 0.000030 seconds. Thus to five decimal places the difference between TDT and TDB is a periodic function with magnitude approximately 0.001658 seconds and period equal to one sidereal year.
The eccentric anomaly E is given by
 E = M + EB sin (M)where EB and M are the eccentricity and mean anomaly of the heliocentric orbit of the Earth-Moon barycenter. The mean anomaly is in turn given by
 M = M0 + M1*twhere t is the epoch TDB expressed in barycentric dynamical seconds past the epoch of J2000.
The values K, EB, M0, and M1 are retrieved from the kernel pool. These are part of the leapseconds kernel. They correspond to the ``kernel pool variables'' DELTET/K, DELTET/EB, and DELTET/M. The nominal values are:
DELTET/K = 1.657D-3 DELTET/EB = 1.671D-2 DELTET/M = ( 6.239996D0 1.99096871D-7 )
In the Toolkit ET Means TDB
Ephemeris time is given in terms of seconds past a reference epoch. The reference epoch used throughout the Toolkit is the epoch J2000 (roughly noon on January 1, 2000). Using the Toolkit software, you can find out how many seconds the J2000 epoch is from right now.
Naming the Seconds of Ephemeris Time
However, ephemeris time is described as a count of ephemeris seconds past the ephemeris reference epoch (J2000). For most of us the expression
-312819349 seconds past the ephemeris epoch J2000bears little relationship to the time system we use to organize our lives. For this reason, it is common to give names to the various ephemeris seconds in a manner analogous to the UTC naming of the seconds of TAI---as a calendar date and time of day. The above string corresponds to
'1990 FEB 1 21:44:11 (TDB)'There is an important distinction between the names given to ephemeris seconds and the names used by the UTC system. The names assigned to ephemeris times never have leap seconds. The `seconds' component of the name is restricted to and includes all values from 0 to 59.999... . Thus the time string above does not represent the same moment in time as does ``1990 FEB 1 21:44:11 (UTC)'' There are two reasons. First, ephemeris time is ahead of atomic time by 32.184 seconds. Second, when a leap second occurs UTC strings fit an extra name into the sequence of valid UTC names. Thus it appears that UTC names fall behind ET names by a second after each leapsecond. At the present time UTC time strings appear to be 62.184 seconds behind ET time strings. This appearance is due to the fact that the two naming conventions are not the same. They simply have a lot of names in common.
It is both fortunate and unfortunate that there is a huge set of common names between calendar dates ET and calendar dates UTC. Since there are relatively few leapseconds, a time given by an ET name is always close to the time in the UTC system having the same name. Thus for planning observations, you can know what day the observation will take place, whether or not you are likely to need a coat and how to arrange your daily activities around the observation. But for precise work you must pay attention to the difference between the two times systems. If in planning the observation of a stellar occultation by an asteroid the difference between the two naming systems is neglected, it is likely that the observation will be missed.
The routine cspice_str2et will convert an ephemeris calendar date to seconds past the ephemeris epoch J2000.
Some Consequences of Leapseconds
Any given Leapseconds Kernel will eventually become obsolete. Sometime after the creation of any Leapseconds Kernel there will be new leapseconds. When future leapseconds occur the old Leapseconds Kernel will no longer correctly describe the relationship between UTC, TDT and TDB for epochs that follow the new leapsecond. However, for epochs prior to the new leapsecond, the old kernel will always correctly describe the relationship between UTC, TDT and TDB.
Computing UTC from TDB (cspice_deltet)
1996, Oct 11, 12:01:02.1840 (TDT) 1996, Oct 11, 12:00:00.0000 (UTC) 1996, Oct 12, 12:01:02.1840 (TDT) 1996, Oct 12, 12:00:00.0000 (UTC) 1996, Oct 13, 12:01:02.1840 (TDT) 1996, Oct 13, 12:00:00.0000 (UTC) 1996, Oct 14, 12:01:02.1840 (TDT) 1996, Oct 14, 12:00:00.0000 (UTC) 1996, Oct 15, 12:01:02.1840 (TDT) 1996, Oct 15, 12:00:00.0000 (UTC)At least in October 1996, it's clear that if you have either TDT or UTC you can construct the corresponding representation for the same epoch in the UTC or TDT system by simply subtracting or adding 62.184 seconds.
If you don't worry about what happens during a leapsecond you can express the above idea as:
 DeltaTDT = TDT - UTCFor all epochs except during UTC leapseconds the above expression makes sense. DeltaTDT is simply a step function increasing by one after each leapsecond. Thus DeltaTDT can be viewed as a step function of either UTC or TDT.
If you rearrange this expression, you can get
 UTC = TDT - DeltaTDTSince, TDT can be expressed as seconds past J2000 (TDT), the above expression indicates the UTC can be expressed as some count of seconds. This representation is referred to by the dubious name of ``UTC seconds past J2000.'' If you write down the UTC calendar time string corresponding to an epoch and count the number of seconds between that calendar expression and the UTC calendar expression ``January 1, 2000 12:00:00'' and ignore leapseconds, you get the value of UTC in the expression above.
In practice this expression is broken down as follows:
 UTC = TDT - DeltaTA - DeltaATwhere
DeltaTA = (TDT - TAI)and
DeltaAT = DeltaTDT - DeltaTAThe value DeltaTA is a constant, its value is nominally 32.184 seconds. DeltaTA is a step function. These two variables appear in the leapseconds kernel.
If we combine equation  above with equation  from the section ``The Relationship between TDT and TDB'' we get the following expression
 TDB - UTC = DeltaTA + DeltaAT + K*sin(E)This last value is called DeltaET and is computed by the Icy routine cspice_deltet. The various values that are used in the computation of DeltaET are contained in the Leapseconds Kernel. Indeed, a Leapseconds Kernel consists of precisely the information needed to compute DeltaET. Below is a sample Leapseconds kernel.
\begindata DELTET/DELTA_T_A = 32.184 DELTET/K = 1.657D-3 DELTET/EB = 1.671D-2 DELTET/M = ( 6.239996D0 1.99096871D-7 ) DELTET/DELTA_AT = ( 10, @1972-JAN-1 11, @1972-JUL-1 12, @1973-JAN-1 13, @1974-JAN-1 14, @1975-JAN-1 15, @1976-JAN-1 16, @1977-JAN-1 17, @1978-JAN-1 18, @1979-JAN-1 19, @1980-JAN-1 20, @1981-JUL-1 21, @1982-JUL-1 22, @1983-JUL-1 23, @1985-JUL-1 24, @1988-JAN-1 ) \begintext DELTET/DELTA_T_A corresponds to DeltaTA in equation . DELTET/K corresponds to K in equation . DELTET/EB corresponds to EB in equation . DELTET/M corresponds to M0 and M1 of equation . DELTET/DELTA_AT corresponds to DeltaAT of equation . Note that this expression gives the points on the UTC scale at which DeltaAT changes.Although NAIF recommends against it, you could modify this file to alter the conversion. For example, until 1985 JPL's Orbit Determination Program (ODP) set used a value of 32.1843817 for DeltaTA, and some older CRS tapes were created using this value in the conversion from TAI to TDT. The value returned by cspice_deltet can be made compatible with these tapes by replacing the current value (32.184, exactly) with the older value. Also, JPL'S Optical Navigation Program (ONP) set does not use the periodic term (K sin E) of the difference TDB-TDT. Setting the value of K to zero eliminates this term.
Problems With the Formulation of DeltaET
1996 Jan 01, 00:01:01.6840 (TDT) 1996 Dec 31, 23:59:60.5000 (UTC)Given these two epochs, it is no longer clear what we should assign to the value TDT - UTC. Thus although equation  above provides a simple expression for computing the ``difference between UTC and TDB'', the expression fails to tell us how to convert between TDB (or TDT) and UTC during leapseconds. For this reason the Icy system does not use DeltaET when converting between TDB (or TDT) and UTC. Instead, the table of offsets corresponding to DeltaAT in the leapseconds kernel is converted to an equivalent table as shown below.
Day Number of 1971-DEC-31 TAI seconds past 2000 at beginning of 1971-DEC-31 Day Number of 1972-JAN-01 TAI seconds past 2000 at beginning of 1972-JAN-01 Day Number of 1972-JUN-30 TAI seconds past 2000 at beginning of 1972-JUN-30 Day Number of 1972-JUL-01 TAI seconds past 2000 at beginning of 1972-JUL-01 Day Number of 1972-DEC-31 TAI seconds past 2000 at beginning of 1972-DEC-31 Day Number of 1973-JAN-01 TAI seconds past 2000 at beginning of 1973-JAN-01 Day Number of 1973-DEC-31 TAI seconds past 2000 at beginning of 1973-DEC-31 . . . . . .where the day number associated with a particular calendar date is the integer number of days that have passed since Jan 01, 0001 A.D. (on the extended Gregorian Calendar).
Given an epoch to be converted between UTC and some other time system (call this other system `S'), we decompose the conversion problem into two parts:
Spacecraft Clock (SCLK)
Each spacecraft clock can be constructed differently. For Galileo the Icy spacecraft clock times looks like
p/rrrrrrrr:mm:t:e p - partition number r - rim counts m - minor frame t - real time interrupt e - mod eight countWhen asking for the matrix which describes the pointing for some structure or instrument used to perform an observation, you will usually request this information by supplying the spacecraft clock string that was used to tag the observation. This string must usually be related to UTC or ET. Consequently it is necessary to load a file of ``spacecraft clock coefficients'' that enables Icy software to transform the spacecraft clock string into one of the other time systems. This file of spacecraft clock coefficients is loaded with the routine cspice_furnsh.
A more detailed discussion of Spacecraft Clock is contained in the Required Reading file sclk.req that is included with the Icy Toolkit.
Julian Ephemeris Date is computed directly from ET via the formula
jed = cspice_j2000() + et/cspice_spd()where J2000 is a constant function that returns the Julian Ephemeris Date of the reference epoch for ET, and SPD is a constant function that gives the number or seconds per day.
Julian Date UTC has an integer value whenever the corresponding UTC time is noon.
We recommend against using the JDUTC system as it provides no mechanism for talking about events that might occur during a leapsecond. All of the other time systems discussed can be used to refer to events occurring during a leap second.
The abbreviation JD
Appendix B. Parsing Time Strings
This appendix is not for everyone. Unless you need to understand in great detail how parsing of strings is performed, you can safely skip this appendix. The discussion below is quite technical and mirrors very closely the code in tpartv_ that handles the parsing of time strings.
An Outline of the Parser
Having identified the components in the string as integers, months, weekdays, time systems, etc. An internal representation of the string is constructed. This representation is simply a list of the identified substrings in the order they are encountered. Each item in the list is called a token.
Working with the list of tokens, various rules are applied to remove some tokens and combine others into new tokens. The process of combination and removal of tokens continues until all tokens belong to a special set of ``meaningful'' tokens or until no further combinations and removals can be performed. If processing stops before all tokens are meaningful, a diagnostic message is created and the string is regarded as un-parsable. If all of the tokens are meaningful, a compatibility check is performed on the tokens to make sure that they unambiguously specify an epoch.
Once it is clear that an unambiguous epoch has been specified, the substrings corresponding to the meaningful tokens are converted into numeric representations or are noted so that the time conversion software can properly interpret the numeric components.
Almost all of the work of manipulating tokens is carried out by Icy private routines. These routines are not considered part of the Icy public interface. Feel free to read and copy these routines. However, we strongly recommend that you not call these routines in your own code since we do not guarantee backward compatibility of these routines in future releases of the Toolkit.
Tokenizing the Input String
Starting with the next unexamined character (on the first pass this is the first character in the string), scan from left to right looking for one of the following classes of substrings:
The steps above are then repeated until the entire substring has been tokenized or a failure to recognize some substring occurs. If a failure occurs the location in the string is noted and a diagnostic message is created indicating the failure in the attempt to parse the string.
When the tokenization is finished, there will be a list of tokens from which a string can be constructed that lists the class of each token. Each class of token is represented by a single character. By placing these characters in a string a simple list of token classes is maintained. The characters used for the remainder of this discussion are listed below.
Q stands for the quote character [ stands for the left parenthesis character ] stands for the right parenthesis character , stands for the comma character - stands for the dash character . stands for the decimal point character / stands for the slash character : stands for the colon character N stands for one of the symbols A.M. or P.M. O stands for the symbol UTC+ Z stands for a time zone such as PDT, PSD, CDT, b stands for a block of white space (spaces or tabs) d stands for the day of year marker (// or ::) e stands for the era (B.C. or A.D.) j stands for Julian date m stands for a month o stands for the symbol UTC- s stands for a time system (UTC, TDT, TDB) t stands the ISO date-T-time separator w stands for the day of the week i stands for a sequence of digitsThus the list of token classifications corresponding to
'1995 Jan 12 12:28:28'will be
Combining and Removing Tokens
There are 3 basic operations that can be performed on the tokenized representation:
Initial Token Processing
Any integer class tokens (`i') whose corresponding substrings represent integers greater than or equal to 1000 are reclassified as years (`Y').
Y-i-iT ........ YmD Y-i-iTi ....... YmDH Y-i-iTi:i ..... YmDHM Y-i-iTi:i:i ... YmDHMS Y-i-iTi:i:n ... YmDHMS Y-i-iTi:n ..... YmDHM Y-i-iTn ....... YmDH Y-iT .......... Yy Y-iTi ......... YyH Y-iTi:i ....... YyHM Y-iTi:i:i ..... YyHMS Y-iTi:i:n ..... YyHMS Y-iTi:n ....... YyHM Y-iTn ......... YyH i-i-iT ........ YmD i-i-iTi ....... YmDH i-i-iTi:i ..... YmDHM i-i-iTi:i:i ... YmDHMS i-i-iTi:i:n ... YmDHMS i-i-iTi:n ..... YmDHM i-i-iTn ....... YmDH i-iT .......... Yy i-iTi ......... YyH i-iTi:i ....... YyHM i-iTi:i:i ..... YyHMS i-iTi:i:n ..... YyHMS i-iTi:n ....... YyHM i-iTn ......... YyH Y --- Year m --- Month D --- Day of Month y --- Day of Year H --- Hour M --- Minute S --- SecondIf the token list contains the ISO separator (`T') but the list does not match one of the patters shown above, the input string is regarded as erroneous.
Other Calendar Formats
'[e]' ---> '*e*' (parenthesized era to era) '[w]' ---> '*w*' (parenthesized weekday to weekday) '[N]' ---> '*N*' (parenthesized AM/PM to AM/PM) '[Z]' ---> '*Z*' (parenthesized time zone to time zone) '[s]' ---> '*s*' (parenthesized time system to time system) 'ie', ---> 'Ye' (integer-era to Year-era)
Built in Representations
Y-i-it......... YmD i/i/ii:i:n..... mDYHMS Y-i-iti........ YmDH i/i/ii:n....... mDYHM Y-i-iti:i...... YmDHM i/i/ii:n....... mDYHM Y-i-iti:i:i.... YmDHMS i:i:ii-i-Y..... HMSmDY Y-i-iti:i:n.... YmDHMS i:i:ii/i/Y..... HMSmDY Y-i-iti:n...... YmDHM i:i:ii/i/i..... HMSmDY Y-i-itn........ YmDH i:i:iimY....... HMSDmY Y-i/........... Yy i:i:imiY....... HMSmDY Y-i/i:i........ YyHM i:i:ni-i-Y..... HMSmDY Y-i/i:i:i...... YyHMS i:i:ni/i/Y..... HMSmDY Y-i/i:i:n...... YyHMS i:i:ni/i/i..... HMSmDY Y-i/i:n........ YyHM i:i:nimY....... HMSDmY Y-id........... Yy i:i:nmiY....... HMSmDY Y-idi:i........ YyHM i:ii-i-Y....... HMmDY Y-idi:i:i...... YyHMS i:ii/i/Y....... HMmDY Y-idi:i:n...... YyHMS i:ii/i/i....... HMmDY Y-idi:n........ YyHM i:iimY......... HMDmY Y-it........... Yy i:imiY......... HMmDY Y-iti.......... YyH i:ni-i-Y....... HMmDY Y-iti:i........ YyHM i:ni/i/Y....... HMmDY Y-iti:i:i...... YyHMS i:ni/i/i....... HMmDY Y-iti:i:n...... YyHMS i:nimY......... HMDmY Y-iti:n........ YyHM i:nmiY......... HMmDY Y-itn.......... YyH iYd............ yY Yid............ Yy iYdi:i......... yYHM Yidi:i......... YyHM iYdi:i:i....... yYHMS Yidi:i:i....... YyHMS iYdi:i:n....... yYHMS Yidi:i:n....... YyHMS iYdi:n......... yYHM Yidi:n......... YyHM iiY............ mDY Yii............ YmD iiYi........... mDYH Yiii........... YmDH iiYi:i......... mDYHM Yiii:i......... YmDHM iiYi:i:i....... mDYHMS Yiii:i:i....... YmDHMS iiYi:i:n....... mDYHMS Yiii:i:n....... YmDHMS iiYi:n......... mDYHM Yiii:n......... YmDHM iiYn........... mDYH Yiiii.......... YmDHM iid............ Yy Yiiiii......... YmDHMS iidi:i......... YyHM Yiiiin......... YmDHMS iidi:i:i....... YyHMS Yiiin.......... YmDHM iidi:i:n....... YyHMS Yiin........... YmDH iidi:n......... YyHM Yim............ YDm iim............ YDm Yimi........... YDmH iimi........... YDmH Yimi:i......... YDmHM iimi:i......... YDmHM Yimi:i:i....... YDmHMS iimi:i:i....... YDmHMS Yimi:i:n....... YDmHMS iimi:i:n....... YDmHMS Yimi:n......... YDmHM iimi:n......... YDmHM Yimn........... YDmH iimii.......... YDmHM Yin............ YmD iimiii......... YDmHMS Ymi............ YmD iimiin......... YDmHMS Ymii........... YmDH iimin.......... YDmHM Ymii:i......... YmDHM iimn........... YDmH Ymii:i:i....... YmDHMS imY............ DmY Ymii:i:n....... YmDHMS imYi........... DmYH Ymii:n......... YmDHM imYi:i......... DmYHM Ymin........... YmDH imYi:i:i....... DmYHMS Ymn............ YmD imYi:i:n....... DmYHMS Ynm............ YDm imYi:n......... DmYHM i-Y/........... yY imYn........... DmYH i-Y/i:i........ yYHM imi............ YmD i-Y/i:i:i...... yYHMS imi:i:iY....... DmHMSY i-Y/i:i:n...... yYHMS imi:i:nY....... DmHMSY i-Y/i:n........ yYHM imi:iY......... DmHMY i-Yd........... yY imi:nY......... DmHMY i-Ydi:i........ yYHM imii........... YmDH i-Ydi:i:i...... yYHMS imii:i......... YmDHM i-Ydi:i:n...... yYHMS imii:i:i....... YmDHMS i-Ydi:n........ yYHM imii:i:n....... YmDHMS i-i-Y.......... mDY imii:n......... YmDHM i-i-Yi:i....... mDYHM imiii.......... YmDHM i-i-Yi:i:i..... mDYHMS imiiii......... YmDHMS i-i-Yi:i:n..... mDYHMS imiiin......... YmDHMS i-i-Yi:n....... mDYHM imiin.......... YmDHM i-i-it......... YmD imin........... YmDH i-i-iti........ YmDH imn............ YmD i-i-iti:i...... YmDHM inY............ mDY i-i-iti:i:i.... YmDHMS inm............ YDm i-i-iti:i:n.... YmDHMS miY............ mDY i-i-iti:n...... YmDHM miYi........... mDYH i-i-itn........ YmDH miYi:i......... mDYHM i-i/i:i........ YyHM miYi:i:i....... mDYHMS i-i/i:i:i...... YyHMS miYi:i:n....... mDYHMS i-i/i:i:n...... YyHMS miYi:n......... mDYHM i-i/i:n........ YyHM miYn........... mDYH i-idi:i........ YyHM mii............ mDY i-idi:i:i...... YyHMS mii:i:iY....... mDHMSY i-idi:i:n...... YyHMS mii:i:nY....... mDHMSY i-idi:n........ YyHM mii:iY......... mDHMY i-it........... Yy mii:nY......... mDHMY i-iti.......... YyH miii........... mDYH i-iti:i........ YyHM miii:i......... mDYHM i-iti:i:i...... YyHMS miii:i:i....... mDYHMS i-iti:i:n...... YyHMS miii:i:n....... mDYHMS i-iti:n........ YyHM miii:n......... mDYHM i-itn.......... YyH miiii.......... mDYHM i/i/Y.......... mDY miiiii......... mDYHMS i/i/Y/i:n...... mDYHM miiiin......... mDYHMS i/i/Yi:i....... mDYHM miiin.......... mDYHM i/i/Yi:i:i..... mDYHMS miin........... mDYH i/i/Yi:i:n..... mDYHMS mnY............ mDY i/i/i.......... mDY mni............ mDY i/i/ii:i....... mDYHM nmY............ DmY i/i/ii:i:i..... mDYHMSIf the token list agrees with one of the items in the above list, the double precision value corresponding to each token is computed and the parsing process halts with success.
Last Resort Production Rules
Assuming that the error checks just discussed do not produce an error diagnosis, the string is processed according to the following rules:
'i:i:i:n' ---> 'D*H*M*S' (days, hours, minutes, seconds) 'i:i:i:i' ---> 'D*H*M*S' (days, hours, minutes, seconds) 'i:i:n' ---> 'H*M*S' (hours, minutes, seconds) 'i:i:i' ---> 'H*M*S' (hours, minutes, seconds) 'i:n' ---> 'H*M' (hours, minutes) 'i:i' ---> 'H*M' (hours, minutes)
'<miiH' ---> 'mDY' (month, day, year) '<mi' ---> 'mD' (month, day) 'Siim>' ---> 'SYDm' (seconds, year, day, month) 'im>' ---> 'Dm' (day, month) 'miY>' ---> 'mDY' (month, day, year) 'Ymi' ---> 'YmD' (year, month, day) 'Smi' ---> 'SmD' (seconds, month, day) 'Mmi' ---> 'MmD' (minutes, month, day) 'imY' ---> 'DmY' (day, month, year) 'imH' ---> 'DmH' (day, month, hour) 'Yid' ---> 'Yy*' (year, day-of-year) 'iYd' ---> 'yY*' (day-of-year, year) 'Ydi' ---> 'Y*y' (year, day-of-year) The characters '<' and '>' mean that the transformation is performed only if the token list occurs at the beginning or end respectively of the token list.
Appendix C: Document Revision History
September 9, 2015
Corrected typo in the start date for the applicable period of the Gregorian calendar when the MIXED calendar option is selected. The date was changed to October 5, 1582.
Corrected formatting of the Utility Routines section: the ASCII versions of this document for Mice and Icy displayed function names truncated to 8 characters (the problem did not occur in the HTML versions).
April 9, 2009
Added a note about the SPICE file identification word for LSK files.
December 23, 2004
22 July 1997
In addition to the new routine cspice_et2lst, we document a slight extension of the set of time strings that are recognized by the Icy time software. This extension is documented in Appendix B.
15 October 1996
The following routines are new as of version N0046 of SPICELIB.
2012 JUN 14, EDW (JPL)
2009 APR 09, BVS (JPL)
30 June 1994
13 April 1992