.. _myxclass-short:

myXCLASS
========

**creating single, synthetic spectra**

The **myXCLASS** function is the core of *XCLASS* and models a spectrum
by solving the radiative transfer equation for an isothermal object in
one dimension, called *detection equation* [Stahler_Palla_2005]_.
The **myXCLASS** function is designed to describe line-rich
sources which are often dense, where LTE is a reasonable approximation.
Details of the call of the myXCLASS function are described in
Sect. ":ref:`api-myxclass`".

Example call of the **myXCLASS** function:

::

    >>> from xclass import task_myXCLASS
    >>> import os

    # get path of current directory
    >>> LocalPath = os.getcwd() + "/"

    ## define path and name of molfit file
    >>> MolfitsFileName = LocalPath + "files/12C.molfit"

    ## define path and name of obs. xml file
    >>> ObsXMLFileName = LocalPath + "files/SMF_obs.xml"

    # call myXCLASS function
    >>> spectra, log, te, IntOpt, JobDir = task_myXCLASS.myXCLASSCore(MolfitsFileName = MolfitsFileName, \
                                                                      ObsXMLFileName = ObsXMLFileName)


What is myXCLASS?
-----------------

The **myXCLASS** function is able to model a spectrum with an arbitrary
number of molecules where the contribution of each molecule is described
by an arbitrary number of components. These could be identified with
clumps, hot dense cores etc. The **myXCLASS** function offers the
possibility to describe the position and shape of each component in a
simple 1-d, see Sect. ":ref:`myxclass-molfit-1d`", or in an advanced 3-d
description, see Sect. ":ref:`myxclass-molfit-stacking`" and Sect.
":ref:`myxclass-molfit-subbeam`". Additionally, **myXCLASS** is able to
take the local and non-local overlap between different lines into
account, see Sect. ":ref:`myxclass-localoverlap`".

In general, the **myXCLASS** function assumes, that all components are
aligned in a user-defined stack along the line-of-sight, where the
background and the observer are located at the ends, respectively. The
solution of the radiative transfer equation for components which are
located in a layer (``i=1``) closest to the background is [3]_,

.. math::
   :label: myXCLASS:modelFirstDist

   T_{\rm mb}(\nu) = \sum_{m,c \in i} &\Bigg[\eta \left(\theta^{m,c}\right) \left[S^{m,c}(\nu) \left(1 - e^{-\tau_{\rm total}^{m,c}(\nu)}\right) + I_{\rm bg} (\nu) \left(e^{-\tau_{\rm total}^{m,c}(\nu)} - 1\right) \right] \Bigg] \\
   &+ \left(I_{\rm bg}(\nu) - J_\mathrm{CMB} \right),

where the sums go over the indices :math:`m` for molecule, and :math:`c`
for component, respectively. In the following we will briefly describe
each term in Eq. :eq:`myXCLASS:modelFirstDist`.

The beam filling (dilution) factor :math:`\eta(\theta^{m,c})` of
molecule :math:`m` and component :math:`c` in Eq. :eq:`myXCLASS:modelFirstDist`
for a source with a Gaussian brightness profile, see below, and a Gaussian
beam is given by [4]_

.. math::
   :label: myXCLASS:BeamFillingFactor

   \eta(\theta^{m,c}) = \frac{(\theta^{m,c})^2}{\theta_t(\nu)^2 + (\theta^{m,c})^2},

where :math:`\theta^{m,c}` and :math:`\theta_t` represents the source
and telescope beam full width half maximum (FWHM) sizes, respectively.
The sources beam FWHM sizes :math:`\theta^{m,c}` (in arcsec) for the different
components are defined by the user in the molfit file, described in
Sect. ":ref:`myxclass-molfit`". Additionally, the **myXCLASS** program
assumes for single dish observations (indicated by
``Inter_Flag = False``), that the telescope beam FWHM size is related to
the diameter of the telescope by the diffraction limit

.. math::
   :label: myXCLASS:DiffractionLimit

   \theta_t(\nu) = \left(1.22 \cdot \frac{\lambda}{D}\right) \cdot \xi = \left(1.22 \cdot \frac{c_{\rm light}}{\nu \, D}\right) \cdot \xi,

where :math:`D` describes the diameter of the telescope,
:math:`c_{\rm light}` the speed of light, and
:math:`\xi = 3600 \cdot 180 /\pi` a conversion factor to get the
telescope beam FWHM size in arcsec. For interferometric observations
(indicated by ``Inter_Flag = True``, the user has to define the
interferometric beam FWHM size directly using parameter
``TelescopeSize``. In contrast to single dish observations the
**myXCLASS** program assumes a constant interferometric beam FWHM size
for the whole frequency range.

In general, the brightness temperature of radiation temperature
:math:`J(T, \nu)` is defined as

.. math::
   :label: myXCLASS:JT

   J(T, \nu) = \frac{h \, \nu}{k_B}\frac{1}{e^{h \, \nu / k \, T} - 1}.

The expression :math:`J_\mathrm{CMB}` describes the radiation
temperature Eq. :eq:`myXCLASS:JT` of the cosmic
background :math:`T_{\rm cbg}` = 2.7 K,
i.e. :math:`J_\mathrm{CMB} \equiv J(T_{\rm cbg}, \nu)`.

In Eq. :eq:`myXCLASS:modelFirstDist`, the
expression :math:`S^{m,c}(\nu)` represents the source function and is
according to Kirchhoff's law of thermal radiation given by

.. math::
   :label: myxclass-sourceFunction


   S^{m,c}(\nu) &= \frac{\epsilon_l^{m,c}(\nu) + \epsilon_{\rm dust}^{m,c}(\nu)}{\kappa_l^{m,c}(\nu) + \kappa_{\rm dust}^{m,c}(\nu) }  \\
               &= \frac{\kappa_l^{m,c}(\nu) \, J(T_\mathrm{ex}^{m,c}, \nu) + \kappa_{\rm dust}^{m,c}(\nu) \, J(T_{\rm dust}^{m,c}, \nu) }{\kappa_l^{m,c}(\nu) + \kappa_{\rm dust}^{m,c}(\nu)} \\
               &= \left(1 - \delta_{\gamma, 0}\right) \times \Bigg[ \frac{\tau_l^{m,c}(\nu) \, J(T_\mathrm{ex}^{m,c}, \nu) + \tau_{\rm dust}^{m,c}(\nu) \, J(T_{\rm dust}^{m,c}, \nu) }{\tau_l^{m,c}(\nu) + \tau_{\rm dust}^{m,c}(\nu) }\Bigg] + \delta_{\gamma, 0} \, J(T_\mathrm{ex}^{m,c}, \nu),

where :math:`\epsilon_{i}^{m,c}(\nu)` and
:math:`\kappa_{i}^{m,c}(\nu)` are the emission and absorption
coefficients for line and dust, respectively.
Additionally, the optical depth is given by
:math:`\tau^{m,c}_i(\nu) = \int \kappa^{m,c}_i(\nu) \, ds`, which
assumes that molecules and continuum contributions are well mixed. In
older versions, the background temperature could only be defined as
the measured continuum offset, which corresponds to the beam-averaged
continuum brightness temperature. At the same time, the dust, as agent
of line attenuation, was described by column density and opacity. This
is practical, because the observable :math:`T_{\rm bg}` is used, but
does not constitute a self-consistent and fully physical description.
Therefore, we now use optionally either a physical
(:math:`\gamma \equiv 1`, defined by the input parameter setting
``t_back_flag = False``) or phenomenological (:math:`\gamma \equiv 0`,
defined by the input parameter setting ``t_back_flag = True``)
description of the background indicated by the Kronecker delta
:math:`\delta_{\gamma, 0}`,
i.e. :math:`S^{m,c}(\nu) \equiv J(T_\mathrm{ex}^{m,c}, \nu)` for
:math:`\gamma \equiv 0`. Note, if :math:`\gamma \equiv 0`, the
definition of the dust temperature :math:`T_d^{m,c} (\nu)`,
Eq. :eq:`myXCLASS:EffDustTempTbgLocal`, is superfluous.

The total optical depth :math:`\tau_{\rm total}^{m,c}(\nu)` of each
molecule :math:`m` and component :math:`c` is defined as the sum of
the optical depths :math:`\tau_l^{m,c}(\nu)` of all lines of each
molecule :math:`m` and component :math:`c` plus the dust optical depth
:math:`\tau_{\rm dust}^{m,c}(\nu)` (see
Sect. ":ref:`mxclass-contDust`"), i.e.

.. math::
   :label: myXCLASS:taud

   \tau_{\rm total}^{m,c}(\nu) = \tau_l^{m,c}(\nu) + \tau_{\rm dust}^{m,c}(\nu).

The optical depth :math:`\tau_t^{m,c}(\nu)` for a transition :math:`t`
of molecule :math:`m` and component :math:`c` is described as [5]_

.. math::
   :label: myXCLASS:tau

   \tau_t^{m,c}(\nu) = \Bigg[\frac{c_{\rm light}^2}{8 \pi \nu^2} \, A_{ul}^t \, N_{\rm tot}^{m,c} \, \frac{g_u^t \, e^{-E_l^t/k_B \, T_{\rm ex}^{m,c}}}{Q \left(m, T_{\rm ex}^{m,c} \right)} \left(1 - e^{-h \, \nu^t /k_B \, T_{\rm ex}^{m,c}} \right) \cdot \phi^{m,c,t}(\nu)\Bigg],

where :math:`\phi^{m,c,t}(\nu)` indicates the Gaussian line profile function,
described in Sect. ":ref:`myxclass:Gauss`". The Einstein :math:`A_{ul}`
coefficient [6]_, the energy of the lower state :math:`E_l`, the upper
state degeneracy :math:`g_u`, and the partition function [7]_
:math:`Q \left(m, T_{\rm ex}^{m,c} \right)` of molecule :math:`m` are
taken from the embedded SQLite3 database. In addition, the values of the
excitation temperatures :math:`T_{\rm ex}^{m,c}` and the column
densities :math:`N_{\rm tot}^{m,c}` for the different components and
molecules are taken from the user defined molfit file.

If local-overlap of lines is not taken into account
(``LocalOverlapFlag = False``) the optical depth
:math:`\tau_l^{m,c}(\nu)` of all lines for each molecule :math:`m` and
component :math:`c` is described as

.. math:: \tau_l^{m,c}(\nu) = \sum_t \tau_t^{m,c}(\nu),

where the sum with index :math:`t` runs over all spectral line
transitions of molecule :math:`m` within the given frequency range. The
calculation procedure including local-overlap is described in
Sect. ":ref:`myxclass-localoverlap`".

The beam-averaged continuum background temperature
:math:`I_{\rm bg} (\nu)` is parameterized as

.. math::
   :label: myXCLASS:UserTbg

   I_{\rm bg} (\nu) = T_{\rm bg} \cdot \left(\frac{\nu}{\nu_{\rm min}} \right)^{T_{\rm slope}} + J_\mathrm{CMB} + I_{\rm bg}^{\rm file} (\nu)

to allow the user to define the continuum contribution for each
frequency range, individually. Here, :math:`\nu_{\rm min}` indicates the
lowest frequency of a given frequency range. :math:`T_{\rm bg}` and
:math:`T_{\rm slope}`, defined by the user, describe the background
continuum temperature and the temperature slope, respectively.
Additionally, *XCLASS* offers the possibility to describe the background
continuum, i.e. the continuum seen by the layer close to the cosmic
microwave background, by a so-called background file
:math:`I_{\rm bg}^{\rm file} (\nu)`.

Finally, the last term :math:`J_\mathrm{CMB}` in
Eq. :eq:`myXCLASS:modelFirstDist` describes the OFF position for
single dish observations (defined by ``Inter_Flag = False``) where
we have an intensity caused by the cosmic background
:math:`J_\mathrm{CMB}`. For interferometric observations, the
contribution of the cosmic background is filtered out and has to
be subtracted as well.

Hence, the layers, which do not belong to the largest distance
parameter, have to be considered in an iterative manner where the
solution of the radiative transfer equation for a certain distance
:math:`i>1` can be expressed as

.. math::
   :label: myXCLASS:modelForeground

   T_{\rm mb}^i(\nu) = \sum_{m,c \in i} \left(S^{m,c}(\nu) - T_{\rm mb}^{i-1}(\nu)\right) \, \left(1 - e^{-\tau_{\rm total}^{m,c}(\nu)}\right) + T_{\rm mb}^{i-1}(\nu) e^{-\tau_{\rm total}^{m,c}(\nu)},

where :math:`m` and :math:`c` indicates the index of the current
molecule and component, respectively. Here, the expression
:math:`T_{\rm mb}^{\rm i=1}(\nu)`, described by
Eq. :eq:`myXCLASS:modelFirstDist`,
represents the spectrum caused by layers which are closest to the
background, including the beam-averaged continuum background
temperature :math:`I_{\rm bg}^{\rm core} (\nu)`. The contribution by
other components (:math:`i > 1`) is considered by first calculating
:math:`T_{\rm mb}^{\rm i=1}(\nu)` and then use this as new continuum
for lines at distance :math:`i`.

By fitting all species and their components at once, line blending and
optical depth effects are taken into account. The modeling can be done
simultaneously with isotopologues (and higher vibrational states) of a
molecule assuming an isotopic ratio stored in the so-called iso ratio
file, see Sect. ":ref:`myxclass-iso`". Here, all parameters are expected
to be the same except the column density which is scaled by one over
the isotopic ratio for each isotopologue. Additionally, it is assumed
that radiation emitted by all isotopologues of a molecule in a
component interact with all other isotopologues, but the radiation
emitted in one component does not interact with other molecules or
with the same molecule in different components, i.e. their intensities
are added, except local-overlap is taken into account, see
Sect. ":ref:`myxclass-localoverlap`".

In order to correctly take instrumental resolution effects into
account in comparing the modeled spectrum with observations,
**myXCLASS** integrates the calculated spectrum over each channel.
Thereby, **myXCLASS** assumes that the given frequencies :math:`\nu`
describe the center of each channel, respectively. The resulting value
is than given as

.. math::
   :label: myXCLASS:Int

   T_{\rm mb}(\nu) = \frac{1}{\Delta_c} \int_{\nu-\frac{\Delta_c}{2}}^{\nu+\frac{\Delta_c}{2}} T_{\rm mb}(\tilde{\nu}) d\tilde{\nu},

where :math:`\Delta_c` represents the width of a channel. Due to the
complexity of Eqn. :eq:`myXCLASS:modelFirstDist`,
:eq:`myXCLASS:modelForeground` the integration in Eq. :eq:`myXCLASS:Int`
can not be done analytically. Therefore, **myXCLASS** performs a
piecewise integration of each component and channel using the
trapezoidal rule and summaries the resulting values to get the final
value used in Eq. :eq:`myXCLASS:Int`. In order to reduce the
computation effort **myXCLASS** determines the minimal line width of
all components of a certain distance. If a channel contains no
transition, **myXCLASS** determines the intensities at
:math:`\nu \pm \frac{\Delta_c}{2}` and evaluates
Eq. :eq:`myXCLASS:Int` by applying the trapezoidal
rule. But, if transitions are included, **myXCLASS** re-samples the
corresponding channel, whereby the number :math:`n_\nu` of additional
frequency points is given by

.. math:: n_\nu = (m \cdot 3) \cdot \min \left[1, {\rm int} \left[\frac{\Delta_c}{\sigma_{\rm min}} \right] \right],

where :math:`m` represents the number of transitions contained in the
current channel and
:math:`\sigma_{\rm min} = \frac{\Delta v_{\rm min}}{2 \, \sqrt{2 \, \ln \, 2} \, c_{\rm light}} \, \nu`.
If local-overlap is taken into account, see
Sect. ":ref:`myxclass-localoverlap`", :math:`\Delta v_{\rm min}`
indicates the minimal line width of all components of the current
layer, otherwise :math:`\Delta v_{\rm min}` describes the line width
of the current component. Here, the function int(:math:`x`) gives the
integer part of :math:`x`. Finally, **myXCLASS** computes the
intensities at these frequencies and evaluates
Eq. :eq:`myXCLASS:Int`.



.. _myxclass-molfit:

The molfit file
---------------

Within the *molfit file* the user defines both which molecules (or radio
recombination lines (RRLs)) are taken into account and how many components
are used. The definition of parameters for a molecule (or RRLs) starts
with a line describing the name of the molecule [8]_ (or RRLs), followed
by the number of components :math:`N`. The following :math:`N` lines
describe the parameters for each components, separately. The number of
columns and their meaning depends on the modeled contribution (molecule,
or RRL). Generally, all parameters have to be separated by blanks, comments
are marked with the % character.



.. _myxclass-molfit:molecules:

Molecules
^^^^^^^^^

For molecules, the user has to define for each component the excitation
temperature :math:`T_{\rm ex}` in K (``T_rot``), the column density
:math:`N_{\rm tot}` in cm\ :math:`^{-2}` (``N_tot``), and the velocity
offset (relative to v\ :math:`_{\rm LSR}`) in km s\ :math:`^{-1}`
(``V_off``). Depending of the used source description, see
Sect. ":ref:`myxclass-source`", the size of the source
:math:`\theta^{m,c}` in arcsec (``s_size``) and their offset relative to
the beam center is required as well. Furthermore, the Gaussian line
profile requires the velocity width (FWHM) :math:`\Delta \nu` in
km s\ :math:`^{-1}` (``V_width``). Additionally, the stacking of the
components along the line-of-sight requires the cf-flag (``CFFlag``),
see Sect. ":ref:`myxclass-molfit-1d`", or the distance parameter
(``distance``), see Sect. ":ref:`myxclass-molfit-stacking`". Finally,
the column (``keyword``) describes so-called keywords, that are used
for the sub-beam description, among other things. Note, different keywords
have to be separated by “\_” character.

Example of a molfit file describing two molecules CS\ :math:`_{v=0}` and
HCS\ :math:`^+_{v=0}` with two components, respectively:

::

       % Number of molecules = 2
       % s_size:  T_rot:    N_tot:  V_width:   V_off:  CFFlag:   keyword:
       CS;v=0;   3
          48.470  300.00  3.91E+17      2.86  -20.564        c
          21.804  320.00  6.96E+17      8.07   30.687        c
          81.700  208.00  1.46E+17      5.16  -10.124        c
       HCS+;v=0;   2
       % s_size:  T_rot:    N_tot:  V_width:   V_off:  CFFlag:   keyword:
                  150.00  1.10E+18      5.00   -0.154        f
                  200.00  2.20E+17      3.10   -2.154        f



.. _myxclass-molfit-sql:

Limiting the number of transitions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*XCLASS* offers the possibility to limit the number of transitions of
molecules which enter
Eq. :eq:`myXCLASS:modelFirstDist`. Therefore,
the user has to add the following command words to the beginning of the
molfit file:

-  ``"%%MinNumTransitionsSQL"``: defines the minimum number of
   transitions, i.e. *XCLASS* takes only those molecules into account
   which have at least this number of transition in the given frequency
   ranges.

-  ``"%%MaxNumTransitionsSQL"`` describes the max. number of transitions
   (in conjunction with ``"%%TransOrderSQL"``). Here, ``"0"`` means all
   transitions are included.

-  ``"%%TransOrderSQL"`` (in conjunction with
   ``"%%MaxNumTransitionsSQL"``) defines the order of transition.
   (E.g. ``"%%MaxNumTransitionsSQL = 10"`` and ``"%%TransOrderSQL = 1"``
   means, that only the first 10 transitions with the lowest lower
   energy are taken into account.)

-  ``"%%MaxElowSQL"`` defines the upper limit of the lower energy of a
   transition.

-  ``"%%MingASQL"`` describes the lower limit of gA (upper state
   degeneracy \* Einstein A coefficient) of a transition.

| Please note, for recombination lines only the command words
  ``"%%MinNumTransitionsSQL"`` and ``"%%MaxNumTransitionsSQL"`` are
  taken into account.
| Example for a molfit file containing limiting transition parameters:

::

   %==============================================================================
   %
   % define transition parameters:
   %
   %==============================================================================
   %%MinNumTransitionsSQL = 1      % min. number of transitions
   %%MaxNumTransitionsSQL = 0      % max. number of transitions,
                                   % =0): all transitions are taken into account
   %%TransOrderSQL = 1             % order of transitions:
                                   %  (=1): by lower energy,
                                   %  (=2): by gA,
                                   %  (=3): gA/E_low^2, else by trans. freq.
   %%MaxElowSQL = 1.0e+06          % max. lower energy, i.e. upper limit of
                                   %  the lower energy of a transition
   %%MingASQL = 0.0                % minimal intensity, i.e. lower limit of
                                   %  gA of a transition


   %==============================================================================
   %
   % define molecules and their components:
   %
   %==============================================================================
   % s_size:   T_rot:    N_tot:  V_width:   V_off:  CFFlag:   keyword:
   CS;v=0;   3
       48.470  300.00  3.91E+17      2.86  -20.564        c
       21.804  320.00  6.96E+17      8.07   30.687        c
       81.700  208.00  1.46E+17      5.16  -10.124        c
   HCS+;v=0;   2
   % s_size:   T_rot:    N_tot:  V_width:   V_off:  CFFlag:   keyword:
               150.00  1.10E+18      5.00   -0.154        f
               200.00  2.20E+17      3.10   -2.154        f



.. _myxclass-iso:

The iso ratio file
------------------

In order to reduce the number of model parameters, *XCLASS* offers the
possibility to use a so-called ``iso ratio file``. Here, *XCLASS* assumes,
that both molecules (isotopologue and iso master molecule) are described
by the same number of components, where the source size, the rotation
temperature, the line width, and the velocity offset are identical. The
corresponding column densities of the isotopologue
:math:`\left({\rm N}_{\rm tot}^{\rm (isotopologue)}\right)` are scaled
by the so-called iso ratio, i.e.

.. math:: {\rm N}_{\rm tot}^{\rm (isotopologue)} = {\rm N}_{\rm tot}^{\rm (iso \,\, master)} / {\rm (iso \, \, ratio)}.

The iso ratio file contains three columns separated by tabs or at
least two blank characters, where the first two columns indicates the
isotopologue and the corresponding iso master molecule, respectively.
The third column defines the ratio for both molecules. Comments are
marked with a ``%`` character, i.e. all characters on the right side of
a ``%`` are ignored.

Example for an iso ratio file:

::

       % isotopologue:         molecule:        ratio:
       HC-33-S+;v=0;           HCS+;v=0;          75.0
       HC-34-S+;v=0;           HCS+;v=0;          22.5
       CS;v=4;                 CS;v=0;             2.3
       CS;v=3;                 CS;v=0;             2.1
       CS;v=2;                 CS;v=0;             2.1
       CS;v=1;                 CS;v=0;             2.0
       CS-34;v=0;              CS;v=0;            22.5
       CS-34;v=1;              CS;v=0;            22.5
       CS-33;v=1;              CS;v=0;            75.0
       CS-33;v=0;              CS;v=0;            75.0

In the example described above we define in the first line an iso ratio
of ``75.0`` between ``HC-33-S+;v=0;`` and ``HCS+;v=0;``. Assuming that
``HCS+;v=0;`` is described with one component and with a column density
of :math:`9 \cdot 10^{16}` cm\ :math:`^{-2}` the column density of
``HC-33-S+;v=0;`` is

.. math:: {\rm N}_{\rm tot} = 9 \cdot 10^{16} \, {\rm cm}^{-2} / 75.0 = 1.2 \cdot 10^{15} \, {\rm cm}^{-2}.



.. _global-iso-ratios:

Globally defined iso-ratios
^^^^^^^^^^^^^^^^^^^^^^^^^^^

In addition, the user can defined so-called globally defined iso ratios,
e.g. (:math:`^{12}`\ C / :math:`^{13}`\ C). This defined ratio is
multiplied to all ratios of isotopologues in the iso ratio file which
contain e.g. :math:`^{13}`\ C raised to the power of occurrences of the
globally defined ion in each isotopologue. For example, the ratio
(:math:`^{12}`\ C / :math:`^{13}`\ C) is set globally to 45.
Additionally, we set the ratio of (CH\ :math:`_3`\ CN,v=0 /
:math:`^{13}`\ CH\ :math:`_3 ^{13}`\ CN,v=0) to 3.0. The final iso ratio
used by *XCLASS* for (CH\ :math:`_3`\ CN,v=0 /
:math:`^{13}`\ CH\ :math:`_3 ^{13}`\ CN,v=0) is then given by
:math:`3.0 \times 45^2 = 6075`. (Here, the exponent :math:`2` is caused
by the two :math:`^{13}`\ C ions). Additionally, globally defined
iso-ratios can be combined as well. In order to determine the used iso
ratio for e.g. (:math:`^{12}`\ C\ :math:`^{32}`\ S)/(:math:`^{13}`\ C
:math:`^{33}`\ S) we just have to multiply the globally defined is
ratios for (:math:`^{12}`\ C / :math:`^{13}`\ C) and (:math:`^{32}`\ S /
:math:`^{33}`\ S).

Globally defined ratios in the iso ratio file are indicated by the
phrase "``GLOBAL__``" and can not be used alone without other iso
ratios, e.g.

::

       % isotopologue:         molecule:           ratio:
       GLOBAL__C-13            C-12                45.0
       HO-18;v=0;              OH;v=0;             500
       HDO-18;v=0;             HDO;v=0;            500
       C-13-H3C-13-N;v=0;      CH3CN;v=0;          1.0



.. _myxclass-isoFit:

Fitting iso ratios in the iso ratio file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The **myXCLASSFit** function offers the possibility to optimize the
ratios between isotopologues as well. For that purpose, the user has to
add two additional columns on the right indicating the lower and the
upper limit of a certain ratio.

Example for an iso ratio file where the ratios are optimized by the
**myXCLASSFit** function:

::

       % isotopologue:         molecule:        ratio:     lower:     upper:
       CS;v=4;                 CS;v=0;             2.3        0.1      500.0
       CS;v=3;                 CS;v=0;             2.1        0.1      500.0
       CS;v=2;                 CS;v=0;             2.1        0.1      500.0
       CS;v=1;                 CS;v=0;             2.0        0.1      500.0
       CS-33;v=1;              CS;v=0;            75.0        0.1      500.0
       CS-33;v=0;              CS;v=0;            75.0        0.1      500.0
       HC-33-S+;v=0;           HCS+;v=0;          75.0        0.1      500.0
       HC-34-S+;v=0;           HCS+;v=0;          22.5        0.1      500.0

If the lower and upper limit are equal or if the lower limit is higher
than the upper limit, the ratio is kept constant and is not optimized by
the **myXCLASSFit** function. Note, if either the iso master molecule or
a corresponding isotopologue has no transition within at least one given
frequency range, the **myXCLASSFit** function does not optimize the
corresponding iso-ratio. For example, if the isotopologue
``HNC-13;v=0;`` (used in the example described above) has no transition
in at least one given frequency range, the given iso-ratio (here 60) is
kept constant. Additionally, if a iso master molecule has no transition
within at least one given frequency range, the iso-ratios to all of its
isotopologues are kept constant.



.. _myxclass-localoverlap:

Local-overlap of neighboring lines
----------------------------------

*XCLASS* offers the possibility to take the local overlap of neighboring
(molecules and recombination) lines into account. Here, we follow the
derivation described by [Cesaroni_Walmsley_1991]_ and define an average
source function :math:`S_l` at frequency :math:`\nu` and distance :math:`l`

.. math::
   :label: myxclass-sourceFkt:LocalOverlap

   S_l (\nu) = \frac{\varepsilon_l (\nu)}{\alpha_l (\nu)} = \frac{\sum_{c, t \in l} \tau_t^c (\nu) \, S_\nu (T_{{\rm rot}}^c)}{\sum_{c, t \in l} \tau_t^c (\nu)},

where :math:`\varepsilon_l` represents the emission and :math:`\alpha_l`
the absorption function, respectively. Additionally,
:math:`T_{\rm rot}^c` indicates the excitation temperature and
:math:`\tau_t^c` the optical depth of transition :math:`t` and component
:math:`c`. For each frequency channel, we take all components :math:`c`
and transitions :math:`t` into account, which belongs to the current
distance and whose Doppler-shifted transitions frequencies are located
within a range of 5\ :math:`\Delta v_{\rm max}`, where
:math:`\Delta v_{\rm max}` describes the largest line width of all
components of the current layer. The iterative treatment of components
at different distances, takes non-local effects into account as well. In
the optically thin limit,
Eq. :eq:`myxclass-sourceFkt:LocalOverlap`
is equal to the traditional approach of convolving a line with several
Gaussians. But it better describes situations in which both optically
thin and optically thick lines are present: photons emitted from the
optically thin transition are locally absorbed by the optically thick
emission. The intensities of the lines do not simply add up like in the
optically thin limit, but the intensity at the overlapping frequencies
is mainly described by the optically thick emission.

Please note, that the **myXCLASS** function can not compute the
intensity and corresponding optical depth for each component if the
local overlap is taken into account. Only the intensities and optical
depths at each distance can be determined.



.. _myxclass-source:

Source description
------------------

The position and size of each component in the molfit file can be
defined in two different ways: A simple 1-d description with a very
simplistic geometrical structure offers a fast but not very accurate and
flexible description with a minimum of parameters, wheres the advanced
3-d description is more accurate but requires more parameters and more
computational effort. The different source descriptions can be applied
to all kinds of components, i.e. to molecules and RRLs.


.. figure:: ../figures/Sketch__Emission.png
   :align: center
   :width: 40%
   :name: fig-myxclassEmissionSketch

   Sketch of a distribution of core layers within the Gaussian beam of
   the telescope (black ring). Here, we assume three different core
   components :math:`1`, :math:`2`, and :math:`3`, centered at the middle
   of the beam with different source sizes, excitation temperatures,
   velocity offsets (relative to v\ \ :math:`_{\rm LSR}`) etc. indicated
   by different colors. Additionally, we assume that all core components
   have the same distance to the telescope, i.e. all core layers are
   located within a plane perpendicular to the line of sight.
   Furthermore, we assume that this plane is located in front of a
   background layer :math:`4` with homogeneous intensity
   :math:`I_{\rm bg}^{\rm core}(\nu)` over the whole beam. Core
   components do not interact with each other radiatively.



.. _myxclass-molfit-1d:

Simple 1-d description
^^^^^^^^^^^^^^^^^^^^^^

For the 1-d description the molfit file has to contain column
(``CFFlag``) indicating the core and foreground flag and must not
contain column (``distance``) describing the stacking parameter, see
Sect. ":ref:`myxclass-molfit-stacking`". The 1-d assumption imposes a
very simplistic geometrical structure where we recognize two classes of
components:

One, the core objects (in earlier implementations called emission
component), consists of an ensemble of objects centered at the middle of
the beam. These could be identified with clumps, hot dense cores etc.
which overlaps but do not interact either because they do not overlap in
physical or in velocity space. For computational convenience, they are
assumed to be centered in the beam, as shown in
:numref:`fig-myxclassEmissionSketch`. It is also assumed that the
dust emission emanates (partly) from these components. Their intensities
are added, weighted with the beam filling factor, see
Eq. :eq:`myXCLASS:BeamFillingFactor`.
Note, all core components are contained in the layer which is closest to
the background.

The second class, foreground objects (in earlier implementations
called absorption components), are assumed to be in layers in front of
the core components. In the current 1-d implementation, they would
have a beam-averaged intensity of the core sources as background, and
would fill the whole beam. Examples for such structures would be
source envelopes in front of dense cores, or foreground components
along the line-of-sight.

As shown in :numref:`fig-myxclassEmissionSketch`, we assume that
core components do not interact with each other radiatively, i.e. one
core layer is not influenced by the others, if local-overlap is not
taken into account. But the core layers may overlap to offer the
possibility to model sources consisting of several molecules and
compounds. For core components,
Eq. :eq:`myXCLASS:modelFirstDist` has to be
slightly modified [9]_, so that the solution of the radiative transfer
equation for core layers is [10]_,

.. math::
   :label: myXCLASS:modelEm

   T_{\rm mb}^{\rm core}(\nu) = \sum_m \sum_c &\Bigg[\eta \left(\theta^{m,c}\right) \left[S^{m,c}(\nu) \left(1 - e^{-\tau_{\rm total}^{m,c}(\nu)}\right) + I_{\rm bg}^{\rm core} (\nu) \left(e^{-\tau_{\rm total}^{m,c}(\nu)} - 1\right) \right] \Bigg] \\
   &+ \left(I_{\rm bg}^{\rm core} (\nu) - J_\mathrm{CMB} \right),

where the sums go over the indices :math:`m` for molecule, and
:math:`c` for (core) component, respectively. The different terms
contained in Eq. :eq:`myXCLASS:modelEm` are
described in the previous sections.


.. figure:: ../figures/Sketch__Absorption.png
   :align: center
   :width: 50%
   :name: fig-myxclassAbsorptionSketch

   Sketch of a distribution of core and foreground layers within the
   Gaussian shaped beam of the telescope (black ring). Here, we assume
   three different core components :math:`2a`, :math:`2b`, and :math:`2c`
   located in a plane perpendicular to the line of sight which lies in
   front of the background layer :math:`1` with intensity
   :math:`I_{\rm bg}^{\rm core}(\nu)`, see
   Eq. :eq:`myXCLASS:UserTbg`. The foreground
   layers :math:`3` and :math:`4` are located between the core layers and
   the telescope along the line of sight (black dashed line). Here, each
   component is described by different excitation temperatures, velocity
   offsets etc. indicated by different colors. The thickness of each
   layer is described indirectly by the total column density
   :math:`N_{\rm tot}^{m,c}`, see Sect. ":ref:`deriv-OpticalDepth`". For
   each foreground layer we assume a beam filling factor of 1, i.e. each
   foreground layer covers the whole beam.|

In contrast to core layers, foreground components may interact with each
other, as shown in :numref:`fig-myxclassAbsorptionSketch`, where
absorption takes places only, if the excitation temperature for the
absorbing layer is lower than the temperature of the background.

Hence, the solution of the radiative transfer equation for foreground
layers can not be given in a form similar to
Eq. :eq:`myXCLASS:modelEm`. Foreground components
have to be considered in an iterative manner similar to
Eq. :eq:`myXCLASS:modelForeground`. The
solution of the radiative transfer equation for foreground layers can be
expressed as

.. math::
   :label: myXCLASS:modelAbs

   T_{\rm mb}^{\rm fore}(\nu)_{m,c=1} &= \eta \left(\theta^{m,c=1} \right) \left(S^{m,c=1}(\nu) - T_{\rm mb}^{\rm core}(\nu)\right) \, \left(1 - e^{-\tau_{\rm total}^{m,c=1}(\nu)}\right) + T_{\rm mb}^{\rm core}(\nu) \\
   T_{\rm mb}^{\rm fore}(\nu)_{m,c=i} &= \eta \left(\theta^{m,c=i} \right) \left(S^{m,c=i}(\nu) - T_{\rm mb}^{\rm fore}(\nu)_{m,c=(i-1)}\right) \, \left(1 - e^{-\tau_{\rm total}^{m,c=i}(\nu)}\right) + T_{\rm mb}^{\rm fore}(\nu)_{m,c=(i-1)},

where :math:`m` indicates the index of the current molecule and
:math:`i` represents an index running over all foreground components
:math:`c` of all molecules. Additionally, we assume that each foreground
component covers the whole beam,
i.e. :math:`\eta \left(\theta^{m,c=i} \right) \equiv 1` for all
foreground layer [11]_. Thus,
Eq. :eq:`myXCLASS:modelAbs` simplifies to

.. math::
   :label: myXCLASS:modelAbsFinal

   T_{\rm mb}^{\rm fore}(\nu)_{m,c=1} &= \Big[ S^{m,c=1}(\nu) \left(1 - e^{-\tau_{\rm total}^{m,c=1}(\nu)}\right) + T_{\rm mb}^{\rm core}(\nu)  e^{-\tau_{\rm total}^{m,c=1}(\nu)}\Big] \\
   T_{\rm mb}^{\rm fore}(\nu)_{m,c=i} &= \Big[S^{m,c=i}(\nu) \left(1 - e^{-\tau_{\rm total}^{m,c=i}(\nu)}\right) + T_{\rm mb}^{\rm fore}(\nu)_{m,c=(i-1)} e^{-\tau_{\rm total}^{m,c=i}(\nu)}\Big],

where :math:`T_{\rm mb}^{\rm core}(\nu)` describes the core spectrum,
see Eq. :eq:`myXCLASS:modelEm`, including the
beam-averaged continuum background temperature
:math:`I_{\rm bg}^{\rm core} (\nu)`. For foreground lines the
contribution by other components is considered by first calculating the
contribution of core objects and then use this as new continuum for
foreground lines reflecting the fact that cold foreground layers are
often found in front of hotter emission sources. The **myXCLASS**
function assumes, that the cosmic background describes together with the
core components one end of a stack of layers. Additionally, the
foreground components are located between this plane and the telescope,
see :numref:`fig-myxclassAbsorptionSketch`. The total column density
:math:`N_{\rm tot}^{m,c}` depends on the abundance of a certain molecule
and on the thickness of a layer containing the molecule. The order of
components along the line of sight is defined by the occurrence of a
certain foreground component in the molfit file.



.. _myxclass-molfit-stacking:

Stacking
^^^^^^^^

.. figure:: ../figures/Stacking.png
   :align: center
   :width: 50%
   :name: fig-stacking

   Sketch of components located at different distances along the line of sight.

In addition to the simple 1-d description described in the previous
section, *XCLASS* offers the possibility to define the order of each
component along the line-of-sight by a so-called *stacking* or
*distance* parameter which replaces column ``CFFlag`` in the molfit
file, i.e. the column ``CFFlag`` is replaced by column ``distance``
right after column ``V_off``. The stacking parameter can be interpreted
as distance of a component to the observer where the component(s) with
the largest distance parameter is (are) closest to the background while
those components with the smallest distance parameter are closest to the
observer. Additionally, the components which have the same distance
parameter (i.e. within a difference of :math:`< 10^{-9}`) are located in
the same plane perpendicular to line-of-sight. In contrast to foreground
components, described in the previous section, which can describe only
one molecule at a certain distance, the stacking formalism offers the
possibility to describe an arbitrary number of clouds consisting of an
arbitrary number of molecules or recombination lines along the line-of-sight.

| Note, the distance parameter has no unit, can not be optimized by
  MAGIX, and must not be used in conjunction with the old cf-flag
  formalism, described in the previous section.
| In the following example SO\ :math:`_2` is described by four and
  CH\ :math:`_3`\ CN with two components where the first components of
  SO\ :math:`_2` and CH\ :math:`_3`\ CN are located close to the
  background, i.e. both components are located in the same plane
  perpendicular to the line of sight and are illuminated by the
  background continuum Eq. :eq:`myXCLASS:UserTbg`.
  The second and third component of SO\ :math:`_2` are located in
  another plane perpendicular to the line of sight, which is closer to
  the observer. Both components “see” a background which is caused by
  the background plus the first components of SO\ :math:`_2` and
  CH\ :math:`_3`\ CN. The fourth component of SO\ :math:`_2` and the
  second component of CH\ :math:`_3`\ CN are located in front of the
  plane at 500, where the second component of SO\ :math:`_2` is closer
  to the observer.

::

       SO2;v=0;   4

       % s_size:  T_rot:   N_tot:   V_width:   V_off: distance:  keyword:
       %[arcsec]     [K]   [cm-2]     [km/s]   [km/s]        []

          500.00   50.00  1.9E+14       2.86     1.22     600.0
          500.00  190.00  3.9E+15       4.16    -1.61     500.0
          500.00  250.00  3.9E+16       8.55    -5.75     500.0
          500.00   80.00  3.9E+14       1.23    -1.82     300.0

       CH3CN;v=0;   2

       % s_size:  T_rot:   N_tot:   V_width:   V_off: distance:  keyword:
       %[arcsec]     [K]   [cm-2]     [km/s]   [km/s]        []

          500.00   50.00  2.2E+15       2.86     6.01     600.0
          500.00   80.00  8.5E+14       1.23    -2.82     200.0



.. _myxclass-molfit-subbeam:

Sub-beam description
^^^^^^^^^^^^^^^^^^^^

.. figure:: ../figures/sub-beam_description.png
   :align: center
   :width: 80%
   :name: fig-subbeam

   Sketch of a sub-beam description for a single frequency channel.
   Here, the gray grid indicates the model grid, the black ellipse the
   beam, and the red dot the center of the beam, respectively.
   Additionally, the filled circles indicate different components, where
   the gray scale represent the location of a component along the
   line-of-sight, i.e. light gray describe components close the cosmic
   microwave background, while dark gray represents components close the
   observer. The projected width :math:`w` and height :math:`h` of the
   beam are described by Eq. :eq:`myXCLASS:BeamWidthHeight`.

Besides to the aforementioned component stacking *XCLASS* offers the
possibility to take the shape and the position of each component
perpendicular to the line-of-sight into account as well, see
:numref:`fig-stacking`. The so-called *sub-beam description*, see
:numref:`fig-subbeam`, is used whenever an offset position of a
component is defined, or if a component at a smaller distance is smaller
than a component at larger distance, or if local-overlap is taken into
account. Each component can have a different size and center position.
In the current version only circle and square-shaped components can be
described. Additionally, elliptical rotated beam sizes, see
Sect. ":ref:`deriv-erGauss`", can be defined as well,
but the frequency dependence of single dish beam sizes is ignored,
i.e. the beam size is assumed to be constant for the whole frequency
range [12]_. For the sub-beam description, *XCLASS* samples the elliptical
rotated beam by an rectangular linear grid, called *model grid*, where
the number of pixels along the x- and y-direction is defined by the
user. The size of each model pixel is defined by the beam, where we
assume that the grid along the x- and y-axis is three times the width
:math:`w` and height :math:`h` of the beam, respectively, described by

.. math::
   :label: myXCLASS:BeamWidthHeight

   w &= \sqrt{\left({\tt BMIN} \cdot \cos {\tt BPA} \right)^2 + \left({\tt BMAJ} \cdot \sin {\tt BPA} \right)^2},\\
   h &= \sqrt{\left({\tt BMIN} \cdot \sin {\tt BPA} \right)^2 + \left({\tt BMAJ} \cdot \cos {\tt BPA} \right)^2}.

Here, :math:`{\tt BMIN}` and :math:`{\tt BMAJ}` represents the minor and
major axis and :math:`{\tt BPA}` the position angle of the beam.
Furthermore, *XCLASS* identifies for each component the model pixels,
which are covered by the corresponding component. While the
identification of all pixels covered by a component is trivial for
square components, the Bresenham's circle algorithm
[Bresenham_1977]_ is used for circular components. After this,
*XCLASS* computes the spectra for each model pixel based on the
corresponding component configuration. Afterwards, *XCLASS* convolves the
calculated intensity map for each frequency channel with the elliptical
rotated Gaussian beam using the FFTW library [13]_
[Padua_2011]_. Finally, *XCLASS* uses the spectrum at the beam
center for the final output. The intensities and optical depths for each
component / distance are computed in the same way.

For beam-centered components only the diameter of the component (in
arcsec) is required which has to be defined in the first column
``s_size`` of the molfit file, e.g.

::

       SO2;v=0;   4

       % s_size:  T_rot:   N_tot:   V_width:   V_off: distance:  keyword:
       %[arcsec]     [K]   [cm-2]     [km/s]   [km/s]        []

           50.00   50.00  1.9E+14       2.86     1.22     600.0
          110.00  190.00  3.9E+15       4.16    -1.61     500.0

| Components whose center are not identical to the center of the beam
  require three additional parameters: The column ``s_off_x`` and
  ``s_off_y`` describe the x- and y-coordination of the component center
  position relative to the beam center (in arcsec), respectively.
  Additionally, column (``keyword``) has to contain the keyword
  ``circleoff``.
| In the following example, we describe SO\ :math:`_2` with two
  components, where the first component has a size (diameter) of
  50 arcsec, and a relative offset of 1.0 and 1.45 arcsec, respectively.
  The second component has a larger diameter of 200 arcsec and is
  centered at the middle of the beam.

::

   SO2;v=0;   2

   % s_size: s_off_x: s_off_y: T_rot: N_tot: V_width:   V_off: distance: keyword:
   %[arcsec] [arcsec] [arcsec]    [K] [cm-2]   [km/s]   [km/s]        []

       50.00      1.0    1.45   50.00  1.e14     2.86     1.22     600.0 circleoff
      200.00                    90.00  3.e15     4.16    -1.61     500.0

Additionally, the user can use keywords ``box`` and ``boxoff`` to define
quadratic components. For keyword ``box``, *XCLASS* assumes that the
corresponding component is located at the center of the beam, where
column ``s_size`` indicates the length (in arcsec) of the square.
Similar to keyword ``circleoff`` the keyword ``boxoff`` defines a square
which center (in arcsec) is defined by columns ``s_off_x`` and
``s_off_y``, respectively.



.. _myxclass:rrls:

Radio recombination lines (RRLs)
--------------------------------

In addition to molecules **myXCLASS** can deal with radio recombination
lines (RRLs) as well.



.. _myxclass:rrls:lte:

RRLs in LTE
^^^^^^^^^^^

The optical depths of RRLs (in LTE) is given by

.. math::
   :label: myxclass:RRLopticalDepthLine

   \tau_{{\rm RRL}, \nu} &= \int \kappa_{n_1, n_2, \nu}^{\rm ext} \, ds  \\
   &= \frac{\pi \, h^3 \, e^2}{(2 \pi \, m_e \, k_B)^{3/2} \, m_e \, c} \cdot {\rm EM} \cdot \frac{n_1^2 \, f_{n_1, n_2}}{T_e^{3/2}} \, \exp \left[\frac{Z^2 \, E_{n_1}}{k_B T_e} \right] \, \left(1 - e^{-h \nu_{n_1, n_2} / k_B T_e} \right) \, \phi_\nu,

where the LTE source function :math:`S_{{\rm RRL}, \nu}^{\rm LTE}` can
be written in terms of the brightness temperature
Eq. :eq:`myXCLASS:JT` as

.. math::
   :label: myxclass:RRLSLTE

   S_{{\rm RRL}, \nu}^{\rm LTE} = \frac{\tau_{{\rm RRL}, \nu} \cdot J(T_e)}{\tau_{{\rm RRL}, \nu}}.

The terms :math:`n_1`, :math:`f_{n_1, n_2}`, :math:`E_{n_1}`, and
:math:`\nu_{n_1, n_2}` are taken from the embedded database whereas the
emission measure EM (in cm\ :math:`^{-6}` pc), electronic temperature
:math:`T_e` (in K), source size :math:`\theta^{m,c}` (in arcsec) (or
other parameters related to source description), line width :math:`\Delta v`
(in km/s), and velocity offset :math:`v` (in km/s) used for the line
profile function :math:`\phi_\nu` are taken from the user-defined
molfit file.

The parameters which are used for the description of radio recombination
lines (RRLs) are quite similar to the parameters used for molecules.
Here, the kinetic temperature is interpreted as electronic temperature
(in K) and the column density as emission measure EM (in
pc cm\ :math:`^{-6}`). RRLs of hydrogen are marked as ``RRL-H``, of
Helium as ``RRL-He``, of Carbon as ``RRL-C``, of Nitrogen as ``RRL-N``,
and of Oxygen as ``RRL-O``. In the following example we describe RRLs of
hydrogen at two distances with a Gaussian line shape:

::

       RRL-H    2
       % s_size:     T_e:   EM_RRL:  V_width:   V_off:  distance:
       500.00000    6.9e4   5.5E+16       1.3      2.0      2.e15
       500.00000    2.3e4   2.3E+12       2.5      2.0      1.e15



.. _myxclass:Gauss:

Gaussian line profile
^^^^^^^^^^^^^^^^^^^^^

In order to take broadening caused by the thermal motion of the gas
particles and micro-turbulence into account a normalized Gaussian line
profile,
i.e. :math:`\int_0^{\infty} \phi^{m,c,t}_{\rm Gauss}(\nu) \, d\nu` = 1,
for a spectral line :math:`t` can be assumed:

.. math:: \phi^{m,c,t}_{\rm Gauss}(\nu) = \frac{1}{\sqrt{2 \pi} \, \sigma^{m,c,t}} \cdot e^{-\frac{\left(\nu - \nu_0^{m,c,t} \right)^2} {2 (\sigma^{m,c,t})^2}},

where :math:`\nu_0^{m,c,t}` indicates the Doppler-shifted transition
frequency and
:math:`\sigma^{m,c,t}` the standard deviation which is related to the
full width at half maximum :math:`f_G` by

.. math::
   :label: myXCLASS:FWHMGauss

   f_G = \left(2 \, \sqrt{2 \, \ln 2}\right) \cdot \sigma^{m,c,t} = \frac{\Delta {\rm v}_{\rm width-Gauss}^{m,c}}{c_{\rm light}} \cdot \left(\nu^t + \delta \nu_{\rm LSR}^{m,c,t} \right).

Similar to the Lorentzian line profile
:math:`\Delta {\rm v}_{\rm width-Gauss}^{m,c}` and
:math:`\delta {\rm v}_{\rm offset}^{m,c}` indicates the line width and
offset of molecule :math:`m` and component :math:`c`, respectively and
:math:`{\rm v}_{\rm LSR}` the source velocity.

The **myXCLASS** function assumes a Gaussian line shape for all
components by default.



.. _myxclass:cont:

Continuum
---------



.. _mxclass-contDust:

Dust contribution
^^^^^^^^^^^^^^^^^

The dust optical depth :math:`\tau_d^{m,c}(\nu)` takes the dust
attenuation into account and is given by

.. math::
   :label: myXCLASS:dustOpacity

   \tau_d^{m,c}(\nu) &= \tau_{d, {\rm ref}}^{m,c} \cdot \left(\frac{\nu}{\nu_{\rm ref}} \right)^{\beta^{m,c}} + \tau_d^{\rm file}(\nu) \\
                     &= \left(N_H^{m,c} \cdot \kappa^{m,c}_{\nu_{\rm ref}} \cdot m_{H_2} \cdot \frac{1}{\zeta_{\rm gas-dust}}\right) \cdot \left(\frac{\nu}{\nu_{\rm ref}} \right)^{\beta^{m,c}}  + \tau_d^{\rm file}(\nu).

Here, :math:`N_H^{m,c}` describes the hydrogen column density (in
cm\ :math:`^{-2}`), :math:`\kappa^{m,c}_{\nu_{\rm ref}}` the dust mass
opacity for a certain type of dust (in cm\ :math:`^{2}`
g\ :math:`^{-1}`) [Ossenkopf_Henning_1994]_, and :math:`\beta^{m,c}` the
spectral index. Additionally, :math:`\nu_{\rm ref}` = 230 GHz indicates
the reference frequency for :math:`\kappa^{m,c}_{\nu_{\rm ref}}`,
:math:`m_{H_2}` the mass of a hydrogen molecule, and
:math:`1 / \zeta_{\rm gas-dust}` the dust to gas ratio which is set here
to (1/100) [Hildebrand_1983]_. The equation is valid for dust and
gas well mixed. Furthermore, the expression
:math:`\tau_d^{\rm file}(\nu)` represents the dust optical depth
described in an ASCII file, which path and name is defined by the input
parameter ``DustFileName``.

| In Eqn. :eq:`myXCLASS:modelFirstDist` and
  :eq:`myXCLASS:modelForeground`, the dust
  continuum contribution is described through the source function
  :math:`S^{m,c}(\nu)`,
  Eq. :eq:`myxclass-sourceFunction`, by an
  effective dust temperature :math:`T_d^{m,c}` (in K) (through
  :math:`J(T_d^{m,c}, \nu)`).
| The **myXCLASS** function offers three different ways to define the
  dust parameters :math:`N_H^{m,c}`,
  :math:`\kappa^{m,c}_{\nu_{\rm ref}}`, :math:`\beta^{m,c}`, and
  :math:`T_d^{m,c}`:

On the one hand the dust parameters :math:`N_H^{m,c}`,
:math:`\kappa^{m,c}_{\nu_{\rm ref}}`, and :math:`\beta^{m,c}` can be
defined globally for all components in the molfit file by the input
parameters ``N_H``, ``kappa_1300``, and ``beta_dust`` of the
**myXCLASS** function, while the dust temperature is set to the
excitation temperature of the corresponding component. For the
**myXCLASSFit**, **myXCLASSMapFit**, **myXCLASSMapRedoFit**,
and **LineID** function the dust parameters can be defined globally in
an obs. xml file as well, see Sect. ":ref:`myxclassfit-obs-xml-file`".

Additionally, the dust parameters can be described in the molfit file
for different distances, while the dust continuum has to be marked as
``cont-dust``. Each component is described by the size of the dust
component ``s_size`` (in arcsec), the dust temperature ``T_cont_dust``
(in K), the hydrogen column density ``nHcolumn_cont_dust`` (in
cm\ :math:`^{-2}`), the dust mass opacity ``kappa_cont_dust`` (in g
cm\ :math:`^{-2}`), the spectral index ``beta_cont_dust``, and the
distance parameter ``distance``. In the example described below, we
define four different dust components with different dust temperatures
at different distances

::

   cont-dust    4
   % s_size: T_cont_dust: nHcolumn_cont_dust: kappa_cont_dust: beta_cont_dust: distance:
   500.00000       50.000             3.9E+16             0.42             2.0    4.e15
   500.00000       10.000             1.2E+20             0.42             2.0    3.e15
   500.00000       32.000             5.3E+12             0.42             2.0    2.e15
   500.00000        5.000             7.1E+18             0.42             2.0    1.e15

In order to be backward compatible with older *XCLASS* releases, the user
can define the dust parameters for each component of a molecule as well.
Here, the dust temperature :math:`T_d^{m,c}` is parameterized as offset
to the corresponding excitation temperature :math:`T_{\rm ex}^{m,c}` as

.. math::
   :label: myXCLASS:EffDustTempTbgLocal

   T_d^{m,c} (\nu) &= T_{\rm ex}^{m,c} + \Delta T_d^{m,c}(\nu) \\
                   &= T_{\rm ex}^{m,c} + T_{d, {\rm off}}^{m,c} \cdot \left(\frac{\nu}{\nu_{\rm min}} \right)^{T_{d, {\rm slope}}^{m,c}},

where :math:`T_{d, {\rm off}}^{m,c}` and
:math:`T_{d, {\rm slope}}^{m,c}` can be defined by the user for each
component in the molfit. If :math:`T_{d, {\rm off}}^{m,c}` and
:math:`T_{d, {\rm slope}}^{m,c}` are not defined for a certain
component, we assume
:math:`T_d^{m,c} (\nu) \equiv T_{\rm ex}^{m,c} (\nu)` for all
components. For a physical (:math:`\gamma \equiv 1`) description of the
background intensity, see
Eq. :eq:`myxclass-sourceFunction`, the user
can define the dust opacity,
Eq. :eq:`myXCLASS:dustOpacity`, and dust
temperature,
Eq. :eq:`myXCLASS:EffDustTempTbgLocal`,
for each component. In order to define a dust temperature for each
component which is not identical to the excitation temperature
:math:`T_{\rm ex}` of the corresponding component, the molfit file has
to contain two additional columns between columns ``V_off`` and
``CFFlag`` (or column ``distance``), describing the parameters
:math:`T_{\rm d, off}^{m,c}` (``T_doff``) and
:math:`T_{\rm d, slope}^{m,c}` (``T_dSlope``), respectively, and keyword
``t-dust-inline`` in column (``keyword``), e.g.

::

   CS;v=0;    3
   % s_size: T_rot: N_tot: V_width: V_off: T_doff: T_dSlope: CFFlag: keyword:
   %[arcsec]    [K] [cm-2]   [km/s] [km/s]     [K]        []   [c/f]
       48.47  50.00   3e16     2.86  -2.56     3.0       0.0       c t-dust-inline
       40.10  56.53   2e18     4.21  -7.31     3.0       0.0       c t-dust-inline
       29.09  68.44   2e17     4.02   0.21     2.5       1.0       c t-dust-inline

Additionally, the **myXCLASS** program offers the possibility to define
:math:`N_H`, :math:`\kappa_{\nu_{\rm ref}}` and :math:`\beta` for each
component of a molecule as well. In order to define these parameters
individually for each component, the molfit file has to contain three
additional columns on the left side of column ``CFFlag`` (or column
``distance``), indicating parameters :math:`N_H^{m,c}` (``nHcolumn``),
:math:`\kappa^{m,c}_{\nu_{\rm ref}}` (``kappa``), and
:math:`\beta^{m,c}` (``beta``), and keyword ``nh-dust-inline`` in column
(``keyword``), e.g.

::

   CS;v=0;    3
   % s_size: T_rot: N_tot: V_width: V_off: nHcolumn:  kappa: beta: CFFlag: keyword:
   %[arcsec]    [K] [cm-2]   [km/s] [km/s]    [cm-2] [cm2/g]    []   [c/f]
       48.47  50.00   3e16     2.86  -2.56      3e24    0.42   2.0       c nh-dust-inline
       56.53  20.00   2e18     4.21  -7.31      2e24    0.42   2.1       c nh-dust-inline
       68.44  90.00   2e17     4.02   0.21      3e21    0.42   1.9       c nh-dust-inline

| In order to define :math:`T_{d, {\rm off}}^{m,c}`,
  :math:`T_{d, {\rm slope}}^{m,c}`, :math:`N_H`,
  :math:`\kappa_{\nu_{\rm ref}}`, and :math:`\beta` for each component
  the columns defining the dust
  temperature\ :math:`T_{d, {\rm off}}^{m,c}` (``T_doff``),
  :math:`T_{d, {\rm slope}}^{m,c}` (``T_dslope``) have to be given
  before the hydrogen column density, kappa and beta, i.e. in the order
  of ``s_size``, ``T_rot``, ``N_tot``, ``V_width``, ``V_off``,
  ``T_doff``, ``T_dslope``, ``nHcolumn``, ``kappa``, ``beta``, and
  ``CFFlag``. Additionally, the column (``keyword``) has to contain the
  keyword ``t-dust-inline_nh-dust-inline``.



.. _mxclass-contPhen:

Phenomenological continuum description
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In addition to the the dust continuum contribution described
above, *XCLASS* offers the possibility to describe the continuum of a
given distance by phenomenological functions. Currently, the following
functions are included:

-  Standing wave (``ContPhenFuncID = 1``):

   .. math:: c(\nu) = A_1 \, \sin \left( (\nu \cdot x) + \phi_1 \right) + A_2 \, \cos \left( (\nu \cdot x) + \phi_2 \right),

   where :math:`A_{1, 2}` and :math:`x` describe scale parameters
   whereas :math:`\phi_{1,2}` indicate phase shifts. Here, :math:`A_1`
   and :math:`A_2` are defined by parameters ``ContPhenFuncParam1`` and
   ``ContPhenFuncParam2``, respectively. Parameter
   ``ContPhenFuncParam3`` indicates the scale parameter :math:`x` and
   the phase shifts :math:`\phi_{1,2}` are described by parameters
   ``ContPhenFuncParam4`` and ``ContPhenFuncParam5``, respectively.

-  Planck function (``ContPhenFuncID = 2``):

   .. math:: c(\nu) = \frac{h \, \nu}{k_B}\frac{1}{e^{h \, \nu / k \, T} - 1},

   with temperature :math:`T` described by input parameter
   ``ContPhenFuncParam1``. The other input parameters
   ``ContPhenFuncParam2`` - ``ContPhenFuncParam5`` have to be set to
   zero.

-  beam-averaged continuum background temperature
   (``ContPhenFuncID = 3``)

   .. math::
      :label: PhenContFunc3

      c(\nu) = T_{\rm bg} \cdot \left(\frac{\nu}{\nu_{\rm ref}} \right)^{T_{\rm slope}},

   where :math:`\nu_{\rm ref}` (described by input parameter
   ``ContPhenFuncParam1``) indicates the reference frequency for
   :math:`T_{\rm bg}` (defined by input parameter
   ``ContPhenFuncParam2``). The temperature slope :math:`T_{\rm slope}`
   is defined by input parameter ``ContPhenFuncParam3``. If input
   parameter ``ContPhenFuncParam4`` is set to zero
   Eq. :eq:`PhenContFunc3` is applied to all frequency
   ranges. But the user can restrict the application of
   Eq. :eq:`PhenContFunc3` to a given frequency range
   by using input parameters ``ContPhenFuncParam1`` and
   ``ContPhenFuncParam4``, where ``ContPhenFuncParam1`` defines the
   first and ``ContPhenFuncParam4`` the last frequency, respectively.
   The other input parameter ``ContPhenFuncParam5`` must always be set
   to zero.

Note, the aforementioned continuum function :math:`c(\nu)` is added to
the background intensity of the corresponding distance.

In order to use a phenomenological description of the continuum in the
molfit file, the phrase ``cont-phen`` has to be used. Each component is
described by the source size ``s_size`` (in arcsec) (or
other parameters related to source description), the function-id
``func-id``, the input parameters ``p_1``, ``p_2``, ``p_3``, ``p_4``,
and ``p_5``, representing the input parameters ``ContPhenFuncParam1`` -
``ContPhenFuncParam5`` and the distance ``distance``. In the example
describe below, we use an expression for a standing wave to describe the
continuum phenomenologically at a given distance:

::

       cont-phen    1
       % s_size:   func-id:   p_1:   p_2:   p_3:   p_4:   p_5:   distance:
       500.00000          1    0.2    0.2    0.2    0.2    0.2       1.e20

Similar to the dust contribution, the phenomenological continuum
parameters can be defined globally, by using the input parameters
``ContPhenFuncID``, ``ContPhenFuncParam1``, ``ContPhenFuncParam2``,
``ContPhenFuncParam3``, ``ContPhenFuncParam4``, and
``ContPhenFuncParam5``. For the **myXCLASSFit**, **myXCLASSMapFit**,
**myXCLASSMapRedoFit**, and **LineID** function the
phenomenological parameters can be defined globally in a obs. xml file
as well, see Sect. ":ref:`myxclassfit-obs-xml-file`".



Derivations
-----------



.. _deriv-DetectionEquation:

Detection Equation
^^^^^^^^^^^^^^^^^^

In absence of scattering, the radiative transfer equation

  .. math:: \frac{\mathrm{d} I_{\nu}}{\mathrm{d} s} = -\kappa_{\nu}(s) I_{\nu} + \epsilon_{\nu}(s)

describes the propagation of radiation which passes through a medium.
During the propagation photons are absorbed and emitted indicated by
the emission and absorption coefficients :math:`\epsilon_\nu` and
:math:`\kappa_{\nu}`, respectively.

The optical depth :math:`\tau_{\nu}(s)` which measures the distance in
units of the mean free path, is given by

.. math::
   :label: DE:tau

   \tau_{\nu}(s) = \int_{s'=0}^{s'=s} \kappa_{\nu} \, d s'.

By using the source function
:math:`S_{\nu} = \frac{\epsilon_{\nu}}{\kappa_{\nu}}`, the radiative
transfer equation can be expressed as

.. math::
   :label: DE:dI

   \frac{\mathrm{d} I_{\nu}}{\mathrm{d} \tau} = I_{\nu}(\tau) + S_{\nu}(\tau).

Within the local thermodynamic equilibrium (LTE) the source function
is described by Planck's law for black body radiation
:math:`B_{\nu}(T)`.
Integrating Eq. :eq:`DE:dI` over :math:`\tau` leads to

  .. math:: I_{\nu}(s) = I_{\nu}(0) \, e^{-\tau_{\nu}} + \int_{\tau'=0}^{\tau'=\tau} S_{\nu}(\tau'_{\nu}) e^{\tau'_{\nu} - \tau_{\nu}} d \tau'_{\nu}.

Assuming a constant source function, i.e. constant emission and
absorption coefficients through the medium, the transfer equation can
be written as

.. math::
   :label: DE:final

   I_{\nu}(s) = I_{\nu}(0) \, e^{-\tau_{\nu}} + S_{\nu} \left(1 - e^{-\tau_{\nu}} \right).

Additionally, we have to take into account, that the different
components may not cover the whole beam, i.e. that the background
behind a certain component might contribute as well. So, we have to
extend Eq. :eq:`DE:final` by introducing the beam filling
factor :math:`\eta`, Eq. :eq:`myXCLASS:BeamFillingFactor`,
which describes the fraction of the beam covert by a component

.. math::
   :label: DE:finalExt

   I_{\nu}(s) = \eta \, \left[I_{\nu}(0) \, e^{-\tau_{\nu}} + S_{\nu} \left(1 - e^{-\tau_{\nu}} \right)\right] + \left(1 - \eta\right) \, I_{\nu}(0).

Here, the term :math:`\eta \, I_{\nu}(0) \, e^{-\tau_{\nu}}` indicates
the attenuated radiation from the background :math:`I_{\nu}(0)`. The
second term :math:`\eta \, S_{\nu} \left(1 - e^{-\tau_{\nu}} \right)`
describes the self attenuated radiation emitted by a certain
component. Finally, the last term
:math:`\left(1 - \eta\right) \, I_{\nu}(0)` represents the
contribution of the background which is not covert by a component.

In real observations, we do not measure absolute intensities but only
differences of intensities, i.e. we have to subtract the OFF-position
from Eq. :eq:`DE:finalExt` as well, where we have an
intensity caused by the cosmic background :math:`J_\mathrm{CMB}`. So,
we achieve

.. math::
   :label: DE:FinalEq

   I_{\nu}(s) = \eta \, \left[I_{\nu}(0) \, e^{-\tau_{\nu}} + S_{\nu} \left(1 - e^{-\tau_{\nu}} \right)\right] + \left(1 - \eta\right) \, I_{\nu}(0) - J_\mathrm{CMB}.



.. _deriv-BeamFillingFactor:

Beam Filling Factor
^^^^^^^^^^^^^^^^^^^

.. figure:: ../figures/Gaussians.png
   :align: center
   :width: 100%
   :name: fig-bFf

   a)~A single two-dimensional Gaussian function,
   Eq. :eq:`bFf:General2DGauss`, with
   :math:`\sigma_x = \sigma_y = 1.9` and
   :math:`\mu_x = \mu_y = 0` representing a
   Gaussian beam of a telescope. b)~Cut through
   the Gaussian function described in a) at half
   height. c)~A single two-dimensional Gaussian
   function, with :math:`\sigma_x = \sigma_y = 1.1`
   and :math:`\mu_x = 0.5` and :math:`\mu_y = 0.9`
   representing a Gaussian beam of a point source.
   d)~Cut through the Gaussian function described
   in a) at half height. e)~Convolved Gaussian of
   telescope and point`source as given by
   Eq. :eq:`bFf:GaussConvSimp`. f)~Cut through
   the convolved Gaussian function described in
   e) at half height.

The derivation of the beam filling factor
:eq:`myXCLASS:BeamFillingFactor` starts
with the normalized two-dimensional Gaussian function

.. math::
   :label: bFf:General2DGauss

   g(x, y, \sigma_x, \sigma_y, \mu_x, \mu_y) = \frac{1}{\sqrt{2 \, \pi \, \left(\sigma_x^2+\sigma_y^2\right)}} \, e^{-\left(\frac{\left(x-\mu_x\right)^2}{2 \, \sigma_x^2}+\frac{\left(y - \mu_y\right)^2}{2 \, \sigma_y^2}\right)},

where :math:`\sigma_x^2` and :math:`\sigma_y^2` describe the variances
and :math:`\mu_x` and :math:`\mu_y` the center along the :math:`x` and
:math:`y` axis, respectively.

Observing a Gaussian shaped extended source with a telescope is
described by a convolution of two two-dimensional Gaussian functions:

.. math::
   :label: bFf:GaussConvGeneral

   \left(g_1 * g_2 \right) &= \int_{-\infty}^\infty \, \int_{-\infty}^\infty \, g_1(x - u, y - v, \sigma_{x,1}, \sigma_{y,1}, \mu_{x, 1}, \mu_{y, 1}) \cdot g_2(u, v, \sigma_{x,2}, \sigma_{y,2}, \mu_{x,2}, \mu_{y, 2}) \, du \, dv\\
                           &= \frac{1}{2 \pi  \sqrt{\left(\sigma_{x,1}^2 + \sigma_{x,2}^2\right) \left(\sigma_{y,1}^2 + \sigma_{y,2}^2\right)}} \, e^{-\left(\frac{\left(\mu_{x,1} + \mu_{x,2} - x\right)^2}{2 \, \left(\sigma_{x,1}^2 + \sigma_{x,2}^2\right)} + \frac{\left(\mu_{y,1} + \mu_{y,2} - y\right)^2}{2 \, \left(\sigma_{y,1}^2 + \sigma_{ y,2}^2\right)}\right)}.

Assuming that :math:`g_1` describes the telescope with
:math:`\mu_{x,1} = \mu_{y, 1} \equiv 0` and that telescope and
extended source are described by non-elliptical Gaussians,
i.e. :math:`\sigma_{x,1} = \sigma_{y,1} \equiv \sigma_1` and
:math:`\sigma_{x,2} = \sigma_{y,2} \equiv \sigma_2`,
Eq. :eq:`bFf:GaussConvGeneral` can be simplified to [25]_

.. math::
   :label: bFf:GaussConvSimp

   \left(g_1 * g_2 \right) = \frac{1}{2 \pi \left(\sigma_1^2 + \sigma_2^2\right)} \, e^{-\frac{\left(x - \mu_{x,2}\right)^2 + \left(y - \mu_{y,2}\right)^2}{2 \left(\sigma_1^2  + \sigma_2^2\right)}}.

The FWHM of the resulting Gaussian is given by

.. math::
   :label: bFf:GaussConvSimpFWHM

   {\rm FWHM} = 2 \sqrt{2 \, \log 2} \sqrt{\sigma_1^2 + \sigma_2^2}

which describe an area of

.. math::
   :label: bFf:EllipseArea

   A_{\rm conv}^{\rm FWHM} &= \pi \cdot 2 \, \log 2 \cdot \left(\sigma_1^2 + \sigma_2^2\right) \\
                           &= \frac{\pi}{4} \cdot \left(\theta_1^2 + \theta_2^2\right).

In the last line we used the relation between the variances
:math:`\sigma_{1,2}` and the user defined FWHM of telescope
(:math:`\theta_1 \equiv \theta_t`) and source size
(:math:`\theta_2 \equiv \theta^{m,c}`) which is given by

.. math::
   :label: bFf:FWHMvariance

   \theta_i = 2 \, \sqrt{2 \, \log 2} \cdot \sigma_i.

The beam filling factor
Eq. :eq:`myXCLASS:BeamFillingFactor` is defined as ratios of areas

.. math::
   :label: bFf:etaGeneral

   \eta_{g_1,g_2} = \frac{A_{\rm source}^{\rm FWHM}}{A_{\rm conv}^{\rm FWHM}} = \frac{\frac{\pi \, \theta_2^2}{4}}{\frac{\pi}{4} \cdot \left(\theta_1^2 + \theta_2^2\right)} = \frac{\theta_2^2}{\left(\theta_1^2 + \theta_2^2\right)},

which is completely independent of the position :math:`\mu_x` and
:math:`\mu_y` of the extended source within the telescope beam.

If more extended sources are observed with the telescope, we have to
convolve the already convolved Gaussian Eq. :eq:`bFf:GaussConvSimp`
with a further two-dimensional Gaussian function with variance
:math:`\sigma_{x,3} = \sigma_{y,3} \equiv \sigma_3` and center
:math:`\mu_{x,3}` and :math:`\mu_{y,3}`. We get

.. math::

   \left(\left(g_1 * g_2 \right) * g_3 \right) = \left(g_1 * g_2 * g_3 \right) = \frac{1}{2 \pi  \left(\sigma_1^2 + \sigma_2^2 + \sigma_3^2\right)} \, e^{\left(-\frac{\left(\mu_{x,2} + \mu_{x,3} - x\right)^2 + \left(\mu_{y,2} + \mu_{y,3} - y\right)^2}{2 \, \left(\sigma_1^2 + \sigma_2^2 + \sigma_3^2\right)}\right)}.

The FWHM of the resulting Gaussian is given by

.. math::
   :label: bFf:NextGaussConvSimpFWHM

   {\rm FWHM} = 2 \sqrt{2 \, \log 2} \sqrt{\sigma_1^2 + \sigma_2^2 + \sigma_3^2},

which describe an area of

.. math::
   :label: bFf:NextEllipseArea

   A_{\rm conv}^{\rm next} &= \pi \cdot 2 \, \log 2 \cdot \left(\sigma_1^2 + \sigma_2^2 + \sigma_3^2\right) \\
                           &= \frac{\pi}{4} \cdot \left(\theta_1^2 + \theta_2^2 + \theta_3^2\right).

In the last line we used again the relation between the variances and
FWHM, Eq. :eq:`bFf:FWHMvariance`. Now, we can again define a beam
filling factor similar to Eq. :eq:`myXCLASS:BeamFillingFactor` and
get

.. math::
   :label: bFf:NextEtaGeneral

   \eta_{g_1,g_2,g_3} = \frac{\frac{\pi \, \theta_2^2}{4}+\frac{\pi \, \theta_3^2}{4}}{\frac{\pi}{4} \cdot \left(\theta_1^2 + \theta_2^2 + \theta_3^2\right)} = \frac{\theta_2^2+\theta_3^2}{\left(\theta_1^2 + \theta_2^2 + \theta_3^2\right)}.

When we observe more than three extended sources with a telescope we
have to iteratively convolve the resulting Gaussian with a further
two-dimensional Gaussian function and we can generalize
Eq. :eq:`bFf:NextEtaGeneral` to

.. math::
   :label: bFf:NextNextEtaGeneral

   \eta_{\rm general} = \frac{\sum_{i > 1} \theta_i^2}{\left(\sum_i \theta_i^2\right)} =  \frac{\sum_{i > 1} \theta_i^2}{\theta_t^2 + \sum_{i > 1} \theta_i^2},

where :math:`\theta_1 \equiv \theta_t` describes the FWHM of the
Gaussian shaped beam of the telescope, defined by the diffraction
limit, Eq. :eq:`myXCLASS:DiffractionLimit`.



.. _deriv-OpticalDepth:

Optical Depth
^^^^^^^^^^^^^

.. figure:: ../figures/Sketch__OpticalDepth.png
   :align: center
   :width: 40%
   :name: fig-od

   Transitions between the lower :math:`l` and the upper :math:`u`
   level with the corresponding Einstein coefficients.

In order to derive Eq. :eq:`myXCLASS:tau` we consider
a system which involves radiative transitions between a lower
:math:`l` and an upper :math:`u` level only. As shown in
:numref:`fig-od` , the lower level has an energy :math:`E_l` and
the upper level an energy :math:`E_u > E_l`. With

.. math::
   :label: od:nu

   h \, \nu_{u,l} = E_u - E_l

describing the energy difference between these two levels we can
express the emissivity due to spontaneous radiative decay as

.. math::
   :label: od:epsilon

   \epsilon_{l,u,\nu} = \frac{h \, \nu}{4 \, \pi} \, n_u \, A_{u,l} \, \phi_{l,u} (\nu),

where :math:`A_{u,l}` describes the *Einstein A-coefficient*, or
radiative decay rate for the transition from the lower :math:`l` to
the upper :math:`u` level. The expression :math:`1 / A_{u,l}` gives
the averaged time, that a quantum mechanical system can stay in level
:math:`u` before radiatively decaying to level :math:`l`, where we
assume no collisional (de-)excitation. The expression
:math:`\phi_{l,u} (\nu)` describes the line profile of the transition
of photons of frequency :math:`\nu` and is normalized to 1,
i.e. :math:`\int_0^\infty \phi(\nu) \, d \nu = 1`.

Similar to Eq. :eq:`od:epsilon` we can write the extinction
coefficient, which describes the radiative excitation from
the lower to the upper level

.. math::
   :label: od:kappaExt

   \kappa_{l,u,\nu}^{\rm ext} = \frac{h \, \nu}{4 \, \pi} \, n_l \, B_{l,u} \, \phi_{l,u} (\nu),

where :math:`B_{l,u}` describes the *Einstein B-coefficient for
extinction*.

In addition to spontaneous emission and extinction we have to take the
stimulated emission into account, which can be described by adding a
negative opacity contribution to Eq. :eq:`od:kappaExt`:

.. math::
   :label: od:kappa

   \kappa_{l,u,\nu} = \frac{h \, \nu}{4 \, \pi} \, \left(n_l \, B_{l,u} - n_u \, B_{u,l}\right) \, \phi_{l,u} (\nu),

where :math:`B_{u,l}` represents the *Einstein B-coefficient for
stimulated emission*. So, for :math:`n_l B_{l,u} < n_u \, B_{u,l}` we
get laser (maser) emission.

The different Einstein coefficients are related to each other by the
Einstein relations:

.. math::
   :label: od:EinsteinRelations

   A_{u,l} &= \frac{2 \, h \, \nu^3}{c_{\rm light}^2} \, B_{u,l},\\
   g_l \, B_{l,u} &= g_u \, B_{u,l}.

Following Eq. :eq:`DE:tau`, the differential optical depth
:math:`\tau_{\nu}` is defined as

.. math::
   :label: od:tauFirstPart

   d \tau_{\nu} = \kappa_{\nu} \, ds &= \left(\frac{h \, \nu}{4 \, \pi} \, \left(n_l \, B_{l,u} - n_u \, B_{u,l}\right) \, \phi_{l,u} (\nu) \right) \, ds \\
                                     &= \left(\frac{c_{\rm light}^2}{8 \, \pi \, \nu^2} \, A_{u,l} \, \left(n_l \, \frac{g_u}{g_l} - n_u \right) \, \phi_{l,u} (\nu) \right) \, ds,

where we used the Einstein relations Eqn. :eq:`od:EinsteinRelations`
in the last line. By assuming LTE conditions and therefore Boltzmann
population distribution

.. math:: \frac{n_u}{n_l} = \frac{g_u}{g_l} \, e^{(-E_u - E_l)/k_B T_{\rm ex}} = \frac{g_u}{g_l} \, e^{-h \, \nu_{u,l}/k_B T_{\rm ex}}

we can rewrite Eq. :eq:`od:tauFirstPart` by using Eq. :eq:`od:nu`

.. math::
   :label: od:tau2ndPart

   d \tau_{\nu} = \left(\frac{c_{\rm light}^2}{8 \, \pi \, \nu^2} \, A_{u,l} \, n_u \, \left(e^{h \, \nu_{u,l} / k_B \, T_{\rm ex}} - 1 \right) \, \phi_{l,u} (\nu) \right) \, ds.

Finally, we have to integrate along the line of sight and obtain the
optical depth :math:`\tau_{\nu}`

.. math::
   :label: od:tau3rdPart

   \tau_{\nu} = \frac{c_{\rm light}^2}{8 \, \pi \, \nu^2} \, A_{u,l} \, N_u \, \left(e^{h \, \nu_{u,l} / k_B \, T} - 1 \right) \, \phi_{l,u} (\nu),

where :math:`N_u = \int n_u \, ds` describes the column density of a
certain molecule in the upper state.

In order to express Eq. :eq:`od:tau3rdPart` in terms of the total
column density :math:`N_{\rm tot} = \sum_{i=0}^\infty n_i` we start
again with the Boltzmann population distribution

.. math::
   :label: od:NtotGeneral

   N_{\rm tot} = \sum_{i=0}^\infty n_i = n_j \, \sum_{i=0}^\infty \frac{n_i}{n_j} = n_j \, \sum_{i=0}^\infty \frac{g_i}{g_j} \, e^{(-E_i+E_j)/k_B T_{\rm ex}} = \frac{n_j}{g_j} \, e^{E_j/k_B T_{\rm ex}} \cdot Q \left(T_{\rm ex} \right),

where we used the partition function :math:`Q(T_{\rm ex})`, which is
defined as sum over all states

.. math::
   :label: od:PartFunc

   Q(T_{\rm ex}) = \sum_{i=0}^\infty g_i \, e^{-E_i/k_B \, T_{\rm ex}}.

For our purpose we rewrite Eq. :eq:`od:NtotGeneral`
in terms of :math:`N_u` and :math:`N_l`:

.. math::
   :label: od:NtotUL

   N_{\rm tot} = \frac{N_u}{g_u} \, e^{E_u/k_B T_{\rm ex}} \cdot Q \left(T_{\rm ex} \right).

Inserting this expression into Eq. :eq:`od:tau3rdPart` gives

.. math::
   :label: od:tauFinal

   \tau_{\nu} &= \frac{c_{\rm light}^2}{8 \, \pi \, \nu^2} \, A_{u,l} \, \left[\frac{N_{\rm tot} \, g_u}{Q \left(T_{\rm ex} \right)} \, e^{-E_u/k_B T_{\rm ex}} \right] \, \left(e^{h \, \nu_{u,l} / k_B \, T} - 1 \right) \, \phi_{l,u} (\nu) \\
              &= \frac{c_{\rm light}^2}{8 \, \pi \, \nu^2} \, A_{u,l} \, N_{\rm tot} \, \frac{g_u \, e^{-E_l/k_B T_{\rm ex}}}{Q \left(T_{\rm ex} \right)} \, \left(1 - e^{-h \, \nu_{u,l} / k_B \, T}  \right) \, \phi_{l,u} (\nu),

where we used Eq. :eq:`od:nu` to achieve Eq. :eq:`myXCLASS:tau`
for a single line of a certain component and molecule.



.. _deriv-erGauss:

Elliptical rotated Gaussians
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

An arbitrary rotated elliptical 2D-Gaussian can be written as

.. math::
   :label: deriv:erGauss:2dGauss

   f(x,y) = \frac{1}{V} \cdot A \cdot \exp \left[ -\left( a(x - x_0)^2 + 2 b (x - x_0) (y - y_0) + c (y - y_0)^2 \right) \right],

where the coefficient :math:`A` describes the amplitude, :math:`x_0`,
:math:`y_0` the center and :math:`\sigma_x`, :math:`\sigma_y` are the
:math:`x` and :math:`y` spreads of the blob. Additionally, :math:`V`
indicates the volume of the Gaussian and is given by

.. math::
   :label: deriv:erGauss:Volume

   V = \int_{-\infty}^{\infty} \int_{-\infty}^{\infty} f(x,y) \, dx \, dy = 2 \pi A \sigma_{x} \sigma_{y}.

The coefficients :math:`a`, :math:`b`, and :math:`c` are

.. math::

   a &= {\frac {\cos^{2} \theta} {2 \sigma_{x}^{2}}} + {\frac{\sin^{2} \theta} {2 \sigma_{y}^{2}}},  \\
   b & = -{\frac{\sin 2\theta } {4 \sigma_{x}^{2}}} + {\frac{\sin 2 \theta } {4 \sigma_{y}^{2}}}, \\
   c &= {\frac{\sin^{2} \theta }{2 \sigma_{x}^{2}}} + {\frac{\cos^{2} \theta }{2\sigma_{y}^{2}}}  .

where the blob is rotated by a clockwise angle :math:`\theta`.



.. ----------------------------------------------------------------------------------------



Footnotes
---------

.. Footnotes
.. [3]   A derivation of the expression can be found in the Sect. ":ref:`deriv-DetectionEquation`".

.. [4]   Derivations of the beam filling factor Eq. :eq:`myXCLASS:BeamFillingFactor`,
         are described in the Sect. ":ref:`deriv-BeamFillingFactor`".

.. [5]   A derivation of the expression is given in the Sect. ":ref:`deriv-OpticalDepth`.

.. [6]   The indices :math:`u` and :math:`l` represent upper and lower state of
         transition :math:`t`, respectively.

.. [7]   Because the database usually does not describe the partition functions
         at the given excitation temperature :math:`T_{\rm ex}^{m,c}`, the value
         of :math:`Q \left(m,T_{\rm ex}^{m,c} \right)` is computed from a linear
         interpolation in log space. (With the new catalog, extrapolation should
         not be necessary for most conditions encountered in molecular cores.)

.. [8]   For molecules and RRLs the name declared in the molfit file must be
         identical to the name of the molecule included in the database.

.. [9]   Here, :math:`i = 1` indicates the core component, i.e. components which
         are closest to the background.

.. [10]  A derivation of the expression can be found in the
         Sect. ":ref:`deriv-DetectionEquation`".

.. [11]  Note, the definition of the source size :math:`\theta^{m,c}` for
         an foreground component will be ignored, because we assume that
         all foreground layers cover the whole beam.

.. [12]  For single dish observations the telescope beam FWHM size is related
         to the diameter of the telescope by the diffraction limit. For the
         sub-beam description, Eq. :eq:`myXCLASS:DiffractionLimit` is used to
         compute the beam size for single dish observations for the lowest
         frequency of each frequency range.This value is used for the whole
         range, respectively.

.. [13]  https://www.fftw.org/

.. [25]  Here “\*” indicates the convolution of two functions :math:`g_1` and
         :math:`g_2`.



.. ----------------------------------------------------------------------------------------



References
----------

.. citation reference
.. [Bresenham_1977]           Bresenham, J. 1977, Commun. ACM, 20, 100–106

.. [Cesaroni_Walmsley_1991]   Cesaroni, R. \& Walmsley, C. 1991, Astronomy
                              and Astrophysics, 241, 537

.. [Hildebrand_1983]          Hildebrand, R. 1983, Molster, FJ, Dorschner,
                              J., Henning, T.,  \& Mutschke, H.

.. [Ossenkopf_Henning_1994]   Ossenkopf, V. \& Henning, T. 1994, Astronomy and
                              Astrophysics, 291, 943

.. [Padua_2011]               Padua, D. 2011, Encyclopedia of parallel computing
                              (Springer Science \& Business Media)

.. [Stahler_Palla_2005]       Stahler, S. \& Palla, F. 2005, Stahler,
                              SW \& Palla, F, 3, 9
