Command Line Scripts for the Instrument Simulator

These command-line scripts allow one to run and modify the instrument simulator. For details on what’s going on under the hood, see Instrument Simulation in SOXS.

instrument_simulator

The instrument_simulator script takes a SIMPUT catalog and generates a simulated observation in a standard event file format which can then be processed by standard tools such as CIAO, HEATOOLS, XSPEC, etc.

usage: instrument_simulator [-h] [--overwrite] [--roll_angle ROLL_ANGLE]
                            [--bkgnd_file BKGND_FILE] [--subpixel_res]
                            [--no_dither] [--dither_params DITHER_PARAMS]
                            [--aimpt_shift AIMPT_SHIFT]
                            [--random_seed RANDOM_SEED]
                            [--ptsrc_bkgnd | --no_ptsrc_bkgnd]
                            [--instr_bkgnd | --no_instr_bkgnd]
                            [--foreground | --no_foreground]
                            simput_file out_file exp_time instrument
                            sky_center

Run the instrument simulator and produce a simulated event file.

positional arguments:
  simput_file           The SIMPUT file to be used as input, or "None" if you
                        only want to simulate backgrounds.
  out_file              The name of the event file to be written.
  exp_time              The exposure time to use, in seconds.
  instrument            The name of the instrument to use, or alternatively
                        the name of a JSON file which contains an instrument
                        specification.
  sky_center            The center RA, Dec coordinates of the observation, in
                        degrees, comma-separated

optional arguments:
  -h, --help            show this help message and exit
  --overwrite           Overwrite an existing file with the same name.
  --roll_angle ROLL_ANGLE
                        The roll angle in degrees. Default: 0.0
  --bkgnd_file BKGND_FILE
                        Use background stored in a file instead of generating
                        one.
  --subpixel_res        Don't uniformly distribute event positions within
                        pixels.
  --no_dither           Turn dithering off entirely.
  --dither_params DITHER_PARAMS
                        The parameters controlling the size and period of
                        dither. Four floats joined by commas, in the form of
                        x_amp,y_amp,x_period,y_period. The first two numbers
                        are in arcseconds and the second are in seconds.
                        Default: 8.0,8.0,1000.0,707.0
  --aimpt_shift AIMPT_SHIFT
                        The shift of the aimpoint on the detector in both
                        directions from the nominal aimpoint in arcseconds.
                        Default: [0.0, 0.0]
  --random_seed RANDOM_SEED
                        A constant integer random seed to produce a consistent
                        set of random numbers.
  --ptsrc_bkgnd         Turn the point-source background on.
  --no_ptsrc_bkgnd      Turn the point-source background off.
  --instr_bkgnd         Turn the instrumental background on.
  --no_instr_bkgnd      Turn the instrumental background off.
  --foreground          Turn the galactic foreground on.
  --no_foreground       Turn the galactic foreground off.

Examples

Changing Instrument Specification

This example uses the pre-built HDXI instrument specification, assuming a 50 ks observation with the pointing (RA, Dec) = (30, 45) degrees.

[~]$ instrument_simulator sloshing_simput.fits evt.fits 50.0,ks hdxi 30.,45. --overwrite

The same, but use the HDXI specification with mirror diameter of \(d\) = 3 m and focal length of \(f\) = 20 m:

[~]$ instrument_simulator sloshing_simput.fits evt.fits 50.0,ks hdxi_3x20 30.,45. --overwrite

See The instrument Argument for details on the options for the instrument argument.

This example uses a JSON file created by the user, which contains a custom instrument specification. See Creating New Instrument Specifications for details on how to do this.

[~]$ instrument_simulator sloshing_simput.fits evt.fits 50.0,ks my_inst.json 30.,45. --overwrite

The following details how to change the other options, for more info see Other Modifications.

Changing Roll Angle, Dither, and Aimpoint Shift

Change the roll angle to 45 degrees:

[~]$ instrument_simulator sloshing_simput.fits evt.fits 50.0,ks hdxi 30.,45. --roll_angle=45.0 --overwrite

Change the dither amplitudes to 32 arcseconds and the periods to 707 and 1200 seconds:

[~]$ instrument_simulator sloshing_simput.fits evt.fits 50.0,ks hdxi 30.,45. --dither_params=32.,32.,707.,1200. --overwrite

Turn dither off entirely:

[~]$ instrument_simulator sloshing_simput.fits evt.fits 50.0,ks hdxi 30.,45. --no_dither --overwrite

Shift the aimpoint (units are in arcseconds):

[~]$ instrument_simulator sloshing_simput.fits evt.fits 50.0,ks hdxi 30.,45. --aimpt_shift=10.0,-15.0 --overwrite

Customizing Backgrounds

Turn off the instrumental background:

[~]$ instrument_simulator sloshing_simput.fits evt.fits 50.0,ks hdxi 30.,45. --no_instr_bkgnd --overwrite

Turn off the Galactic foreground:

[~]$ instrument_simulator sloshing_simput.fits evt.fits 50.0,ks hdxi 30.,45. --no_foreground --overwrite

Turn off the point-source background:

[~]$ instrument_simulator sloshing_simput.fits evt.fits 50.0,ks hdxi 30.,45. --no_ptsrc_bkgnd --overwrite

Any combination of these may be used to turn multiple components off or all of them.

To use a background stored in an event file:

[~]$ instrument_simulator sloshing_simput.fits evt.fits 50.0,ks hdxi 30.,45. --bkgnd_file="bkg_evt.fits" --overwrite

Note

If you use a background stored in an event file, the background will be entirely determined from the contents of this file and any of the above background flags will be ignored.

simulate_spectrum

Generate a PI or PHA spectrum from a spectrum in an ASCII table (such as one made by one of the commands detailed in Command Line Scripts for Spectra) by convolving it with responses. To be used if one wants to create a spectrum without worrying about spatial response, or if the underlying instrument supports only simulating spectra. Similar to XSPEC’s “fakeit”.

usage: simulate_spectrum [-h] [--overwrite] [--bkgnd_area BKGND_AREA]
                         [--random_seed RANDOM_SEED]
                         [--ptsrc_bkgnd | --no_ptsrc_bkgnd]
                         [--instr_bkgnd | --no_instr_bkgnd]
                         [--foreground | --no_foreground] [--no_noise]
                         spec_file instrument exp_time out_file

Convolve a spectrum with an ARF and RMF and produce a PHA or PI spectrum.

positional arguments:
  spec_file             The file containing the spectrum to be used. If None,
                        then only a simulated background may be generated if
                        they are turned on.
  instrument            The name of the instrument to use, or alternatively
                        the name of a JSON file which contains an instrument
                        specification.
  exp_time              The exposure time to use, in seconds.
  out_file              The file to write the convolved spectrum to.

optional arguments:
  -h, --help            show this help message and exit
  --overwrite           Overwrite an existing file with the same name.
  --bkgnd_area BKGND_AREA
                        The area on the sky for the background components, in
                        square arcminutes. Default: None. Must be specified if
                        any of the background components are turned on.
  --random_seed RANDOM_SEED
                        A constant integer random seed to produce a consistent
                        set of random numbers.
  --ptsrc_bkgnd         Turn the unresolved point-source background on.
  --no_ptsrc_bkgnd      Turn the unresolved point-source background off.
  --instr_bkgnd         Turn the instrumental background on.
  --no_instr_bkgnd      Turn the instrumental background off.
  --foreground          Turn the galactic foreground on.
  --no_foreground       Turn the galactic foreground off.
  --no_noise            If set, no noise will be included in the spectrum. This
                        cannot be set if backgrounds are included.

Examples

Simulate a Lynx microcalorimeter spectrum.

[~]$ simulate_spectrum power_law_spec.dat lynx_lxm 300.0,ks plaw_spec.pha

The same spectrum, but with point-source, foreground, and instrumental backgrounds added. Two square arcminutes of background assumed.

[~]$ simulate_spectrum power_law_spec.dat lynx_lxm 300.0,ks plaw_spec.pha --bkgnd_area 2.0 --ptsrc_bkgnd --foreground --instr_bkgnd

Simulate backgrounds only.

[~]$ simulate_spectrum None lynx_lxm 300.0,ks plaw_spec.pha --bkgnd_area 2.0 --ptsrc_bkgnd --foreground --instr_bkgnd

Simulate a spectrum without noise:

[~]$ simulate_spectrum power_law_spec.dat lynx_lxm 300.0,ks plaw_spec.pha --no_noise

get_instrument_data

Download the files needed for a particular instrument to a location of one’s choosing.

usage: get_instrument_data [-h] [--loc LOC] instrument

Download files associated with a particular instrument model.

positional arguments:
  instrument  The name of the instrument to download files for.

optional arguments:
  -h, --help  show this help message and exit
  --loc LOC   The path to download the files to. Defaults to the current
              working directory.

Examples

Get the instrument files for the "lynx_hdxi" instrument model, saved to the current working directory.

[~]$ get_instrument_data lynx_hdxi

Get the instrument files for the "xrism_resolve" instrument model, saved to a particular directory.

[~]$ get_instrument_data lynx_hdxi --loc /Users/jzuhone/Data/soxs