COSI GRB Group Simulations

This repository contains the code and inputs for COSI GRB simulations, as well as other short-duration transients which will need to be classified and investigated by the GRB group. This is a work in progress; please open an issue if you notice any problems/mistakes or missing features, and contact Eliza ([email protected]) with any questions.

Steps to Running Simulations

1. Create source input files, either using data observed by other telescopes (e.g. Fermi-GBM) or theoretical models. download_gbm_data.py is an example script that can be used to download lightcurves and spectra from Fermi-GBM. These files should be uploaded here. gbm_to_megalib.py may be used to convert the downloaded lightcurves and spectra to the formats required to generate the MEGAlib .source files. These files should be uploaded to MEGAlib_source_inputs/.
2. Generate MEGAlib .source files for transient events. source_file_generation.py may be used to generate these files. They are too large to store on GitHub and should be uploaded here.
3. Simulate the .source files using cosima, reconstruct the resulting .sim files using revan, and perform event selections on the resulting .tra files using mimrec. run_cosima.py, run_revan.py, and run_mimrec.py are example scripts that can be used to run cosima, revan, and mimrec, respectively. For onboard trigger algorithm simulations or anti-coincidence shield (BGO) only simulations, only the cosima step is necessary. The MEGAlib simulations are too large to store on GitHub and should be uploaded here.
4. Combine source simulations with background simulations. Depending on the analysis, this may be done at either the .sim or .tra file level. There are MEGAlib tools (e.g. mtraconcatter) which do this (see the MEGAlib documentation), and trigger_algorithm_list_generation.py can be used to create input files for the onboard trigger algorithm.

Directories

• data/ contains the information necessary to download the data used to create the files in MEGAlib_source_inputs/.
• example_scripts/ contains scripts that can be used to download Fermi-GBM spectra and lightcurves, bin the lightcurves using Bayesian blocks and convert the spectra and lightcurves into MEGAlib input files, create MEGAlib .source files, run simulations in MEGAlib, and create input files for the onboard trigger algorithm. See the README file in example_scripts/ for more details.
• grb_simulator/ contains the code used for the scripts in example_scripts/.
• MEGAlib_source_inputs/ contains the information necessary to generate a given simulation set in COSI. This is sub-divided into folders by event type, currently including gamma-ray bursts (grbs), magnetar giant flares (mgfs), soft gamma-ray repeater short bursts (sgr bursts), solar flares (solar_flares), and terrestrial gamma-ray flashses (tgfs). Each of these is further subdivided into the specific input samples generated by various team members. These will generally be spectral (.dat/.yaml) and lightcurve (.dat) files, as well as relevant images (.pdf, .png, etc.). Each of these individual samples should contain a text or catalog file describing the sample as well as the responsible team member. For use with source_file_generation.py, spectral files must be in the form event-name_spectrum.dat or event-name_spectrum.yaml and lightcurves must be in the form event-name_lightcurve.dat. Examples of spectral and lightcurve .yaml files can be found in example_yaml_files/, and information about the spectral .dat file format can be found in the MEGAlib documentation.

Simulation Files

• MEGAlib source files (outputs of sample_source_file_generation.py) can be found here.
• Source simulations of GRBs and other transients (outputs of run_cosima.py, run_revan.py, and run_mimrec.py) can be found here, and background simulations can be found here.
• Event list files used to test the onboard trigger algorithm (outputs of trigger_algorithm_list_generation.py) can be found here.