Model definition files
Spectroscopic data are modelled as a superposition of certain basis profile functions, which is convoluted with the instrumental line spread function, and multiplied with a smooth background continuum modelled by a linear combination of Legendre basis polynomials. The figure below illustrates how data (red dots) and models (blue curve) typically look like.
Especia offers three different parameterisations (termed flavours) to model an absorption line: the Voigt profile function, the Doppler profile function, and a Doppler profile function parameterised to infer a tenable variation of the fine-structure constant. All basis profile functions used in a model must be of the same flavour.
Voigt profile functions are required to model extragalactic and interstellar absorption lines (H I, He I, He II) that exhibit Lorentzian damping wings. The Voigt profile function is defined by seven parameters:
- laboratory wavelength (Å)
- oscillator strength
- cosmological redshift
- radial velocity (km s-1)
- line broadening velocity (km s-1)
- decadic logarithm of column number density of photon-absorbing particles (cm-2)
- damping constant (s-1)
The curve of growth above illustrates the dependence of the Voigt profile on the particle column number density. When no damping wings are present, i.e on the linear part of the curve of growth, the absorption is well described by a Doppler profile, which is much cheaper to calculate.
The Doppler profile function can be used to model extragalactic and interstellar metal absorption lines. Because Lorentzian broadening is negligible, the damping constant is not relevant. A Doppler profile function is defined by six parameters:
- laboratory wavelength (Å)
- oscillator strength
- cosmological redshift
- radial velocity (km s-1)
- line broadening velocity (km s-1)
- decadic logarithm of column number density of photon-absorbing particles (cm-2)
The Doppler profile function to infer a tenable variation of the fine-structure constant α in a many-multiplet analysis is defined by eight parameters. The seventh parameter is the sensitivity of the line position with respect to the variation Δα/α which constitutes the eighth parameter:
- laboratory wavelength (Å)
- oscillator strength
- cosmological redshift
- radial velocity (km s-1)
- line broadening velocity (km s-1)
- decadic logarithm of column number density of photon absorbing particles (cm-2)
- relativistic correction coefficient
- variation of the fine-structure constant Δα/α (1E-6)
Especia model definition files are text files using the US-ASCII character set. This example data file starts with a comment on what the data is and where it comes from. The comment mark is the percent % character. All characters from the comment mark % to the end of the line are ignored by Especia. Empty lines are ignored, too.
% Example model definition file
% Copyright (c) 2016 Ralf Quast
%
In fact, any text not typed in a { model definition block } is ignored. You may type anything you want outside a model definition block, except curly braces { and }.
A model definition block applies to certain spectroscopic data (termed section). A model definition file may contain several model definition blocks. Each model definition block begins with an opening curly brace { and ends with a closing curly brace }.
The first significant line in a block consists of five entries separated by space characters:
- section identifier (alphanumeric)
- path to the spectroscopic data file
- photon wavelength (Å) specifying the begin of the data section (0 = as in data file)
- photon wavelength (Å) specifying the end of the data section (0 = as in data file)
- number of Legendre basis polynomials to model the background continuum (0, 1, 2, ...)
{
% section 1
% id source begin end polynomials
C_I_1560 /data/virtual1561.dat 3355.00 3359.00 3
%
The second significant line in a block specifies the spectral resolution (R = λ/∆λ, to be specified in units of 1000.0) of the spectroscopic data. The spectral resolution is a model parameters and may be optimized. The line consists of five entries separated by space characters:
- value of the spectral resolution λ/∆λ (only used, if optimization is switched off)
- minimum value of the spectral resolution λ/∆λ (only used, if optimization is switched on)
- maximum value of the spectral resolution λ/∆λ (only used, if optimization is switched on)
- switch the optimization of this parameter on (1 = on, 0 = off)
- the identifier of a different model definition block (optional)
The reference to a different model definition block adopts the values from entries 1 - 4 defined in the referred block to the spectral resolution of the referring block. The values specified at entries 1 - 4 in the referring block are ignored.
% spectral resolution (1E+3)
% initial min max optimize reference
50 40 60 0
%
The subsequent lines specify the profile function parameters. Here Doppler profile functions are used. Each profile function is specified by an individual parameter block. Each parameter block starts with a single text line that specifies an alphanumeric identifier of the profile function.
In this example, the identifier denotes a certain fine-structure transition in the electronic state of neutral carbon (spectroscopic notation).
The remaining text lines in the profile function parameter block specify the profile function parameters. There is one line of text for each profile function parameter. In this example, there are six lines of text. Each line of text consists of five entries separated by space characters:
- parameter value (only used, if optimization is switched off)
- minimum parameter value (only used, if optimization is switched on)
- maximum parameter value (only used, if optimization is switched on)
- switch the optimization of this parameter on (1 = on, 0 = off)
- the identifier of a different profile function definition block (optional)
The reference to a different profile function parameter block adopts the values from entries 1 - 4 defined in the referred block to the corresponding parameter of the referring block. The values specified at entries 1 - 4 in the referring block are ignored. A profile function parameter block may refer to a profile function parameter block defined in a different model definition block (or section). A profile function parameter block may exhibit comments, starting with a %character.
% absorption lines
% id
% initial min max optimize reference comment
C_I_3P0-3D1_1 % C I
1560.3092 0 0 0 % 1. wavelength (A)
0.0719 0 0 0 % 2. oscillator strength
1.1508 1.150 1.152 1 % 3. cosmological redshift
0 -10.0 0.0 0 % 4. radial velocity (km s-1)
0 0.0 10.0 1 % 5. line broadening velocity (km s-1)
12.0 11.0 14.0 1 % 6. decadic logarithm of particle column density (cm-2)
Further profile function parameters blocks are specified in the same manner. Some make references to the first profile function parameter block. Profile function identifiers must be unique.
C_I_3P1-3D2_1 % C I*
1560.6822 0 0 0
0.0539 0 0 0
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
12.0 11.0 14.0 1
C_I_3P1-3D1_1 % C I*
1560.7090 0 0 0
0.0180 0 0 0
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P1-3D2_1
C_I_3P2-3D2_1 % C I**
1561.3402 0 0 0
0.0108 0 0 0
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
12.0 11.0 14.0 1
C_I_3P2-3D1_1 % C I**
1561.3667 0 0 0
0.000716 0 0 0
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P2-3D2_1
C_I_3P2-3D3_1 % C I**
1561.4384 0 0 0
0.0603 0 0 0
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P2-3D2_1
C_I_3P0-3D1_2 % C I
1560.3092 0 0 0
0.0719 0 0 0
1.1508 1.150 1.152 1
0 -10.0 10.0 0
0 0.0 10.0 1
12.0 11.0 14.0 1
C_I_3P1-3D2_2 % C I*
1560.6822 0 0 0
0.0539 0 0 0
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
12.0 11.0 14.0 1
C_I_3P1-3D1_2 % C I*
1560.7090 0 0 0
0.0180 0 0 0
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P1-3D2_2
C_I_3P2-3D2_2 % C I**
1561.3402 0 0 0
0.0108 0 0 0
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
12.0 11.0 14.0 1
C_I_3P2-3D1_2 % C I**
1561.3667 0 0 0
0.000716 0 0 0
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P2-3D2_2
C_I_3P2-3D3_2 % C I**
1561.4384 0 0 0
0.0603 0 0 0
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P2-3D2_2
}
The first model definition block is closed with a curly brace }. A second model definition block is opened {. The spectral resolution and profile function parameter blocks make references to corresponding parameters defined in the first model definition block. Model definition block identifiers must be unique.
{
% section 2
% id source begin end polynomials
C_I_1656 /data/virtual1657.dat 3562.00 3567.00 3
%
% spectral resolution (1E+3)
% initial min max optimize reference
0 0 0 0 C_I_1560
%
% absorption lines
% id
% initial min max optimize reference
C_I_3P1-3P2_1 % C I*
1656.2672 0 0 0
0.0589 0 0 0
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P1-3D2_1
C_I_3P0-3P1_1 % C I
1656.9283 0 0 0
0.139 0 0 0
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
C_I_3P2-3P2_1 % C I**
1657.0082 0 0 0
0.104 0 0 0
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P2-3D2_1
C_I_3P1-3P1_1 % C I*
1657.3792 0 0 0
0.0356 0 0 0
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P1-3D2_1
C_I_3P1-3P0_1 % C I*
1657.9068 0 0 0
0.0473 0 0 0
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P1-3D2_1
C_I_3P2-3P1_1 % C I**
1658.1212 0 0 0
0.0356 0 0 0
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P0-3D1_1
0 0 0 0 C_I_3P2-3D2_1
C_I_3P1-3P2_2 % C I*
1656.2672 0 0 0
0.0589 0 0 0
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P1-3D2_2
C_I_3P0-3P1_2 % C I
1656.9283 0 0 0
0.139 0 0 0
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
C_I_3P2-3P2_2 % C I**
1657.0082 0 0 0
0.104 0 0 0
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P2-3D2_2
C_I_3P1-3P1_2 % C I*
1657.3792 0 0 0
0.0356 0 0 0
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P1-3D2_2
C_I_3P1-3P0_2 % C I*
1657.9068 0 0 0
0.0473 0 0 0
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P1-3D2_2
C_I_3P2-3P1_2 % C I**
1658.1212 0 0 0
0.0356 0 0 0
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P0-3D1_2
0 0 0 0 C_I_3P2-3D2_2
The remaining parameter blocks specify three generic lines (unidentified lines) that are modelled by Doppler profile functions of the same width.
G1 % generic
3564.10 3563.90 3564.20 1
1.0 0 0 0
0.0 0 0 0
0.0 0 0 0
7.0 4.0 10.0 1
12.0 10.0 14.0 1
G2 % generic
3564.30 3564.20 3564.40 1
1.0 0 0 0
0.0 0 0 0
0.0 0 0 0
0 0 0 0 G1
12.0 10.0 14.0 1
G3 % generic
3564.55 3564.40 3564.70 1
1.0 0 0 0
0.0 0 0 0
0.0 0 0 0
0 0 0 0 G1
12.0 10.0 14.0 1
}
The model definition block is closed with a closing curly brace }. No further model definition blocks are specified. Here you may want to add any text like references or additional notes.
A model definition block may declare wavelength intervals to be excluded from the analysis. For instance, because of hits by cosmic rays in the respective regions of the CCD. To exclude such a wavelength interval type:
% section
% id source begin end polynomials exclude
Fe_II_2383 uves_5800.dat 5110.00 5140.00 3 5124.0 5126.0
You may exclude more than a single wavelength interval by appending more intervals to the first line of the model definition block:
% section
% id source begin end polynomials exclude
Fe_II_2383 uves_5800.dat 5110.00 5140.00 3 5124.0 5126.0 5131.0 5133.0 ...
Additional example model definition (.md) files are included with the documentation of Especia.
Please note that Especia does not check the correctness of a model definition file. Some mistakes, like self references and cyclic references are detected and reported. Most other mistakes, like specifying inconsistent minimum and maximum parameter bounds are not detected. It is your responsibility to specify a correct model definition file.