How MSG Works

This chapter expands on the Python, Fortran and C walkthroughs, by describing in detail how MSG evaluates stellar spectra and photometric colors.

Evaluating a Spectrum

To evaluate a spectrum, MSG interpolates in a grid of pre-calculated spectroscopic data. Focusing on specific intensity evaluation, this involves constructing a (preferably continuous and smooth) function

\[I_{\lambda}(\mu; \lambda; x, y, z, \ldots)\]

representing the intensity (in units of \(\erg\,\cm^{-2}\,\second^{-1}\,\angstrom^{-1}\,\sterad^{-1}\)) emerging at direction cosine \(\mu\) and wavelength \(\lambda\) from an atmosphere characterized by a set of \(N\) parameters \(x, y, z, \ldots\) (which can correspond to quantities such as effective temperature \(T_{\rm eff}\), gravity \(g\), etc.).

Limb-Darkening Laws

The \(\mu\) dependence of the specific intensity is represented using limb-darkening laws. The simplest and most well known is the linear law

(1)\[\frac{I_{\lambda}(\mu; \ldots)}{I_{\lambda}(1; \ldots)} = 1 - a (\ldots) \left[1 - \mu\right]\]

where \(I_{\lambda}(1; \ldots)\) represents the normally emergent (\(\mu=1\)) intensity and \(a(\ldots)\) is the linear limb-darkening coefficient (here the ellipses \(\ldots\) represent the other parameters, which have been omitted for brevity). A better characterization involves introducing additional \(\mu\)-dependent terms on the right-hand side; for instance, the four-coefficient law devised by Claret (2000) is

(2)\[\frac{I_{\lambda}(\mu; \ldots)}{I_{\lambda}(1, \ldots)} = 1 - \sum_{k=1}^{4} a_{k}(\ldots) \left[1 - \mu^{k/2}\right],\]

where there are now four limb-darkening coefficients \(a_{k}(\ldots)\).

The advantage of using limb-darkening laws is the ease with which other useful quantities can be calculated. For instance, the emergent flux

(3)\[F_{\lambda}(\ldots) = \int_{0}^{1} I_{\lambda}(\mu; \ldots) \, \mu \, \diff\mu\]

can be evaluated analytically, as can any of the Eddington (1926) intensity moments (or E-moments, as MSG terms them):

\[\mathcal{E}^{i}_{\lambda}(\ldots) = \frac{1}{2} \int_{0}^{1} I_{\lambda}(\mu; \ldots) \, \mu^{i} \,\diff\mu.\]

MSG supports the following limb-darkening laws:

CONST: Constant law, where \(I_{\lambda}\) has no dependence on \(\mu\) whatsoever. This is discussed further below.
LINEAR: Linear law given in equation (1) above.
SQRT: Square-root law introduced by Diaz-Cordoves & Gimenez (1992).
QUAD: Quadratic law introduced by Wade & Rucinski (1985).
CLARET: Four-coefficient law introduced by Claret (2000) and given in equation (2) above.

The choice of law is made during grid construction (see the Grid Tools appendix for more details). The coefficients appearing in the limb-darkening laws (e.g., \(a\) and \(a_{k}\)) are typically determined from least-squares fits to tabulations of the specific intensity. In cases where these tabulations include flux but not specific intensity data, the CONST law is used; the angle-independent specific intensity is determined so that it produces the correct flux when evaluated using equation (3).

Interpolation in Wavelength

The \(\lambda\) dependence of the specific intensity is represented as a piecewise-constant function on a wavelength abscissa \(\lambda = \{\lambda_{1},\lambda_{2},\ldots,\lambda_{M}\}\):

\[I_{\lambda}(\lambda; \ldots) = I_{i}(\ldots) \qquad \lambda_{i} \leq \lambda < \lambda_{i+1}.\]

(as before, the ellipses represent the omitted parameters). Mapping intensity data onto a new abscissa \(\lambda' = \{\lambda'_{1},\lambda'_{2},\ldots\,\lambda'_{M'}\}\) is performed conservatively, according to the expression

\[I'_{i}(\ldots) = \frac{\int_{\lambda'_{i}}^{\lambda'_{i+1}} I_{\lambda}(\lambda; \ldots) \diff{\lambda}}{\lambda'_{i+1} - \lambda'_{i}}.\]

Beyond its simplicity, the advantage of this approach (as compared to higher-order interpolations) is that the equivalent width of line profiles is preserved.

Interpolation in Atmosphere Parameters

The dependence of the specific intensity on atmosphere parameters (\(x, y, z, \ldots\)) is represented using cubic tensor product interpolation. The appendices provide a (relatively) gentle introduction to tensor product interpolation. The short version is that intensity, flux, etc. are represented as piecewise-cubic functions in each atmosphere parameter, constructed to be continuous and smooth at the join between each piecewise region.

Grids often contain holes and/or ragged boundaries (the latter typically arising near the edge of the region of the \(T_{\rm eff}-g\) plane corresponding to super-Eddington luminosity). When an interpolation tries to access such missing data, MSG either switches to a lower-order scheme, or (if there simply aren’t sufficient data to interpolate) returns with an error (see the Exception Handling section below).

Disk Storage

MSG spectroscopic and photometric grid data are stored on disk in HDF5 files with a bespoke schema. Throughout this documentation, these files are known as specgrid and photgrid files, respectively.

Memory Management

It’s often the case that the data stored in specgrid and photgrid files greatly exceed the available computer memory (RAM). MSG handles such situations by loading data into memory only when they are required. These data are retained in memory until a user-defined capacity limit reached (see the SpecGrid.cache_limit and PhotGrid.cache_limit properties in the Python Interface, and corresponding functionality in the Fortran and C interfaces); then, data are evicted from the memory cache via a least recently used algorithm.

Evaluating Photometric Colors

To evaluate a photometric color, MSG convolves a stellar spectrum with appropriate passband response function \(S'(\lambda)\). This function represents the combined sensitivity of the optical pathway, filter and the detector. The mean flux in the passband is evaluated as

(4)\[\langle F \rangle = \frac{\int_{0}^{\infty} F_{\lambda}(\lambda) S'(\lambda) \diff{\lambda}}{\int_{0}^{\infty} S'(\lambda) \diff{\lambda}},\]

…meaning that \(S'(\lambda)\) is interpreted as an energy response function (see appendix A of Bessell & Murphy, 2012 for a discussion of the relationship between \(S'\) and the corresponding photon response function \(S\)). The apparent magnitude at the location where \(\langle F \rangle\) is measured follows as

\[m = -2.5 \log_{10} \left\langle \frac{F}{F_{0}} \right\rangle,\]

where the normalizing flux \(F_{0}\) is determined by the zero-point of the photometric system.

For a given response function, the convolution (4) can be performed before or after the interpolations discussed above:

the ‘before’ option performs the convolution as a pre-processing step using the specgrid_to_photgrid tool to create a photgrid file from a specgrid file (as discussed in the Creating Photometric Grids section). This is computationally more efficient, but requires a separate photgrid file to be created for each passband.
the ‘after’ option loads data from a specgrid file, but performs the convolution on-the-fly after each spectrum is interpolated. This is computationally less efficient, but incurs no storage requirements beyond the specgrid file.

Exception Handling

When a call to an MSG routine encounters a problem, the course of action depends on which langauge is being used:

In Python, an exception is thrown with a (reasonably) relevant subtype and error message.
In Fortran, if the optional integer argument stat is present during the call, then on return stat is set to an value indicating the nature of the problem (see the Parameters chapter for the list of possible values). If stat is not present, then execution halts with an error message printed to standard output.
In C, if the pointer argument stat is non-null during the call, then on return the target of stat is set to a value indicating the nature of the problem (see the Enums chapter for the list of possible values). If stat is null, then execution halts with an error message printed to standard output.