API Reference

This page documents the public API of ebltable.

EBL Photon Density

The EBL class loads an EBL photon density model and provides interpolation over redshift and wavelength. It can also compute the optical depth by numerical integration over the line of sight.

A model is loaded with the class method readmodel():

from ebltable.ebl_from_model import EBL
import numpy as np

ebl = EBL.readmodel(model='saldana-lopez')

# EBL intensity in nW/m^2/sr at z=0 for wavelengths 0.1–100 µm
lmu = np.logspace(-1, 2, 100)
nuInu = ebl.ebl_array(0., lmu)

# Optical depth for 1 TeV photons at z=0.5
tau = ebl.optical_depth(0.5, 1.0)

Available models can be listed with get_models().

class ebltable.ebl_from_model.EBL(z, lmu, nuInu, kx=1, ky=1, **kwargs)[source]

Bases: GridInterpolator

Class to calculate EBL intensities from EBL models.

__init__(z, lmu, nuInu, kx=1, ky=1, **kwargs)[source]

Initiate EBL photon density model class.

Parameters:

z (numpy.ndarray or list) – source redshift, m-dimensional
lmu (numpy.ndarray or list) – Wavelengths in micro m
nuInu (numpy.ndarray or list) – n x m array with EBL photon density in nW / sr / m^2
kx (int) – order of interpolation spline along energy axis, default: 2
ky (int) – order of interpolation spline along energy axis, default: 2
**kwargs – Additional kwargs passed to scipy.interpolate.RectBivariateSpline

ebl_array(z, lmu)[source]

Returns EBL intensity in nuInu [nW / m^2 / sr] for redshift z and wavelength l (micron) from BSpline Interpolation

Parameters:

z (array-like) – source redshift, m-dimensional
lmu (array-like) – wavelenghts in micrometer, n-dimensional

Returns:

(m x n) array with corresponding nuInu values in nW / m^2 / sr

Return type:

numpy.ndarray

Notes

if any z < self._z[0] (from interpolation table), self._z[0] is used and RuntimeWarning is issued.

ebl_int(z, lmin=0.01, lmax=1000.0, steps=50)[source]

Returns integrated EBL intensity in I [nW / m^2 / sr] for redshift z between wavelegth lmin and lmax (micron)

Parameters:

z (float) – redshift
lmin (float) – minimum wavelength in micrometer
lmax (float) – maximum wavelength in micrometer
steps (int) – number of steps for simpson integration

Return type:

Float with integrated nuInu value

static get_models()[source]: Get the available EBL model strings and return them as a list

mean_free_path(z, ETeV, steps_e=50, LIV_scale=0.0, nLIV=1, egamma_LIV=True)[source]

Calculates mean free path in Mpc for gamma-ray energy ETeV at redshift z

z: array-like: redshift, n-dimensional
ETeV: array-like: Energies in TeV, m-dimensional
steps_e: int: number of integration steps for integration over EBL density (default: 60)
LIV_scale: float: Lorentz invariance violation parameter (quantum gravity scale), if 0. (default), do not include LIV
nLIV: int: order of LIV, only applied if LIV_scale > 0, default: 1
egamma_LIV: bool: if true, apply LIV to both electrons and photons

Returns:: (m x n) array with mean free path values in Mpc. If m or n == 1, that axis is squeezed.
Return type:: numpy.ndarray

Notes

For calculation, see e.g. see Dwek & Krennrich 2013 or Mirizzi & Montanino 2009. For kernel see Biteau & Williams 2015

n_array(z, EeV)[source]

Returns EBL photon density in [1 / cm^3 / eV] for redshift z and energy from BSpline Interpolation

Parameters:

z (array-like) – source redshift, n-dimensional
EeV (array-like) – Energies in eV, m-dimensional

Returns:

(N x M) array with corresponding photon density values in 1 / cm^3 / eV

Return type:

numpy.ndarray

Notes

if any z < self._z[0] (from interpolation table), self._z[0] is used and RuntimeWarning is issued.

optical_depth(z0, ETeV, OmegaM=0.3, OmegaL=0.7, H0=70.0, steps_z=50, steps_e=50, egamma_LIV=True, LIV_scale=0.0, nLIV=1)[source]

calculates mean free path for gamma-ray energy ETeV at redshift z

Parameters:

z0 (float) – source redshift
ETeV (array-like) – Energies in TeV, n-dimensional
H0 (float,) – Hubble constant in km / Mpc / s. Default: 70.
OmegaM (float,) – critical density of matter at z=0. Default: 0.3
OmegaL (float,) – critical density of dark energy. Default: 0.7
steps_z (int) – intergration steps for redshift (default : 50)
steps_e (int) – number of integration steps for integration over EBL density (default: 60)
LIV_scale (float) – Lorentz invariance violation parameter (quantum gravity scale), if 0. (default), do not include LIV
nLIV (int) – order of LIV, only applied if LIV_scale > 0, default: 1
egamma_LIV (bool) – if true, apply LIV to both electrons and photons

Returns:

n-dim array with optical depth values

Return type:

numpy.ndarray

Notes

For the opacity calculation, see Biteau & Williams (2015), 2015ApJ…812…60B.

static readascii(file_name, kx=1, ky=1, model_name=None, **kwargs)[source]

Read in an EBL model file from an arbitrary file.

Parameters:

file_name (str) – full path to EBL photon density model file, with a (n+1) x (m+1) dimensional table. The zeroth column contains the wavelength values in mu meter, first row contains the redshift values. The remaining values are the EBL photon density values in nW / m^2 / sr. The [0,0] entry will be ignored.
kx (int) – Spline order in x direction
ky (int) – Spline order in y direction
model_name (str or None,) – Name of EBL model
kwargs (dict) – Additional kwargs passed to scipy.interpolate.RectBivariateSpline

static readfits(file_name, hdu_nuInu_vs_z='NUINU_VS_Z', hdu_wavelength='WAVELENGTHS', zcol='REDSHIFT', eblcol='EBL_DENS', lcol='WAVELENGTH', kx=1, ky=1, model_name=None, **kwargs)[source]

Read EBL photon density from a fits file using the astropy.io module

Parameters:

filename (str,) – full path to fits file containing the opacities, redshifts, and energies
hdu_nuInu_vs_z (str) – optional, name of hdu that contains ~astropy.Table with redshifts and tau values
hdu_wavelengths (str) – optional, name of hdu that contains ~astropy.Table with wavelegnths
zcol (str) – optional, name of column of ~astropy.Table with redshift values
eblcol (str) – optional, name of column of ~astropy.Table with EBL density values
lcol (str) – optional, name of column of ~astropy.Table with wavelength values
kx (int) – Spline order in x direction
ky (int) – Spline order in y direction
model_name (str or None,) – Name of EBL model
kwargs (dict) – Additional kwargs passed to scipy.interpolate.RectBivariateSpline

static readmodel(model, kx=1, ky=1)[source]

Read in an EBL model from an EBL model file

Parameters:

model (str,) – EBL model to use. Currently supported models are listed in Notes Section
kx (int) – Spline order in x direction
ky (int) – Spline order in y direction

Notes

Supported EBL models:

Model name	Publication	Notes
`franceschini`	Franceschini et al. (2008)
`kneiske`	Kneiske & Dole (2010)
`dominguez`	Dominguez et al. (2011)
`dominguez-upper`	Dominguez et al. (2011)	upper uncertainty
`dominguez-lower`	Dominguez et al. (2011)	lower uncertainty
`saldana-lopez`	Saldana-Lopez et al. (2021)
`saldana-lopez-err`	Saldana-Lopez et al. (2021)	uncertainties
`gilmore`	Gilmore et al. (2012)	fiducial model
`gilmore-fixed`	Gilmore et al. (2012)	fixed model
`finke`	Finke et al. (2010)	model C
`finke2022`	Finke et al. (2022)	model A
`cuba`	Haardt & Madau (2012)

writefits(filename, z, lmu, overwrite=True)[source]

Write optical depth to a fits file using the astropy table environment.

Parameters:

filename (str,) – full file path for output fits file
z (array-like) – source redshift, m-dimensional
lmu (array-like) – wavelenghts in micrometer, n-dimensional
overwrite (bool) – Overwrite existing file.

Optical Depth

The OptDepth class loads a pre-computed optical depth table and provides fast interpolation over redshift and energy.

from ebltable.tau_from_model import OptDepth
import numpy as np

tau = OptDepth.readmodel(model='saldana-lopez')

# Optical depth for 0.1–10 TeV photons at z=0.5
ETeV = np.logspace(-1, 1, 50)
tau_values = tau.opt_depth(0.5, ETeV)

class ebltable.tau_from_model.OptDepth(z, EGeV, tau, kx=1, ky=1, **kwargs)[source]

Bases: GridInterpolator

Class to calculate attenuation of gamma-rays due to interaction with the EBL from EBL models.

__init__(z, EGeV, tau, kx=1, ky=1, **kwargs)[source]

Initiate Optical depth model class.

Parameters:

z (array-like) – source redshift, m-dimensional
EGeV (array-like) – Energies in GeV, n-dimensional
tau (array-like) – n x m array with optical depth values
kx (int) – order of interpolation spline along energy axis, default: 1
ky (int) – order of interpolation spline along energy axis, default: 1
**kwargs – Additional kwargs passed to scipy.interpolate.RectBivariateSpline

static get_models()[source]: Get the available EBL model strings and return them as a list

opt_depth(z, ETeV)[source]

Returns optical depth for redshift z and Engergy (TeV) from BSpline Interpolation for z,E arrays

Parameters:

z (array-like) – source redshift, m-dimensional
ETeV (array-like) – Energies in TeV, n-dimensional

Returns:

(m x n) array with optical depth values. If z or ETeV are scalars, the corresponding axis is squeezed.

Return type:

numpy.ndarray

opt_depth_Ebin(z, Ebin, func, params, Esteps=50)[source]

Compute average optical depth within an energy bin assuming a specific spectral shape

Parameters:

z (float,) – redshift
Ebin (array-like) – Energies of bin bounds in TeV, n-dimensional
func (function pointer) – Spectrum, callable of the form func(Energy_TeV, **params)
params (dict,) – parameters that are past to func
Esteps (int) – number of energy integration steps, default: 50

Returns:

(n-1)-dim array with average tau values for each energy bin.

Return type:

numpy.ndarray

Notes

Any energy dispersion is neglected.

opt_depth_inverse(z, tau)[source]

Return Energy in GeV for redshift z and optical depth tau from interpolation

Parameters:

z (float) – redshift
tau (float) – optical depth

Return type:

float, energy in GeV

static readascii(file_name, kx=1, ky=1, **kwargs)[source]

Read in an optical depth model file from an arbritrary file.

Parameters:

file_name (str,) – full path to optical depth model file, with a (n+1) x (m+1) dimensional table. The zeroth column contains the energy values in Energy (GeV), first row contains the redshift values. The remaining values are the tau values. The [0,0] entry will be ignored.
kx (int) – order of interpolation spline along energy axis, default: 1
ky (int) – order of interpolation spline along energy axis, default: 1
kwargs (dict) – Additional kwargs passed to scipy.interpolate.RectBivariateSpline

static readfits(file_name, hdu_tau_vs_z='TAU_VS_Z', hdu_energies='ENERGIES', zcol='REDSHIFT', taucol='OPT_DEPTH', ecol='ENERGY', kx=1, ky=1, **kwargs)[source]

Read opacities from a fits file using the astropy.io module

Parameters:

filename (str,) – full path to fits file containing the opacities, redshifts, and energies
hdu_tau_vs_z (str, optional) – name of HDU containing the redshift/tau table
hdu_energies (str, optional) – name of HDU containing the energies table
zcol (str, optional) – column name for redshift values
taucol (str, optional) – column name for optical depth values
ecol (str, optional) – column name for energy values
kx (int) – order of interpolation spline along energy axis, default: 1
ky (int) – order of interpolation spline along redshift axis, default: 1
**kwargs – Additional kwargs passed to scipy.interpolate.RectBivariateSpline

static readmodel(model, kx=1, ky=1, pad_zeros=True)[source]

Read in an EBL model from an EBL model file

Parameters:

model (str) – EBL model to use. Currently supported models are listed in Notes Section
pad_zeros (bool) – if true, pad tau array with zeros for z=0
kx (int) – Spline order in x direction
ky (int) – Spline order in y direction

Notes

Supported EBL models:

Model name	Publication	Notes
`franceschini`	Franceschini et al. (2008)
`franceschini2017`	Franceschini & Rodighiero (2017)
`saldana-lopez`	Saldana-Lopez et al. (2021)
`saldana-lopez-upper`	Saldana-Lopez et al. (2021)	upper uncertainty
`saldana-lopez-lower`	Saldana-Lopez et al. (2021)	lower uncertainty
`kneiske`	Kneiske & Dole (2010)
`finke`	Finke et al. (2010)	model C
`finke2022`	Finke et al. (2022)	model A
`dominguez`	Dominguez et al. (2011)
`dominguez-upper`	Dominguez et al. (2011)	upper uncertainty
`dominguez-lower`	Dominguez et al. (2011)	lower uncertainty
`inoue`	Inoue et al. (2013)	baseline
`inoue-low-pop3`	Inoue et al. (2013)	low pop III
`inoue-up-pop3`	Inoue et al. (2013)	upper pop III
`gilmore`	Gilmore et al. (2012)	fiducial model
`gilmore-fixed`	Gilmore et al. (2012)	fixed model

writefits(filename, z, ETeV, overwrite=True)[source]

Write optical depth to a fits file using the astropy table environment.

Parameters:

filename (str,) – full file path for output fits file
z (array-like) – source redshift, m-dimensional
ETeV (array-like) – Energies in TeV, n-dimensional
overwrite (bool) – Overwrite existing file.

Interpolation Base Class

Both EBL and OptDepth inherit from the GridInterpolator base class, which handles the underlying 2-D B-spline interpolation.

class ebltable.interpolate.GridInterpolator(x, y, Z, logx=False, logy=False, logZ=False, kx=1, ky=1, **kwargs)[source]

Bases: object

Base class for 2D grid interpolation

property Z

__init__(x, y, Z, logx=False, logy=False, logZ=False, kx=1, ky=1, **kwargs)[source]

Initialize the class.

Parameters:

x (array-like) – Array with values of x axis of grid, n-dimensional
y (array-like) – Array with values of y axis of grid, m-dimensional
z (array-like) – Array with grid (z) values, n x m-dimensional
logx (bool) – Use logarithmic interpolation over x axis. Default: False
logy (bool) – Use logarithmic interpolation over y axis. Default: False
logZ (bool) – Use logarithmic interpolation over Z axis. Default: False
kx (int) – Order of spline interpolation in x direction. Default: 1
ky (int) – Order of spline interpolation in y direction. Default: 1
kwargs (dict) – Additional kwargs passed to scipy.interpolate.RectBivariateSpline

evaluate(x, y)[source]

Evaluate Spline for some x and y values

Parameters:

x (array-like) – x coordinates for evaluation, n-dimensional
y (array-like) – y coordinates for evaluation, m-dimensional

Returns:

Interpolated Z values for input x and y values (m x n dimensional).
If n or m are equal to one, drop this axis.

property x

property y