NAME

rslmxsgti - Generate coarse and fine GTI files for the XRISM Resolve MXS, and populate the appropriate columns of a Resolve HK file with MXS start and stop times for the different LED sources using rslmxstime; invert the GTI using gtiinvert, and create merged GTI

USAGE

rslmxsgti infilehk outfilehk finegti coarsegti timfile

DESCRIPTION

The Modulated X-ray Source (MXS) consists of two redundant pairs of LEDs. Each pair has one direct source and one indirect fluorescent source that illuminate the pixels of the Resolve array with a specific pulse length and time spacing (duty cycle).

The rslmxsgti task is a script that runs the rslmxstime and gtiinvert tasks. The rslmxstime task does two operations: (1) it reads an input HK file and assigns MXS start and stop times, which it inserts into the output HK file; and (2) it creates coarse and fine GTI files. If the parameter 'calctime=no' rslmxstime does not re-calculate MXS start and stop times, in which case the MXS start and stop times must already have been assigned. The GTI files are created by default, but this step can be suppressed by specifying 'calcgti=no'.

Information used to compute the GTI comes from HK columns specified by the parameters 'tioncol', 'tioffcol', 'plslencol', 'plsspccol', and 'iledcol'.

The coarse GTI file gives the time intervals when the MXS LED sources are switched on. The fine GTI file gives the time intervals of the LED pulses, during which time the detector is illuminated by calibration photons. The GTI are derived from the values of columns in the input Resolve HK, TIM, and DELAY files.

After running rslmxstime, rslmxsgti applies the gtiinvert task to the coarse and fine GTI in order to calculate two more sets of GTI: (1) the time intervals when the MXS LEDs are off, and (2) the time intervals between LED pulses, respectively.

The output GTI files contain multiple extensions with on and off intervals for each MXS, together with combined on and off intervals for the odd-numbered (direct mode) and even-numbered (indirect mode) LEDs, respectively.

The output fine GTI file has twelve extensions:

The output coarse GTI file has twelve extensions:

By default, the rslmxstime task increases the stop time of each individual pulse by an amount given in the MXS parameters CalDB file, or in a user-supplied equivalent ('mxsledfile'). This change in stop time can originate either from the duration of the afterglow or from a pulse stop time offset, which are degenerate in the sense that both are measured from the commanded end of the LED pulse. In practice, the larger of the two offsets is applied to the end of the GTI. The afterglow duration may be estimated using the lookup tables in 'mxsledfile', or by direct calculation using an afterglow function with coefficients stored in 'mxsledfile'. It is also possible to specify a constant stop offset by specifying a positive numerical value [ms] for the parameter 'dtafterglow', or to set the stop offset to a constant fraction of the pulse spacing by specifying a negative numerical value for 'dtafterglow'. In the MXS parameters CalDB file, the stop offset is a function of the commanded pulse duration. The afterglow offset may be disabled altogether by setting 'afterglow=no'. However, note that this does not turn off the stop-time offset. If the afterglow duration is large enough to extend into the next pulse, GTI are merged to avoid creating overlapping exposure intervals. In this case, fine GTI become, effectively, equivalent to coarse GTI except for the last stop time in the case where 'afterglow=yes' where the stop time is extended by the afterglow duration.

An offset to all MXS GTI start times is applied using the MXS parameters CalDB file (the offset is a function of LED current), or a user-supplied file ('mxsledfile'). Alternatively, a constant offset may be applied by specifying a numerical value [ms] for the parameter 'mxsoffset'. The MXS GTI stop times are not affected by 'mxsoffset'. Regardless of the 'mxsoffset' parameter, an additional offset is always applied to both start and stop times to account for the offset of the spacecraft clock time. The value is obtained from the keyword MXSSCDLT in the MXS parameters CalDB file, supplemented by the keywords SCDLTNOM and SCDLTRED, representing physical delays between the spacecraft clock time and MXS pulses for the nominal and redundant LED pairs, respectively.

Each pulse is also extended on either side by a constant margin stored as the MXSMARGN keyword in the MXS parameters CalDB file, or a user-supplied file ('mxsledfile'), to account for the finite rise and fall times of the pulse.

PARAMETERS

infilehk [filename]
Input Resolve HK file containing the MXS telemetry information.

outfilehk [filename]
Output HK file. This is a copy of the input file with start and stop time columns in the appropriate extension populated for each MXS LED.

finegti [filename]
Output fine GTI file for MXS.

coarsegti [filename]
Output coarse GTI file for MXS.

timfile [filename]
Input TIM file relating spacecraft time (TI) to time.

(mxsledfile = CALDB) [filename]
Input file of MXS afterglow and time offset characteristics, referred to above as the MXS parameters file. If 'mxsledfile' is set to CALDB, the data are read from a file in the calibration database.

(delayfile = CALDB) [filename]
Input delay file specifying the time delay between the central processor and each MXS. If the parameter is set to CALDB, the file is read from the calibration database.

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

(stimecol = S_TIME) [string]
Name of S_TIME column.

(tioncol = FWE_TI_LED#_ON) [string]
Input TI columns with LED turned on (the hash character, "#", takes values 1 to 4, inclusive).

(tioffcol = FWE_TI_LED#_OFF) [string]
Input TI columns with LED turned off ("#" takes values 1 to 4, inclusive).

(plslencol = FWE_LED#_PLS_LEN) [string]
Input pulse length columns ("#" takes values 1 to 4, inclusive).

(plsspccol = FWE_LED#_PLS_SPC) [string]
Input pulse spacing columns ("#" takes values 1 to 4, inclusive).

(iledcol = FWE_I_LED#_CAL) [string]
Input LED current columns ("#" takes values 1 to 4, inclusive).

(iledsetcol = FWE_I_LED#_SET_CAL) [string]
Input LED SET current columns ("#" takes values 1 to 4, inclusive).

(timeoncol = TIME_LED#_ON) [string]
Output LED-on time columns ("#" takes values 1 to 4, inclusive).

(timeoffcol = TIME_LED#_OFF) [string]
Output LED-off time columns ("#" takes values 1 to 4, inclusive).

(calctime = yes) [boolean yes|no]
If 'calctime' is set to yes, time is assigned in the output HK file.

(calcgti = yes) [boolean yes|no]
If 'calcgti' is set to yes, GTI files are produced. Time must be assigned either by setting 'calctime' to yes, or by a previous run.

(afterglow = yes) [boolean yes|no]
If 'afterglow' is set to yes, the fine GTI intervals are extended by the afterglow decay time, derived either from a calibration file, or specified by the parameter 'dtafterglow'.

(dtafterglow = FILE) [string]
Specifies the afterglow decay time of a pulse in one of three ways. If the value is any non-numeric string, the afterglow time is obtained from 'mxsledfile' as a function of pulse length. If the value [ms] is numeric and positive, it is added to the stop time of every pulse as a constant afterglow. If the value is numeric and negative, then the product of its magnitude and the pulse spacing is added to the stop time of every pulse as a constant afterglow. Note that afterglow duration is degenerate with the pulse stop offset, since both are measured from the commanded LED off time. Therefore, a constant value of the stop offset cannot be specified as a separate parameter and is effectively included in a numerical value of 'dtafterglow'. However, if the afterglow time is obtained from 'mxsledfile', the treatment is more complex. In this case, the stop time offset is given separately in 'mxsledfile' and is applied only if it is greater than the afterglow duration.

(agmethod = TABLE) [string [TABLE]|CALC]
If 'agmethod' is set to TABLE, the afterglow extensions of the fine GTI intervals are calculated from the lookup table extensions in the calibration file specifed by 'mxsledfile'. If set to CALC, these are calculated using the afterglow decay function determined by the coefficients stored in 'mxsledfile'. This parameter is ignored unless 'dtafterglow' is set to FILE and 'afterglow' is set to YES.

(itmax = 1000) [integer]
Maximum number of iterations allowed to reach convergence in determining the afterglow decay time using the functional form of the afterglow. This parameter is ignored unless 'agmethod' is set to to CALC, 'dtafterglow' is set to FILE, and 'afterglow' is set to YES.

(reltol = 1.0e-6) [double]
Tolerance relative to the threshold defining convergence in determining the afterglow decay time using the functional form of the afterglow. This parameter is ignored unless 'agmethod' is set to to CALC, 'dtafterglow' is set to FILE, and 'afterglow' is set to YES.

(decaythresh = 0.001) [double]
Threshold fraction of maximum pulse amplitude defining the end time of the afterglow.

(mxsoffset = FILE) [string]
Specifies the start time offset of a pulse in one of two ways. If the value is any non-numeric string, the offset is obtained from 'mxsledfile' as a function of LED current. If the value is numeric, then it gives the offset [ms] added to the start time of every pulse, measured from the LED commanded on time. This offset is not applied to the stop times. The value of 'mxsoffset' does not include the spacecraft time offset, which is always obtained from the keyword MXSSCDLT, and either SCDLTNOM or SCDLTRED, in 'mxsledfile' and is always applied to both start and stop times.

(interp = TWOPOINT) [string NEAREST|TWOPOINT]
Interpolation method used in time assignment.

(margingti = yes) [boolean yes|no]
If 'margingti' is set to yes, GTI for the intervals between TSTART and the earliest GTI START time, and between the last GTI STOP time and TSTOP, are created by the gtiinvert task.

(tstart = DEFAULT) [string]
Value (in seconds) to use for TSTART in the inverted (MXS off) GTI. The default is to use the value taken from the header of the 'infilehk' HK_SXS_FWE extension.

(tstop = DEFAULT) [string]
Value (in seconds) to use for TSTOP in the inverted (MXS off) GTI. The default is to use the value taken from the header of the 'infilehk' HK_SXS_FWE extension.

(dt = 0.0) [double]
Time gap [s] between input GTI times and corresponding inverted output GTI times. Output start times begin later than the input stop times by 'dt', and output stop times begin earlier than input start times by 'dt'.

(cleanup = yes) [boolean yes|no]
Delete temporary files if 'cleanup=yes'.

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

(chatter = 2) [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]
Log file name. 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 to the screen if set to yes.

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

EXAMPLES

  1. The following command calculates GTI for the MXS with the same settings as in the example shown in the rslmxstime help:

    rslmxsgti infilehk=rslmxs_pls90ms_spc203ms_i2mA_hksim002.fits outfile=rslmxs.fits.out finegti=rslmxs_fn.gti coarsegti=rslmxs_cs.gti timfile=xrism_test.tim delayfile=xa_gen_delay_20140101v001.fits mxsledfile=xa_rsl_mxsparam_trial004b.fits

  2. This example uses default files (from the CalDB) where applicable:

    rslmxsgti infilehk=rslmxs_pls90ms_spc203ms_i2mA_hksim002.fits outfile=rslmxs.fits.out finegti=rslmxs_fn.gti coarsegti=rslmxs_cs.gti timfile=xrism_test.tim

SEE ALSO

rslmxstime, gtiinvert

LAST MODIFIED

August 5, 2024