NAME

swifttime -- Swift Time Converter

USAGE

swifttime intime=<string> insystem=<string> informat=<string> outsystem=<string> outformat=<string>

DESCRIPTION

This script converts times between different time systems/formats (listed in NOTES, below). When applicable a correction to the spacecraft clock is determined and (optionally) applied during the conversion (details below).

PARAMETERS

intime [string]
Time/Date string to be converted (2001.0 UTC or beyond).

insystem [enumerated string]
Time system of input time (MET, TT, or UTC)

informat [enumerated string]
Format of input time string (see explanation of formats below)

outsystem [enumerated string]
Time system for output (converted) time (MET, TT, or UTC)

outformat [enumerated string]
Format of output (converted) time string (see explanation of formats below)

(swcofile = CALDB) [string]
Specifies the "Swift Clock Offset" file to be used. This may be given as an absolute path name (ie, beginning with a '/'), a relative path name (which will be searched for in TIMING_DIR and then in LHEA_DATA), or as "CALDB" in which case the CALDB will be queried for an appropriate file. The task can handle either FITS or ascii clock offset file formats. If the requested time falls outside of the range of the file a message to that effect will be displayed. The tool will extrapolate beyond the end of this file to estimate the clock correction, subject to the limits set by the "extrapolate" parameter (see below).

(allowcorr = yes) [boolean]
Allow the computed Swift spacecraft clock correction (if any) to be applied during the conversion. Note that leap seconds are always included, independent of this parameter.

(extrapolate = 90.0) [real]
Limits the number of days over which the tool will extrapolate to determine the clock correction. If within this limit the tool will estimate the clock correction for the requested time based on the last available correction in the file referenced via the "swcofile" parameter (see above) along with an assumption for the current clock drift rate (which is roughly 1 second per year). For maximum accuracy in time conversion one should always use the latest clock correction file.

(outtime = ) [string - OUTPUT]
The final converted time is stored in this output parameter. It is also printed on the screen if the chatter parameter has a value of 3 or more.

(corr = ) [real - OUTPUT]
The clock correction (in seconds) that applies at the specified time. This correction should be added to the spacecraft time when converting to UTC/TT. The "corrapp" parameter (below) indicates whether this correction was included in the conversion or not.

(corrapp = ) [boolean - OUTPUT]
This output parameter is set to "yes" if the Swift clock correction has been included in the output time.

(chatter = 3) [enumerated integer]
Standard HEAdas chatter parameter (1-5) controlling the verbosity of the task. A value of zero supresses all screen output.

NOTES

Only strictly valid for times after the Swift epoch (2001.0 UTC). Pre-epoch dates should yield correct number of negative seconds, but will not include pre-epoch leap seconds.

In the normal case (i.e., for dates after 2001.0 UTC) leap seconds are always accounted for in the conversion regardless of the setting of the "allowcorr" parameter.

This tool is a Perl wrapper to the standalone tool "sTime2" which is based on a tool originally written for RXTE by Arnold Rots. The time system and formats are enumerated lists with only specific values allowed. They are:

timesys
-------
  m  MET
  t  TT
  u  UT

timefmt
-------
  s  Seconds since 2001.0 (decimal)                -  e.g., 135153600
  n  Mission day number, hours, minutes, seconds   -  e.g., 1564:06:40:00
  f  Decimal mission day                           -  e.g., 1564.2778
  d  Year and day number, hours, minutes, seconds  -  e.g., 2005:104:06:40:00
  c  Calendar date and time                        -  e.g., "2005Apr14 at 06:40:00"
  j  Julian Day                                    -  e.g., 2453474.778
  m  Modified Julian Day (= JD - 2400000.5)        -  e.g., 53474.2778
This tool equates "MET" with "Spacecraft Clock Time". Therefore the Swift clock correction is only applied if the user is converting either to or from MET to another time system (ie, TT or UTC). The clock correction can be always be supressed by setting the hidden "allowcorr" parameter to "no" at runtime.

SEE ALSO

LAST MODIFIED

Oct 2008