pts.band.broadband.BroadBand Class Reference

An instance of the BroadBand class represents a broadband filter with a given transmission curve. More...

Public Member Functions
def	__init__ (self, bandspec)
	As mentioned in the class header, built-in Broadband instances can be obtained using one of the class functions builtinBands() or builtinBand() as opposed to directly invoking the constructor. More...
def	builtinBand (cls, nameSegments)
	This function returns the single BroadBand instance that matches the specified criteria. More...
def	builtinBands (cls, nameSegments="", minWavelength=0<< u.m, maxWavelength=1e99<< u.m)
	This function returns a list of BroadBand instances that match the specified criteria. More...
def	convolve (self, wavelengths, fluxes, *numWavelengths=None, flavor=None)
	This function calculates and returns the band-averaged value $⟨F_{\lambda }⟩$ for a given spectral energy distribution $F_{\lambda }(\lambda )$. More...
def	effectiveWidth (self)
	This function returns the effective band width (a wavelength interval) as defined in the class header as an astropy quantity. More...
def	maxWavelength (self)
	This function returns the maximum wavelength for the band, as an astropy quantity. More...
def	minWavelength (self)
	This function returns the minimum wavelength for the band, as an astropy quantity. More...
def	name (self)
	This function returns the built-in band's name, or "Uniform" or "Custom" for uniform or custom bands respectively. More...
def	pivotWavelength (self)
	This function returns the pivot wavelength as defined in the class header, as an astropy quantity. More...
def	transmissionCurve (self)
	This function returns a tuple containing a copy of the wavelength and transmission arrays representing the transmission curve for this band, normalized to unity. More...
def	wavelengthRange (self)
	This function returns a tuple of astropy quantities specifying the wavelength range for this band. More...

Private Member Functions
def	_addBuiltinBands (cls, directory)
	This private function recursively searches the contents of the specified directory and adds files with a name ending in "_BroadBand.stab" to the list of built-in bands. More...
def	_ensureBuiltinBands (cls)
	This private function adds any band definitions detected in the SKIRT or PTS resources directories to the list of built-in bands. More...
def	_normalize (self)
	This private function normalizes the transmission curve for uniform and custom bands, and attaches the appropriate astropy units (micron and 1/micron, respectively). More...

Private Attributes
	_added
	_bandname
	_transmissions
	_wavelengths

Static Private Attributes
bool	_added
	Flag becomes True as soon as bandpaths have been added for the SKIRT and PTS resource directories. More...
	_bandpaths
	The file paths for all detected built-in band definitions (i.e. More...

Detailed Description

An instance of the BroadBand class represents a broadband filter with a given transmission curve.

BroadBand instances are usually obtained by loading built-in band definitions using one of the class functions builtinBands() or builtinBand() as opposed to directly invoking the constructor. However, for specific use cases, a BroadBand instance can also be constructed directly, for example to obtain a uniform filter with constant transmission over a specified wavelength range. For more information, refer to the documentation of the constructor.

Built-in bands

This class relies on SKIRT resource files to provide built-in broadband definitions. These resource files are written in the SKIRT stored table format and have names that end with "_BroadBand.stab". The first part of the file name identifies the particular band being represented.

The class recursively searches for broadband resource files in the contents of two directories, if they exist: the ~/SKIRT/resources directory and the ~/PTS/resources directory. In other words, if SKIRT has been installed and all relevant resource packs have been installed, all broadbands available to SKIRT are available to this class as well. In case SKIRT is not installed on the same system (and in the same project directory), one can manually download the appropriate resource packs from the SKIRT web site, unzip the archives, and place the files in the ~/PTS/resources directory.

For a list of available broadbands, see the documentation of the SKIRT BroadBand class, or use the "pts list_bands" command.

Band properties and operations

This class offers operations such as determining the band's pivot wavelength and convolving an SED or a frame data cube with the band's transmission curve.

Refer to the appendix in Camps et al. 2016 (MNRAS 462, 1057-1075) for a brief introduction of the relevant concepts and a derivation of the corresponding formulas. For the purposes of this class, a band is defined through its arbitrarily scaled transmission curve $T(\lambda )$. The relative transmission at a given wavelength can then be written as

$$T_{\text{rel}}(\lambda )=\frac{T(\lambda )}{max[T(\lambda )]}.$$

Given a spectral energy distribution $L_{\lambda }(\lambda )$, the mean specific luminosity over the band $⟨L_{\lambda }⟩$ can then be obtained through

$$⟨L_{\lambda }⟩=\frac{\int L_{\lambda }(\lambda )T(\lambda )\mathrm{d}\lambda }{\int T(\lambda )\mathrm{d}\lambda }.$$

The pivot wavelength of the band is defined as the wavelength at which the mean specific luminosity can be properly converted between wavelength and frequency representations. It is given by

$${\lambda }_{\mathrm{p}\mathrm{i}\mathrm{v}\mathrm{o}\mathrm{t}}=\sqrt{\frac{\int T(\lambda )\mathrm{d}\lambda }{\int T(\lambda )\mathrm{d}\lambda /{\lambda }^2}}.$$

The effective width of the band is defined as the horizontal size of a rectangle with height equal to the maximum transmission and with the same area as the one covered by the band's transmission curve. It is given by

$$W_{\mathrm{e}\mathrm{f}\mathrm{f}}=\frac{\int T(\lambda )\mathrm{d}\lambda }{max[T(\lambda )]}.$$

As set forth by Camps et al. 2016, for energy measuring devices (bolometers) the total system transmission $T(\lambda )$ is usually given by the instrument designers, and it can be used directly for this class. For photon counters (including all instruments in the UV, optical and near infrared), the total system response $R(\lambda )$ is usually given instead. The transmission curve needed for this class can be derived from the response curve through

$$T(\lambda )=\lambda R(\lambda ).$$

Also, to further simplify the above formulas, the constructor normalizes the transmission curve to unity, i.e.

$$\int T(\lambda )\mathrm{d}\lambda =1.$$

Constructor & Destructor Documentation

__init__()

def pts.band.broadband.BroadBand.__init__	(		self,
			bandspec
	)

As mentioned in the class header, built-in Broadband instances can be obtained using one of the class functions builtinBands() or builtinBand() as opposed to directly invoking the constructor.

For more information, refer to the doumentation of these functions.

The constructor supports the following use cases, depending on the type of the bandspec argument:

• If bandspec is a string or a pathlib.Path, it should refer to a file in SKIRT stored table format that contains a properly normalized band definition (i.e., the same format as built-in band definitions). The BroadBand instance is constructed by loading the contents of this file.
• if bandspec is a tuple with two numbers, a bolometer-type band is constructed with a uniform transmission curve in the indicated (min,max) wavelength range expressed in micron.
• if bandspec is a two-dimensional numpy array, a custom bolometer-type band is constructed using bandspec[:,0] as wavelength grid and bandspec[:,1] as transmission curve. The wavelengths must be expressed in micron, while the transmission curve has arbitrary scaling. The array layout used here is identical to what one would obtain when applying numpy.loadtxt() to the input file for a SKIRT FileBand.

If bandspec has a different type, or if the string/path does not refer to a file in the proper format, the constructor raises an exception.

Note

As indicated above, the constructor expects the wavelengths specifying uniform and custom bands as plain numbers expressed in micron. In contrast, the wavelengths and transmissions stored and returned by this class are astropy quantities that include poper units. For uniform and custom bands, these units will be micron (wavelengths) and 1/micron (transmissions). For built-in bands, these units will be m (wavelengths) and 1/m (transmissions). Clients of this class should thus properly honor the astropy units of any values returned by this class.

Member Function Documentation

_addBuiltinBands()

def pts.band.broadband.BroadBand._addBuiltinBands (   cls,   directory  )

private

This private function recursively searches the contents of the specified directory and adds files with a name ending in "_BroadBand.stab" to the list of built-in bands.

_ensureBuiltinBands()

def pts.band.broadband.BroadBand._ensureBuiltinBands (   cls )

private

This private function adds any band definitions detected in the SKIRT or PTS resources directories to the list of built-in bands.

It does so only the first time it is called.

_normalize()

def pts.band.broadband.BroadBand._normalize (   self )

private

This private function normalizes the transmission curve for uniform and custom bands, and attaches the appropriate astropy units (micron and 1/micron, respectively).

builtinBand()

def pts.band.broadband.BroadBand.builtinBand	(		cls,
			nameSegments
	)

This function returns the single BroadBand instance that matches the specified criteria.

It raises an error if multiple bands or no band match the criteria.

• nameSegments is a string specifying broadband name segments seperated by an underscore, a comma or a space. A built-in broad-band matches as soon as its name contains all of the specified segments. The comparison is case-insensitive. To specify a given band, it suffices to include two or more segments of its name that uniquely identify the band, seperated by an underscore or a space. For example, to select the HERSCHEL_PACS_100 band, one could enter "Herschel 100", "PACS 100", or "HERSCHEL_PACS_100".

builtinBands()

def pts.band.broadband.BroadBand.builtinBands	(		cls,
			nameSegments = "",
			minWavelength = 0<<u.m,
			maxWavelength = 1e99<<u.m
	)

This function returns a list of BroadBand instances that match the specified criteria.

The list is in arbitrary order and can be empty.

• nameSegments is a string specifying broadband name segments seperated by an underscore, a comma or a space. A built-in broad-band matches as soon as its name contains one or more of the specified segments. The comparison is case-insensitive. An empty string (the default) matches all bands. To specify a set of bands, it suffices to include a name segment common to those bands. For example, to select all six Herschel bands, one could specify "Herschel" or "PACS,SPIRE".
• minWavelength and maxWavelength are astropy quantities specifying a wavelength range. A built-in broad-band matches only if its pivot wavelength is inside the specified range. The default values specify an unlimited wavelength range.

convolve()

def pts.band.broadband.BroadBand.convolve	(		self,
			wavelengths,
			fluxes,
		*	numWavelengths = None,
			flavor = None
	)

This function calculates and returns the band-averaged value $⟨F_{\lambda }⟩$ for a given spectral energy distribution $F_{\lambda }(\lambda )$.

For a band with transmission curve $T(\lambda )$,

$$⟨F_{\lambda }⟩=\frac{\int F_{\lambda }(\lambda )T(\lambda )\mathrm{d}\lambda }{\int T(\lambda )\mathrm{d}\lambda }.$$

The function in fact accepts a distribution (over a range of wavelengths) of various spectral quantities, including flux density, surface brightness, spectral radiance, or spectral luminosity of any "flavor" (neutral, per wavelength, or per frequency) and in arbitrary units. For the purposes of this function, these quantities are generically referred to as "flux". The incoming fluxes are converted to an equivalent "per-wavelength" flavor, the convolution is calculated according to the equation above, and the result is converted back to the flavor and units of the incoming fluxes, or to the optionally specified flavor and/or units.

The function accepts the following arguments:

• wavelengths: an astropy quantity array specifying the wavelengths ${\lambda }_{\ell }$, in increasing order, on which the fluxes are sampled. The convolution is performed on a wavelength grid that combines the grid points given here with the grid points on which the band transmission curve is defined.
• fluxes: an astropy quantity array specifying the flux distribution(s) $F_{\lambda }({\lambda }_{\ell })$. This can be an array with the same length as wavelengths, or a multi-dimensional array where the last dimension has the same length as wavelengths. The returned result will have the shape of fluxes minus the last (or only) dimension.
• numWavelengths: an integer specifying the approximate number of wavelength grid points used in the convolution calculation, or None (or omitted) to indicate no limit. The incoming flux distribution is resampled to all wavelength points in the combined convolution grid. Convolving large data cubes may thus consume a prohibitive amount of memory and/or computation time unless the number of wavelengths is limited.
• flavor: the flavor and/or units to which the result must be converted. If missing or None, the result is converted back to the flavor and units of the incoming fluxes. If specified, this can be one of the strings "neutral", "wavelength", or "frequency", or an explicit astropy unit instance that is compatible with the incoming flux type (density, brightness, luminosity), after flavor conversion.

effectiveWidth()

def pts.band.broadband.BroadBand.effectiveWidth

(

self

)

This function returns the effective band width (a wavelength interval) as defined in the class header as an astropy quantity.

maxWavelength()

def pts.band.broadband.BroadBand.maxWavelength

(

self

)

This function returns the maximum wavelength for the band, as an astropy quantity.

minWavelength()

def pts.band.broadband.BroadBand.minWavelength

(

self

)

This function returns the minimum wavelength for the band, as an astropy quantity.

name()

def pts.band.broadband.BroadBand.name

(

self

)

This function returns the built-in band's name, or "Uniform" or "Custom" for uniform or custom bands respectively.

pivotWavelength()

def pts.band.broadband.BroadBand.pivotWavelength

(

self

)

This function returns the pivot wavelength as defined in the class header, as an astropy quantity.

Note

The implementation here does purposefully not use a call to numpy.trapz() to exactly reproduce the numerical quadrature rule implemented in the Band class in SKIRT. This to avoid significant differences in pivot wavelength for a uniform band consisting of only two wavelength points. Both the implementation here and in SKIRT are bad approximations for the real pivot wavelength in this case, but at least they will be the same, which is important when identifying bands in SKIRT output.

transmissionCurve()

def pts.band.broadband.BroadBand.transmissionCurve

(

self

)

This function returns a tuple containing a copy of the wavelength and transmission arrays representing the transmission curve for this band, normalized to unity.

Both arrays are astropy quantities.

wavelengthRange()

def pts.band.broadband.BroadBand.wavelengthRange

(

self

)

This function returns a tuple of astropy quantities specifying the wavelength range for this band.

The transmission may be zero in some (usually small) intervals within the range, but it is guaranteed to be zero outside the range.

Member Data Documentation

_added

bool pts.band.broadband.BroadBand._added

staticprivate

Flag becomes True as soon as bandpaths have been added for the SKIRT and PTS resource directories.

_bandpaths

pts.band.broadband.BroadBand._bandpaths

staticprivate

The file paths for all detected built-in band definitions (i.e.

ending with "_BroadBand.stab")

---

The documentation for this class was generated from the following file:

• broadband.py