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:
- GTIMXSFNON1 (LED1 pulses)
- GTIMXSFNON2 (LED2 pulses)
- GTIMXSFNON3 (LED3 pulses)
- GTIMXSFNON4 (LED4 pulses)
- GTIMXSFNOFF1 (intervals between LED1 pulses)
- GTIMXSFNOFF2 (intervals between LED2 pulses)
- GTIMXSFNOFF3 (intervals between LED3 pulses)
- GTIMXSFNOFF4 (intervals between LED4 pulses)
- GTIMXSFNON13 (LED1 and LED3 pulses)
- GTIMXSFNON24 (LED2 and LED4 pulses)
- GTIMXSFNOFF13 (intervals when both LED1 and LED3 are between pulses)
- GTIMXSFNOFF24 (intervals when both LED2 and LED4 are between pulses)
The output coarse GTI file has twelve extensions:
- GTIMXSCSON1 (LED1 on)
- GTIMXSCSON2 (LED2 on)
- GTIMXSCSON3 (LED3 on)
- GTIMXSCSON4 (LED4 on)
- GTIMXSCSOFF1 (LED1 off)
- GTIMXSCSOFF2 (LED2 off)
- GTIMXSCSOFF3 (LED3 off)
- GTIMXSCSOFF4 (LED4 off)
- GTIMXSCSON13 (LED1 on or LED3 on)
- GTIMXSCSON24 (LED2 on or LED4 on)
- GTIMXSCSOFF13 (both LED1 and LED3 off)
- GTIMXSCSOFF24 (both LED2 and LED4 off)
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
-
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
-
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