NAME

USAGE

DESCRIPTION

The Modulated X-ray Source (MXS) consists of two pairs of LEDs. One LED in each pair is a direct source, and the other is an indirect fluorescent source.

Each LED illuminates the pixels of the Resolve array with a specific pulse length and time spacing (duty cycle). One LED pair is called the "nominal" pair, and the other LED pair is called the "redundant" pair. One or both sources of a single LED pair may be in operation at a given time. The operational timeline of all LEDs is encoded in the MXS telemetry, which is in the Resolve housekeepting (HK) file, extension HK_SXS_FWE.

If the parameter 'calctime=yes', the rslmxstime task does time assignment to compute start and stop times for the four LEDs. The time assignment is similar to that done in other cases by the task xatime. The resulting values are stored in the columns of the HK_SXS_FWE extension specified by the parameters 'timeoncol' and 'timeoffcol' (default values TIME_LED#_ON and TIME_LED#_OFF), where "#" has one of the integer values 1 through 4 (1 and 3 representing the MXS in direct mode, and 2 and 4 the corresponding indirect mode). The user may choose to skip time assignment by setting 'calctime=no'. In this case, rslmxstime examines the first value in the relevant output column to determine whether time was previously set; if this value is zero, the task halts and notifies the user.

The times are assigned using information from (a) the input columns of the HK_SWS_FWE extension, (b) the TIM file (specified by the parameter 'timfile'), and (c) the CalDB files containing the time delay (parameter 'delayfile') and leap second information (parameter 'leapsecfile').

The input columns in the HK_SWS_FWE extension are specified by by the parameters 'tioncol' (default FWE_TI_LED#_ON), 'tioffcol' (default FWE_TI_LED#_OFF), 'plslencol' (default FWE_LED#_PLS_LEN), 'iledcol' (default FWE_I_LED#_CAL), and 'stimecol' (default S_TIME). The header keywords TSTART and TSTOP from the HK_SW_FWE extension define the beginning and end of the Resolve observation. The first-row values in the 'timeoncol' and 'timeoffcol' columns are set equal to this TSTART keyword, unless the task detects that an LED is on for the entire observation. In the latter case the task calculates the most recent, with respect to TSTART, pulse start for that LED and sets the 'timeoncol' column accordingly.

In any row of the HK_SXS_FWE extension, the value of a time ON or time OFF column encodes the last time when the relevant LED was turned on or off, respectively. This is true of both the input columns and the output columns. Hence, each of these columns is a step function, with the value of the ON columns changing when the LED is turned on, and the value of the OFF columns changing when the LED is turned off. By default, each of these columns is constant, if the LED is never turned on or off.

By default (parameter 'calcgti=yes'), rslmxstime also creates two GTI files, each containing four extensions, one for each LED. One GTI file records the coarse GTI corresponding to LED start and stop time intervals. In addition to these START and STOP columns, the coarse GTI output includes PLSLEN and PLSSPC columns, which record the pulse length and pulse spacing, respectively, as well as an LED#CUR column recording the LED set current. Each extension of the coarse GTI also includes two keywords, LED#LEN and LED#SPC (where # denotes an integer from 1 to 4), corresponding to the recorded pulse length and spacing, respectively. These are set to

positive numbers

if there is only one value for all coarse intervals

negative numbers

if there is more than one value, in which case the magnitude of the number gives the value in the first coarse GTI

0

if that LED has not been turned on.

For a given LED, it is possible that the value in either of the columns 'tioncol' (default TI_LED#_ON) or 'tioffcol' (default TI_LED#_OFF) changes in the input file, but not both. In the first case the GTI are calculated starting from when the 'tioncol' value changes, going forward to the end of the file. In the second case the GTI are calculated starting from when the 'tioffcol' value changes, going backward to the start of file.

If a particular LED is off through the entire observation, then the time on and off columns in the output HK file (see parameters 'timeoncol' and 'timeoffcol') are filled with the TSTART value in every row, and the corresponding output GTI file extensions are empty.

A second GTI file records the fine GTI corresponding to the individual LED pulses. The fine GTI are calculated using the telemetered information in the columns specified by the parameters 'plslencol' (default FWE_LED#_PLS_LEN) and 'plsspccol' (default FWE_LED#_PLS_SPC), which record the pulse length and pulse spacing, respectively. 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 numerical value [ms] for the parameter 'dtafterglow' (as opposed to a non-numerical value, which causes rslmxstime to use 'mxsledfile'). If the numerical value of 'dtafterglow' is negative, the afterglow duration is set to the magnitude of 'dtafterglow' multiplied by the pulse spacing. In the MXS parameters CalDB file, the stop offset is a function of the current. The afterglow duration in this file is a function of the effective pulse length (the commanded pulse length adjusted for the start and stop offsets), and of the fraction of the maximum pulse amplitude defining the end of the afterglow specified by the parameter 'decaythresh'. 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, the fine GTI are in effect equivalent to coarse GTI, except for the last stop time when 'afterglow=yes'; this 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 different file given by 'mxsledfile'. Alternatively, a constant offset may be applied by specifying a numerical value [ms] for the parameter 'mxsoffset' (as opposed to a non-numerical value, which causes rslmxstime to use 'mxsledfile'). 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. This keyword is supplemented by the keywords SCDLTNOM and SCDLTRED, which represent physical delays between the spacecraft clock time and MXS pulses for the nominal and redundant LED pairs, respectively. TSTART and TSTOP keywords in the GTI extensions are are set equal to the first START time and last STOP time, respectively, in each GTI table.

Each pulse is also extended on either side by a constant margin stored as the MXSMARGN keyword in the MXS parameters CalDB file to account for the finite rise and fall times of the pulse.

Rows in the input file with bad PROC_STATUS, or non-positive values in the 'tiocol', 'tioffcol', 'plslencol', or 'plsspccol' columns, are excluded from the GTI calculation procedure.

The coarse GTI file includes keywords specifying whether the offsets are variable (VARDELAY) and their maximum and minimum values (MINDELAY, MAXDELAY), whether the afterglow is derived from a file (VARGLOWT) and its maximum and minimum values (MINGLOWT, MAXGLOWTY).

PARAMETERS

infile [filename]

Input Resolve HK file containing the MXS telemetry information.

outfile [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.

outgti = rslmxs_#.gti [filename]

Root name, including a hash character (#) to be replaced by the strings "cs" and "fn", for coarse and fine output GTI files, respectively. Each file has four extensions, one per LED.

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 data are read from a file in 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 = no) [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.

(buffer = -1) [integer -1|0|N]

Rows to buffer (-1=auto, 0=none, N>0=number of rows).

(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]

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. Assign time to the input MXS file rslmxs_pls90ms_spc203ms_i2mA_hksim002.fits using the TIM file xrism_test.tim and the delay file xa_gen_delay_20140101v001.fits. Write the results into rslmxs.fits.out. Create coarse and fine MXS GTI files, rslmxs_cs.gti and rslmxs_fn.gti, respectively. The timing columns in the input file have the default names as noted above.

   rslmxstime infile=rslmxs_pls90ms_spc203ms_i2mA_hksim002.fits outfile=rslmxs.fits.out outgti=rslmxs_#.gti timfile=xrism_test.tim delayfile=xa_gen_delay_20140101v001.fits mxsledfile=xa_rsl_mxsparam_trial004b.fits

SEE ALSO

LAST MODIFIED