Working with SIMPUT Catalogs

The default storage format for creating 2D models of X-ray sources in SOXS is SIMPUT, which is fast becoming a standard for making mock X-ray observations.

SOXS provides three classes to handle SIMPUT I/O: SimputSpectrum, SimputPhotonList, and SimputCatalog. These utilize the spectral and spatial model classes described in the Creating and Using Spectra and Spatial Models in SOXS sections of the SOXS documentation.

SIMPUT Spectral Models

The simplest SIMPUT source model in SOXS is that of a point-source located at a particular location on the sky, with a given energy spectrum. A SimputSpectrum can be created using the from_spectrum() method, using a Spectrum object:

import soxs

# Create a thermal Spectrum
agen = soxs.ApecGenerator(0.1, 10.0, 1000)
spec1 = agen.get_spectrum(6.0, 0.3, 0.01, 1.0e-3)
spec1.apply_foreground_absorption(0.02)

# Pick some coordinates
ra1 = 22.0 # degrees
dec1 = -30.0 # degrees

name1 = "ptsrc" # name of source

# Create a SimputSpectrum
src1 = soxs.SimputSpectrum.from_spectrum(name1, spec1, ra1, dec1)

An extended source can be created from a FITS image if you have one. Note that the image must have a header with some coordinate information, where \(n \in {1,2}\):

• "CRPIXn": reference pixel x,y coordinates, usually the image center

• "CUNITn": both should contain "deg"

• "CDELTn": width of each pixel in the x and y directions in units of "CUNITn", "CDELT1" should be negative

• "CRVALn": reference celestial x,y coordinates–required, but these will generally not be used.

• "CTYPEn": must be a projection type, typically "RA---TAN" and "DEC--TAN" are used.

from astropy.io import fits

# Create a thermal Spectrum
spec2 = agen.get_spectrum(5.0, 1.0, 0.03, 1.0e-4)
spec2.apply_foreground_absorption(0.02)

# Pick some coordinates
ra2 = 22.01 # degrees
dec2 = -29.98 # degrees

imhdu "cluster_image.fits[0]" # this specifies the name and extension of the
                              # image

name2 = "cluster1" # name of source

# Create a thermal SimputSpectrum
src2 = soxs.SimputSpectrum.from_spectrum(name2, spec2, ra2, dec2,
                                         imhdu=imhdu)

Note in this case that the entire extended source will have the same spectrum.

Alternatively, if you have a SpatialModel, you can use the from_models() method to create an extended source, where you use the SpatialModel to create an image with a specific width and resolution nx:

from astropy.io import fits

# Create a Spectrum
spec3 = agen.get_spectrum(2.2, 0.5, 0.05, 2.0e-2)
spec3.apply_foreground_absorption(0.02)

# Create an AnnulusModel
ra3 = 22.03 # degrees
dec3 = -30.03 # degrees
r_in = 5.0 # arcseconds
r_out = 20.0 # arcseconds
ann = soxs.AnnulusModel(ra3, dec3, r_in, r_out)

width = 20.0 # of the image, in arcminutes
nx = 4000 # resolution of the image

name3 = "cluster2" # name of source

# Create a SimputSpectrum
src3 = soxs.SimputSpectrum.from_models(name3, spec3, ann, width, nx)

In this case the whole extended source has the same spectrum as well.

SIMPUT Photon List Models

Spectral and spatial models for X-ray sources can be combined to produce a list of photon coordinates and energies using the SimputPhotonList class. Specifically, one can generate a SimputPhotonList using the from_models() method. This requires a Spectrum for the spectral model, a SpatialModel for modeling the spatial extent of the source, an exposure time, and a flat effective area.

import soxs

# Create the spectral model
spec4 = soxs.Spectrum.from_powerlaw(1.0, 0.01, 1.0e-2, 0.1, 10.0, 100000)
spec4.apply_foreground_absorption(0.04)

# Create a RectangleModel
ra4 = 21.97 # degrees
dec4 = -30.0 # degrees
width = 100.0 # in arcseconds
height = 4.0 # in arcseconds
theta = 30.0
rect = soxs.RectangleSource(ra4, dec4, width, height, theta=theta)

# Set the parameters
exp_time = (500.0, "ks")
area = (3.0, "m**2")

name4 = "jet" # name of source

# Create the photon list
src4 = soxs.SimputPhotonList.from_models(name4, spec4, rect, exp_time, area)

Plotting Photon Lists

The event positions from a SimputPhotonList can be plotted using the plot() method. This will make a scatter plot of the photon RA and Dec on the sky, optionally filtered within an energy band. For an example of how to use this method, see the “Two Clusters” cookbook example.

SIMPUT Catalogs

A SIMPUT catalog can be worked with using the SimputCatalog class. A SimputCatalog object associated with a single SimputSource can be created using the from_source() method:

import soxs

# Create the SIMPUT catalog
sim_cat = SimputCatalog.from_source("my_sources.simput", src1, overwrite=True)

which writes both the catalog and the source to the same file "my_sources.simput". If you want to write the SimputSource to a separate file, use the src_filename keyword argument:

import soxs

# Create the SIMPUT catalog
sim_cat = SimputCatalog.from_source("my_sources.simput", src1,
                                    src_filename="ptsrc.fits",
                                    overwrite=True)

To add more sources to an existing SimputCatalog, use the append() method:

# This adds src2 to the catalog in "my_sources.simput" and the same file
sim_cat.append(src2)

# This adds src3 to the catalog in "my_sources.simput" and the file
# cluster1.fits
sim_cat.append(src3, src_filename="cluster1.fits", overwrite=True)

An existing SIMPUT catalog can be read in from disk using from_file():

import soxs
sim_cat = soxs.SimputCatalog.from_file("my_sources_simput.fits")

Creating Background Model SIMPUT Catalogs

SOXS has the ability to model astrophysical background and foreground components (see Background Models in SOXS for more details). This modeling is typically carried out automatically during instrument simulation in SOXS (see Backgrounds). However, as SIMPUT catalogs can be used in conjunction with other instrument simulators (such as SIXTE, SIMX, and MARX), SOXS provides the ability to generate background and foreground models and write them to a SIMPUT catalog for reading in by these packages.

This capability is provided by the make_bkgnd_simput() function. It generates a galactic foreground model spectrum (see Galactic Foreground Model for how to tune its parameters) uniformly over a square field of view between the energies of 0.05 and 10 keV, and for the same field of view generates a photon-list realization of the cosmic X-ray background (CXB, see Point Source Background Model). Both of these are stored to the same SIMPUT catalog. Because the CXB component requires a photon-list realization, an exposure time and collecting area must be specified, so make sure that these are at least somewhat larger than the exposure time and effective area that will be used in the instrument simulation.

A simple invocation of make_bkgnd_simput() is shown here:

import soxs
t_exp = (100.0, "ks")
area = (3.0, "m**2")
fov = (1.0, "deg")
sky_center = (30.0, 45.0)
soxs.make_bkgnd_simput("bkgnd.simput", t_exp, area, fov, sky_center,
                       overwrite=True)

A number of optional customizations are possible. For example, the model for Galactic absorption and the value of the hydrogen column can be changed:

import soxs
t_exp = (100.0, "ks")
area = (3.0, "m**2")
fov = (1.0, "deg")
sky_center = (30.0, 45.0)
soxs.make_bkgnd_simput("bkgnd.simput", t_exp, area, fov, sky_center,
                       overwrite=True, absorb_model="wabs", nH=0.02)

The foreground model can be switched between "default" or "halosat":

import soxs
t_exp = (100.0, "ks")
area = (3.0, "m**2")
fov = (1.0, "deg")
sky_center = (30.0, 45.0)
soxs.make_bkgnd_simput("bkgnd.simput", t_exp, area, fov, sky_center,
                       overwrite=True, frgnd_spec_model="halosat")

If you generate a pre-existing set of point sources for the CXB using make_point_source_list(), you can input them here:

import soxs
t_exp = (100.0, "ks")
area = (3.0, "m**2")
fov = (1.0, "deg")
sky_center = (30.0, 45.0)
soxs.make_bkgnd_simput("bkgnd.simput", t_exp, area, fov, sky_center,
                       overwrite=True, input_sources="my_srcs.dat")

or you can let the function generate the sources for you and output them for later use:

import soxs
t_exp = (100.0, "ks")
area = (3.0, "m**2")
fov = (1.0, "deg")
sky_center = (30.0, 45.0)
soxs.make_bkgnd_simput("bkgnd.simput", t_exp, area, fov, sky_center,
                       overwrite=True, output_sources="my_srcs.dat")

Other customizations are detailed in the API docs, see make_bkgnd_simput().