spi psd adcgain User Manual
Contents
1. History 1 4 0 20 Aug 2002 First ISDC delivery Rev 4 K K AAA RER Input DOLs inDOL s ql swg prp fitslil Input Group DOL SWG OG IDX alertDOL s ql psd_limits_idx fits 1 Alert Limit DOL File IDX Output DOL outDOL s ql adc fits Output DOL HDU optionally OBT limits minOBT s ql Gurve usage minimum OBT maxOBT s ql GCurve usage maximum OBT append b ql yes Append minimum OBT to last results slice b ql yes Split time interval in constant ONTIME intervals nopart b ql yes Skip partial time intervals ontime r ql 7200 0 Constant ONTIME slice seconds ADC analysis parameters H dopmax i h 6 1 19 Maximum degree of polynomial used for baseline fit fitmin r h 505 0 0 5 785 0 First timestep ns to use for baseline fit fitmax r h 785 0 0 5 785 0 Last timestep ns to use for baseline fit SPI mode usage usemodeO b h yes Use OPER mode spi_psd_adcgain User Manual 4 usemode2 b h yes Use CALB mode usemode3 b h yes Use DIAG mode PSD channel usage usedete00 b h yes Use PSD channel 0 7 usedete01 b h yes Use PSD channel 1 7 usedete02 b h yes Use PSD channel 2 7 usedete03 b h yes Use PSD channel 3 7 usedete04 b h yes Use PSD channel 4 usedete052. and spi_toolslib version 1 8 0 or higher After downloading the spi psd adcgain tar gz file step into a directory that should hold the distribution move the spi psd adcgain tar gz file into this directory and type gunzip spi psd adcgain tar gz tar xvf spi psd adcgain tar The first command uncompresses the distribution file the second unpacks the files Before configuration the distribution needs to be reset to a clean state To do this type make distclean Then configure the distribution It is assumed here that you have previously installed the ISDC support platform thus you should type bin ac_stuff configure Finally build the distribution by typing make global install To perform a unit test type spi_psd_adcgain User Manual 2 make test Make sure that the test data spi_test_data 1 0 tar gz are available at your site they should reside in a directory whose name is defined by the ISDC TEST DATA DIR environment variable spi_psd_adcgain User Manual 3 Parameter file HR HEAR RAMA RMA RHR HERBE RHEE HRA RHEE RAMA RMA AMMA RARER RE Centre d Etude Spatiale des Rayonnements in collaboration with ISDC SPI PSD ADC gain correction BR MMMM MMMM File spi_psd_adcgain par Version 1 4 0 Component osm Author Juergen Knoedlseder knodlseder cesr fr CESR Purpose Parameter file of the SPI PSD gain correction executable
3. b h yes Use PSD channel 5 7 usedete06 b h yes Use PSD channel 6 7 usedete07 b h yes Use PSD channel 7 usedete08 b h yes Use PSD channel 8 7 usedete09 b h yes Use PSD channel 9 usedete10 b h yes Use PSD channel 10 7 usedeteli b h yes Use PSD channel 11 7 usedete12 b h yes Use PSD channel 12 7 usedete13 b h yes Use PSD channel 13 7 usedetel4 b h yes Use PSD channel 14 usedete15 b h yes Use PSD channel 15 7 usedete16 b h yes Use PSD channel 16 7 usedete17 b h yes Use PSD channel 17 usedete18 b h yes Use PSD channel 18 7 Limit checking definitions 2 2 2 2 2 2 2 2 2 2 2 limcheck b h yes Perform limit checking alerto b h yes Generate level O alerts alerti b h yes Generate level alerts alert2 b h yes Generate level 2 alerts alert3 b h yes Generate level 3 alerts minCRVE i h 500 Minimum number of PSD curves for limit checking ISDC Standard Parameters clobber b h no Overwrite existing data structures mode s h ql Execution mode The following parameters have to be specified inDOL specifies the input DOL science window observation group or index file for which the PSD ADC gain correction factors should be derived An ISDC level of PRP is required with full OBTs alertDOL optional if alert limit check
4. slice no and only a single SPI science mode is present in the input group only one row will be added If time slicing has been selected the number of rows will depend on the number of time slices that have been found Also each new SPI science mode that is found in the input group will add a new row to the data structure Optionally time slices that are shorter than 95 of the requested ONTIME may be skipped thus assuring an uniform quality in terms of data statistics of the PSD ADC gain correction results spi_psd_adcgain fills all columns of the SPI ADC PSD HDU hence it can be considered as complete after the task has finished The OBTFIRST and OBTLAST keywords are also updated so that index group generating tools may be used to assess the validity interval of the data structure In particular spipsd_adcgain may access the OBTLAST keyword set by a previous run if continuous time slices should be added to the output file parameter append yes The following columns are filled by spi_psd_adcgain e OBT_START OBT start of the time interval of the actual row e OBT_STOP OBT stop or end of the time interval of the actual row e ONTIME ontime for this row in seconds e PSD_ADC_GAIN gain correction factors for all four A D convertors PSD_ADC_OFFSET offset correction factors for all four A D convertors spi_psd_adcgain User Manual 7 e CRVE NUM number of PSD curves used to determine the gain correction factors Opti
5. a If all parameters are set to yes the default all curves that can be found in the data will be used for ADC gain correction estimation However a new time interval will be inserted in the SPI ADC PSD HDU for each science mode change e usedetenn specifies which detectors should be used for PSD ADC gain correction estimation where nn 00 18 By default all detectors will be used yes and pulses will be averaged from all detectors for ADC gain correction determination If however one or several PSD channels are too noisy they may be excluded from the analysis by setting the correspondent field to no spi_psd_adcgain User Manual 6 e limcheck specifies if alert limit checking should be performed by spi_psd_adcgain If set to yes spi_psd_adcgain compares all ADC gain corrections to the limits that are specified in the alert limit file see alertDOL and optionally creates ISDC alerts see parameters alertO to alert3 Alert limit checking will be only performed for time slices that show sufficient curve statistics The curve statistics limit is defined by the parameter minCRVE e alertO optional if alert limit checking is enabled limcheck yes generates level 0 ISDC alerts optional if alert limit checking is enabled limcheck es generates level 1 ISDC alerts e alerti ll lt e alert2 optional if alert limit checking is enabled limcheck yes generates level 2 ISDC alerts e al
6. arameter limits are checked before maximum parameter limits and minimum limits have precedence over maximum limits this is not really of relevance since a parameter can not both violate the minimum and maximum limit unless the alert limit file has not been set up correctly i e the minimum limit is always smaller or equal to the maximum limit Alert limits are inclusive i e a minimum limit violation alert is generated if PARAMETER lt MIN_VAL 2 is fulfilled and a maximum limit violation alert is generated if PARAMETER gt MAX_VAL 3 is fulfilled Limit violation alerts are only generated if CRVE_NUM gt minCRVE 4 is fulfilled where CRVE_NUM is the total number of curves in a time slice including also curves for which a PSD algorithm error occured see the spi psdlib User Manual for a definition of PSD algorithm errors 6 Alerts spi_psd_adcgain may optionally generate alerts that signal possible PSD SPI misfunctions The following list provides the alert parameters and the actions that should be taken in case of occurence of the alerts The alert parameter in the alert message is followed by the extension Ln where n 0 3 specifies the ADC convertor number for which the alert occured If the action standard is specified in the table the standard alert action should be performed TBD Parameter Level Action PSD_ADC_GAIN 0 3 standard PSD_ADC_OFFSET 0 3 standard 7 Error codes The executable spi_psd_adcgain may stop wit
7. e input data structure Curves for which an on board analysis error occured are removed it is likely that for these curves the baseline is badly defined Further curve filters are possible but not implemented so far The baseline which 1s defined by the two task parameters fitmin and fitmax is then fitted by a polynomial function in order to get an adequate average description of the baseline shape The degree of the polynomial varies between 1 i e a linear function and the value given by the task parameter dopmax typically 6 Fits are done for all possible degrees between these limits The optimum fit is then given by the polynomial that produces the smallest reduced x i e where x d o f takes a minimum where d o f is the degrees of freedom of the fit Using this method the optimum polynomial is the polynomial that describes the baseline sufficiently well without introducing unnecessary parameters that s a kind of Ockham s razor approach spi_psd_adcgain User Manual 8 In the actual version of this program no gain correction is assumed i e gain 1 0 and only ADC offset corrections offset are calculated Following the polynomial fit the offset for ADC 7 is then calculated using Jfitmaz 4 Vkzfitmin a 1 yofimazja k fitmin 4 CUTUEAL i of fset Optional alert limit checks are performed with higher alert levels preceeding lower alert levels 1 e an alert of the highest possible level is generated Minimum p
8. ert3 optional if alert limit checking is enabled limcheck yes generates level 3 ISDC alerts e minCRVE optional if alert limit checking is enabled 1imcheck yes specifies the minimum re quired number of PSD curves CRVE to initiate alert limit checking This parameter avoids alert limit checking in case of insufficient curve statistics To achieve reasonably good ADC corrections a minimum number of curves of the order of 1000 should be requested for a nominal curve rate of one each four seconds this implies an average acquisition duration of about one hours and ten minutes hence ONTIME gt 4000 in this case e clobber ISDC standard parameter not used so far e mode ISDC standard parameter not used so far 4 Interface definition On input spi psd adcgain reads PSD curves from either a science window group or an observation group The analysis level PRP is required with OBT information for each PSD curve Also PSD onboard analysis errors are gathered from the PRP data and only pulse shapes will be used that had no onboard error pulse shapes with onboard error may have an invalid baseline hence they would falsify the ADC gain determination On output spi_psd_adcgain adds rows to the SPI ADC PSD data structure with gain correction factors for the analysed PSD curves The number of rows that are added depends on the number of time intervals that have been found by spi_psd_adcgain If no time slicing has been specified
9. h the following error codes SPI_PSD_ADCGAIN_ERROR_MEM_ALLOC 230000 SPI_PSD_ADCGAIN_ERROR_INDEX_SELECT 230001 They have the following meaning e SPI PSD ADCGAIN ERROR MEM ALLOC the allocation of dynamical memory has failed Probable your system resources are too limited to run this task If you cannot increase your resources you may reduced the number SPI_PSD_ADCGAIN_BUFFER in the spi psd adcgain h header file and recompile the code spi_psd_adcgain User Manual 9 e SPI PSD ADCGAIN ERROR INDEX SELECT while searching a single member in an index group DAL3GEN returned more than one member This should never happen If this error occurs it is likely that the index you specified on input is corrupted In addition all errors that may occur in calls to ISDC support functions such as for example DAL RIL or PIL are forwarded Please consult the ISDC web pages for getting information about these error codes
10. he performance of the electronics For this purpose spi psd adcgain implements a limit violation alert logic that automatically generates ISDC alerts upon task execution Eventually this monitoring will lead to an update of the PSD ADC gain correction factors these factors are set by telecommand spi_psd_adcgain has been designed to execute in any kind of pipeline such as the science window pipeline or the revolution pipeline however it could also be applied to an observation group for deep performance analysis Since a sufficient number of PSD curves is required for reliable ADC gain correction the revo lution pipeline is the priviledged location for spi psd adcgain spi psd adcgain has been designed to append regularily ADC gain corrections to a file and hence to build a time history of the ADC gains To make the logic work spi psd adcgain needs an index group on input which it will search automatically for sufficient new data i e data that are dated after the last entry in result file for ADC gain correction computation If not enough new data is available spi_psd_adcgain will do nothing spi psd adcgain has been developped under ISDC support platform 4 1 and requires spi psdlib version 1 5 0 and spi_toolslib version 1 8 0 or higher 2 Getting started Before installing spi psd_adcgain make sure that the ISDC support platform 4 1 or higher is installed on your system and that you have installed the libraries spi_psdlib version 1 5 0
11. ing is requested limcheck yes this parameter specifies the DOL of the alert limit file SPI ALRT LIM or the alert limit index SPI ALRT LIM IDX including the HDU outDOL specifies the output filename into which the PSD ADC gain correction factors will be written The specification of the HDU SPI ADC PSD s optional and is not required by the task If the data structure exists already spi psd adcgain appends rows to the existing table If the data structure or the file does not exist spi_psd_adcgain creates a new file HDU minOBT specifies the minimum OBT limit of the curves that should be used for PSD ADC gain correction determination The OBT format is a character string Leading 0 may be omitted If the spi_psd_adcgain User Manual 5 character string is empty or if any non number character is specified such as no for example no mimimum OBT limit is applied and data accumulation starts with the first curve in the input group e maxOBT specifies the maximum OBT limit of the curves that should be used for PSD ADC gain correction determination The OBT format is a character string Leading 0 may be omitted If the character string is empty or if any non number character is specified such as no for example no maximum OBT limit is applied and data accumulation stops with the last curve in the input group e append specifies if the minimum OBT limit should be set to the last OBT that occurs in the output file
12. nored The validity of the alert limit file is defined by the two keywords VSTART and VSTOP If an alert limit index is used these keywords are used to selected the alert limit file that is appropriate for the ADC gain correction validity time interval If the ADC gain correction validity time interval stops before the validity of the earliest alert limits the earliest alert limits are used by spi_psd_adcgain a warning is issued by spi psd adcgain in this case If the validity time interval starts after the validity of the last alert limits the last alert limits are used by spi psd adcgain a warning is issued by spi psd adcgain in this case If the ADC gain correction validity time interval overlaps with the transition of two or more alert limits files those alert limits are applied that have the longest time overlap with the ADC gain correction validity time interval 5 Algorithm The PSD ADC gain correction factors are derived from the baseline of the PSD pulses The baseline is defined as the last say 25 bins of the PSD pulse shape which follow the detector pulse Normally this baseline is rather flat and represents the baseline current of the front end electronics Since the four A D convertors that digitise the detector current pulses are common for all 19 detection channels all PSD curves are used irrespectively of their detector identifier Thus in a first step an average PSD curve is derived by summing all available PSD curves in th
13. ntime e dopmax specifies the maximum degree of the polynomial that will be used to estimate the PSD ADC gain correction factors The minimum setting is 1 corresponding to a linear function the maximum is 19 Values above 6 or 7 have shown to produce invalid fit results yet this does not disturb the executable since always the best degree of polynomial will be taken As default a value of 6 should be specified e fitmin specifies together with fitmax a time interval of the PSD pulse shapes or curves that should be used for ADC gain correction estimation Usually this time interval is the pulse baseline which normally is found between 500 and 790 ns By default 505 ns is used since the PSD time step is 10 ns 505 ns specifies a time bin that starts at 500 ns The unit of this parameters is ns e fitmax specifies together with fitmin a time interval of the PSD pulse shapes or curves that should be used for ADC gain correction estimation Usually this time interval is the pulse baseline which normally is found between 500 and 790 ns By default 785 ns is used since the PSD time step is 10 ns 785 ns specifies a time bin that ends at 790 ns The unit of this parameters is ns e usemoden specifies which science modes should be used for PSD ADC gain correction estimation where n 0 2 3 for the three SPI science modes OPER CALB and DIAG that produce PSD curve data the EMER mode has been excluded since it does not produce PSD curve dat
14. onally spi_psd_adcgain is able to generate ISDC alerts if some of the ADC gain corrections fall out of the defined limits The alert limits are defined by an SPI ALRT LIM structure from which the following columns are used by spi psd adcgain for alert generation e PAR NAME specifies the parameter for which the limits apply Valid parameter names are PSD ADC GAIN and PSD ADC OFFSET If one of those parameter names is defined the specified limits apply to all 4 A D convertors By adding Ln to the parameter name where n runs from 0 to 3 ADC gain correction limits may be specified for a given convertor for example PSD ADC OFFSET 13 specifies the limits for the offset of the A D convertor 3 Convertor specific parameters have precedence over common parameters i e those without the Lr extension hence one may define common limits for all 4 A D convertors and overwrite a few limits for specific convertors by specifying explicitely the convertor number e MIN VAL specifies the lower ADC gain correction limits inclusive for the four ISDC alert levels DAL table columns 1 3 corresponds to alert levels 0 3 e MAX VAL specifies the upper ADC gain correction limits inclusive for the four ISDC alert levels DAL table columns 1 3 corresponds to alert levels 0 3 e SUB ASSEMBLY specifies the SPI PSD sub assembly and must contain the entry SPI PSD All other columns OBT_START 0BT END CHECK MODE ALERT DELAY of the SPI ALRT LIM structure are ig
15. specified by outDOL in order to produce a continuous set of PSD ADC gain corrections The last OBT will be extracted from the keyword OBTLAST in the output file This parameter is only active if minOBT has not been set by the user i e minOBT has precedence and will not be overwritten e slice specifies if the input group should be sliced into time frames of constant ONTIME the ONTIME is the time specified in seconds during which SPI science data were accumulated and made available to the observer Such time slices are also referred to as Good Time Intervals GTIs e nopart optional if slice yes specifies if partial time slices i e time slices with durations that are shorter than the requested ONTIME should be skipped Partial time slices may occur at the end of a data stream and to assure a uniform quality of the PSD ADC gain corrections it is recommended to set this parameter to yes Together with append yes re execution of spi_psd_adcgain at a later time will append new time slices that start with the OBT of the last appended time slice e ontime optional if slice yes specifies the ONTIME duration in seconds of each time slice also referred to as Good Time A reasonable ONTIME is of the order of several hours Note that if nopart no the last time slice has generally an effective ONTIME that is shorter than the specified value since in general the available ONTIME is not an integer multiple of the value specified by o
16. spi psd adcgain User Manual Version 1 4 1 30 September 2002 J rgen Kn dlseder Centre d Etude Spatiale des Rayonnements knodlseder cesr fr http www cesr fr jurgen index html spi_psd_adcgain User Manual Note to the user This software has been written to analyse data of the SPI telescope onboard INTEGRAL Particular care has been taken in making the software user friendly and well documented If you appreciated this effort and if this software and User Manual were useful for your scientific work the author would appreciate a corresponding acknowledgment in your published work il spi_psd_adcgain User Manual Contents 1 Introduction 2 Getting started 3 Parameter file 4 Interface definition 5 Algorithm 6 Alerts 7 Error codes il spi_psd_adcgain User Manual 1 1 Introduction The executable spi_psd_adcgain written in the ANSI C language derives the PSD ADC gain correction factors from PSD curve data PSD ADC gain correction factors are employed for onboard pulse shape analysis in order to correct for small differences between the gain and offset of the four pulse shape A D convertors recall that the PSD has four A D convertors for pulse shape digitisation each convertor is clocked at 25 MHz while they are delayed by 10 ns with respect to each other in this manner a total sampling frequency of 100 MHz is reached The PSD ADC gains and offsets have to be monitored regularily in order to detect drifts in t
Download Pdf Manuals
Related Search