Instrument API

soxs.instrument.instrument_simulator(input_events, out_file, exp_time, instrument, sky_center, overwrite=False, instr_bkgnd=True, foreground=True, ptsrc_bkgnd=True, bkgnd_file=None, no_dither=False, dither_params=None, roll_angle=0.0, subpixel_res=False, aimpt_shift=None, input_pt_sources=None, prng=None)[source]

Take unconvolved events and create an event file from them. This function calls generate_events to do the following:

  1. Determines which events are observed using the ARF

  2. Pixelizes the events, applying PSF effects and dithering

  3. Determines energy channels using the RMF

and then calls make_background to add instrumental and astrophysical backgrounds, unless a background file is provided, in which case the background events are read from this file. The events are then written out to a file.

Parameters:

  • input_events (string, dict, or None) – The unconvolved events to be used as input. Can be one of the following: 1. The name of a SIMPUT catalog file. 2. A Python dictionary containing the following items: “ra”: A NumPy array of right ascension values in degrees. “dec”: A NumPy array of declination values in degrees. “energy”: A NumPy array of energy values in keV. “flux”: The flux of the entire source, in units of erg/cm**2/s.

  • out_file (string) – The name of the event file to be written.

  • exp_time (float, (value, unit) tuple, or Quantity) – The exposure time to use, in seconds.

  • instrument (string) – The name of the instrument to use, which picks an instrument specification from the instrument registry.

  • sky_center (array, tuple, or list) – The center RA, Dec coordinates of the observation, in degrees.

  • overwrite (boolean, optional) – Whether to overwrite an existing file with the same name. Default: False

  • instr_bkgnd (boolean, optional) – Whether to include the instrumental/particle background. Default: True

  • foreground (boolean, optional) – Whether to include the local foreground. Default: True

  • ptsrc_bkgnd (boolean, optional) – Whether to include the point-source background. Default: True

  • bkgnd_file (string, optional) – If set, backgrounds will be loaded from this file and not generated on the fly. Default: None

  • no_dither (boolean, optional) – If True, turn off dithering entirely. Default: False

  • dither_params (array-like of floats, optional) – The parameters to use to control the size and period of the dither pattern. The first two numbers are the dither amplitude in x and y detector coordinates in arcseconds, and the second two numbers are the dither period in x and y detector coordinates in seconds. Default: [8.0, 8.0, 1000.0, 707.0].

  • roll_angle (float, (value, unit) tuple, or Quantity, optional) – The roll angle of the observation in degrees. Default: 0.0

  • subpixel_res (boolean, optional) – If True, event positions are not randomized within the pixels within which they are detected. Default: False

  • aimpt_shift (array-like, optional) – A two-float array-like object which shifts the aimpoint on the detector from the nominal position. Units are in arcseconds. Default: None, which results in no shift from the nominal aimpoint.

  • input_pt_sources (string, optional) – If set to a filename, input the point source positions, fluxes, and spectral indices from an ASCII table instead of generating them. Default: None

  • prng (RandomState object, integer, or None) – A pseudo-random number generator. Typically will only be specified if you have a reason to generate the same set of random numbers, such as for a test. Default is None, which sets the seed based on the system time.

Examples

>>> instrument_simulator("sloshing_simput.fits", "sloshing_evt.fits",
...                      300000.0, "lynx_hdxi", [30., 45.], overwrite=True)
soxs.instrument.make_background_file(out_file, exp_time, instrument, sky_center, overwrite=False, foreground=True, instr_bkgnd=True, ptsrc_bkgnd=True, no_dither=False, dither_params=None, subpixel_res=False, input_pt_sources=None, prng=None, **kwargs)[source]

Make an event file consisting entirely of background events. This will be useful for creating backgrounds that can be added to simulations of sources.

Parameters:

  • exp_time (float, (value, unit) tuple, or Quantity) – The exposure time to use, in seconds.

  • instrument (string) – The name of the instrument to use, which picks an instrument specification from the instrument registry.

  • sky_center (array, tuple, or list) – The center RA, Dec coordinates of the observation, in degrees.

  • overwrite (boolean, optional) – Whether to overwrite an existing file with the same name. Default: False

  • foreground (boolean, optional) – Whether to include the Galactic foreground. Default: True

  • instr_bkgnd (boolean, optional) – Whether to include the instrumental background. Default: True

  • ptsrc_bkgnd (boolean, optional) – Whether to include the point-source background. Default: True

  • no_dither (boolean, optional) – If True, turn off dithering entirely. Default: False

  • dither_params (array-like of floats, optional) – The parameters to use to control the size and period of the dither pattern. The first two numbers are the dither amplitude in x and y detector coordinates in arcseconds, and the second two numbers are the dither period in x and y detector coordinates in seconds. Default: [8.0, 8.0, 1000.0, 707.0].

  • subpixel_res (boolean, optional) – If True, event positions are not randomized within the pixels within which they are detected. Default: False

  • input_pt_sources (string, optional) – If set to a filename, input the point source positions, fluxes, and spectral indices from an ASCII table instead of generating them. Default: None

  • prng (RandomState object, integer, or None) – A pseudo-random number generator. Typically will only be specified if you have a reason to generate the same set of random numbers, such as for a test. Default is None, which sets the seed based on the system time.

soxs.instrument.make_source_list(source)[source]
soxs.instrument.simple_event_list(input_events, out_file, exp_time, instrument, overwrite=False, use_gal_coords=False, prng=None)[source]
soxs.instrument.simulate_spectrum(spec, instrument, exp_time, out_file, instr_bkgnd=False, foreground=False, ptsrc_bkgnd=False, bkgnd_area=None, noisy=True, overwrite=False, prng=None, **kwargs)[source]

Generate a PI or PHA spectrum from a Spectrum by convolving it with responses. To be used if one wants to create a spectrum without worrying about spatial response. Similar to XSPEC’s “fakeit”.

Parameters:

  • spec (Spectrum) – The spectrum to be convolved. If None is supplied, only backgrounds will be simulated (if they are turned on).

  • instrument (string or tuple) – Two options: 1. The name of the instrument to use, which picks an instrument specification from the instrument registry. 2. A 2-tuple specifying an ARF, RMF pair, or a 3-tuple specifying an ARF, RMF, and a background spectrum specification, where the latter is a 2-element list giving the name of the background spectrum file and the normalization of the background spectrum in square arcminutes. If the ARF is set to None, a flat ARF will be assumed with a value of 1.0 cm**2. This may be useful for simulating particle backgrounds.

  • exp_time (float, (value, unit) tuple, or Quantity) – The exposure time in seconds.

  • out_file (string) – The file to write the spectrum to.

  • instr_bkgnd (boolean, optional) – Whether to include the instrumental/particle background. Default: False

  • foreground (boolean, optional) – Whether to include the local foreground. Default: False

  • ptsrc_bkgnd (boolean, optional) – Whether to include the unresolved point-source background. Default: False

  • bkgnd_area (float, (value, unit) tuple, or Quantity) – The area on the sky for the background components, in square arcminutes. Default: None, necessary to specify if any of the background components are turned on.

  • noisy (boolean, optional) – If False, simulate_spectrum will not use counting (Poisson) statistics when creating the spectrum. If any backgrounds are on, this must be set to True. Default: True

  • overwrite (boolean, optional) – Whether to overwrite an existing file. Default: False

  • prng (RandomState object, integer, or None) – A pseudo-random number generator. Typically will only be specified if you have a reason to generate the same set of random numbers, such as for a test. Default is None, which sets the seed based on the system time.

Examples

>>> spec = soxs.Spectrum.from_file("my_spectrum.txt")
>>> soxs.simulate_spectrum(spec, "lynx_lxm", 100000.0,
...                        "my_spec.pi", overwrite=True)
class soxs.instrument_registry.InstrumentRegistry[source]
fetch_files(key, loc=None)[source]

A handy method to fetch ARF, RMF, background, and PSF files to a location of one’s choice. Files are only actually downloaded if they are not present already.

Parameters:

  • key (string) – The instrument specification to download the files for.

  • loc (string, optional) – The path to download the files to. If not specified, it will download them to the current working directory.

soxs.instrument_registry.make_simple_instrument(base_inst, new_inst, fov, num_pixels, no_bkgnd=False, no_psf=False, no_dither=False)[source]

Using an existing imaging instrument specification, make a simple square instrument given a field of view and a resolution.

Parameters:

  • base_inst (string) – The name for the instrument specification to base the new one on.

  • new_inst (string) – The name for the new instrument specification.

  • fov (float, (value, unit) tuple, or Quantity) – The field of view in arcminutes.

  • num_pixels (integer) – The number of pixels on a side.

  • no_bkgnd (boolean, optional) – Set this new instrument to have no particle background. Default: False

  • no_psf (boolean, optional) – Set this new instrument to have no spatial PSF. Default: False

  • no_dither (boolean, optional) – Set this new instrument to have no dithering. Default: False