Dust Attenuation

Class computing the fraction of the emission from a galaxy which is transmitted through its dust.

Default implementation: dustAttenuationZero

Methods

transmission → double precision(size(descriptors))

Return the fraction of the emission transmitted through dust, for each of the given parcels of emission from the given node. A value of unity indicates no attenuation. The result has one element per element of descriptors, in the same order.

The value is non-negative, and is normally at most unity—but not necessarily. This is a directional transmission, the fraction reaching an observer in one particular direction, and where dust scatters light it can redirect more into that direction than it removes from it, leaving the galaxy brighter at that angle than it would be with no dust at all. Radiative transfer calculations show this at low optical depth and low inclination: the atlas of Ferrara et al. (1999) exceeds unity by up to 3% there. Consumers must therefore not assume an upper bound of one. Energy is still conserved, since what is gained along one line of sight is lost along others—a constraint on the average over orientation, not on any single direction.

inclination overrides the angle at which an orientation-dependent attenuator is evaluated, in radians. It is how dustAttenuationInclinationAveraged drives its quadrature: the wrapped attenuator is asked for the transmission at each angle in turn, without any shared state being mutated, so the arrangement is safe under threading. An implementation which does not depend on orientation ignores it; one which does falls back to its own galacticInclination object when it is absent.

• type(treeNode) node [inout]

• type(emissionDescriptor)(:) descriptors [in]

• double precision inclination (optional) [in]

request → type(decompositionRequest)

Return the resolution which a decomposition must have for this attenuator to be applied correctly: the boundaries of the age bins it distinguishes, and whether it depends upon component, metallicity, or radius. A producer of luminosities uses this to split its output no more finely than necessary.

The default requests no age resolution and no metallicity or radius resolution, but does request splitting by component—which is what any attenuator depending on the properties of an individual component needs.

supportsComponent → logical

Return true if this attenuator can be applied to emission from the given component.

The default accepts any individual component but rejects componentTypeAll: different components are attenuated differently, so a luminosity summed over components can not meaningfully be attenuated—it must be decomposed, attenuated, and only then summed. This is checked when the attenuating property extractor is constructed, so that a misconfiguration is reported immediately rather than part way through a run.

• type(enumerationComponentTypeType) componentType [in]

countPhases → integer

Return the number of distinct phases of dust—birth clouds and the diffuse interstellar medium, for example—into which this attenuator divides the absorption of light, so that the energy absorbed by each can be re-emitted with a spectrum of its own. The default is a single phase.

labelPhase → type(varying_string)

Return a label for the phase of dust with index indexPhase, used to name the luminosity it absorbs. The default is the short name of the class.

• integer indexPhase [in]

transmissionPhases → double precision, allocatable(:,:)

Return the transmission through each phase of dust separately, for each of the given parcels of emission. The first index of the result runs over parcels and the second over phases, which are ordered along the path of the light: the first phase is the one in which the light is emitted. The product over phases is the transmission returned by transmission, and inclination has the same meaning as there. The default is a single phase, whose transmission is that returned by transmission.

• type(treeNode) node [inout]

• type(emissionDescriptor)(:) descriptors [in]

• double precision inclination (optional) [in]

isOrientationDependent → logical

Return true if the transmission depends on the orientation of the galaxy relative to the observer. The luminosity absorbed by dust must then be averaged over orientation, since light scattered out of one line of sight escapes along another rather than being absorbed. The default is false.

includesTorus → logical

Return true if this attenuator includes a model of the dusty torus around an AGN. Light from an accretion disk whose spectrum already includes the emission of a torus (see accretionDiskSpectraClass) must not be attenuated by such a model, and property extractors use this to reject that combination at construction. Attenuators which combine others report true if any of them does. The default is false.

absorbedFractions → double precision, allocatable(:,:)

Return the fraction of the emission of each of the given parcels which is absorbed by each phase of dust, averaged over orientation. The first index of the result runs over parcels and the second over phases.

For a phase \(k\) of transmission \(T_k\), reached by light which has already passed through phases \(1\) to \(k-1\), the absorbed fraction is \(f_k = (1-T_k)\prod_{j<k} T_j\), so that the fractions sum to one minus the total transmission. Counting one minus the transmission as absorbed is exact for an attenuator which conserves energy once averaged over orientation—a radiative transfer atlas, for example—and is the standard interpretation of the effective attenuation laws applied through screens, such as that of Charlot and Fall (2000), whose transmission already allows on average for light scattered back into the line of sight. It over-estimates absorption if a screen is given the extinction curve of the grains themselves, since that counts scattered light as absorbed.

Where the attenuator depends on orientation the fractions are computed at each abscissa of the quadrature rule given by cosineInclination and weight—whose weights must sum to unity, so that the rule averages over \(\cos i\) between zero and one—and then averaged. The product over phases is formed at each orientation before averaging, since the average of a product is not the product of the averages. An orientation-independent attenuator is evaluated once. Fractions are clamped to be non-negative: a directional transmission may exceed unity, and although its average over orientation should not, a tabulation is only so accurate.

• type(treeNode) node [inout]

• type(emissionDescriptor)(:) descriptors [in]

• double precision(:) cosineInclination [in]

• double precision(:) weight [in]

dustAttenuationAGNTorus

A clumpy torus of dust around the accretion disk of an AGN, following Nenkova et al. (2008). Clouds of dust, each of \(V\)-band optical depth [depthOpticalCloudV], are distributed about the equatorial plane of the torus such that the mean number met along a ray leaving the accretion disk at an angle \(\beta\) from that plane is

\[N(\beta) = N_0 \exp\left( -\frac{\beta^2}{\sigma^2} \right),\]

where \(N_0\) is [countCloudsEquatorial]. For clouds placed at random (Poisson distributed) along the ray, the mean transmission is that of a screen of effective optical depth \(N(\beta)[1-\exp(-\tau_\lambda)]\) (Natta and Panagia, 1984),

\[T(\lambda,\beta) = \exp\left\{ -N(\beta) \left[ 1 - \exp\left( -\tau_\mathrm{V} \frac{k(\lambda)}{k_\mathrm{V}} \right) \right] \right\},\]

with the wavelength dependence \(k(\lambda)/k_\mathrm{V}\) taken from the [dustExtinctionCurve] object. One minus this transmission is counted as absorbed, which counts light scattered by the clouds as absorbed too.

Covering fraction. The torus covers a fraction

\[f_\mathrm{cov} = \int_0^{\pi/2} \left\{ 1 - \exp\left[ -N(\beta) \right] \right\} \cos\beta\,\mathrm{d}\beta\]

of the sky as seen from the accretion disk—the probability that a ray meets at least one cloud. The angular width \(\sigma\) is chosen for each galaxy so that this equals the covering fraction given by the [blackHoleTorusCoveringFraction] object, which may depend on the luminosity of the AGN (as in the receding torus model). The largest covering fraction a torus of \(N_0\) clouds can have is \(1-\exp(-N_0)\), reached as \(\sigma\rightarrow\infty\); a larger one is reduced to it. Because the clouds thin out smoothly away from the equatorial plane, rather than ending at a sharp edge, the transmission is a smooth function of orientation, so that averages over orientation by quadrature—as made by dustAttenuationInclinationAveraged and when finding the luminosity absorbed by dust—converge rapidly.

What is attenuated. Only the continuum emission of the accretion disk of the central black hole (emissionSourceAccretionDisk emitted by componentTypeBlackHole) is attenuated. The narrow-line region lies beyond the torus, so emission lines from the AGN (emissionSourceNebular) are not attenuated, nor is any emission from other components. To see AGN light through the dust of the host galaxy as well, combine this attenuator with others through dustAttenuationSequence, listing it first, since the torus is where the light is emitted.

Orientation. The torus is seen at the inclination \(i\) given by the [galacticInclination] object, with \(\beta=\pi/2-i\). With most classes that is the inclination of the host galaxy, so that the axis of the torus is that of its galaxy; with galacticInclinationMisaligned the axis of the torus is misaligned from that of its galaxy. When averaging over orientation, at the inclination of the galaxy passed in, the average is taken also over the orientations of the torus relative to its galaxy that the [galacticInclination] object gives through its inclinationsMisaligned method.

Spectrum of the accretion disk. The light attenuated must be that of the accretion disk alone. A spectrum which already includes the emission of a dusty torus—that of accretionDiskSpectraHopkins2007, the default, for example—can not be attenuated by this model, which would count the emission of the torus twice; property extractors report that combination as an error at construction. Use, for example, accretionDiskSpectraThinDisk.

Methods

coveringFractionWidth → double precision

Return the covering fraction of a torus of the given angular width, \(\sigma\), in radians.

• double precision widthAngular [in]

widthAngular → double precision

Return the angular width, \(\sigma\) in radians, of the torus around the central black hole of the given node.

• type(treeNode) node [inout]

Parameters

• [countCloudsEquatorial] (real; 0..1; default 5.0d0) — The mean number of clouds, \(N_0\), met along a ray in the equatorial plane of the torus. Default from: Nenkova et al. (2008), who find 5–15.

• [depthOpticalCloudV] (real; 0..1; default 30.0d0) — The \(V\)-band optical depth, \(\tau_\mathrm{V}\), of each cloud. Default from: Nenkova et al. (2008), who find 30–100.

dustAttenuationAGNTorusSKIRTOR

The dusty torus around the accretion disk of an AGN, using the SKIRTOR library of radiative transfer models of a two-phase (clumpy plus smooth) torus (Stalevski et al., 2012, Stalevski et al., 2016). The models are selected by the edge-on optical depth at \(9.7\,\mu\hbox{m}\) ([depthOpticalEdgeOn]), the exponents of the radial ([exponentDensityRadial]) and polar ([exponentDensityPolar]) gradients of dust density, and the ratio of outer to inner radius ([ratioRadii]), each of which must be one of the values tabulated. The angle of the torus is set for each galaxy from its covering fraction (see below).

Transmission. SKIRTOR tabulates, for each model and inclination \(i\), the flux of the accretion disk seen directly (\(F_\mathrm{direct}\)), seen after scattering by the dust (\(F_\mathrm{scattered}\)), and as it would be with no dust (\(F_\mathrm{transparent}\)). The transmission is

\[T(\lambda,i) = \frac{F_\mathrm{direct}(\lambda,i)}{F_\mathrm{transparent}(\lambda,i)} + \frac{F_\mathrm{scattered}(\lambda,i)}{\langle F_\mathrm{transparent}(\lambda) \rangle},\]

where \(\langle\rangle\) denotes an average over all directions. The first term is the transmission along the line of sight, which depends only on the dust, and so applies to an accretion disk which emits isotropically—as assumed here—although the accretion disk of SKIRTOR does not (Netzer, 1987). The second is light scattered towards the observer: since that was emitted in other directions it is counted relative to the mean flux of the accretion disk. Light scattered by the torus is therefore not counted as absorbed. At wavelengths shorter than about \(0.01\,\mu\hbox{m}\) Monte Carlo noise in the scattered flux of some models can make the transmission, averaged over orientation, exceed one; where it does, the scattered term is reduced to make that average exactly one, so that the absorbed luminosity is never negative.

\(T\) is interpolated linearly in inclination and in the logarithm of wavelength, and held fixed beyond the tabulated range of wavelength (\(0.001\) to \(1000\,\mu\hbox{m}\)).

Covering fraction. The covering fraction of each model is taken to be the fraction of the sky obscured in the \(V\) band,

\[f_\mathrm{cov} = 1 - \int_0^{\pi/2} \frac{F_\mathrm{direct}(\lambda_\mathrm{V},i)}{F_\mathrm{transparent}(\lambda_\mathrm{V},i)} \sin i\,\mathrm{d}i,\]

with the same interpolation in inclination. This exceeds \(\sin(\hbox{angle of the torus})\), the covering fraction of the tabulated geometry, because the tabulation, spaced by \(10^\circ\) in inclination, can not resolve the edge of the torus, which interpolation spreads over that interval; defined this way, the covering fraction is that of the attenuation actually applied. For each galaxy the two models whose covering fractions bracket that given by the [blackHoleTorusCoveringFraction] object are combined linearly, which—since \(f_\mathrm{cov}\) is linear in \(T\)—gives exactly that covering fraction. A covering fraction outside the range spanned by the models (for the default parameters, \(0.26\) to \(0.98\)) is moved to its nearer end. The covering fraction must increase with the angle of the torus; for two sets of parameters ([depthOpticalEdgeOn]=3, [exponentDensityRadial]=0, [exponentDensityPolar]=1.5 and [ratioRadii]=10 or \(30\)) Monte Carlo noise makes it decrease slightly between the two largest angles but one, and those sets can not be used.

What is attenuated. As for dustAttenuationAGNTorus, only the continuum emission of the accretion disk of the central black hole (emissionSourceAccretionDisk emitted by componentTypeBlackHole) is attenuated, and the torus is seen at the inclination given by the [galacticInclination] object—that of its host galaxy, or, with galacticInclinationMisaligned, that of a torus whose axis is misaligned from that of its galaxy, in which case averages over orientation are taken also over the orientation of the torus relative to its galaxy.

Tabulation. The library is read from [fileName], in the dust/agnTorus directory of the dynamic datasets path; if it is not present it is downloaded from [url]. The file is made from the SKIRTOR library, as distributed by its authors, by dataPreparation/convertSKIRTOR.py of the galacticusDevTools repository (https://github.com/galacticusorg/galacticusDevTools). By default it is downloaded from the copy archived on Zenodo (https://doi.org/10.5281/zenodo.23424967), which is redistributed with the permission of the authors of SKIRTOR.

Spectrum of the accretion disk. The light attenuated must be that of the accretion disk alone. A spectrum which already includes the emission of a dusty torus—that of accretionDiskSpectraHopkins2007, the default, for example—can not be attenuated by this model, which would count the emission of the torus twice; property extractors report that combination as an error at construction. Use, for example, accretionDiskSpectraThinDisk.

Parameters

• [fileName] (string; 0..1; default SKIRTOR_2016-7-18.hdf5) — The name of the file holding the SKIRTOR tabulation, in the dust/agnTorus directory of the dynamic datasets path.

• [url] (string; 0..1; default https://zenodo.org/records/23424967/files/SKIRTOR_2016-7-18.hdf5) — The URL from which to download fileName if it is not already present. If none, the file must be supplied by other means.

• [depthOpticalEdgeOn] (real; 0..1; default 7.0d0) — The optical depth at \(9.7\,\mu\hbox{m}\) of the torus seen edge-on. One of 3, 5, 7, 9 or 11. Default from: The default of the SKIRTOR module of CIGALE (Boquien et al., 2019).

• [exponentDensityRadial] (real; 0..1; default 1.0d0) — The exponent, \(p\), of the radial gradient of dust density, \(\rho \propto r^{-p}\). One of 0, 0.5, 1 or 1.5. Default from: The default of the SKIRTOR module of CIGALE (Boquien et al., 2019).

• [exponentDensityPolar] (real; 0..1; default 1.0d0) — The index, \(q\), of the polar gradient of dust density, \(\rho \propto \exp(-q|\cos\theta|)\). One of 0, 0.5, 1 or 1.5. Default from: The default of the SKIRTOR module of CIGALE (Boquien et al., 2019).

• [ratioRadii] (real; 0..1; default 20.0d0) — The ratio of the outer to the inner radius of the torus. One of 10, 20 or 30. Default from: The default of the SKIRTOR module of CIGALE (Boquien et al., 2019).

dustAttenuationAtlasCompendium

Dust attenuation from the dust compendium of Benson (2018): radiative transfer solutions for simple galactic geometries, tabulating the fraction of light escaping a galaxy as a function of wavelength, inclination, optical depth, and—for the spheroid—the size of the spheroid relative to the disk.

This is a non-separable attenuator, exactly as dustAttenuationAtlasFerrara2000 is: the tabulated escape fraction is the result of a radiative transfer calculation through a specified geometry, and is not the exponential of a single optical depth times a wavelength-dependent curve, so it takes no dustExtinctionCurve. It also means the transmission can slightly exceed unity where scattering redirects more light into the line of sight than the dust removes from it.

The tabulations are published as a set of HDF5 files, one per combination of grain properties and geometry, and are described in the dust compendium datasets section of the user guide. fileName selects one. If that file is not already present it is downloaded and cached under the dynamic datasets path, so a file is fetched once and reused thereafter. The published file names are known to this class, so naming one is enough; url is needed only for a tabulation which is not among them, such as one the user has produced themselves.

Be aware of the size of these files, which is the reason for the trimming parameters below. Half of each file is Monte Carlo uncertainties, which are not read. The version 2 compendium tabulations are 299 MB apiece, on a grid of 250 wavelengths, 23 inclinations, 61 optical depths, and 51 spheroid sizes, of which 151 MB is read. All but the six original-resolution Ferrara et al. (1999) tabulations among the rest are 584 MB apiece, on a grid of 250 wavelengths, 46 inclinations, 60 optical depths, and 51 spheroid sizes, of which 297 MB is read. Almost all of either figure is the spheroid table.

The tables themselves are held once and shared, rather than being duplicated by the deep copy which gives each OpenMP thread its own attenuator, so that figure is paid once per distinct tabulation rather than once per thread per instance. Two instances reading different files, or the same file trimmed differently, get separate tables. The interpolators are not shared, each caching a bracket index and a GSL accelerator which it mutates as it works; they stay per-thread, where they are small.

Restricting each axis to the range actually needed reduces what is held further—wavelengthMinimum, wavelengthMaximum, opticalDepthMaximum, radiusSpheroidMinimum, and radiusSpheroidMaximum below. Only the retained part of each axis is read from the file, as an HDF5 hyperslab, so a trimmed tabulation is never held at full size even transiently. Trimming changes no result which lies inside the retained range: the bracketing nodes on either side are kept, so values within the range are interpolated exactly as they would have been from the full table.

Two quantities are supplied per galaxy rather than tabulated:

• The \(V\)-band optical depth through the center of the galaxy, perpendicular to the plane. Unlike dustAttenuationAtlasFerrara2000, which delegates this to a dustAttenuationScreen, it is computed here from the tabulation’s own opacity, read from the opacity attribute of the file:

  \[\tau_\mathrm{V} = \kappa_\mathrm{V} \, f_\mathrm{dust:metals} \, \Sigma_\mathrm{Z},\]

  with \(\kappa_\mathrm{V}\) the \(V\)-band opacity per unit mass of dust used in the radiative transfer calculation, \(f_\mathrm{dust:metals}\) the dust-to-metals ratio of the disk supplied by a dustPropertiesClass object, and \(\Sigma_\mathrm{Z} = Z M_\mathrm{gas} / 2 \pi r_\mathrm{d}^2\) the central surface density of gas-phase metals of the disk. Using the opacity which produced the table is what makes the optical depth mean the same thing to the model as it does to the tabulation.

  The dustProperties object must therefore have the opacity of the tabulation, and an error is reported at construction if its opacityExtinctionV differs from it by more than one part in a million: only then is the dust which attenuates the galaxy’s light the same dust whose mass any emission calculation uses. The default dustPropertiesSimple has the opacity which reproduces the Milky Way calibration of Savage and Mathis (1979), which differs from that of the grain models used to compute the compendium, so this attenuator will normally need a dustProperties object of its own. Placing one inside its parameter block leaves every other attenuator unchanged:

  <dustAttenuation value="atlasCompendium">
    <fileName value="Ferrara1999_MW_hz1.0_Attenuations.hdf5"/>
    <dustProperties value="simple">
      <dustToMetalsRatio  value="0.44"         />
      <opacityExtinctionV value="32148.5640546"/>
    </dustProperties>
  </dustAttenuation>
  

  As in dustAttenuationAtlasFerrara2000, the optical depth is always that of the disk, whichever component is being attenuated: the dust lies in the disk, and a spheroid is reddened by the disk’s dust.

• The inclination, from a galacticInclinationClass object, or from the inclination argument when one is imposed, as dustAttenuationInclinationAveraged does. One or the other must be available, and an error is reported if neither is.

• The size of the spheroid, in the units the spheroidScaleRadial axis is tabulated against. Note that this axis does not mean the same thing as the corresponding axis of dustAttenuationAtlasFerrara2000: Ferrara et al. (1999) tabulate against the spheroid effective radius, whereas the compendium tabulates against the spheroid scale radius. spheroidProfile names the profile the tabulation was computed for—hernquist for most of them, jaffe for those computed to match Ferrara et al. (1999)—and the model’s spheroid is matched to it on half-mass radius, which is the radius that means the same thing whatever profile either side assumes, then converted to that profile’s scale radius. For a Hernquist profile the half-mass radius is \((1+\sqrt{2})\) times the scale radius, and for a Jaffe profile the two are equal.

Beyond the largest tabulated optical depth the transmission is extrapolated as \(T = \exp(c_0 + c_1 \ln \tau_\mathrm{V})\), using coefficients tabulated alongside the attenuations. Setting extrapolateOpticalDepth to false instead holds the transmission at its value at the tabulation boundary.

The optical depth axis is interpolated logarithmically, which is worth roughly a factor of two in accuracy over interpolating linearly on the geometric grids these tabulations use, but which a tabulated zero can not take part in. The tabulations generally do carry a zero-optical-depth entry, at which the transmission is unity; it is dropped on reading, and below the smallest remaining depth the transmission is instead interpolated linearly back towards unity. Clamping there would leave a galaxy with almost no dust as attenuated as one at the tabulation’s lower edge, which in the ultraviolet is not a small difference.

Parameters

• [fileName] (string; 1) — The name of the dust compendium tabulation file to use, for example Ferrara1999_MW_hz1.0_Attenuations.hdf5. If no file of this name is present under the dust/compendium directory of the dynamic datasets path it is downloaded—from the Zenodo record holding it if it is one of the published tabulations, and otherwise from url.

• [url] (string; 0..1; default none) — The URL from which to download fileName if it is not already present and is not one of the published tabulations, whose locations this class already knows. If none, such a file must be supplied by other means.

• [wavelengthMinimum] (real; 0..1; default 0.0d0) — The shortest wavelength, in Angstroms, which need be represented. Tabulated wavelengths below this are not read. Zero retains the whole axis.

• [wavelengthMaximum] (real; 0..1; default huge(0.0d0)) — The longest wavelength, in Angstroms, which need be represented. Tabulated wavelengths above this are not read.

• [opticalDepthMaximum] (real; 0..1; default huge(0.0d0)) — The largest \(V\)-band optical depth which need be represented. Tabulated depths above this are not read, and galaxies exceeding it have their transmission held at the retained boundary. There is no corresponding minimum: the low-depth end of the axis costs little and is always needed.

  Trimming this axis requires extrapolateOpticalDepth to be false, and is refused otherwise. The extrapolation coefficients describe the behavior beyond the largest depth in the file and are anchored there; applied just above a trimmed boundary they are far outside the range they were fitted over, and for the published high-resolution tabulation would overestimate the transmission by a factor of seven at an optical depth of five.

• [radiusSpheroidMinimum] (real; 0..1; default 0.0d0) — The smallest spheroid size, as a scale radius in units of the disk scale length, which need be represented. Zero retains the whole axis.

• [radiusSpheroidMaximum] (real; 0..1; default huge(0.0d0)) — The largest spheroid size, as a scale radius in units of the disk scale length, which need be represented.

• [extrapolateOpticalDepth] (boolean; 0..1; default .true.) — If true, transmissions for optical depths beyond the largest tabulated value are extrapolated using the coefficients supplied with the tabulation. If false, they are held at the value at the tabulation boundary.

• [spheroidProfile] (string; 0..1; one of hernquist, jaffe; default hernquist) — The spheroid density profile for which the tabulation was computed: hernquist, or jaffe for tabulations computed to match Ferrara et al. (1999). This sets how a model galaxy’s spheroid is mapped onto the spheroidScaleRadial axis. For a published tabulation the value is checked against the profile that file was actually computed with, since getting it wrong is a silent error of tens of percent.

dustAttenuationAtlasFerrara2000

Dust attenuation from the radiative transfer atlas of Ferrara et al. (1999), which tabulates the fraction of light escaping a galaxy as a function of wavelength, inclination, optical depth, and—for the spheroid—the size of the spheroid relative to the disk.

This is a non-separable attenuator. The tabulated escape fraction is the result of a radiative transfer calculation through a specified geometry, and is not the exponential of a single optical depth times a wavelength-dependent curve, so it takes no dustExtinctionCurve—the wavelength dependence is in the table, which is the point of tabulating it. It also means the transmission can slightly exceed unity at low optical depth and low inclination, where scattering redirects more light into the line of sight than the dust removes from it.

The tabulation is selected by two parameters: dust, the extinction curve of the grains, either milkyWay or smallMagellanicCloud; and heightRatio, the ratio of the dust scale height to the stellar scale height, one of 0.4, 1.0, or 2.5.

Two quantities are supplied per galaxy rather than tabulated:

• The optical depth, obtained from a dustAttenuationScreen object through its depthOpticalV method. Delegating this keeps the normalization of the dust content in one place—a dustAttenuationScreenSurfaceDensityMetals takes it from the same dustPropertiesClass object as every other attenuator—and lets a fixed depth be substituted for testing. It is always evaluated for the disk, whichever component is being attenuated: in this model the dust lies in the disk and a spheroid is reddened by the disk’s dust, so asking for a spheroid’s own optical depth would compute a surface density of a component holding no dust here.

  The atlas defines its optical depth as that through the center of the galaxy perpendicular to the plane, in the \(V\) band. For an exponential disk \(\Sigma_0 = M/2\pi r_\mathrm{d}^2\), which is what screenSurfaceDensityMetals computes, so the definitions agree.

• The size of the spheroid, on the axis the atlas tabulates. That axis is not a radius of the profile the atlas actually simulated: Ferrara et al. (1999) realize their spheroids as Jaffe profiles, but label the axis with the effective radius \(R_\mathrm{e}\) of the \(R^{1/4}\) profile those Jaffe profiles stand in for. Bianchi et al. (1996), whose radiative transfer code the atlas was computed with, give the correspondence in their appendix as \(r_\mathrm{b} = 1.16 R_\mathrm{e}\), with \(r_\mathrm{b}\) the Jaffe scale radius—chosen as the relation which best matches the luminosity enclosed within a given radius, since that is what their Monte Carlo samples.

  For a Jaffe profile the enclosed mass is \(M(r)/M = (r/r_0)/(1+r/r_0)\), so the half-mass radius is exactly the scale radius. One unit of the tabulated axis therefore corresponds to \(1.16\) half-mass radii, and a model galaxy’s half-mass radius is divided by that factor before being interpolated in. Omitting it would place every spheroid 16 percent too far out along the axis, worth up to about ten percent in transmission at the largest tabulated optical depths, and little at small ones.

• The inclination, from a galacticInclinationClass object, or from the inclination argument when one is imposed, as dustAttenuationInclinationAveraged does. One or the other must be available, and an error is reported if neither is.

Parameters

• [dust] (string; 0..1; one of milkyWay, smallMagellanicCloud; default milkyWay) — The extinction curve of the dust grains: milkyWay or smallMagellanicCloud.

• [heightRatio] (real; 0..1; default 1.0d0) — The ratio of the dust scale height to the stellar scale height. Tabulations exist for 0.4, 1.0, and 2.5.

dustAttenuationBirthCloud

Attenuation of stellar populations which remain embedded in the dense clouds from which they formed. Stars younger than timescale are attenuated by a screen of \(V\)-band optical depth

\[\tau_\mathrm{V} = \kappa_\mathrm{V} \, f_\mathrm{dust:metals} \, Z \, \Sigma_\mathrm{cloud},\]

the column of dust through a birth cloud of gas surface density \(\Sigma_\mathrm{cloud}\) (densitySurfaceGas) whose metallicity \(Z\) is that of the gas of the component in which the stars formed. The \(V\)-band extinction opacity per unit mass of dust, \(\kappa_\mathrm{V}\), and the dust-to-metals ratio, \(f_\mathrm{dust:metals}\), are supplied by a dustPropertiesClass object—normally the same one which sets the dust content of the diffuse interstellar medium. Stars older than timescale are not attenuated at all by this class. This is the birth cloud term of the Charlot and Fall (2000) model.

The default column, \(\Sigma_\mathrm{cloud} \approx 22.8\,M_\odot\,\hbox{pc}^{-2}\), is the one for which a cloud of local interstellar medium metallicity has \(\tau_\mathrm{V}=1\) with the default dustPropertiesSimple.

Note that the optical depth depends only on the metallicity of the host component, not on its surface density: a birth cloud is a local structure, and its column is not set by the global structure of the galaxy.

A parcel of emission whose age is unresolved spans all ages, and is therefore treated as old and left unattenuated rather than being attenuated as though it were entirely young. Emission from the central black hole is not surrounded by birth clouds, and is also left unattenuated. Combine this class with a dustAttenuationScreenClass through dustAttenuationSequence to obtain the full two-component model.

Parameters

• [densitySurfaceGas] (real; 0..1; default densitySurfaceGasDepthOpticalVUnitMilkyWay) — The surface density of gas through a stellar birth cloud, in \(M_\odot\,\hbox{pc}^{-2}\). Default from: The column for which a cloud of local interstellar medium metallicity has unit \(V\)-band optical depth with the default dust properties.

• [timescale] (real; 0..1; default 1.0d-2) — The lifetime of a stellar birth cloud, in Gyr. Stellar populations younger than this are attenuated by their birth cloud; older populations are not. Default from: Charlot and Fall (2000).

dustAttenuationCharlotFall2000

The two-component dust attenuation model of Charlot and Fall (2000): young stars are attenuated both by the dust of the birth clouds in which they remain embedded and by the diffuse dust of the interstellar medium, while older stars, having escaped their birth clouds, are attenuated only by the diffuse component.

This class carries no physics of its own. It is exactly

<dustAttenuation value="sequence">
  <dustAttenuation value="birthCloud">
    <dustExtinctionCurve value="powerLaw"><exponent value="0.7"/></dustExtinctionCurve>
  </dustAttenuation>
  <dustAttenuation value="screenSurfaceDensityMetals">
    <dustExtinctionCurve value="powerLaw"><exponent value="0.7"/></dustExtinctionCurve>
  </dustAttenuation>
</dustAttenuation>

and is provided because that is the combination users most often want and because it pins the canonical parameter values of the model in one place. Both components take the mass of their dust from the same dustPropertiesClass object, so that changing the dust-to-metals ratio changes the optical depth of birth clouds and diffuse medium alike. Anything expressible here is expressible with dustAttenuationSequence; use that directly to vary the extinction curve of either component independently, or to build a model with more than two components.

Its two phases of dust are the birth clouds and the diffuse interstellar medium, in that order, labeled birthCloud and screenSurfaceDensityMetals, so that the energy each absorbs can be re-emitted separately.

Parameters

• [coefficientBirthCloud] (real; 0..1; default 1.0d0) — A dimensionless multiplicative coefficient applied to the gas column of birth clouds, in units of the column for which a cloud of local interstellar medium metallicity has unit \(V\)-band optical depth with the default dust properties. With those defaults it is therefore the \(V\)-band optical depth of such a cloud.

• [coefficientISM] (real; 0..1; default 1.0d0) — A dimensionless multiplicative coefficient applied to the \(V\)-band optical depth of the diffuse interstellar medium, representing the effects of geometry. It does not change the mass of dust.

• [timescale] (real; 0..1; default 1.0d-2) — The lifetime of a stellar birth cloud, in Gyr. Default from: Charlot and Fall (2000).

• [exponent] (real; 0..1; default 0.7d0) — The exponent of the power-law extinction curve applied to both components. Default from: Charlot and Fall (2000).

• [wavelengthReference] (real; 0..1; default wavelengthVBand) — The wavelength, in Å, at which the power-law extinction curve is normalized to unity. Set it to \(5500\,\text{Å}\) to reproduce the lmnstyStllrCF2000 property extractor exactly.

dustAttenuationInclinationAveraged

A dust attenuation class which averages the transmission of another attenuator over orientation, for models in which no inclination is available for each galaxy—which is the default, see galacticInclinationNull.

Orientations are isotropic, so uniform in \(\cos i\), and the average is

\[\bar{T}(\lambda) = \int_0^1 T(\lambda,i) \, \mathrm{d}\cos i.\]

It is the transmission which is averaged, not the optical depth. Those are not the same thing: attenuation is exponential in optical depth, so a galaxy seen at a range of orientations transmits more light than one seen at the mean optical depth, and averaging the depth instead would systematically over-attenuate. What an observer averaging over an orientation-blind sample measures is the mean flux, which is the mean transmission.

The wrapped attenuator is evaluated at each abscissa through the optional inclination argument of its transmission method, so nothing is mutated and the arrangement is safe under threading. Wrapping a dustAttenuationSequence averages the sequence as a whole—the product of its members evaluated at a common orientation—rather than the product of separately averaged members, which is a different and incorrect quantity.

The integral is evaluated by Gauss-Legendre quadrature of order order. Fixed-order quadrature is used in preference to an adaptive rule because the integrand is smooth and bounded, so it converges quickly, and because the cost of the average multiplies the cost of every luminosity: a fixed order makes that cost predictable and puts it under the user’s control. Order 8 is accurate to better than one part in \(10^{6}\) for the attenuation curves of interest.

The phases of dust of the wrapped attenuator are preserved. Their absorbed fractions are averaged over orientation with this class’s own quadrature, whether or not a consumer asks for an average, and the class itself reports no dependence on orientation.

Parameters

• [order] (integer; 0..1; default 8) — The order of the Gauss-Legendre quadrature used to average over orientation. The cost of the average is proportional to this.

dustAttenuationMixedSlab

Attenuation by dust mixed uniformly with the emitting stars, rather than lying in a screen in front of them. For a slab in which emitters and absorbers are uniformly interspersed the emergent fraction is

\[T = \frac{1-\mathrm{e}^{-\tau}}{\tau},\]

which tends to unity as \(\tau \rightarrow 0\) and, crucially, falls only as \(1/\tau\) at large optical depth rather than exponentially: stars on the near side of the slab always escape, so a mixed geometry can never extinguish a component completely. This is the qualitative difference from a screen, and it matters whenever the inferred optical depths are large.

This class is a decorator: it takes the transmission \(T_\mathrm{screen}\) computed by any other attenuator, recovers the equivalent optical depth \(\tau = -\ln T_\mathrm{screen}\), and re-applies it in the mixed geometry. Any prescription for how much dust a galaxy has can therefore be used in either geometry without being reimplemented.

dustAttenuationScreen

An abstract dust attenuation class describing a uniform screen of dust lying between the emitting stars and the observer, so that

\[T(\lambda) = \exp\left[ -\tau_\mathrm{V} \frac{k(\lambda)}{k_\mathrm{V}} \right],\]

where the wavelength dependence \(k(\lambda)/k_\mathrm{V}\) is supplied by a dustExtinctionCurveClass object and the normalization \(\tau_\mathrm{V}\) by the depthOpticalV method of a concrete subclass. Separating the two means any extinction curve may be combined with any prescription for how much dust a galaxy has.

A screen is the simplest possible geometry. It attenuates all of the light it is applied to equally, and—unlike a mixed distribution of dust and stars—has no upper limit to the attenuation it can produce.

When the absorbed luminosity is needed—to be re-emitted by dust—one minus the transmission is counted as absorbed. That is the standard interpretation of an effective attenuation law, such as the power law of Charlot and Fall (2000) or the curve of Calzetti et al. (2000), whose transmission already allows on average for light scattered back into the line of sight. It over-estimates the absorbed energy if the screen is given the extinction curve of the grains themselves (that of Cardelli et al. (1989), say), since that counts light which is merely scattered as absorbed.

Methods

depthOpticalV → double precision

Return the \(V\)-band optical depth of the screen for one component of one node.

• type(treeNode) node [inout]

• type(enumerationComponentTypeType) componentType [in]

dustAttenuationScreenFixed

A uniform dust screen whose \(V\)-band optical depth is a fixed parameter, independent of the properties of the galaxy. This is the appropriate choice when the optical depth is to be treated as a free parameter—when fitting an observed spectral energy distribution, for example—rather than predicted from a model of the interstellar medium.

Parameters

• [depthOpticalV] (real; 0..1; default 1.0d0) — The \(V\)-band optical depth of the dust screen.

dustAttenuationScreenSurfaceDensityMetals

A uniform dust screen whose \(V\)-band optical depth is proportional to the surface density of dust in the component being attenuated,

\[\tau_\mathrm{V} = C \, \kappa_\mathrm{V} \, f_\mathrm{dust:metals} \, \Sigma_\mathrm{Z},\]

where \(\Sigma_\mathrm{Z}\) is the surface density of metals in the gas, and the \(V\)-band extinction opacity per unit mass of dust, \(\kappa_\mathrm{V}\), and the dust-to-metals ratio, \(f_\mathrm{dust:metals}\), are supplied by a dustPropertiesClass object. Taking both from that object, rather than fixing them here, keeps the dust which attenuates a galaxy’s light consistent with the dust which re-emits it. With the default dustPropertiesSimple the product \(\kappa_\mathrm{V} f_\mathrm{dust:metals}\) reproduces the Milky Way relation between column density and reddening of Savage and Mathis (1979).

The dimensionless coefficient \(C\) (coefficient) scales the optical depth without changing the mass of dust. It therefore stands for the effects of geometry—clumping of the dust, say, or a screen which covers only part of the emission—and should not be used to change how much dust a galaxy has: set the dust-to-metals ratio of the dustPropertiesClass object for that.

The surface density is that of an exponential disk or of a spheroid of the same scale radius, \(\Sigma_\mathrm{Z} = Z M_\mathrm{gas} / 2\pi r^2\), and is taken to be zero for a component with no gas or no size.

Emission from the central black hole—the continuum of its accretion disk, and the lines of its narrow-line region—arises at the center of the galaxy, and so is seen through the dust of both the disk and the spheroid: its optical depth is the sum of theirs.

Parameters

• [coefficient] (real; 0..1; default 1.0d0) — A dimensionless multiplicative coefficient applied to the \(V\)-band optical depth, representing the effects of geometry. It does not change the mass of dust, which is set by the dustProperties object.

dustAttenuationSequence

A dust attenuation class which applies a sequence of other attenuators, returning the product of their transmissions. Because transmission is multiplicative, this is exactly the result of the light passing through each in turn, and the order in which they are listed does not change the total transmission.

The order does matter for absorption. Each member contributes its phases of dust, in the order listed, and the light is taken to pass through them in that order: the first member is where it is emitted. A phase absorbs a fraction of only the light which has survived the phases before it, so list a birth cloud before the diffuse interstellar medium which surrounds it. The sequence depends on orientation if any member does.

The canonical use is to build a two-component model: a dustAttenuationBirthCloud attenuating young populations, followed by a diffuse interstellar medium screen attenuating everything. See dustAttenuationCharlotFall2000 for that combination pre-assembled.

The decomposition requested by a sequence is the union of those requested by its members: the age bin boundaries are merged, and an axis is resolved if any member depends upon it. A component is supported only if every member supports it.

dustAttenuationStellarMassRedshift

A uniform dust screen whose attenuation at a reference wavelength (by default that of H\(\alpha\)) depends on the stellar mass and redshift of the galaxy, following the relation of Garn and Best (2010) between H\(\alpha\) attenuation and stellar mass, generalized with free offsets and slopes:

\[\bar{A} = A_\mathrm{GB10}(X) + \delta_0 + \delta_\mathrm{M} X + \delta_z u + \delta_{\mathrm{M}z} X u,\]

where \(X = \log_{10}(M_\star/10^{10}\mathrm{M}_\odot)\), with \(M_\star\) limited to the range [[massStellarMinimum], [massStellarMaximum]], \(u = \ln[(1+z)/(1+z_\mathrm{p})]\) with \(z_\mathrm{p}\) given by [redshiftPivot], and

\[A_\mathrm{GB10}(X) = 0.91 + 0.77 X + 0.11 X^2 - 0.09 X^3.\]

The parameters \(\delta_0\), \(\delta_\mathrm{M}\), \(\delta_z\), and \(\delta_{\mathrm{M}z}\) are given by [delta0], [deltaMass], [deltaRedshift], and [deltaMassRedshift]. The attenuation applied is \(\max(\bar{A},0)\) (in magnitudes) at the wavelength [wavelengthReference], and scales with wavelength following the [dustExtinctionCurve], so that the same screen may attenuate other emission lines consistently. Any scatter in the attenuation about this mean relation is applied separately, by the outputAnalysisDistributionOperatorAttenuationScatter distribution operator.

The attenuation depends only on the properties of the galaxy as a whole, so is applied equally to all components (including a central black hole), and to their combined emission.

Methods

attenuationMean → double precision

Return the mean attenuation, \(\bar{A}\) (in magnitudes, and not limited to be non-negative), at the reference wavelength for the given node.

• type(treeNode) node [inout]

Parameters

• [delta0] (real; 0..1; default 0.0d0) — The offset, \(\delta_0\), in magnitudes, of the attenuation from the relation of Garn and Best (2010).

• [deltaMass] (real; 0..1; default 0.0d0) — The change, \(\delta_\mathrm{M}\), in the slope of the attenuation with \(\log_{10}\) stellar mass, in magnitudes per dex.

• [deltaRedshift] (real; 0..1; default 0.0d0) — The slope, \(\delta_z\), of the attenuation with \(u = \ln[(1+z)/(1+z_\mathrm{p})]\), in magnitudes.

• [deltaMassRedshift] (real; 0..1; default 0.0d0) — The coefficient, \(\delta_{\mathrm{M}z}\), of the product \(X u\) of log stellar mass and redshift, in magnitudes.

• [redshiftPivot] (real; 0..1; ≥ 0.0d0; default 1.0d0) — The pivot redshift, \(z_\mathrm{p}\), of the redshift dependence.

• [massStellarMinimum] (real; 0..1; > 0.0d0; default 1.0d8) — The stellar mass (in \(\mathrm{M}_\odot\)) below which the attenuation is evaluated at this mass.

• [massStellarMaximum] (real; 0..1; > 0.0d0; default 1.0d11) — The stellar mass (in \(\mathrm{M}_\odot\)) above which the attenuation is evaluated at this mass.

• [wavelengthReference] (real; 0..1; > 0.0d0; default 6564.61d0) — The wavelength (in Å) at which the attenuation is specified. The default is that of H\(\alpha\) (in vacuum).

dustAttenuationZero

A dust attenuation class in which nothing is attenuated: the transmission is unity at all wavelengths, for all components, and at all ages. This is the default, and is useful as a control against which the effect of a dust model can be measured.

Because it depends on nothing, it requests no decomposition at all—not even by component—so that wrapping a luminosity in this attenuator costs a single parcel per output element.

(Default implementation)