xdust.halos¶

The superclass Halo holds all information and special functions for working with a simulated X-ray dust scattering halo.

The UniformGalHalo object assumes that all dust is uniformly distributed along the line-of-sight towards the X-ray light source.

The ScreenGalHalo object assumes that all dust is confined within an infinitesimally thin sheet with the specified column density.

See Corrales & Paerels (2015) for a description of the mathematics and geometry.

Warning

In the xdust code, the position of the scattering material (\(x\)) is defined as \(x = 1 - d/D\), where \(d\) is the distance to the scattering material and \(D\) is the distance to the X-ray light source. This is the opposite of the conventions used in many other papers on X-ray dust scattering halos, e.g., from R. K. Smith and S. Heinz.

Any scattering model physics can be used in the halo calculations. For the semi-analytic (fast) model described in Corrales & Paerels 2015, utilizing the Rayleigh-Gans approximation with the Drude approximation for the complex index of refraction, on can use the UniformGalHaloCP15 and ScrenGalHaloCP15 objects.

Classes

UniformGalHalo
ScreenGalHalo
UniformGalHaloCP15
ScreenGalHaloCP15

Functions

path_diff
time_delay
calculate_taux

Halo¶

class xdust.halos.Halo(lam=1.0, theta=1.0, from_file=None)[source]¶

Bases: object

An X-ray scattering halo.

Sliceable object: can input a range of energy/wavelength values and it will return the halo values for the range of interest. Can also summon values according using integers within range(len(lam))

description¶

Text description of this scattering halo.

Type:: str

lam¶

Wavelength or energy grid; plain values default to keV.

Type:: astropy.units.Quantity

theta¶

Scattering angle grid; plain values default to arcsec.

Type:: astropy.units.Quantity

norm_int¶

Normalized scattering halo intensity as a function of energy (NE x NTH)

Type:: astropy.units.Quantity array [arcsec^-2]

taux¶

Integrated X-ray scattering opacity as a function of energy

Type:: numpy.ndarray (NE)

fabs¶

Bin-integrated absorbed flux (photon/cm^2/s -or- erg/cm^2/s), used for calculating total halo intensity

Type:: numpy.ndarray or astropy.units.Quantity (NE)

intensity¶

Energy-integrated intensity calculated for the scattering halo [fabs x norm_int]

Type:: astropy.units.Quantity (NTH) [arcsec^-2 x fabs.unit]

Parameters:

lam (astropy.units.Quantity or numpy.ndarray) – Wavelength or energy grid; plain values default to keV.
theta (astropy.units.Quantity or numpy.ndarray) – Scattering angle grid; plain values default to arcsec.
from_file (str) – If not None, the filename of a FITS file containing the halo parameters and normalized intensity. The file should be in the format produced by the write method of this class

calculate_intensity(flux, ftype='abs')[source]¶

Calculate the scattering halo intensity from a flux spectrum.

Parameters:

flux (numpy.ndarray or astropy.units.Quantity) – Bin-integrated absorbed flux [photon/cm^2/s or erg/cm^2/s].
ftype (str) – 'abs' if the input is absorbed flux; 'ext' if it is point-source (extinction-corrected) flux.

ecf(th, n, log=False)[source]¶

Return the fraction of (energy-integrated) scattering halo flux enclosed by theta < th

Parameters:

th (astropy.units.Quantity or float) – Maximum theta value; plain values are assumed to be in arcsec.
n (int) – Number of theta values to use for interpolating.
log (bool) – If True, use a log-spaced theta grid. Default False.

Returns:

Enclosed fraction of halo flux within theta < th.

Return type:

float

Note

Small-angle scattering is assumed.

fake_image(arf, src_flux, exposure, pix_scale=0.5, num_pix=[2400, 2400], lmin=None, lmax=None, save_file=None, **kwargs)[source]¶

Make a fake image file using a telescope ARF as input.

Parameters:

arf (str) – Filename of telescope ARF
src_flux (numpy.ndarray [phot/cm^2/s]) – Describes the absorbed (without X-ray scattering) flux model for the central X-ray point source. Must correspond to the values in Halo.lam
exposure (float [seconds]) – Exposure time to use
pix_scale (float [arcsec]) – Size of simulated pixels
num_pix (ints (nx,ny)) – Size of pixel grid to use
lmin (float) – Minimum halo.lam value (Default:None uses entire range)
lmax (float) – Maximum halo.lam value (Default:None uses entire range)
save_file (str, optional) – Filename to use if you want to save the output to a FITS file. Default None.

Returns:

Image of a dust scattering halo. The halo intensity at different energies are converted into counts using the ARF. Then a Poisson distribution is used to simulate the number of counts in each pixel.

Return type:

numpy.ndarray (2D)

property fext¶

The point-source flux component, \(F_{ps} = F_{abs} \exp(-\tau_{sca})\)

Return type:: numpy.ndarray or astropy.units.Quantity (NE) [fabs.unit]

property fhalo¶

The theoretical bin-integrated flux spectrum for the total scattering halo flux. This is computed using the formula \(F_h = F_{abs} (1 - \exp(-\tau_{sca}))\)

Return type:: numpy.ndarray or astropy.units.Quantity (NE) [fabs.unit]

frac_halo(th, n, log=False)[source]¶

Calculate fraction of halo, as a function of energy, enclosed by theta < th

Parameters:

th (astropy.units.Quantity or float) – Maximum theta value; plain values are assumed to be in arcsec.
n (int) – Number of theta values to use for interpolating.
log (bool) – If True, use a log-spaced theta grid. Default False.

Returns:

Enclosed halo fraction as a function of energy [size NE].

Return type:

numpy.ndarray

Note

Small-angle scattering is assumed.

property percent_fabs¶

Calculates the fraction of absorbed flux that goes into the scattring halo, effectively \((1 - \exp(-\tau))\)

Return type:: numpy.ndarray or astropy.units.Quantity (NE) [unitless]

property percent_fext¶

Calculates the fraction of point source flux that goes into the scattering halo, effectively \((1 - \exp(-\tau)) / \exp(-\tau) = \exp(\tau) - 1\)

Return type:: numpy.ndarray or astropy.units.Quantity (NE) [unitless]

write(filename, overwrite=True)[source]¶

Parameters:

filename (str) – Name for the output FITS file.
overwrite (bool) – If True (default), overwrite an existing file of the same name.
file (Writes the norm_int attribute to a FITS)
with (along)
LAM (the)
THETA
values. (and TAUX)

UniformGalHalo¶

class xdust.halos.galhalo.UniformGalHalo(*args, **kwargs)[source]¶

Bases: Halo

calculate(gpop, nx=500, **kwargs)[source]¶

Calculate the X-ray scattering intensity for dust distributed uniformly along the line of sight

Parameters:

gpop (xdust.grainpop.SingleGrainPop)
nx (int) – Number of x-values to use for calculation (Default: 500)
**kwargs – Passed to gpop.calculate_ext.

Returns:

Updates the md, norm_int, and taux attributes.

Return type:

None

ScreenGalHalo¶

class xdust.halos.galhalo.ScreenGalHalo(*args, **kwargs)[source]¶

Bases: Halo

calculate(gpop, x=0.5, **kwargs)[source]¶

Calculate the X-ray scattering intensity for dust in an infinitesimally thin wall somewhere on the line of sight.

Parameters:

gpop (xdust.grainpop.SingleGrainPop)
x (float (0.0, 1.0]) – 1.0 - (distance to screen / distance to X-ray source)
**kwargs – Passed to gpop.calculate_ext.

Returns:

Updates the md, x, norm_int, and taux attributes.

Return type:

None

fake_variable_image(time, lc, arf, exposure=10000.0, tnow=None, dist=8.0, pix_scale=0.5, num_pix=[2400, 2400], lmin=None, lmax=None, save_file=None)[source]¶

Make a fake image of a variable scattering halo using a telescope ARF as input.

Parameters:

time (numpy.ndarray [days]) – Time values for light curve
lc (numpy.ndarray (unitless)) – Light curve in units of source flux (i.e. will be multiplied by self.fabs)
arf (str) – Filename of telescope ARF
exposure (float [seconds]) – Exosure time for simulated image
tnow (float [days]) – Time for calculating the halo image (Default: Last time value in light curve)
dist (float [kpc]) – Distance to the object in kpc
pix_scale (float [arcsec]) – Size of simulated pixels
num_pix (ints (nx,ny)) – Size of pixel grid to use
lmin (float) – Minimum halo.lam value (Default:None uses entire range)
lmax (float) – Maximum halo.lam value (Default:None uses entire range)
save_file (str, optional) – Filename to use if you want to save the output to a FITS file.

Returns:

Image of a time variable dust scattering halo. The halo intensity at different energies are converted into counts using the ARF. Then a Poisson distribution is used to simulate the number of counts in each pixel.

Return type:

numpy.ndarray (2D)

variable_profile(time, lc, dist=8.0, tnow=None)[source]¶

Given a light curve, calculate the energy-dependent intensity of the scattering halo at some time afterwards.

Parameters:

time (numpy.ndarray (days)) – Time values for light curve
lc (numpy.ndarray (unitless)) – Light curve in units of source flux (i.e. will be multiplied by self.fabs)
dist (float (kpc)) – Distance to the object in kpc
tnow (float (days)) – Time for calculating the halo image (Default: Last time value in light curve)

Returns:

Scattering halo intensity as a function of energy and observation angle.

Return type:

numpy.ndarray (NE x NTH) [fabs units / arcsec**2]

UniformGalHaloCP15¶

class xdust.halos.galhalo.UniformGalHaloCP15(*args, **kwargs)[source]¶

Bases: Halo

calculate(md, amin=<Quantity 0.005 micron>, amax=<Quantity 0.5 micron>, p=3.5, rho=<Quantity 3. g / cm3>)[source]¶

Calculate the X-ray scattering intensity for dust distributed uniformly along the line of sight utlizing the analytic solution according to the Corrales & Paerels 2015.

Parameters:

md (float or astropy.units.Quantity) – Dust mass column [g cm^-2].
amin (float or astropy.units.Quantity) – Minimum grain radius [micron].
amax (float or astropy.units.Quantity) – Maximum grain radius [micron].
p (float) – Slope of the power law grain size distribution.
rho (float or astropy.units.Quantity) – Grain mass density [g cm^-3].

Returns:

Updates norm_int [arcsec^-2] and taux [unitless] attributes.

Return type:

None

ScreenGalHaloCP15¶

class xdust.halos.galhalo.ScreenGalHaloCP15(*args, **kwargs)[source]¶

Bases: Halo

calculate(md, amin=<Quantity 0.005 micron>, amax=<Quantity 0.5 micron>, p=3.5, rho=<Quantity 3. g / cm3>, x=0.5)[source]¶

Calculate the X-ray scattering intensity for dust in an infinitesimally thin wall somewhere on the line of sight.

Parameters:

md (float or astropy.units.Quantity) – Dust mass column [g cm^-2].
amin (float or astropy.units.Quantity) – Minimum grain radius [micron].
amax (float or astropy.units.Quantity) – Maximum grain radius [micron].
p (float) – Slope of the power law grain size distribution.
rho (float or astropy.units.Quantity) – Grain mass density [g cm^-3].
x (float) – Screen position \(x = 1 - d/D\) where \(d\) is the distance to the screen and \(D\) is the distance to the X-ray source. Must be in (0.0, 1.0].

Returns:

Updates the md, x, norm_int, and taux attributes.

Return type:

None

path_diff¶

xdust.halos.galhalo.path_diff(alpha, x)[source]¶

Calculates path difference associated with a particular observation angle (\(\alpha\)) and x using \(\alpha^2 (1-x) / (2x)\)

Parameters:

alpha (float) – Observation angle [arcsec]
x (float or numpy.ndarray) – Position of dust patch (source is at x=0, observer at x=1)

Returns:

Path difference in units of \(D\) (distance to X-ray source)

Return type:

float or numpy.ndarray

Note

Assumes small angle scattering.

time_delay¶

xdust.halos.galhalo.time_delay(alpha, x, dkpc)[source]¶

Computes the time delay associated with a particular observation angle (\(\alpha\)), and x given a distance (in kpc) to the X-ray source.

Parameters:

alpha (float) – Observation angle [arcsec]
x (float or numpy.ndarray) – Position of a dust patch (source is at x=0, observer at x=1)
dkpc (float) – Distance to the X-ray source [kpc]

Returns:

Time delay in seconds

Return type:

float or numpy.ndarray

Note

Assumes small angle scattering.

calculate_taux¶

xdust.halos.galhalo.calculate_taux(lam, amin, amax, p, rho, md)[source]¶

Calculate the integrated X-ray scattering opacity taux using an analytic expression for a power-law distribution of dust grain sizes, using the Rayleigh-Gans and Drude approximations. See Corrales & Paerels 2015 for details.

Parameters:

lam (astropy.units.Quantity) – Energy or wavelength of the photons.
amin (astropy.units.Quantity [micron] - minimum grain radius)
amax (astropy.units.Quantity [micron] - maximum grain radius)
p (float [unitless] - slope of power law distribution)
rho (astropy.units.Quantity [g cm^-3] - grain mass density)
md (astropy.units.Quantity [g cm^-2] - dust mass column)

Returns:

taux – Integrated X-ray scattering opacity

Return type:

numpy.ndarray or astropy.units.Quantity (NE)