Quick start
===========

Here's an example how to use the myXCLASSFit function of the *XCLASS* package

::

    >>> from xclass import task_myXCLASSFit
    >>> import os

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

    # set path and name of molfit file
    >>> MolfitsFileName = LocalPath + "files/my_molecules.molfit"

    # set path and name of observational (obs.) xml file
    >>> ObsXMLFileName = LocalPath + "files/my_observation.xml"

    # set path and name of algorithm (alg.) xml file
    >>> AlgorithmXMLFileName = LocalPath + "files/my_algorithm__trf.xml"

    # set optimization package
    >>> Optimizer = "scipy"

    # define that results of myXCLASSFit function are return as dictionary
    >>> DictOutFlag = True

    # create transition plots at the end of the fitting procedure
    >>> ExtendedPlotFlag = True

    # call myXCLASSFit function
    >>> OutDict = task_myXCLASSFit.myXCLASSFitCore( \
                                MolfitsFileName = MolfitsFileName, \
                                ObsXMLFileName = ObsXMLFileName, \
                                AlgorithmXMLFileName = AlgorithmXMLFileName, \
                                Optimizer = Optimizer, \
                                ExtendedPlotFlag = ExtendedPlotFlag, \
                                DictOutFlag = DictOutFlag)

This example requires three input files (molfit, observational xml, and algorithm
xml file), which are briefly described in the following.


Molfit file
-----------

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

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
: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 selected line
profile requires one or two velocity widths (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 :ref:`myxclass-molfit-1d`, or the distance parameter
(``distance``), see :ref:`myxclass-molfit-stacking`. Finally,
the column (``keyword``) to describe so-called keywords, indicating the
line profile function, Non-LTE description etc. Note, different keywords
have to be separated by “\_” character. For example, the composed
keyword ``Non-LTE_Voigt`` indicates a Non-LTE description and the usage
of a Voigt line profile for the corresponding component.

In order to fit the parameters described in the moflit file to the
given observation data, additional columns are required to indicate
for each parameter and component whether a parameter remains fixed
and to describe the corresponding parameter range. Therefore, three
additional columns are needed on the left side of each parameter,
indicating whether the current parameter is to be optimized "y" or
not "n", and defining the lower and the upper limit. The lower limit
must not be larger than the upper limit! Please note that neither
the column for the stacking parameter, nor the column specifying the
core or foreground flag, nor the column specifying the keyword need
additional columns. For more details, see Sect.
":ref:`myxclass-molfit`".

In addition, a so-called *iso ratio* file can be defined, to related
molecules defined in the molfit file to their isotopologues and / or
vibrational excited states, see Sect. ":ref:`myxclass-iso`".

The *DatabaseQuery* function can be used to get a list of all
molecules contained in the database, see Sect. ":ref:`databaseQuery`",

::

    >>> from xclass import task_DatabaseQuery

    # set query string
    >>> QueryString = "select PF_Name from Partitionfunctions"

    # call DatabaseQuery function
    >>> Contents = task_DatabaseQuery.DatabaseQuery(QueryString)


Example of a molfit file describing two molecules  CH\ :math:`_3`\ CN\ :math:`_{v=0}` and
CH\ :math:`_3`\ OH\ :math:`_{v=0}` with two and one components, respectively.

::

       CH3CN;v=0;   2
       % fl:  low:   up:  s_size:  fl:  low:    up:   T_rot:  fl:      low:        up:     N_tot:  fl:  low:   up:  V_width:  fl:  low:   up:   V_off:  distance:
          y   0.1  20.0      3.0    y  50.0  550.0    300.0    y  1.00e+12   1.00e+20   2.00e+16    y   4.0  12.0       8.0    y  -2.0  +2.0     -0.3  500.0
          y   0.1  20.0    100.0    y  50.0  550.0     50.0    y  1.00e+12   1.00e+20   2.00e+14    y   4.0  12.0       5.0    y  -2.0  +2.0      1.0  300.0
       CH3OH;v=0;   1
       % fl:  low:   up:  s_size:  fl:  low:    up:   T_rot:  fl:      low:        up:     N_tot:  fl:  low:   up:  V_width:  fl:  low:   up:   V_off:  distance:
          n   0.0   0.0      3.0    y  10.0  300.0    150.0    y  1.00e+12   1.00e+20   3.00e+16    y   4.0  12.0       6.0    y  -2.0  +2.0     -0.3  500.0



Observational xml file
----------------------

The so-called *observational xml file* (or *obs. xml file*) is used
to describe the import of the observational data within an xml file.
Here, each parameter is defined by so-called tags, i.e.
``<TagName>TagValue</TagName>``. For example, the tag ``NumberExpFiles``
defines the number of obs. data files fitted by e.g. the myXCLASSFit
function.

*XCLASS* is able to import any number of files describing the observation
data, each file requiring several additional parameters enclosed by
the ``<file>`` tag. For example, the tags ``<FileNamesExpFiles>``,
``<TelescopeSize>``, ``<Inter_Flag>``, ``<GlobalvLSR>``, and
``<NumberExpRanges>`` describe the path and name of the obs. data file,
the size of the telescope or beam, a flag indicating if size of the
telescope or beam is defined, the source velocity, and the number of
frequency ranges, respectively. For more details, see Sect.
":ref:`myxclassfit-obs-xml-file`".


Example observational xml file used by many *XCLASS* functions

::

      <?xml version="1.0" encoding="UTF-8"?>
      <ExpFiles>


         <!-- define number of experimental data file(s) -->
         <NumberExpFiles>1</NumberExpFiles>


         <!-- ****************************************************************** -->
         <!-- define parameters for first file -->
         <file>


            <!-- define path and name of first data file -->
            <FileNamesExpFiles>files/data/observed_spectrum.dat</FileNamesExpFiles>


            <!-- define import filter -->
            <ImportFilter>xclassASCII</ImportFilter>


            <!-- define number of frequency ranges for first data file -->
            <NumberExpRanges>1</NumberExpRanges>


            <!-- define parameters for each frequency range -->
            <FrequencyRange>
                  <MinExpRange>219764.240</MinExpRange>
                  <MaxExpRange>221471.740</MaxExpRange>
                  <StepFrequency>2.5</StepFrequency>


                  <!-- define background temperature and temperature slope -->
                  <t_back_flag>True</t_back_flag>
                  <BackgroundTemperature>0.0</BackgroundTemperature>
                  <TemperatureSlope>0.0</TemperatureSlope>


                  <!-- define hydrogen column density, beta for dust, and kappa -->
                  <HydrogenColumnDensity>1.00E+24</HydrogenColumnDensity>
                  <DustBeta>0.0</DustBeta>
                  <Kappa>0.0</Kappa>
            </FrequencyRange>


            <!-- define size of telescope -->
            <TelescopeSize>0.38</TelescopeSize>


            <!-- define local standard of rest (vLSR) -->
            <GlobalvLSR>0.0</GlobalvLSR>


            <!-- define if interferrometric observation is modeled -->
            <Inter_Flag>True</Inter_Flag>


            <!-- define parameters for ASCII file import -->
            <ErrorY>no</ErrorY>
            <NumberHeaderLines>0</NumberHeaderLines>
            <SeparatorColumns> </SeparatorColumns>
         </file>


         <!-- ************************************************* -->
         <!-- parameters for isotopologues -->
         <Isotopologues>True</Isotopologues>
         <IsoTableFileName>files/my_isonames.txt</IsoTableFileName>


         <!-- *********************************** -->
         <!-- take local-overlap into account -->
         <LocalOverlap_Flag>False</LocalOverlap_Flag>


         <!-- **************************** -->
         <!-- prevent sub-beam description -->
         <NoSubBeam_Flag>True</NoSubBeam_Flag>
      </ExpFiles>



Algorithm xml file
------------------

The so-called *algorithm xml file* is used to define the optimization
algorithm, used to fit the parameters described in the molfit file to
the given obs. data. A single algorithm or a sequential application
of different algorithms can be used. As for the obs. xml file, each
parameter is defined by tags.

Example algorithm xml file used by many *XCLASS* functions

::

      <?xml version="1.0" encoding="UTF-8"?>
      <FitControl>
         <!-- settings for fit process -->


         <!-- set number of used algorithms -->
         <NumberOfFitAlgorithms>1</NumberOfFitAlgorithms>


         <!-- define settings for 1st algorithm -->
         <algorithm>
            <FitAlgorithm>trf</FitAlgorithm>


            <!-- set variation value -->
            <VariationValue>1.e-3</VariationValue>


            <!-- set max. number of iterations -->
            <number_iterations>10</number_iterations>


            <!-- set max. number of processors -->
            <NumberProcessors>40</NumberProcessors>


            <!-- settings for chi^2 -->
            <LimitChi2>1e-6</LimitChi2>
            <RenormalizedChi2>True</RenormalizedChi2>
            <LogChi2>True</LogChi2>
            <SaveChi2>True</SaveChi2>


            <!-- set plot options -->
            <PlotFlag>True</PlotFlag>
         </algorithm>
      </FitControl>



Transition plots
----------------

The so-called *transition plots* describe the observational data (blue line)
together with the synthetic spectra taking all contributions from the molfit
and the iso ratio file into account (green dashed line). The red line indicates
the contribution of the current molecule only.

.. figure:: ../figures/transition-plots.png
   :align: center
   :width: 100%
   :name: fig:TransitionPlots

   Excerpt from the transition plots for CH\ :math:`_3`\ CN\ :math:`_{v=0}`.



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



Footnotes
---------

.. Footnotes
.. [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.