General Information Regarding the Python Interface to SOXS

Path to SOXS Data Files

To use either instrument_simulator() or simulate_spectrum(), data files such as the instrumental responses, background models, and PSF models are required. In versions of SOXS previous to v3.0.0, it was necessary to download these files on your own and place them either in the current working directory, or in a location specified by the SOXS Configuration File. Now, whenever an instrument is used, SOXS will first check the current working directory for the necessary files, and then will check the location specified by the soxs_data_dir entry in the configuration file. If the files are not found in either location, they will be downloaded automatically. If soxs_data_dir is not set in the configuration file, or is set to an invalid directory, a default directory will be chosen:

soxs : [WARNING  ] 2021-04-14 22:05:49,790 Setting 'soxs_data_dir' to /Users/jzuhone/Library/Caches/soxs for this session. Please update your configuration if you want it somewhere else.

See SOXS Configuration File for more information about the location of the configuration file and how to set its parameters.

Special Argument Handling for Quantities with Units

Many arguments to functions and class defintions which have units can take a special format which allows one to specify that particular quantity in the units desired by the user. For example, the make_cosmological_sources_file() function has several arguments which accept units. If one supplies floating-point numbers, they will be in a default set of units:

import soxs
filename = "cosmo.simput"
name = "cosmo_srcs"
sky_center = [30.0, 45.0]
exp_time = 500000.0 # seconds
fov = 40.0 # arcmin
area = 40000.0 # cm^2
nH = 0.02 # atoms/cm^2
soxs.make_cosmological_sources_file(filename, name, exp_time, fov,
                                    sky_center, nH=nH, area=area):

However, these same arguments accept values with unit information, either in the form of (value, unit) tuples, Quantity, or YTQuantity objects:

import soxs
from astropy.units import Quantity
filename = "cosmo.simput"
name = "cosmo_srcs"
sky_center = [30.0, 45.0]
exp_time = (500.0, "ks")
fov = Quantity(0.666667, "deg")
area = (4.0, "m**2")
nH = Quantity(2.0e20, "cm**-2")
soxs.make_cosmological_sources_file(filename, name, exp_time, fov,
                                    sky_center, nH=nH, area=area):

Since the quantities are the same but in different units, these two calls would be equivalent. Check the SOXS API for any given function or class definition to see which of them have arguments which can take values with specified units, and what the default units are.

Random Number Generation

Many routines in SOXS require generating random numbers for energies, sky positions, spectral channels, etc. By default, for every SOXS run this will be a different set of random numbers. It is often the case, however, that one wants to use a consistent, repeatable set of random numbers to reproduce results exactly. For this, many functions in SOXS take a prng optional argument, which has a default of None, but if set to an integer will use this value as a random seed.

For example, to generate photon energies from a Spectrum object using the generate_energies() method, one would set the random seed in this way:

t_exp = (50.0, "ks")
area = (3.0, "m**2")
prng = 24
e = spec.generate_energies(t_exp, area, prng=prng)

Check the SOXS API to see which functions or methods allow for the input of random seeds.