The UBATSIM software package Simulates UBAT detector frames from a GRB and processes them to trigger and locate the GRB P.H.Connell Image Processing Laboratory University of Valencia Valencia Spain 3.2.2011
1 - Introduction The original aim of this software was to put together an algorithm to create a fast correlation imaging algorithm for the UBAT DPU - for use while processing incoming 48x48 detector frames every 100 msec. However it was also important to have a test program to show that the algorithm would work, and was seen to work, not just an abstraction that should work. So it was decided to write it in C++ and put it into a small C++ test program, and output light curves and an image that would show the final details of the correlation imaging process. For this, input data is necessary, in the form of the 48x48 detector frames that will be delivered to the DPU imaging software every 100 msec, and so it was necessary to first write a detector frame creation program to output test frames for any GRB in the field of view to see if both the C++ algorithm and the equivalent FPGA algorithm would get the same result in terms of a GRB location vector. So the C++ executable UBAT_detector_frame_creation was written to create and output sequences of detector frames in a simple text file format easy to view and easy to read in to a DPU simulator, or FPGA test system. Then the C++ executable UBAT_detector_frame_processing was written to simulate the DPU, consisting of a loop every 100 msec - in real time - to read in a 48x48 detector frame sequence and then do something with it in the 100 msec available until the next frame would come. The basic task for this 100 msec clock cycle was to first save all non-zero frame pixels in a cyclic ring buffer, with frame drift data and a pointer to the first pixel of the frame in another cyclic ring buffer. Thereafter a trigger algorithm could be started to see if enough counts had accumulated for a GRB trigger if this was the case then an imaging trigger would be set and correlation imaging would begin - pixel by pixel as long as there was time left in the DPU clock cycle. Once imaging has been triggered then with each new frame the accumulated image would be searched to see if it had a GRB peak above some SNR threshold and if this was the case a GRB location vector could be calculated and passed to the SMT instrument otherwise it would keep on accumulating the pixel-by-pixel correlation image. The software package here is an initial draft to achieve the objective of a GRB trigger and correlation imaging location. It should be noted that it is a minimalist version, even if it seems complicate in places, that it works, and seems robust, especially the universal trigger algorithm used, and is able to compensate for GRB drift in the UBAT field of view. What remains is to test for any systematic errors in GRB location and how they can be corrected - as it seems the SMT expects the GRB to be within its small FOV and it will not initiate any secondary search for a GRB optical signal.
2 - Download The UBATSIM software package can be found at the public FTP site of the Image Processing Laboratory at ipl.uv.es and accessed with the following command sequence: ftp ipl.uv.es Name (ipl.uv.es:***): anonymous Password: name@institute.xx.yy ls You should now be able to see the contents of the FTP site and you can now download the UBATSIM software with the command: get UBATSIM_installation_package_v.n.tar.gz where v.n is the version-no always take the latest version. You should also download the GNUPLOT software package which is used to display graphs of light curves, etc - but which is also useful to use generally with the command: get gnuplot-4.4.2.tar.gz Now you have the software and can install it.
3 - Installation First create a directory where you want to install the UBATSIM software for example make it UV_UBAT_DPU_simulator in your home directory - move the downloaded file there and install it with three commands: gunzip UBATSIM_installation_package_v.n.tar.gz tar xvf UBATSIM_installation_package_v.n.tar./install For installation you will need a standard gcc and g++ compiler for C and C++ - but the installer will check they are available. The installer will first try to compile CFITSIO subroutines, which are used to output images in FITS format for display with the astronomy image display package ds9 from the Smithsonian Institute this will be verbose. When this is finished the UBATSIM software in C++ will be compiled and it should all be over within 10-15 seconds. There are two pauses to see where you are - just press enter. When the installer is finished it will create the file install_ubatsim_environment containing LINUX environment variables, aliases and pathways, to make using UBATSIM easier for the user. It will be copied into your shell resources file [.shrc /.bashrc /.cshrc /.tcshrc] depending on which shell you use echo $SHELL for this - to be executed every time you bring up a new LINUX window The file install_ubatsim_environment will contain commands like #!/bin/tcsh setenv UBATSIM_ENV /home/phc/uv_ubat_dpu_simulator setenv CFITSIO_ENV ${UBATSIM_ENV}/Software/CFITSIO setenv PATH ${PATH}:${UBATSIM_ENV} setenv PATH ${PATH}:${UBATSIM_ENV}/Docs setenv PATH ${PATH}:${UBATSIM_ENV}/Software setenv PATH ${PATH}:${UBATSIM_ENV}/GRB_frame_sequences setenv PATH ${PATH}:${UBATSIM_ENV}/GRB_frame_imaging setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${UBATSIM_ENV}/Software/lib alias ubatsim "$UBATSIM_ENV/Software/UBAT_detector_frame_processing" alias ubatfra "$UBATSIM_ENV/Software/UBAT_detector_frame_creation" alias UBATSIM "cd $UBATSIM_ENV" alias DS9 "$UBATSIM_ENV/ds9"
The outcome of the installation is to create three directories: Software GRB_frames_sequences GRB_frame_imaging which will be described below in detail. 4 - The Software directory This contains two executable programs and other subroutines in C++ to simulate the creation of 48x48 detector frame sequences and then to simulate the DPU processing them to locate a GRB. The important code which will have to be translated for FPGA processing is: UBAT_detector_frame_processing - DPU simulator executable UBAT_detector_frame_buffering - Buffers input frames and non-zero pixels UBAT_detector_frame_grb_trigger - Searches backwards for a GRB trigger UBAT_detector_pixel_correlation - Accumulates pixel correlation imaging UBAT_detector_image_grb_search - Searches an image for a GRB peak UBAT_detector_image_grb_location - Calculates the final GRB location vector The subroutine UBAT_coded_mask_pattern_input reads in the mask pattern from the file UBAT_coded_mask_pattern_padded.dat, which should be hard-wired in the DPU memory not relevant to FPGA. Note that it is padded to avoid having to find out if a mask pixel is outside the array bounds. The subroutine UBAT_detector_frame_access is used to read frame sequences created with the executable UBAT_detector_frame_creation and is equivalent to a detector frame memory address in the UBAT DPU not relevant to FPGA. All other subroutines are for the output of images, light curves, a GRB trigger curve, or to generate random Poisson numbers for the creation of frame sequences - not relevant to FPGA.
The main executable UBAT_detector_frame_processing has the following structure: Access next 48x48 detector frame in DPU memory every 100 msec UBAT_detector_frame_access Save frame drift and counts plus non-zero pixel locations and counts in cyclic buffers and their pointers UBAT_detector_frame_buffering Frame buffer Non-zero pixel buffer GRB location trigger set? Check dead-time after GRB location is over and then RESET GRB-trigger RESET GRB-imaging-trigger RESET GRB-search-trigger RESET GRB-location-trigger GRB trigger set? YES Integrate prior frames for a GRB count SNR excess UBAT_detector_frame_grb_trigger IF (TRIGGER-SNR > threshold) SET GRB-trigger Image GRB search triggered? YES Search accumulating correlation image for a GRB peak UBAT_detector_frame_grb_search IF (peak-snr > threshold) SET GRB-location-trigger UBAT_detector_image_grb_location GRB correlation imaging triggered? YES Accumulate correlation image pixel-wise until TIMEOUT UBAT_detector_pixel_correlation IF (TIMEOUT) RESET GRB-imaging-trigger SET GRB-search-trigger
5 - The GRB_frame_sequences directory This directory contains examples of 48x48 detector frame sequences stored in text file format, plus a command script to define the GRB location and light curve required to generate each frame. The executable for this is UBAT_detector_frame_creation which can be found in the directory Software and should be aliased to the name ubatfra. To create a detector frame sequence you need only execute the command: ubatfra < UBAT_detector_frame_creation.com > UBAT_detector_frame_creation.log where UBAT_detector_frame_creation.com is a text file of simple commands to define the location and light curve of a GRB and the name of the output file for the resulting sequence of 100 millisecond spaced detector frames. UBAT_detector_frame_creation.log is a log-file of each simulation step. A typical example of the file UBAT_detector_frame_creation.com is: mask-file:ubat_coded_mask_pattern_padded.dat grb-zenith-angle:30.0 grb-azimuth-angle:150.0 grb-mean-flux:5.0 background:2.2 drift-rate:0.0 drift-azimuth:0.0 lead-time:3.0 rise-time:1.0 fall-time:4.0 tail-time:3.0 frame-output-file:ubat_detector_frame_sequence_30_150.dat frame-time-msec:100 end This uses the mask pattern defined in the mask-file UBAT_coded_mask_pattern_padded.dat and will output a sequence of 48x48 detector frames to the frame-output-file UBAT_detector_frame_sequence_30_150.dat and a light curve to the default file UBAT_detector_frame_lightcurve.dat which can be displayed with the plotting software gnuplot as follows:
Here you can clearly see the GRB light curve properties: A lead-time of 3.0 seconds creates background frames only A rise-time of 1.0 seconds A fall-time of 4.0 seconds A tail-time of 3.0 seconds - creates background frames only Other GRB properties are: The GRB was located at a zenith angle of 30.0 off-axis The GRB was located at a azimuth angle of 150.0 relative to the UBAT X-axis The background detector count-rate was assumed to be 2.2 cnts/cm2/sec The incoming GRB mean-flux over the 5.0 second duration was 5.0 ph/cm2/sec The GRB drift-rate in the UBAT FOV was set to 0.0 arcsecs/sec or degrees/hour The GRB drift-azimuth angle was zero The frame-time between successive frames was 100 milliseconds
6 - The GRB_frame_imaging directory This directory contains examples of the DPU simulator using a command script to define the file containing detector frame sequences, triggering parameters, and various output file names. The executable for this is UBAT_detector_frame_processing which can be found in the directory Software and should be aliased to the name ubatsim. To simulate the DPU processing of detector frames you need only execute the command: ubatsim < UBAT_FOV_imaging.com > UBAT_FOV_imaging.log where UBAT_FOV_imaging.com is a text file of simple commands shown below and UBAT_FOV_imaging.log is a log-file of the progress of each detector frame processed. A typical example of the file UBAT_FOV_imaging.com is: frame-sequence:../grb_frame_sequences/ubat_detector_frame_sequence_30_150.dat trigger-backg-count-rate:420 trigger-backg-window-lagtime:50 trigger-backg-window-length:5 trigger-sigma-threshold:9 trigger-curve-output:ubat_grb_trigger_curve.dat coded-mask-pattern:ubat_coded_mask_pattern_padded.dat lightcurve-output.:ubat_grb_light_curve.dat imaging-output...:ubat_fov_imaging_location.fits end This will prompt the DPU simulator to read in each 48x48 detector frame from the frames previous created with the executable UBAT_detector_frame_creation or ubatfra and execute the following sequence of tasks: Save the drift rate, number of non-zero pixels for each frame in a ring buffer Save the (i,j) location and counts of each non-zero pixel of a frame in a ring buffer Look for a GRB trigger by accumulating frame counts and background backwards Accumulate correlation imaging for each frame pixel store after trigger onset frame Search the accumulated image for a GRB peak above some SNR threshold Return a GRB location vector Flag a dead-time delay until all remaining GRB counts have passed by
This will result in the following output: A log-file of each detector frame processed plus a GRB trigger-location summary A light curve of all detector frames processed A trigger curve showing the characteristic curve of backward integrated SNR A GRB correlation location image in tangent projection A GRB correlation location image in zenith angle projection The detector frame light curve shown here is on a time scale of 100 milliseconds (black) along with another on a time scale of 0.5 seconds (red). There are trigger algorithms, tried and tested for different time scales, but for this DPU simulator a universal trigger algorithm was used, which works by scanning backwards over a sequence of frames prior to the current one and creating: An array of integrated frame counts An array of a integrated expected background counts An array of signal-noise-ratio (squared) of S*S/(S+B) where S and B are integrated frame counts and integrated expected background. The expected background is calculated by starting at a frame at some fixed time prior to the current frame and integrating backwards over a fixed background time window - if there are not enough frames for this at program start it will begin at the first frame read.
This results in a characteristic trigger curve - shown below - which rises to a peak, then falls and tails off into background SNR. At some point the peak will rise above some SNR threshold 7.0 in this case and from this we can set a GRB trigger and calculate an estimate of the frame-no at which of GRB onset, where it begins to ramp up. This kind of trigger algorithm returns a variable time scale for GRB triggering not a fixed time scale. After a GRB trigger an imaging trigger will be set to start correlation imaging beginning at the the frame-no of GRB onset estimated from the trigger curve. After a GRB trigger the DPU simulator will keep accumulating the correlation image for each non-zero frame pixel saved, until the DPU clock cycle of 100 msec is complete, and then it will stop to get the next detector frame, save it, check the correlation image to see if a GRB peak is found above some threshold SNR, and if not it will continue imaging frame pixels until the next DPU clock cycle is complete. At some point the correlation image might be found to have a GRB above some SNR threshold and at that point a GRB direction vector, in integer form, will be found, along with an estimate of the time in the past when imaging began, and a flag will be set to force the DPU to do nothing but read in frames until a dead-time delay has passed to allow the remaining counts of the GRB to be ignored, or perhaps saved for telemetry another question. It is important to note that while detector frames are a 48x48 array these must be translated into the 58x58 physical array on which the LSO cells are to be found, with a gap of two dead cells in between each 8x8 LSO module on a 28.8 mm lattice.
When the DPU simulator has reached the last frame in the input file it will: Output the light curve accumulated Output the trigger curve if there was a GRB trigger Output the correlation image as a count map in tangent projection Output the correlation image as a SNR map in a zenith projection Output a summary at the end of the log-file of the GRB trigger parameters Output a summary at the end of the log-file of the GRB location vector and time Detector pixel correlation image - as a count map - tangent projection
Detector pixel correlation image as a SNR map zenith projection and smoothed The correlation image is effectively the correlation of the accumulating UBAT detector count pattern with the mask transparency pattern - in length units and as it is done pixel by pixel it is equivalent to a back-projection image. For output it is then rescaled by the detector-mask height as tangent projection image. The image is then transformed into a zenith angle projection and divided by the image background standard deviation to be output as a SNR map. Both these image may be viewed and examined in detail using ds9 which should be in the UBATSIM installation directory - and accessible by the alias DS9 - please check to see if this is possible.
7 How to create your own detector frame sequences To create detector frames for a particular kind of GRB, or GRB drift, simply create your own directory for it and copy the contents of the directory GRB_frame_sequences to it. Delete all the *.dat files and change the file UBAT_detector_frame_creation.com to simulate the kind of GRB you want. Whatever you do make sure you have the correct path for the UBAT mask pattern it is in the Software directory as UBAT_coded_mask_pattern_padded.dat but you can copy it to your test directory if you want. Then you start execution with ubatfra < UBAT_detector_frame_creation.com > UBAT_detector_frame_creation.log or by using the prepared script UBAT_detector_frame_creation UBAT_detector_frame_creation UBAT_detector_frame_creation.com which will automatically divert output to a standard log-file. If you have installed gnuplot which is easy you can display the resulting light curve by typing UBAT_detector_frame_lightcurve_plot. This will use gnuplot to read the command file UBAT_detector_frame_lightcurve.cmd and plot the resulting light curve, with output as a postscript (*.ps) file which you can view with ghostview or gv check your system has it. If you have the display and convert function of image magick you can also display any output *.ps file, or convert it to a *.jpg or *.png, or whatever, with display UBAT_detector_frame_lightcurve.ps or convert -rotate 90 UBAT_detector_frame_lightcurve.ps UBAT_detector_frame_lightcurve.jpg or convert -rotate 90 UBAT_detector_frame_lightcurve.ps UBAT_detector_frame_lightcurve.png
8 - How to simulate the DPU with your own frame sequences To see how the DPU processes the detector frames created, again create your own test directory and copy the contents of GRB_frame_imaging to it, then deleting all *.dat, *.fits, or any *.ps or *.png files. Then change the command file UBAT_FOV_imaging.com to use the correct mask pattern file and the input file of detector frames you have created. Then you start execution with ubatsim < UBAT_detector_frame_creation.com > UBAT_detector_frame_creation.log or by using the prepared script UBAT_FOV_imaging UBAT_FOV_imaging UBAT_FOV_imaging.com which will automatically divert output to a standard log-file. If you have gnuplot installed you can display the trigger curve and light curves seen by the DPU by typing: UBAT_GRB_trigger_curve_plot - which will use the gnuplot instructions found in the file UBAT_GRB_trigger_curve_plot.cmd to output the trigger curve as a *.ps file or UBAT_GRB_light_curve_plot - which will use the gnuplot instructions found in the file UBAT_GRB_light_curve_plot.cmd to output light curves as a *.ps file. Again these can be displayed with ghostview, gv, display or converted to *.jpg and *.png file with the convert software. However the most important file is the log-file which has details of just where the GRB was triggered, how the correlation imaging was accumulated, and a GRB direction vector, which must be corrected for drift since imaging was triggered, before being passed to the SMT optical instrument. Have fun being the DPU of UBAT!