
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

    # call myXCLASSFit function
    >>> OutDict = task_myXCLASSFit.myXCLASSFitCore( \
                                MolfitsFileName = MolfitsFileName, \
                                ObsXMLFileName = ObsXMLFileName, \
                                AlgorithmXMLFileName = AlgorithmXMLFileName, \
                                Optimizer = Optimizer, \
                                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)) 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 component,
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.

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
the definition of the 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`.

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
HCS\ :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+14   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+14   1.00e+20   2.00e+14    y   4.0  12.0       5.0    y  -2.0  +2.0      1.0  300.0
       HCS+;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      0.5    y  10.0  300.0     50.0    y  1.00e+17   1.00e+21   3.00e+20    y   4.0  12.0       8.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>



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



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.
