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 \(N\). The
following \(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 \(T_{\rm ex}\) in K (T_rot), the column density
\(N_{\rm tot}\) in cm\(^{-2}\) (N_tot), and the velocity
offset (relative to v\(_{\rm LSR}\)) in km s\(^{-1}\)
(V_off). Depending of the used source description, see
Source description, the size of the source \(\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) \(\Delta \nu\) in
km s\(^{-1}\) (V_width). Additionally, the stacking of the
components along the line-of-sight requires the cf-flag (CFFlag),
see Simple 1-d description, or the distance parameter
(distance), see 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. “The molfit file”.
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. “The iso ratio file”.
The DatabaseQuery function can be used to get a list of all molecules contained in the database, see Sect. “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\(_3\)CN\(_{v=0}\) and HCS\(^+_{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.
“Observational 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>