Table of contents
CSPICE_UTC2ET converts an input time from Calendar or Julian Date format,
UTC, to ephemeris seconds past J2000.
Given:
utcstr an input time string, containing a Calendar or Julian Date,
UTC.
help, utcstr
STRING = Scalar
Any input string acceptable to the SPICELIB routine TPARTV
are acceptable to cspice_utc2et. The length of `utcstr'
should not exceed 80 characters.
the call:
cspice_utc2et, utcstr, et
returns:
et the equivalent of `utcstr', expressed in ephemeris seconds
past J2000.
help, et
DOUBLE = Scalar
If an error occurs, or if the input string is ambiguous, `et'
is not changed.
None.
Any numerical results shown for these examples may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) Below is a sampling of some of the time formats that
are acceptable as inputs to cspice_utc2et. A complete discussion
of permissible formats is given in the SPICELIB routine
TPARTV as well as the User's reference file time.req
located in the "doc" directory of the toolkit.
ISO (T) Formats (with or without trailing "Z").
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.18Z 1986 Jan na 18 12 19 52.18
1995-08T18:28:12Z 1995 na 008 na 18 28 12
1995-18T 1995 na 018 na 00 00 00
0000-01-01T 1 BC Jan na 01 00 00 00
Calendar 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.298
Day 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.182
Julian Date Strings
jd 28272.291 Julian Date 28272.291
2451515.2981 (JD) Julian Date 2451515.2981
2451515.2981 JD Julian Date 2451515.2981
Abbreviations Used in Tables
na --- Not Applicable
Mon --- Month
DOY --- Day of Year
DOM --- Day of Month
Wkday --- Weekday
Hr --- Hour
Min --- Minutes
Sec --- Seconds
* The default interpretation of a year that has been
abbreviated with a leading quote as in 'xy (such as '92) is
to treat the year as 19xy if xy > 68 and to treat it is
20xy otherwise. Thus '69 is interpreted as 1969 and '68 is
treated as 2068. However, you may change the "split point"
and centuries through use of the Icy routine cspice_tsetyr
which is a routine in the Icy module TEXPYR. See
that routine for a discussion of how you may reset the
split point.
** All epochs are regarded as belonging to the Gregorian
calendar. We formally extend the Gregorian calendar
backward and forward in time for all epochs. If you have
epochs belonging to the Julian Calendar, consult the
SPICELIB routines TPARTV and JUL2GR for a discussion
concerning conversions to the Gregorian calendar and `et'.
+ When a day of year format or calendar format string is
input and neither of the integer components of the date is
greater than 1000, the first integer is regarded as being
the year.
2) Convert a calendar date in UTC string format to Julian
Ephemeris date.
Use the LSK kernel below to load the leap seconds and time
constants required for the conversions.
naif0012.tls
Example code begins here.
PRO utc2et_ex2
;;
;; Load a leapseconds kernel.
;;
cspice_furnsh, 'naif0012.tls'
;;
;; Set the time string.
;;
utcstr = 'December 1, 2004 15:04:11'
;;
;; Make the call.
;;
cspice_utc2et, utcstr, et
print, 'Calendar time in UTC : ', utcstr
print, FORMAT='(" corresponding ET (s): ",F25.9)', et
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_kclear
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Calendar time in UTC : December 1, 2004 15:04:11
corresponding ET (s): 155185515.183104306
Note: NAIF recommends the use of cspice_str2et instead of cspice_utc2et.
This routine handles that task of converting strings
representing epochs in the UTC system to ephemeris seconds
(TDB) past the epoch of the J2000 frame.
Although this routine is intended primarily for the
conversion of epochs during the "space age" it may also
be used to convert much earlier epochs. However, before
using this routine to convert epochs prior to 1972
you must be sure that the assumptions made by in the
implementation are consistent with the accuracy of
the input calendar string.
As noted in the -Exceptions section, this routine does not attempt
to account for variations in the length of the second that were
used prior to Jan 1, 1972. Instead each "UTC" day prior to
Jan 1, 1972 is assumed to have exactly 86400 TDT seconds.
Ancient Epochs
--------------
The calendar used today, the Gregorian calendar, has its
initial epoch on 15 October, 1582. Prior to that epoch the
Julian calendar was used for the recording of epochs.
October 15, 1582 (Gregorian) corresponds to
October 05, 1582 (Julian). From the point of view of the
implementation of this routine, all epochs belong to the
Gregorian calendar extended indefinitely backward in time.
If you need to obtain ephemeris seconds past the J2000 epoch
from Julian Calendar strings, we suggest that
you make use of the Icy routine cspice_str2et.
1) If the input time string is ambiguous, the error
SPICE(INVALIDTIMESTRING) is signaled by a routine in the call
tree of this routine.
2) This routine does not attempt to account for variations
in the length of the second that were in effect prior
to Jan 1, 1972. For days prior to that date, we assume
there are exactly 86400 ephemeris seconds.
3) If the input argument `utcstr' is undefined, an error is
signaled by the IDL error handling system.
4) If the input argument `utcstr' is not of the expected type, or
it does not have the expected dimensions and size, an error is
signaled by the Icy interface.
5) If the output argument `et' is not a named variable, an error
is signaled by the Icy interface.
None.
1) The conversion between ET and UTC depends on the values in the
input kernel pool. The kernel pool should be loaded prior to
calling this routine.
2) Before using this routine for epochs prior to Jan 1, 1972
be sure to check the -Particulars section to make sure
that the assumptions made in this routine are consistent
with the accuracy you require for your application.
ICY.REQ
KERNEL.REQ
TIME.REQ
[1] J. Jespersen and J. Fitz-Randolph, "From Sundials to Atomic
Clocks, Understanding Time and Frequency," Dover
Publications, Inc. New York, 1982.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.3, 13-AUG-2021 (JDR) (EDW)
Header edits to expand description of ISO format.
Edited the header to comply with NAIF standard.
Added example's problem statement and reference to the required LSK.
Reformatted example's output. Added second example.
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.0.2, 04-NOV-2008 (EDW)
Expanded and improved header
-Icy Version 1.0.1, 27-MAR-2006 (EDW)
Corrected a typo in the -Examples section, 'time_str'
in the cspice_utc2et replaced with 'utcstr'.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
utc to ephemeris time
|