| CHRONOS User's Guide |
Table of ContentsCHRONOS User's Guide Abstract Summary UTC Time Types ET Time Types SCLK Time Types LST Time Types Usage Usage Examples -- Mars Pathfinder Using CHRONOS with Calling Scripts or Aliases Setup File Setup File Examples Appendix 1: Aliases Mimicing MPF Time Tools Appendix 2: Input UTC and ET Time string formats Appendix 3: Output Time String Formatting Rules Appendix 4: Output DP Number Formatting Rules CHRONOS User's Guide
Abstract
Summary
UTC Time Types
ET Time Types
SCLK Time Types
3/1248531085.006
1248543443
1437200032:006:23
4A8ADDCA:48
4A2A34BB
2/4A8A5052.48.1A
LST Time Types
SOL 12 12:00:01
SOL 132 01:22:32.498
SOL 2 9
Usage
% CHRONOS -SETUP <setup file name OR kernel file name(s)>
-FROM <"from" time system>
[-FROMTYPE <"from" time type>]
-TO <"to" time system>
[-TOTYPE <"to" time type>]
[-FORMAT <output time format picture>]
-TIME <input time> | -BATCH
[-SC <sc ID>]
[-CENTER <central body ID>]
[-LANDINGTIME <UTC time of the landing>]
[-SOL1INDEX <index of the first SOL>]
[-NOLABEL]
[-TRACE]
The command line options above have the following meanings:
% CHRONOS -HELP|-H
If ``-USAGE'', ``-U'' or nothing is provided on the command line,
CHRONOS displays usage information:
% CHRONOS [-USAGE|-U]
If ``-TEMPLATE'' command line option is specified, CHRONOS displays
setup file template:
% CHRONOS -TEMPLATE
Command line parameters specified in [] are optional. Command line keys
'-XXXXXXX' are case insensitive. Any of the command line options can be
present in the command line multiple times (in such cases the last
appearance of a key takes precedence.) The order in which options are
specified is insignificant.
Usage Examples -- Mars Pathfinder
The examples below assume that a setup file ``setup.mpf'' exists and contains correct pointers to the needed MPF SPICE kernel files. To compute SCET UTC for a given HEX SCLK CHRONOS must be run with the following command line options:
> chronos -setup setup.mpf -from sclk -fromtype hex \
-to utc -totype scet -time 4A8ADDCA:48
1997-08-18 16:57:36.110 (UTC/SCET)
>
To compute LST for a given UTC/ERT CHRONOS must be run as follows:
> chronos -setup setup.mpf -from lst -to utc -totype ert \
-time SOL 12 13:00
1997-07-16 10:39:34.287 (UTC/ERT)
>
In the example above the "-FROMTYPE" option was not needed since the
time type used was the default.
The same example using the ``-NOLABEL'' option and formatting the output time ``a-la'' UNIX date command output will look like:
> chronos -setup setup.mpf -from lst -to utc -totype ert \
-time SOL 12 13:00 -nolabel \
-format 'Wkd Month DD HR:MN:SC PDT YYYY ::UTC-7'
Wed July 16 03:39:34 PDT 1997
>
Note that in the previous example the ``::UTC-7'' format modifier caused
time on the output to be Pacific Day Time (PDT) instead of Greenwich
Meridian Time (GMT) which is default time zone for UTC.
The opposite conversion with trace ON (``-TRACE'') will produce the following output (note that in this example CHRONOS recognized PDT token in the input string and processed input time as Pacific Day Time):
> chronos -setup setup.mpf -from utc -fromtype ert -to lst \
-time July 16, 1997 3:39:34 PDT -trace
CHRONOS -- Universal Time Conversion Tool
Version 1.0.0, May 14, 1998
Actual command line: -setup setup.mpf -from utc -fromtype ert
-to lst -time July 16, 1997 3:39:34 -trace
Setup file: setup.mpf
Loaded SPICE kernels:
LSK: using LSK parameters from the setup file.
SCLK: /mpf/pds/data/sclk/mpf_final.tsc
SPK: /mpf/pds/data/spk/de405.bsp
SPK: /mpf/pds/data/spk/mpf_ls.bsp
SPK: /mpf/pds/data/spk/mpf_surf.bsp
CK: /mpf/pds/data/ck/mpf_ll.bc
CK: /mpf/pds/data/ck/mpf_sf.bc
FRAMES: /mpf/pds/data/frames/mpf.tfd
PCK: using PCK parameters from the setup file.
Converting time from: UTC/ERT
to: LST/LST
Output time format: NOT APPLICABLE
Spacecraft NAIF ID: -53
Center body NAIF ID: 499
Landing date/time: 1997 JUL 5 09:00
SOL 1 midnight UTC: 1997 JUL 04 13:53:14.703
Average local second: 1.0277116753731E+00 ET seconds
July 16, 1997 3:39:34 (UTC/ERT)
SOL 12 13:00:00 (LST/LST)
>
In the next example CHRONOS is used to convert a few UTC/SCET times
provided in an external file ``input.times'' (each input time on a line
by itself with no blank line between them) to the corresponding SCLK
times written to an output file ``output.times'':
> chronos -setup setup.mpf -from utc -to sclk \
-batch -nolabel < input.times > output.times
>
If input file ``input.times'' contained the following lines:
1997-07-06 12:00:00.000 1997-07-06 13:00:00.000 1997-07-06 14:00:00.000 1997-07-06 15:00:00.000then output file ``output.times'' will contain:
3/1246881607.104 3/1246885207.101 3/1246888807.099 3/1246892407.096 Using CHRONOS with Calling Scripts or Aliases
alias utc2ert 'chronos -from utc -fromtype scet -to utc \
-totype ert -format -time'
or c-shell script ``utc2ert'':
#!/bin/csh -f
chronos -from utc -fromtype scet -to utc \
-totype ert -format -time $argv[*]
Then to perform the conversion you need to type only
> utc2ert 1998 jan 12 13:00 1998-01-12 13:18:04.672 (UTC/ERT) >Note that since for both the alias and the script a setup file name wasn't specified on the command line, CHRONOS used the name provided in the environment variable CHRONOS_SETUP_FILE. A set of aliases mimicking time tools that were used by the Mars Pathfinder project is provided in Appendix 1 at the end of the document. It doesn't cover all possible combinations of the input/output time system/type pairs but it could be easily extended to do so. Using aliases makes using CHRONOS easy, but it seems that by setting command line options in these aliases we are taking away some of the program's flexibility. This is not true. That CHRONOS allows any command line option to be specified as many times as desired (then the last appearance/value of it is used) and that blank values are permitted, allows one to use any pre-specified alias in the same way as the program itself. For example, if you want to specify a custom output format while using the ``utc2ert'' alias, it can be done with the ``-FORMAT'' command line option as it would be while using CHRONOS without any wrappers:
> utc2ert 1998 JAN 12 11:24 -format YYYY-DOY//HR:MN:SCor
> utc2ert -format YYYY-DOY//HR:MN:SC -time 1998 JAN 12 11:24or
> utc2ert -time 1998 JAN 12 11:24 -format YYYY-DOY//HR:MN:SCNote that in the first case the ``-TIME'' command line option wasn't needed because it's already present in the ``utc2ert'' alias, while in the second example it was required to tell the program that ``1998 JAN 12 11:24'' is an input time but not a part of the format string specified after ``-FORMAT''. In the third case, it seems that we have the ``-TIME'' key repeated two times because it's present in the alias and on the command line. This is not a problem for CHRONOS, it just ignores the first ``-TIME'' and the blank value which appears after it. This example can be easily extended to demonstrate other possibilities:
> utc2ert -setup setup.m98lnd -time 1998 JAN 12 11:24
> utc2ert 1998 JAN 12 11:24 -trace
> utc2ert -batch < input.times > output.times
> utc2ert -totype ett -time 1998 JAN 12 11:24
> utc2ert -setup setup.m98lnd \
-totype ett \
-trace \
-batch < input.times > output.times
Setup File
The setup file format must follow the SPICE Kernel Text file format rules, i.e. it must contain data formatted as a set of KEYWORD=VALUE assignments enclosed between
\begindata \begintextmarkers. Each assignment and marker must be on a line by itself. The following parameters may be provided in a setup file:
\begindata
LEAPSECONDS_FILE = 'name of a LSK file'
SCLK_FILE = 'name of a SCLK file for the mission'
PCK_FILE = 'name of a PCK file'
SPK_FILES = ( 'name of an SPK file', '...' )
CK_FILES = ( 'name of a CK file', '...' )
FRAMES_FILE = 'name of a frame definitions file'
SPACECRAFT_ID = NAIF ID for the spacecraft
CENTER_ID = NAIF ID for the center body
LANDING_TIME = 'UTC time of the landing'
LANDING_SOL_INDEX = SOL index of the landing
\begintext
Note that either or all of the SPACECRAFT_ID, CENTER_ID, LANDING_TIME,
and LANDING_SOL_INDEX parameters can also be provided using the command
line switches. If done so, the setup file value corresponding to a
command line value is not needed, and, if present, is ignored by the
program.
Similarly, the kernels files to be loaded can be provided using the standard SPICE interface -- with the KERNELS_TO_LOAD parameter:
\begindata
KERNELS_TO_LOAD = (
'name of a LSK file',
'name of a SCLK file ',
'name of a PCK file',
'name of an SPK file',
'...',
'name of a CK file',
'...',
'name of an FK file'
)
\begintext
or using KERNELS_TO_LOAD with additional path specification keywords --
PATH_VALUES/PATH_SYMBOLS:
\begindata
PATH_VALUES = (
'/directory/where/kernels/are'
)
PATH_SYMBOLS = (
'KERNELS'
)
KERNELS_TO_LOAD = (
'$KERNELS/name of a LSK file',
'$KERNELS/name of a SCLK file ',
'$KERNELS/name of a PCK file',
'$KERNELS/name of an SPK file',
'$KERNELS/...',
'$KERNELS/name of a CK file',
'$KERNELS/...',
'$KERNELS/name of an FK file'
)
\begintext
or even by simply listing them after the -SETUP command line switch. If
KERNELS_TO_LOAD, or KERNELS_TO_LOAD + PATH_VALUES/PATH_SYMBOLS, or
listing kernel names directly on the command line is used, specifying
the LEAPSECONDS_FILE, SCLK_FILE, PCK_FILE, SPK_FILES, CK_FILES, and
FRAMES_FILE setup file parameters is not necessary.
Note that if some data from the LSK or PCK kernels is included directly into the setup file, they get loaded into the program automatically. In such cases program checks whether required LSK values are already loaded and if so it's doesn't load external LSK file(s). Custom format for a particular time system/type pair can be specified in a setup file using keywords [SYSTEM]_{TYPE}_FORMAT, where [SYSTEM] and {TYPE} are corresponding character designations (for example: UTC_SCET_FORMAT = 'YYYY-DOY//HR:MN') Setup File Examples
MER-2 CHRONOS setup file, using FURNSH-style kernel file name specification:
\begindata
PATH_VALUES = (
'/ftp/pub/naif/MER/kernels'
)
PATH_SYMBOLS = (
'KERNELS'
)
KERNELS_TO_LOAD = (
'$KERNELS/lsk/naif0007.tls'
'$KERNELS/sclk/MER_254_SCLKSCET.00003.tsc'
'$KERNELS/pck/mars_iau2000_v0.tpc'
'$KERNELS/spk/de410.bsp'
'$KERNELS/spk/mer2_ls_ep55a2_iau2000_v1.bsp'
'$KERNELS/spk/mer2_still_at_ls_v1.bsp'
)
SPACECRAFT_ID = -254
CENTER_ID = 499
LANDING_TIME = '2004-01-04 04:20'
LANDING_SOL_INDEX = 1
\begintext
Sun GM from pck00006.tpc.
\begindata
BODY10_GM = 132712440041.939
\begintext
M98 Lander CHRONOS setup file:
\begindata
LEAPSECONDS_FILE = '/kernels/gen/lsk/naif0006.tls'
SCLK_FILE = '/kernels/m98lnd/sclk/m98lnd.test.tsc'
PCK_FILE = '/kernels/gen/pck/pck00006.tpc'
SPK_FILES = (
'/kernels/gen/spk/de405s.bsp',
'/kernels/m98lnd/spk/landsite/m98lndst.bsp'
)
SPACECRAFT_ID = -116
CENTER_ID = 499
LANDING_TIME = '1999 DEC 1 12:00'
LANDING_SOL_INDEX = 0
\begintext
MPF CHRONOS setup file:
=====================================================
CHRONOS Setup Keywords.
=====================================================
\begindata
LEAPSECONDS_FILE = '/mpf/pds/data/lsk/mpf.tls'
SCLK_FILE = '/mpf/pds/data/sclk/mpf_final.tsc'
PCK_FILE = '/mpf/pds/data/pck/mpf.tpc'
SPK_FILES = (
'/mpf/pds/data/spk/de405.bsp',
'/mpf/pds/data/spk/mpf_ls.bsp',
'/mpf/pds/data/spk/mpf_surf.bsp'
)
CK_FILES = (
'/mpf/pds/data/ck/mpf_ll.bc',
'/mpf/pds/data/ck/mpf_sf.bc'
)
FRAMES_FILE = '/mpf/pds/data/frames/mpf.tfd'
SPACECRAFT_ID = -53
CENTER_ID = 499
LANDING_TIME = '1997 JUL 5 09:00'
UTC_ERT_FORMAT = 'YYYY-DOY//HR:MN:SC.### ERT'
UTC_SCET_FORMAT = 'YYYY-DOY//HR:MN:SC.###'
ET_SCET_FORMAT = 'YYYY-DOY//HR:MN:SC.### ET-ERT'
ET_ERT_FORMAT = 'YYYY-DOY//HR:MN:SC.### ET'
\begintext
=====================================================
Required LSK parameters. Extracted from naif0006.tls.
=====================================================
\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
25, @1990-JAN-1
26, @1991-JAN-1
27, @1992-JUL-1
28, @1993-JUL-1
29, @1994-JUL-1
30, @1996-JAN-1
31, @1997-JUL-1 )
\begintext
=====================================================
Required PCK constants. Extracted from pck00006.tpc.
=====================================================
\begindata
BODY499_POLE_RA = ( 317.68143 -0.1061 0. )
BODY499_POLE_DEC = ( +52.88650 -0.0609 0. )
BODY499_PM = ( 176.901 +350.89198226 0. )
BODY10_GM = 132712440041.939
\begintext
Note that in MPF case more SPICE data is needed to support time
conversions. It even needs some CK files. The reason is that MPF Lander
location in the corresponding SPK file is given relative to the surface
fixed frame rather than relative to the center on Mars in the Mars fixed
frame as is done for the M98 Lander. Therefore, to compute the location
of the MPF Lander relative to the Sun or Earth, which is needed for
converting from/to local time or for computing ERT or ETT, CHRONOS needs
to load all SPICE kernels containing positions and frame transformation
information needed to perform such computations.
The setup file for MPF also contains DOY-style output format pictures for UTC/ERT, UTC/SCET, ERT/ERT and ER/SCET system/types. As already mentioned CHRONOS automatically loads any KEYWORD=VALUE definitions present in the setup file. This can be used to speed program execution by placing required LSK and PCK parameters in the setup file instead of making the program read them from standard LSK and PCK files which will take more time. (Loading data only from one file is is much quicker than loading data from two or three text kernels.) Appendix 1: Aliases Mimicing MPF Time Tools
ert2hex hex2ert lst2ert sclk2ert sol2ert utc2ert
ert2lst hex2lst lst2hex sclk2hex sol2hex utc2ett
ert2ltmst hex2ltmst lst2ltmst sclk2lst sol2sclk utc2hex
ert2sclk hex2sclk lst2sclk sclk2ltmst sol2utc utc2lst
ert2utc hex2utc lst2utc sclk2utc utc2lsun
utc2ltmst
utc2sclk
In the above tool names:
ert2hex hex2ert sclk2ert sol2ert utc2ert
ert2sol hex2sol sclk2hex sol2hex utc2hex
ert2sclk hex2sclk sclk2sol sol2sclk utc2sol
ert2utc hex2utc sclk2utc sol2utc utc2sclk
utc2lsun
utc2ett
can be implemented by using aliases to CHRONOS with the right
combination of command line options. Note that in aliases ``sol''
designates LST/LST rather than approximated local solar time as it was
on MPF.
The c-shell script ``mpf.chronos.aliases'' shown below sets these aliases. The aliases in the script must be made available to the UNIX c-shell by loading the script with the ``source'' command:
> source mpf.chronos.aliases``mpf.chronos.aliases'' script:
alias ert2hex 'chronos -from utc -fromtype ert \'\
'-to sclk -totype hex -time'
alias ert2sol 'chronos -from utc -fromtype ert \'\
'-to lst -totype lst -time'
alias ert2sclk 'chronos -from utc -fromtype ert \'\
'-to sclk -totype sclk -time'
alias ert2utc 'chronos -from utc -fromtype ert \'\
'-to utc -totype scet -time'
alias hex2ert 'chronos -from sclk -fromtype hex \'\
'-to utc -totype ert -time'
alias hex2sol 'chronos -from sclk -fromtype hex \'\
'-to lst -totype lst -time'
alias hex2sclk 'chronos -from sclk -fromtype hex \'\
'-to sclk -totype sclk -time'
alias hex2utc 'chronos -from sclk -fromtype hex \'\
'-to utc -totype scet -time'
alias sol2ert 'chronos -from lst -fromtype lst \'\
'-to utc -totype ert -time'
alias sol2hex 'chronos -from lst -fromtype lst \'\
'-to sclk -totype hex -time'
alias sol2sclk 'chronos -from lst -fromtype lst \'\
'-to sclk -totype sclk -time'
alias sol2utc 'chronos -from lst -fromtype lst \'\
'-to utc -totype scet -time'
alias sclk2ert 'chronos -from sclk -fromtype sclk \'\
'-to utc -totype ert -time'
alias sclk2hex 'chronos -from sclk -fromtype sclk \'\
'-to sclk -totype hex -time'
alias sclk2sol 'chronos -from sclk -fromtype sclk \'\
'-to lst -totype lst -time'
alias sclk2utc 'chronos -from sclk -fromtype sclk \'\
'-to utc -totype scet -time'
alias utc2ert 'chronos -from utc -fromtype scet \'\
'-to utc -totype ert -time'
alias utc2et 'chronos -from utc -fromtype scet \'\
'-to et -totype scet -time'
alias utc2hex 'chronos -from utc -fromtype scet \'\
'-to sclk -totype hex -time'
alias utc2sol 'chronos -from utc -fromtype scet \'\
'-to lst -totype lst -time'
alias utc2sclk 'chronos -from utc -fromtype scet \'\
'-to sclk -totype sclk -time'
alias utc2lsun 'chronos -from utc -fromtype scet \'\
'-to lst -totype lsun -time'
alias utc2ett 'chronos -from utc -fromtype scet \'\
'-to utc -totype ett -time'
Note that each of the command defined by these aliases will expect a
setup file name to be provided using the CHRONOS_SETUP_FILE environment
variable unless aliases are modified to include it on the command line
using the ``-SETUP'' option.
Appendix 2: Input UTC and ET Time string formats
The variety of ways people have developed for representing
times is enormous. It is unlikely that any single subroutine
can accommodate the wide variety of custom time formats that
have arisen in various computing contexts. However, we
believe that this routine will correctly interpret most time
formats used throughout the planetary science community.
For example this routine supports ISO time formats, UNIX
`date` output formats, VMS time formats, MS-DOS formats,
etc. One obvious omission from the strings recognized by
this routine are strings of the form
93234.1829 or 1993234.1829
Some readers may recognize this as the epoch that is 0.1829
days past the beginning of the 234'th day of 1993. However,
other readers may regard this interpretation as a bit
obscure.
Below we outline some of the rules used in the interpretation
of strings. A more complete discussion of the interpretation
of strings is given in the routine TPARTV.
Default Behavior
----------------
Consider the string
1988 June 13, 3:29:48
There 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
------
If you add more information to the string, STR2ET can then
make a more informed interpretation of the time string.
For example:
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:48
For the record: 12:00 A.M. corresponds to Midnight (00:00 on the
24 hour clock. 12:00 P.M. corresponds to Noon. (12:00) on the
24 hour clock.
You may add still further indicators to the string. For example
1988 June 13, 3:29:48 P.M. PST
is interpreted as an epoch in the Pacific Standard Time system.
This is equivalent to
1988 June 13, 07:29:48 UT
The following U.S. time zones are recognized.
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 )
Any other time zone may be specified by
representing its offset from UTC.
This notation 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: Leapseconds occur at the same time in all
time zones. In other words, the seconds component of a time
string is the same for any time zone as is the seconds
component of UTC. Thus the following are all legitimate
ways to represent an epoch of some event that occurred
in the leapsecond
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)
In addition to specifying time zones, you may specify
that the string be interpreted as a formal calendar
representation in either the Barycentric Dynamical Time system
(TDB) or the Terrestrial Dynamical Time system (TDT). In
These systems there are no leapseconds. Times in TDB
are written as
1988 June 13, 12:29:48 TDB
TDT times are written as:
1988 June 13, 12:29:48 TDT
Finally, you may explicitly state that the time system is UT
1988 June 13, 12:29:48 UTC.
Note that you may not specify two different time systems
simultaneously. For example
1988 June 13, 12:29:48 PDT TDT
You might be able to make some kind of reasonable guess as
to the meaning of this string, but we've decided to regard
such strings as errors.
Abbreviating Years
------------------
Although it can lead to confusion, many people are in the
habit of abbreviating years when they write them in dates.
For example
99 Jan 13, 12:28:24
Upon seeing such a string, most of us would regard this
as being 1999 January 13, 12:28:24 and not January 13 of
the year 99. This routine interprets years that are less
than 100 as belonging either to the 1900's or 2000's. Years
greater than 68 ( 69 - 99 ) are regarded as being an
abbreviation with the '19' suppressed (1969 - 1999). Years
smaller than 69 ( 00 - 68 ) are regarded as being an
abbreviation with the '20' suppressed (2000 - 2068).
Note that in general it is usually a good idea to write
out the year. Or if you'd like to save some typing
abbreviate 1999 as '99.
If you need to specify an epoch whose year
is less than 1000, we recommend that you specify the era
along with the year. For example if you want to specify
the year 13 A.D. write it as
13 A.D. Jan 12
When specifying the era it should immediately follow the year.
Both the A.D. and B.C. eras are supported.
Changing Default Behavior
-------------------------
As discussed above, if a string is unlabelled, it is regarded
as representing a string in the UTC time system on the
Gregorian calendar. Abbreviated years are
regarded as abbreviations of the years from 1969 to 2068.
You may modify these defaults through the routines TIMDEF
and TSETYR (an entry point of TEXPYR).
You may:
Set the calendar to be Gregorian, Julian or a mixture of
the two using TIMDEF;
Set the time system to be UTC, TDB, TDT or any time zone
using TIMDEF;
Set the range of year abbreviations to be any 100 year
interval using TSETYR.
See the routines TEXPYR and TIMDEF for details on changing
defaults.
These alterations affect only the interpretation of unlabelled
strings. If an input string is labelled the specification
in the label is used.
If some component of a date or time is "out-of-range" STR2ET
regards the string as erroneous. Below is a list of
erroneous strings and why they are regarded as such.
1997 Jan 32 12:29:29 --- there are only 31 days in January
'98 Jan 12 13:29:29 A.M. --- Hours must be between 1 and 12
inclusive when A.M. or P.M. is
specified.
1997 Feb 29, 12:29:20.0 --- February has only 28 days in
1997. This would be ok if the
year was 1996.
1992 Mar 12 12:62:20 --- Minutes must be between 0 and 59
inclusive.
1993 Mar 18 15:29:60.5 --- Seconds is out of range for this
date. It would not be out of
range for Dec 31 23:59:60.5 or
Jun 30 23:59:60.5 because these
can be leapseconds (UTC).
Specifics On Interpretation of the Input String
-----------------------------------------------
The process of examining the string to determine its meaning
is called "parsing" the string. The string is parsed by first
determining its recognizable substrings (integers, punctuation
marks, names of months, names of weekdays, time systems, time
zones, etc.) These recognizable substrings are called the
tokens of the input string. The meaning of some tokens are
immediately determined. For example named months, weekdays and
time systems have clear meanings. However, the meaning of
a numeric component must be deciphered from its magnitude
and location in the string relative to the immediately recognized
components of the input string.
To determine the meaning of the numeric tokens in the input
string, a set of "production rules" and transformations 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.
1) Unless the substring 'JD' or 'jd' is present, the string is
assumed to be a calendar format (day-month-year or year and
day of year). If the substring JD or jd is present, the
string is assumed to represent a Julian date.
2) If the Julian date specifier is not present, any integer
greater than 999 is regarded as being a year specification.
3) A dash '-' can represent a minus sign only if it precedes
the first digit in the string and the string contains
the Julian date specifier (JD). (No negative years,
months, days, etc are allowed).
4) Numeric components of a time string must be separated
by a character that is not a digit or decimal point.
Only one decimal component is allowed. For example
1994219.12819 is sometimes interpreted as the
219th day of 1994 + 0.12819 days. STR2ET does not
support such strings.
No exponential components are allowed. For example you
can't input 1993 Jun 23 23:00:01.202E-4 you have
to explicitly list all zeros that follow the decimal
point: i.e. 1993 Jun 23 23:00:00.0001202
5) The single colon (:) when used to separate numeric
components of a string is interpreted as separating
Hours, Minutes, and Seconds of time.
6) If a double slash (//) or double colon (::) follows
a pair of integers, those integers are assumed to
represent the year and day of year.
7) A quote followed by an integer less than 100 is regarded
as an abbreviated year. For example: '93 would be regarded
as the 93rd year of the reference century. See TEXPYR
for further discussion of abbreviated years.
8) An integer followed by 'B.C.' or 'A.D.' is regarded as
a year in the era associated with that abbreviation.
9) All dates are regarded as belonging to the extended
Gregorian Calendar (the Gregorian calendar is the calendar
currently used by western society). See the routine TIMDEF
to modify this behavior.
10) If the International Standard Organization (ISO)
date-time separator (T) is present in the string
ISO allowed token patterns are examined for a match
with the current token list. If no match is found the
search is abandoned and appropriate diagnostic messages
are generated.
11) If two delimiters are found in succession in the time
string, the time string is diagnosed as an erroneous
string. ( Delimiters are comma, white space, dash, forward
slash, period, day of year mark "//" or "::" )
Note the delimiters do not have to be the same. The pair
of characters ",-" counts as two successive delimiters.
12) White space and commas serve only to delimit tokens in the
input string. They do not affect the meaning of any
of the tokens.
13) If an integer is greater than 1000 (and the 'JD' label
is not present, the integer is regarded as a year.
14) When the size of the integer components does not clearly
specify a year the following patterns are assumed
Calendar Format
Year Month Day
Month Day Year
Year Day Month
Where Month is the name of a month, not its numeric
value.
When integer components are separated by slashes (/)
as in 3/4/5. Month, Day, Year is assumed (2005 March 4)
Day of Year Format.
If a day of year marker is present (// or ::) the
pattern
I-I// or I-I:: (where I stands for an integer)
is interpreted as Year Day-of-Year. However, I-I/ is
regarded as ambiguous.
Examples
--------
Below is a sampling of some of the time formats that
are acceptable as inputs to STR2ET and the way they
are interpreted. A complete discussion
of permissible formats is given in the SPICE routine
TPARTV as well as in this document reference file time.req
located in the /doc directory of the toolkit. "na"
means Not Applicable.
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
1986-01-18T12:19:52.18Z 1986 Jan na 18 12 19 52.18
1995-08T18:28:12 1995 na 008 na 18 28 12
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 to two digits with or without a leading quote
as in 'xy or xy (such as '92 or 92) is to treat the year as
19xy if xy > 68 and to treat it as 20xy otherwise. Thus '70
is interpreted as 1970 and '67 is treated as 2067. However,
you may change the "split point" and centuries through use
of the SPICE routine TSETYR. 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. The routines
TIMDEF and STR2ET, used together, also support conversions
from Julian Calendar epochs to 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.
Any integer greater than 1000 is regarded as a year
specification. Thus 1001-1821//12:28:28 is interpreted as
specifying two years and will be rejected as ambiguous.
...
Appendix 3: Output Time String Formatting Rules
A format picture is simply a string of letters that lets TIMOUT know where various components of a time representation should be placed during creation of the time string. Here's an example of such a picture: MON DD,YYYY HR:MN:SC.#### (TDB) ::TDB Here is a sample of times that would be created by using this format. JAN 12,1992 12:28:18.2772 (TDB) FEB 13,1994 23:18:25.2882 (TDB) AUG 21,1995 00:02:00.1881 (TDB) As you can see from the samples above, the format picture specifies that every time string created should begin with a three-letter abbreviation for the month, followed by a space and the day of the month. The day of month is followed immediately by a comma and the year. The year component is followed by two spaces. The next outputs are hours represented as a two digit integer, a colon, minutes as represented a two digit integer, another colon, and seconds rounded to 4 decimal places and having a two digit integer part. This is followed by a space and the string (TDB). The special marker `::TDB' in the time picture is an ``invisible'' marker. It is used to specify the time system that should be used in creating the time string (in this case Barycentric Dynamical Time). TIMOUT does not recognize all of the parts of the time format picture in the example above. The list of recognized parts and unrecognized parts is shown in the table below. Recognized Unrecognized ---------- ------------ 'MON' ' ' 'DD' ',' 'YYYY' ' ' 'HR' ':' 'MN' '(TDB)' 'SC' '.####' '::TDB' The unrecognized parts are called literal markers. They are copied exactly as they appear in PICTUR into the output string. The recognized parts of the picture are replaced by a component of time or, as in the case of `::TDB', are used as instructions about the overall properties of the time string. The full list of recognized markers, their classification and meaning are given below. MARKER CLASS MEANING ----------- -------- ----------------------------------------- '.##...' modifier represent a numeric component that immediately precedes this in a decimal format. Number of decimal places equals the number of '#' characters '::GCAL' meta dates are reported in Gregorian Calendar '::JCAL' meta dates are reported in Julian Calendar '::MCAL' meta dates after 15 October, 1582 are reported in Gregorian Calendar, before that dates are reported in Julian Calendar '::RND' meta round output to places specified by least significant component '::TDB' meta all components should be TDB '::TDT' meta all components should be TDT '::TRNC' meta truncate all output components (default) '::UTC' meta all components should be UTC (default) '::UTC+h:m' meta all components in UTC offset by +h (hours) and +m (minutes) so as to allow time zones. '::UTC-h:m' meta all components in UTC offset by -h (hours) and -m (minutes) so as to allow time zones. 'AMPM' string String (either 'A.M.' or 'P.M.') indicating whether hours are before or after noon. 'ampm' string String (either 'a.m.' or 'p.m.') indicating whether hours are before or after noon. 'AP' numeric AM/PM equivalents of the hour component of a time. 'DD' numeric Day of month 'DOY' numeric Day of year 'ERA' string String (either 'B.C.' or 'A.D.') giving era associated with an epoch. 'era' string String (either 'b.c.' or 'a.d.') giving era associated with an epoch. 'HR' numeric hour component of time 'JULIAND' numeric Julian date component of time 'MM' numeric numeric representation of month component 'MN' numeric minute component of time 'MON' string upper case three letter abbreviation for month 'Mon' string capitalized three letter abbreviation for month 'mon' string lower case three letter abbreviation for month 'MONTH' string upper case full name of month 'Month' string capitalized full name of month 'month' string lower case full name of month 'SC' numeric seconds component of time 'SP1950' numeric seconds past 1950 component of time 'SP2000' numeric seconds past 2000 component of time 'YR' numeric last two digits of year component of time 'YYYY' numeric year component of time 'WEEKDAY' string upper case day of week 'Weekday' string capitalized day of week 'weekday' string lower case day of week 'WKD' string upper case three letter abbreviation for day of week. 'Wkd' string capitalized three letter abbreviation for day of week. 'wkd' string lower case three letter abbreviation for day of week. String Markers String markers are portions of the format picture that will be replaced with a character string that represents the corresponding component of a time. Numeric Markers Numeric markers are portions of the format picture that will be replaced with a decimal string that represents the corresponding component of a time. Meta Markers Meta markers (listed under the class ``meta'' in the table above) are used to indicate `global' properties of your time string. You may specify time scale and how rounding should be performed on the components of time in your output string. Meta markers may be placed anywhere in your format picture. They do not contribute to placement of characters in output time strings. Also there are no restrictions on how many meta markers you may place in the format picture. However, if you supply conflicting `meta' markers (for example ::TDT and ::TDB) in your picture the first marker listed (in left to right order) overrules the conflicting marker that appears later in the picture. Default Meta Markers If you do not specify a time system, calendar, or time zone through the use of a Meta Marker, TIMOUT uses the values returned by the SPICE routine TIMDEF. The default time system, calendar returned by TIMDEF are UTC and the Gregorian calendar. The default time zone returned by TIMDEF is a blank indicating that no time zone offset should be used. See the header for the routine TIMDEF for a more complete discussion of setting and retrieving default values. Modifier Markers The numeric markers listed in the table above stand for integers unless they are modified through use of a modifier marker. The strings .# .## .### .#### are used to this end. When a numeric marker is followed immediately by one of these modifiers, the corresponding time component will be written with the number of decimal places indicated by the number of successive occurrences of the character '#'. Any numeric token may be modified. Rounding vs. Truncation The meta markers ::TRNC and ::RND allow you to control how the output time picture is rounded. If you specify ::TRNC all components of time are simply truncated to the precision specified by the marker and any modifier. If you specify ::RND the output time is rounded to the least significant component of the format picture. The default action is truncation. Whether an output time string should be rounded or truncated depends upon what you plan to do with the string. For example suppose you simply want to get the calendar date associated with a time and not the time of day. Then you probably do not want to round your output. Rounding 1992 Dec 31, 13:12:00 to the nearest day produces 1993 Jan 1. Thus in this case rounding is probably not appropriate. However, if you are producing output for plotting using Julian Date, seconds past 1950 or seconds past 2000, you will probably want your output rounded so as to produce a smoother plot. Time Systems TIMOUT can produce output strings for epochs relative to any of the three systems UTC, TDT, or TDB. If you do not explicitly specify a time system, TIMOUT will produce strings relative to the time system returned by the SPICE routine TIMDEF. Unless you call TIMDEF and change it, the default time system is UTC. However, by using one of the Meta Markers ::UTC, ::TDT, or ::TDB you may specify that TIMOUT produce time strings relative to the UTC, TDT, or TDB system respectively. Time Zones The meta markers ::UTC+h:m and ::UTC-h:m allow you offset UTC times so that you may represent times in a time zone other than GMT. For example you can output times in Pacific Standard time by placing the meta-marker ::UTC-8 in your format picture. For instance, if you use the picture YYYY Mon DD, HR:MN:SC ::UT you will get output strings such as: 1995 Jan 03, 12:00:00 If you use the picture YYYY Mon DD, HR:MN:SC ::UTC-8 you will get output strings such as: 1995 Jan 03, 04:00:00 Finally, if you use the picture YYYY Mon DD, HR:MN:SC ::UTC-8:15 you will get output strings such as 1995 Jan 03, 03:45:00 Note that the minutes are always added or subtracted based on the sign present in the time zone specifier. In the case of ::UTC+h:m, minutes are added. In the case ::UTC-h:m, minutes are subtracted. The unsigned part of the hours component can be no more than 12. The unsigned part of the minutes component can be no more than 59. Calendars The calendar currently used by western countries is the Gregorian calendar. This calendar begins on Oct 15, 1582. Prior to Gregorian calendar the Julian calendar was used. The last Julian calendar date prior to the beginning of the Gregorian calendar is Oct 5, 1582. The primary difference between the Julian and Gregorian calendars is in the determination of leap years. Nevertheless both can be formally extended backward and forward in time indefinitely. By default TIMOUT uses the default calendar returned by TIMDEF. Under most circumstances this will be the Gregorian calendar (::GCAL). However you may specify that TIMOUT use a specific calendar through use of one of the calendar Meta Markers. You may specify that TIMOUT use the Julian calendar (::JCAL), the Gregorian calendar (::GCAL) or a mixture of both (::MCAL). If you specify ::MCAL, epochs that occur after the beginning of the Gregorian calendar will be represented using the Gregorian calendar and epochs prior to the beginning of the Gregorian calendar will be represented using the Julian calendar. Getting Software to Construct Pictures for You. Although it is not difficult to construct time format pictures, you do need to be aware of the various markers that may appear in a format picture. There is an alternative means for getting a format picture. The routine TPICTR constructs format pictures from a sample time string. For example, suppose you would like your time strings to look like the basic pattern of the string below. 'Fri Jul 26 12:22:09 PDT 1996' You can call TPICTR with this string, and it will create the appropriate PICTUR for use with TIMOUT. CALL TPICTR ( 'Fri Jul 26 12:22:09 PDT 1996', PICTUR, OK ) The result will be: 'Wkd Mon DD HR:MN:SC (PDT) ::UTC-7' Note: not every date that you can read is interpretable by TPICTR. For example, you might be able to understand that 19960212121116 is Feb 2 1996, 12:11:16. However, TPICTR cannot recognize this string. Thus it is important to check the logical output OK to make sure that TPICTR was able to understand the time picture you provided. Even thought TPICTR can not recognize every time pattern that has been used by various people, it does recognize nearly all patterns that you use when you want to communicate outside your particular circle of colleagues. ... Appendix 4: Output DP Number Formatting Rules
Format Picture Construction Rules --------------------------------- A format picture is a string used to describe the format of the output string. There are four special characters recognized by DPFMT --- a leading + or -, a leading zero ( '0' ) or a zero that follows a leading + or -, and the first decimal point of the string. All other non-blank characters are regarded as equivalent. The picture ends at the first blank character. The effects associated with the various characters in a picture are spelled out in the description of the output STRING. The following pictures are treated as errors. ' ', '+', '-', '.', '+.', '-.' If the first character of the picture is a minus sign, the first character in the output string will be a blank if the number is non-negative, a minus sign if the number is negative. If the first character of the picture is a plus sign, the first character of the output string will be a plus if the number is positive, a blank if the number is zero, and a minus sign if the number is negative. If the first character of the string is NOT a sign (plus or minus) the first character of the output string will be a minus sign if the number is negative and will be the first character of the integer part of the number otherwise. The integer portion of STRING will contain the same number of characters as appear before the decimal point (or last character if there is no decimal point) but after a leading + or -. If the picture begins with any of the following '+0', '-0', or '0' it is said to have a leading zero. If a picture has a leading zero and the integer portion is not large enough to fill up the integer space specified by PICTUR, STRING will be zero padded from the sign (if one is required) up to the first character of the integer part of the number. If picture does NOT have a leading zero and the integer portion is not large enough to fill up the space specified by PICTUR, STRING will be blank padded on the left between the sign (if one is required) and the first character of the integer part of the number. If a decimal point ( '.' ) is present in PICTUR it will be present following the integer portion of STRING. Moreover, the decimal portion of STRING will contain the same number of digits as there are non-blank characters following the decimal point in PICTUR. However, only the first 14 digits starting with the first non-zero digit are meaningful. If the format specified by PICTUR does not provide enough room for the integer portion of X, the routine determines whether or not the number of characters present in the picture is sufficient to create a representation for X using scientific notation. If so, the output is displayed using scientific notation (leading signs if they are present in PICTUR, will also appear in STRING). If the format specified by PICTUR is too short to accommodate scientific notation, the output string is filled with '*' to the same length as the length of PICTUR. Leading signs are not preserved in this overflow case. Examples -------- Suppose that X has the binary representation of PI. Then the table below illustrates the strings that would be produced by a variety of different pictures. PICTUR | STRING ------------------------------- '0x.xxx' | '03.142' 'xx.xxx' | ' 3.142' '+xxx.yyyy' | '+ 3.1416' '-.yyyy' | '******' 'xxxxxxxx' | ' 3' '00xx' | '0003' '-00.0000000' | ' 03.1415927' '00' | '03' 'x.' | '3.' '.mynumber' | '3.142E+00' 'my dog spot' | ' 3' 'my.dog spot' | ' 3.142' '+my.dog,spot' | '+ 3.14159265' Suppose that X has the binary representation of 2/3. Then the table below illustrates the strings that would be produced by a variety of different pictures. PICTUR | STRING ------------------------------- '+x.xxx' | '+0.667' '+xx.xxx' | '+ 0.667' 'xxx.yyyy' | ' 0.6667' '.yyyy' | '.6667' 'xxxxxxxx' | ' 1' '00xx' | '0001' '-0.0000000' | ' 0.6666667' '00' | '01' 'x.' | '1.' 'mynumber' | ' 1' 'my dog spot' | ' 1' 'my.dog spot' | ' 0.667' 'my.dog,spot' | ' 0.66666667' Suppose that X has the binary representation of -8/9. Then the table below illustrates the strings that would be produced by a variety of different pictures. PICTUR | STRING ------------------------------- '+x.xxx' | '-0.889' '-00.xxxx' | '-00.8889' 'xxx.xxx' | ' -0.889' '000.000' | '-00.889' |