NAME

ahmktim - Calculates the relation of Hitomi time invariant (TI) vs. TIME and the GTI for when the GPS is on

USAGE

ahmktim infile frqtemfile timfile outtimfile outgtifile

DESCRIPTION

The ahmktim task has two functions: 1) calculate the time invariant (TI) vs. TIME relation (using a look-up table) and 2) write the GTI for when the GPS is on. The TI vs. TIME look-up table is derived for each observation and is used to assign time to all instruments and housekeeping. The relation is calculated either using the GPS, when it is on, or the on-board clock if the GPS is off (known also as Suzaku mode). Both of these data are in the general HK file extensions (see 'infile'). To calculate TI vs. TIME, ahmktim uses the following files: a) the general HK file (see 'infile'), b) the TIM file (see 'timfile'), and c) the CALDB clock frequency vs. temperature file (see 'frqtemfile').

The GPS status is defined in the HK GPS extension (see 'hkgpsext') by 4 flags written in columns (see 'gpsacol', 'gpsbcol', 'gpsccol', and 'gpsdcol'). The combination of the 4 flags indicates if the GPS is on or off. If the GPS is on, the TI vs. TIME relation is derived using the column S_TIME (rough time that corresponds to the time when the packets are sent to the telemetry) and L32TI (lower 32 bits of the Time Indicator) in the GPS extension. If the GPS is off, the relation is derived using the "Suzaku mode", where S_TIME in the GPS extension is matched with the closest time in the temperature extension (see 'hktempext'). This temperature is then used to derive the frequency from the CALDB 'frqtemfile' and the temperature to adjust L32TI to when the GPS is off. The extension names for the GPS and temperature, as well as the column names, depend on which on board computer, SMU (A or B), is disseminating the timing information. The TI vs. TIME relationship is added as a second extension (EXTNAME = TIM_LOOKUP) of the TIM input file ('timfile'), which includes three columns: TIME, L32TI, and STATUS. The STATUS column is a 10-bit column indicating the following status:

    Bit 1:1  Legal or illegal                          0=ok, 1=not ok 
    Bit 2:3  Mode : GPS/suzaku transition              00=GPS mode, 01=Suzaku mode, 10=transition   
    Bit 4:5  Indicates status in transition region     00=monotonic, 10=skip, 11=duplicate 
    Bit 6:10 Indicates error of illegal status 
The ahmktim task calculates the GTI for when the GPS is on, using the 4 flags written in HK GPS extension.

PARAMETERS

infile = something.hk [filename]
Name of the general HK file containing the GPS and temperature extensions. If is the sequence number of an observation, this file is usually named ahgen_a0.hk.

frqtemfile = CALDB [filename CALDB|file name]
Name of the calibration file containing the frequency vs. temperature relation. If the parameter is set to CALDB, the file is read from a file in the calibration database.

timfile = tim.hk [filename]
Name of the input TIM file containing the extension TIM_PACKETS.

outtimfile = tim.fine.hk [filename]
Name of the output TIM file where the calculated TIM_LOOKUP extension is added.

outgtifile = gps.gti [filename]
Name of the output GTI file containing the intervals when the GPS is on.

(leapsecfile = REFDATA) [string CALDB|REFDATA|file name]
Name of the input leap second file. If set to CALDB or REFDATA, the file in CALDB or the REFDATA area respectively is used.

(hkgpsext = HK_SMU_A_DHFS_SIB2GEN_dhfs_tlm_attseq) [string]
Name of the extension with the GPS information, found in the general HK file (see 'infile'). The default is for SMUA (for SMUB replace the substring "SMU_A" with "SMU_B").

(hktempext = HK_SMU_A_AUX_HCE_HK2) [string]
Name of the extension with the temperature information, found in the general HK file (see 'infile'). The default is for SMUA (for SMUB replace the substring "SMU_A" with "SMU_B").

(timext = TIM_LOOKUP) [string]
Name of output extension in the TIM file.

(gaptime = 2.0) [double]
Minimum value [s] to define a gap.

(stimecol = S_TIME) [string]
Name of the column containing S_TIME in the GPS extension.

(l32ticol = L32TI) [string]
Name of the column containing L32TI in the GPS extension.

(tempcol = HCE_A_SENS_SMU_A_TEMP_CAL) [string]
Name of the column containing quartz temperature in the temperature extension. The default is for SMUA (for SMUB replace the substring "SMU_A" with "SMU_B").

(packheadcol = PACKET_HEADER) [string]
Name of the column containing the packet header. This counts consecutive packets and is compared with their relative L32TI to determine whether or not there are dropped packets between two GPS measurements, or a large gap between two measurements.

(gpsacol = SMU_A_DHFS_TI_MNG_TIM_CRNT_TIM) [string]
Name of the column containing the GPS_A on/off flag. The default is for SMUA (for SMUB replace the substring "SMU_A" with "SMU_B").

(gpsbcol = SMU_A_DHFS_TI_MNG_TIM_GPS_SYC_STAT) [string]
Name of the column containing the GPS_B on/off flag. The default is for SMUA (for SMUB replace the substring "SMU_A" with "SMU_B").

(gpsccol = SMU_A_DHFS_TI_MNG_TIM_AUT_SYC) [string]
Name of the column containing the GPS_C on/off flag. The default is for SMUA (for SMUB replace the substring "SMU_A" with "SMU_B").

(gpsdcol = SMU_A_DHFS_TI_MNG_TIM_GPS_STAT) [string]
Name of the column containing the GPS_D on/off flag. The default is for SMUA (for SMUB replace the substring "SMU_A" with "SMU_B").

(suzdrifttime = 100.) [double]
Time between TIM calibrations in Suzaku-mode. Interior anchor points are required when the duration of the unsynchronized period is greater than a time given by the suzdrifttime parameter. The interior anchor points will be separated from each other by at least suzdrift time.

(buffer = -1) [integer -1|0|N]
Rows to buffer (-1=auto, 0=none, N>0=numrows).

(clobber = no) [boolean yes|no]
Overwrites the existing output file if set to yes.

(chatter = 1) [integer 0|1|2|3]
Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]
Log filename. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]
Diagnostic output is printed out on the screen if set to yes.

(history = yes) [boolean yes|no]
Records tool parameters in HISTORY.

EXAMPLES

1. Calculate a TIM_LOOKUP and a GPS GTI that are written to the files output.tim and gps.gti, respectively. Use the general HK file (gen.hk), the CALDB file for the frequency vs. temperature, and the input TIM file (input.tim) for the SMUA.

   ahtime infile=gen.hk1 frqtemfile=CALDB timfile=input.tim outtim=output.tim outgtifile=gps.gti \
      hkgpsext=HK_SMU_A_DHFS_SIB2GEN_dhfs_tlm_attseq hktempext=HK_SMU_A_HCE_HCE_A_SENS_STS \
      tempcol=HCE_A_SENS_SMU_A_TEMP_CAL gpsacol=SMU_A_DHFS_TI_MNG_TIM_CRNT_TIM gpsbcol=SMU_A_DHFS_TI_MNG_TIM_GPS_SYC_STAT \
      gpsccol=SMU_A_DHFS_TI_MNG_TIM_AUT_SYC gpsdcol=SMU_A_DHFS_TI_MNG_TIM_GPS_STAT

SEE ALSO

LAST MODIFIED

November 1, 2023