gtobssim Help File

Generate photon events from astrophysical sources and process those
photons according to the specified instrument response functions.

Usage: gtobssim infile srclist scfile evroot simtime startdate
use_ac ra dec radius irfs seed

The gtobssim tool is used to simulate Fermi observations of both point sources and diffuse sources using a specific spectral shape for a selected region of the sky; simulations can be in either survey or pointed mode. These simulations are useful for observation and proposal planning, as well as for assessing actual Fermi observations.

Both types of sources can be simulated with different spectral shapes, including for example:

• Non-variable-point sources with a power-law spectrum or broken power-law spectrum.

• Extended sources, where the incident photons are distributed as a 2D Gaussian projected on the sky.

• Sources where the user-specified energy distribution is entered as a 2 column ASCII file.

• Sources for which the energy distribution is determined by a symbolic expression.

• Isotropic sources, for which the photons are generated uniformly on the sky following a power-law spectrum.

• Sources for which the incident photons are generated from a 3D FITS image comprising an energy axis for the 3rd dimension and, e.g., RA and Dec as the sky coordinates.

• Sources where the photons are generated using a 2D FITS image as a template, and a single power-law spectrum is used for the entire map.

• Periodic sources, i.e., point sources with sinusoidal light curve.

• Transient sources including gamma-ray burst.

While you may want to use gtlike to perform a likelihood analysis on your simulated data set in order to obtain the significance of a detection, it is important to remember that not all sources available in gtobssim are available in gtlike. Those source models that are included in gtlike are a subset of the ones available in gtobssim.

Required inputs to gtobssim:

• Livetime pointing and history file. In order to simulate a source, gtobssim requires that you provide the spacecraft pointing and livetime history file in FITS format. You may use an existing one, create one using gtorbsim, or define a pointing strategy and let gtobssim compute one.

• XML Source Model. A source model file in XML format is also required. This file file contains information about the source, including: integral flux, photon spectral index, type of spectra, energy range, position of the source (RA, DEC), etc. This file can be made using templates, or by using the Model Editor, which is a GUI-driven tool included in the Fermi ScienceTools for use in generating source model files for both gtlike and gtobssim.

Note that – even though the source models for gtlike are in xml format – the files are not exactly the same as the source xml files for gtobssim. However, for the models supported in both gtobssim and in gtlike, you have the option to save them in either format, which helps in the preparation of your analysis.

Tip: To access Model Editor Help, enter modeleditor at the command line; a gui appears. Then go to "HELP" in the main menu.

The source model file may contain more sources than you want to simulate for a given task. You will need to provide an ASCII file with the list of sources you are interested in simulating for that specific task as an input to gtobssim.

• Additional inputs. You will also need to specify the:
  • Total simulation "exposure" time.
  • Simulation "start date".
  • Instrument Response Function (IRF)
  • A random seed number for the task.

Examples: gtobssim

Parameters are passed following the FTOOLs model (i.e., they can be passed as answers to a prompt, or listed in a command line). To be prompted for gtobssim parameter values, enter (at the command line): gtobssim

Note: "Hidden" parameters are not prompted. If you want to change one of the "hidden" parameters, specify the values in the command line, or click advanced in the GUI. For example, if you would like to change the minimum energy value for the events in the simulation, enter (at the command line): gtobssim emin=100

In this case, the minimum energy of the event will be set to 100 MeV instead of 30 MeV (the default value).

Some, but not all, examples of sources that can be simulated by gtobssim are listed below:

Example 1: Point Source with a Power-law Spectra

An example using parameters that are appropriate for 3C 279 is shown below:

<source_library title="example_3C279">
  <source name="_3C279" flux="3.48e-4">
    <spectrum escale="MeV">
      <particle name="gamma">
        <power_law emin="20.0" emax="200000." gamma="1.96"/>
      </particle>
      <celestial_dir ra="193.98" dec="-5.82"/>
    </spectrum>
  </source>
</source_library>

It is strongly recommended that you produce these source model files directly using the Model Editor(modeleditor).

In this case, 3C 279 (Ra=193.98, Dec=-5.82) is simulated with a photon spectral index of 1.96 and an integrated flux between 20 MeV and 200000 MeV of 3.48e-4 m^-2s^-1. The parameter escale specifies the units of energy used elsewhere in the source specification. It can have values of MeV or GeV. (default: GeV)

The file passed as the srclist parameters should contain the entry: _3C279.

Notes:

• The xml parser does not allow source names that begin with a number; so, in this case, an underscore "_" has been prepended to the name.

• Be sure to avoid spaces in the source names.

In this case, the simulation started on 2008-12-31 and lasted for 1 month (2592000 seconds), and the Pointing history file used was spacecraft_data_file.fits. The Response Function used was P6_V3_DIFFUSE. The number of events generated was 15, and two files were created: 3C279_events_0000.fits (the fits file with the events); and 3C279_srcIds.txt (an ASCII file with the summary information). The minimum and maximum energy values for the simulation are the default values.

Note: If we had entered emin=30 in the command line, the resulting events would have an energy larger that 30 MeV. Remember that the expected integrated flux between 20 MeV and 200000 MeV will be the one that is in the source model file: 3.48e-4 m^-2s^-1.

The above example can also be run from the command line as follows:

>gtobssim infile= src_sim.xml srclist= source.dat
scfile=spacecraft_data_file.fits evroot=mysource simtime=2592000
startdate=2008-12-31 use_ac=yes ra=193.98 dec=-5.82 radius=40 irfs=
P6_V3_DIFFUSE seed=29304

2) Diffuse Background Source

Note: To produce a realistic model,include the simulation of the Galactic and extragalactic diffuse emission.

Example 2a) Background Model Recommended by the Diffuse Group:

To produce a realistic model, include the simulation of the Galactic and Extragalactic background.

Notes:

• The model file gll_iem_v02.fit is a MapCube source, suitable for use with Likelihood and ObsSim XML source models. The MapCube is all-sky in Galactic coordinates with 0.5 deg pixels. It has 30 planes of energy, logarithmically spaced from 50 MeV to 100 GeV.

• The model is a 'Ring' or 'Hybrid' model developed by Jean-Marc Casandjian and Isabelle Grenier using the same gas ring maps that GALPROP uses, and the inverse Compton intensity calculated by GALPROP. Most or all of the rings have been generated by Guðlaugur Jóhannesson (Gulli), with the CO rings based on a specially-filtered composite data set prepared by Tom Dame.
  

• GALPROP is developed by Gulli, Igor Moskalenko, Troy Porter, and Andy Strong. gll_iem_v02.fit is defined only up to 100 GeV.

• You can generate the same source model using directly the Model Editor (modeleditor) tool.

Example 2b) Other Galactic Background Models

To simulate the diffuse Galactic background you may use MapSource as spectral class. In Mapsource the photons are generated using a 2D FITS image as a template. A single power-law spectrum is used for the entire map. A sample xml source file is given below:

<source_library title="galactic_back">
 <source name="Galactic_Diffuse">
  <spectrum escale="MeV">
      <SpectrumClass name="MapSource" params="26.56,2.1,$(FERMI_DIR)/
      refdata/fermi/galdiffuse/EGRET_diffuse_gal.fits,20.,2e5"/>
      <use_spectrum frame="galaxy"/>
  </spectrum>
 </source>
</source_library>

In the example above the total photon flux from the map is (#/m^2/s) = 26.56; the Photon spectral index is 2.1; the minimum photon energy is 30 MeV; and the maximum photon energy is 2x10^5 MeV. The fits file EGRET_diffuse_gal.fits is the EGRET interstellar emission model (basically that of Hunter et al. ApJ 481 pag 205 1997), which is available in the ScienceTools distribution in "$(FERMI_DIR)/refdata/fermi/galdiffuse" directory.

You can generate the same source model using directly the Model Editor (modeleditor) tool.

An example of input parameters to simulate the all-sky diffuse background is given below for a
1-day simulation starting 2008-12-31 and with P6_V3_DIFFUSE as response function:

Two files were created: galactic_back_events_0000.fits (the fits file with the events) and galactic_back_srcIds.txt (an ASCII file with the source ID information). This example generated 29827 events.

Another way to simulate the diffuse emission is to use the MapCube source, which is a generalization of MapSource source. A MapCube FITS file comprises a data cube of separate maps specified for arbitrary energies. This allows for spectral variations across a diffuse source.
MapCube was used to generate the interstellar gamma rays from the Milky Way using a cube generated from gamma-ray intensities calculated by the GALPROP software. The example below is for the GP_gamma.fits model of the interstellar emission of the Milky Way.

<source_library title="galactic_back">
   <source name="Galactic_Diffuse">
      <spectrum escale="MeV">
         <SpectrumClass name="MapCube" params="18.58,$(FERMI_DIR)/
             refdata/fermi/galdiffuse/GP_gamma.fits"/>
         <use_spectrum frame="galaxy"/>
      </spectrum>
   </source>
</source_library>

The MapCube source has only 2 parameters, total photon flux from the map, integrated over the energy range of the cube (#/m^2/s); and the FITS filename. Note that MapCube requires that the input FITS file contains a binary table extension called 'ENERGIES' that defines the energy of each of the spatial planes in the cube. The units of the map are differential intensity (e.g., photons cm^-2 s^-1 MeV^1 sr^-1), although the integral value is renormalized by whatever total photon flux is specified in the specification of the source. Note that GP_gamma.fits does not contain extragalactic diffuse emission. See next section for an example of how to simulate the extragalactic background. This file is available in the Science Tools distribution in "$(FERMI_DIR)/refdata/fermi/galdiffuse" directory.

The input example below is for the GP_gamma.fits model of the interstellar emission of the Milky Way:

Two files were created: galactic_back_GP_events_0000.fits and galactic_back_GP_srcIds.txt. This input generated 36952 events.

The above example can also be run from the command line as follows:

>gtobssim infile= src_sim.xml srclist=sources.dat
scfile=spacecraft_data_file.fits evroot= galactic_back_GP simtime=86400 startdate=2008-12-31 use_ac=no irfs=P6_V3_DIFFUSE seed=29304

Example 2b) Extragalactic Emission

The source model file below implements the extragalactic diffuse inferred by EGRET (Sreekumar et al. ApJ 494 pag 523 1998). The flux has units of photons m^-2 s^-1 integrated between emin and emax. The photon spectral index is gamma, i.e., dN/dE = const*E^-gamma.

<source_library title="extragalactic_back">
  <source name="Extragalactic_Diffuse" flux="0.545">
    <spectrum escale="MeV">
      <particle name="gamma">
        <power_law emin="30." emax="100000." gamma="2.1"/>
      </particle>
      <solid_angle mincos="-0.4" maxcos="1."/>
    </spectrum>
  </source>
</source_library>

This source model file could be obtained using directly the Model Editor (modeleditor). For this example, the ASCII srclist file should read: Extragalactic_Diffuse

An example of how to run gtobssim to simulate these sources is given below:

Two files were created: extragalactic_back_events_0000.fits and extragalactic_back_srcIds.txt (an ASCII file with the summary information). This source generated 12136 events in the 1-day observation. The response function used was P6_V3_DIFFUSE.

The above example can also be run from the command line as follows:

>gtobssim infile=src_sim.xml srclist=sources.dat
scfile=spacecraft_data_file.fits evroot= extragalactic_back simtime=86400 startdate=2008-12-31 use_ac=no irfs= P6_V3_DIFFUSE seed=29304

Example 3) Broken Power-Law spectra

An example of an xml source file to simulate a point source with a broken power-law spectra is given below:

<source_library title="example_mysource">
  <source name="mysource" flux="5e-4">
    <spectrum escale="MeV">
      <particle name="gamma">
        <power_law emin="20.0" emax="200000." 
         gamma="1.80" ebreak="1000" gamma2="2.30"/>
      </particle>
      <galactic_dir l="120" b="60"/>
    </spectrum>
  </source>
</source_library>

The total integrated flux between 20 and 200000 MeV is 5e-4m^-2s^-1. The photon spectral index is 1.80 between 20 MeV and 1000 MeV (the break in the spectra) and 2.30 between 1000 MeV and 200000 MeV. The ASCII data file for this source should read: mysource

An example of input parameters is given below:

In this case the simulation started on 2008-12-31 and lasted for 1 month (2592000 seconds). The Pointing history file used was spacecraft_data_file.fits. The Response Function used was P6_V3_DIFFUSE. The number of events generated was 24. Two files were created mysource_events_0000.fits and mysource_srcIds.txt.

The above example can also be run from the command line as follows:

>gtobssim infile= src_sim.xml srclist= sources.dat
scfile=spacecraft_data_file.fits evroot=mysource simtime=2592000
startdate=2008-12-31 use_ac=yes ra=195.555759 dec=57.066813 radius=40
irfs=P6_V3_DIFFUSE seed=29304

Example 4) Gaussian source

In this case, the incident photons are distributed as a 2D Gaussian projected on the sky. An example of source model is given below:

<source_library title="example_gaussian">
  <source name="gaussian_source">
    <spectrum escale="MeV">
      <SpectrumClass name="GaussianSource"
        params="0.1, 2.1, 120., 60., 1.0, 1.0, 0.0, 30., 2e5"/>
      <use_spectrum frame="galaxy"/>
    </spectrum>
  </source>
</source_library>

The parameters are:

This source model file could be obtained using directly Model Editor (modeleditor). The ASCII data file for this source should read: gaussian_source

An example of inputs parameters is given below:

In this case the simulation started on 2008-12-31 and lasted for 1 month (2592000 seconds). The pointing history file used was spacecraft_data_file.fits. The number of events generated was 6053, and two files were created gaussian_events_0000.fits and gaussian_srcIds.txt.

The above example can also be run from the command line as follows:

>gtobssim infile= src_sim.xml srclist= sources.dat
scfile=spacecraft_data_file.fits evroot= gaussian simtime=2592000
startdate=2008-12-31 use_ac=yes ra=120 dec=60 radius=40 irfs=P6_V3_DIFFUSE seed=29304

Example 5) Periodic source

It is possible to simulate a point source with sinusoidal light curve. The example below corresponds to the simulation of a periodic source in the center of the Galaxy:

<source_library title="example_periodic">
  <source name="periodic_source">
    <spectrum escale="MeV">
      <SpectrumClass name="PeriodicSource"
       params="0.1, 2.1, 1e3, 1, 0.75, 30., 2e5"/>
      <galactic_dir l="0" b="0"/>
    </spectrum>
  </source>
</source_library>

The parameters are:

The ASCII data file for this source should read: periodic_source

An example of inputs parameters is given below:

In this case the simulation started on 2008-12-31 and lasted for 1 month (2592000 seconds). The pointing history file used was spacecraft_data_file.fits. P^_V3_DIFFUSE was used as response Function. Two files were created periodic_events_0000.fits and periodic_srcIds.txt.

The above example can also be run from the command line as follows:

>gtobssim infile=src_sim.xml srclist=sources.dat
scfile=spacecraft_data_file.fits evroot=periodic simtime=2592000
startdate=2008-12-31 use_ac=yes ra=266.404996 dec=-28.936172
radius=40 irfs=P6_V3_DIFFUSE seed=29304

Example 6) Pulsar Source

To simulate a pulsar you need to create an ASCII template file containing the light curve. The file should consist of two columns: phase and intensity. The phase intervals must be uniformly spaced. The phase scale and absolute intensities are arbitrary and rescaled using the period and flux parameter values.

The following is an example of the source file for a pulsar. In this case, the Crab pulsar simulated with the template named: CrabTemplate.dat.

<source_library title="example_pulsar">
  <source name="Crab_Pulsar">
    <spectrum escale="MeV">
      <SpectrumClass name="Pulsar"
        params="1e3,2.,0.033,0,0,CrabTemplate.dat,0,30,1e5"/>
      <celestial_dir ra="83.57" dec="22.01"/>
    </spectrum>
  </source>
</source_library>

The parameters are:

The ASCII data file for this source should read: Crab_pulsar

An example of inputs parameters is given below:

In this case the simulation started on 2008-12-31 and lasted for 1 month (2592000 seconds). The Pointing history file used was spacecraft_data_file.fits. P6_V3_DIFFUSE was used as Response Function. The number of events generated was 71, and two files were created crab_events_0000.fits and crab_srcIds.txt (an ASCII file with the summary information.

The above example can also be run from the command line as follows:

>gtobssim infile=src_sim.xml srclist=sources.dat
scfile=spacecraft_data_file.fits evroot=crab simtime=2592000
startdate=2008-12-31 use_ac=yes ra=83.57 dec=22.01 radius=40
irfs=P6_V3_DIFFUSE seed=29304

Example 7) SimpleTransient

This allows the user to simulate a point source with a single active interval during which it has a constant flux and power-law spectrum. An example of source model is given below:

<source_library title="example_simpletransient">
  <source name="simple_transient">
    <spectrum escale="MeV">
      <SpectrumClass name="SimpleTransient"
        params="100., 2.,1000,3500, 30., 2e5"/>
      <celestial_dir ra="83." dec="22."/>
    </spectrum>
  </source>
</source_library>

The parameters are:

The ASCII data file for this source should read: simple_transient. An example of input parameter is given below:

In this case the simulation started on 2008-12-31. The Pointing history file used was spacecraft_data_file.fits. P6_V3_DIFFUSE was used as Response Function. The number of events generated was 10, and two files were created simpleT_events_0000.fits and simpleT_srcIds.txt.

The above example can also be run from the command line as follows:

>gtobssim infile=src_sim.xml srclist=sources.dat
scfile=spacecraft_data_file.fits evroot=simpleT simtime=86400
startdate=2008-12-31 use_ac=yes ra=83 dec=22 radius=40
irfs=P6_V3_DIFFUSE seed=29304

8) SpectralTransient

It is possible to simulate a transient source giving the light curve data as template. Here you have an example of source model:

<source_library title="example_spectraltransient">
  <source name="spectral_transient">
    <spectrum escale="MeV">
      <SpectrumClass name="SpectralTransient"
       params="flux=1e-1, tstart=0., tstop=1e4, 
       templateFile=testTemplate.dat,  
       emin=20, emax=2e5, lc=0, z=0, useLogParabola=0"/>
      <celestial_dir ra="193.4" dec="-5.82"/>
    </spectrum>
  </source>
</source_library>

The parameters are:

The ASCII data file for this source should read: spectral_transient

An example of inputs parameters is given below:

In this case the simulation started on 2008-12-31 and lasted for 1 month (2592000 seconds). The pointing history file used was spacecraft_data_file.fits. P6_V3_DIFFUSE was used as Response Function. The number of events generated was 61, and two files were created spectraT_events_0000.fits and spectraT_srcIds.txt.

The above example can also be run from the command line as follows:

>gtobssim infile=src_sim.xml srclist=sources.dat
scfile=spacecraft_data_file.fits evroot=spectraT simtime=2592000
startdate=2008-12-31 use_ac=yes ra=193.4 dec=-5.82 radius=40
irfs=P6_V3_DIFFUSE seed=29304