.. _database: Database ======== The database with *XCLASS* provides all the molecular data required to fit the spectra, including excitation energies, partition functions, Einstein A-coefficients etc. The underlying basis comes from a variety of sources, but primarily CDMS. The *XCLASS* database file is stored at :: /path-to-user-home-directory/.xclass/.db/ To successfully customize a molecule, the name specified in the input files must match the entry in the database. This is not always trivial to determine as permutations in notation, specification of vibrational, ortho-para, A-E, etc. and multiple versions of entries may exist. The database functions provide a way to ensure these are matched. The *XCLASS* database contains two tables: #. *partitionfunctions*, #. *transitions*. They have 121 and 12 columns respectively. The database format can be read by SQLite3. The database may also be browsed by several available third party tools. A useful example for Linux is ``sqliteman``. For Ubuntu distributions (tested on 18.04), it can be installed by .. code:: shell $ sudo apt-get update -y $ sudo apt-get install -y sqliteman .. _updateDatabase: UpdateDatabase -------------- This function updates the *XCLASS* database file located in the ``.xclass/db/`` subdirectory located in the user's home directory from spectroscopic databases connected to the Virtual Atomic and Molecular Datacentre, VAMDC (www.vamdc.eu). Currently, data access to the CDMS database and the JPL catalog, is supported. Example call of the **UpdateDatabase** function to download a new database file from the CDMS server: :: >>> from xclass import task_UpdateDatabase # call UpdateDatabase function >>> DBUpdateNew = "new" >>> task_UpdateDatabase.UpdateDatabase(DBUpdateNew) .. _databaseQuery: DatabaseQuery ------------- This function sends a given SQL query string to the *XCLASS* database. Example call of the **DatabaseQuery** function: :: >>> from xclass import task_DatabaseQuery # call DatabaseQuery function >>> QueryString = "select PF_Name from Partitionfunctions" >>> Contents = task_DatabaseQuery.DatabaseQuery(QueryString) Please note, in the example described above, all names stored in table "Partitionfunctions" are saved in the output variable "Contents". Here, "Contents[0]" includes the first name and so on. .. _listDatabase: ListDatabase ------------ This function reads in entries from the table *transitions* located in the SQLite3 database file and prints out the contents to the screen or file (defined by the input parameter ``OutputDevice``). The user can limit the output by defining a minimum and maximum for the frequency (or for the lower energy) for the transitions. Example call of the **ListDatabase** function: :: >>> from xclass import task_ListDatabase # call ListDatabase function >>> FreqMin = 20000.0 >>> FreqMax = 20100.0 >>> ElowMin = 100.0 >>> ElowMax = 2000.0 >>> SelectMolecule = [] >>> OutputDevice = " " >>> Contents = task_ListDatabase.ListDatabase(FreqMin, FreqMax, ElowMin, \ ElowMax, SelectMolecule, \ OutputDevice) .. _getTransitions: GetTransitions -------------- .. figure:: ../figures/GetTransition-GUI.png :align: center :scale: 60% :name: fig-gettransition-gui Similar to the *ListDatabase* function, the **GetTransitions** function displays information from the embedded database about transitions within a user-defined frequency range. Here, the frequency range selection is done in an interactive way. Therefore, the **GetTransitions** function starts a graphical user interface (GUI) which describes observational data (defined by parameter ``obsdata``) within a frequency range defined by the parameters ``FreqMin`` and ``FreqMax``. Additionally, the function offers the possibility to plot a synthetic spectrum (defined by parameter ``modeldata``) of a previous myXCLASS or myXCLASSFit function call as well. By using the mouse in combination with the right mouse button, the user defines the central frequency (blue vertical line) of the frequency range (grey vertical bar) which is used for the database query. The initial half width of this range is defined by parameter ``FrequencyWidth``. Note, the width of the range can be enlarged (shrinked) by pressing the “+” (“-”) key. In the following, *XCLASS* prints out information of all transitions within the selected frequency range to the screen, starting with the transition with the lowest transition frequency. In order to sort the transitions by lower energies, the user has to press the “1” key before selecting the central frequency. Using the “2” (“3”) key, sorts the transitions by the Einstein A coefficients (by a products of upper state degeneracies and Einstein A coefficients (gA)). Pressing the “0” key restores the initial order, i.e. by transition frequencies. Additionally, the user can reduce the number of transitions by defining a lower and a upper limit for the lower energies using parameters ``ElowMin`` and ``ElowMax``, respectively. Furthermore, the screen output can be limited to a few molecules by using parameter ``SelectMolecule``. Note, the GUI has to be closed to stop the function! Example call of the **GetTransitions** function :: >>> from xclass import task_LoadASCIIFile >>> from xclass import task_GetTransitions >>> from xclass import task_myXCLASS # use myXCLASS function to create synthetic spectrum >>> FreqMin = 580102.0 >>> FreqMax = 580546.5 >>> FreqStep = 0.5 >>> TelescopeSize = 3.5 >>> Inter_Flag = False >>> t_back_flag = True >>> tBack = 1.06 >>> tSlope = 0.0 >>> N_H = 3.e+20 >>> beta_dust = 2.0 >>> kappa_1300 = 0.02 >>> MolfitsFileName = XCLASSBaseDir + "demo/myXCLASS/CH3OH__pure.molfit" >>> iso_flag = True >>> IsoTableFileName = XCLASSBaseDir + "demo/myXCLASS/iso_names.txt" >>> LocalOverlapFlag = False >>> NoSubBeamFlag = True >>> modeldata, log, TransEnergies, IntOpt, jobDir = task_myXCLASS.myXCLASSCore( \ FreqMin = FreqMin, \ FreqMax = FreqMax, \ FreqStep = FreqStep, \ MolfitsFileName = MolfitsFileName, \ iso_flag = iso_flag, \ IsoTableFileName = IsoTableFileName, \ TelescopeSize = TelescopeSize, \ Inter_Flag = Inter_Flag, \ t_back_flag = t_back_flag, \ tBack = tBack, \ tSlope = tSlope, \ N_H = N_H, \ beta_dust = beta_dust, \ kappa_1300 = kappa_1300, \ LocalOverlapFlag = LocalOverlapFlag, \ NoSubBeamFlag = NoSubBeamFlag, \ printFlag = True) # use LoadASCIIFile function to import obs . data >>> FileName = XCLASSBaseDir + "demo/myXCLASS/band1b.dat" >>> NumHeaderLines = 1 >>> RestFreq = 0.0 >>> vLSR = 0.0 >>> obsdata = task_LoadASCIIFile.LoadASCIIFile(FileName, NumHeaderLines, \ RestFreq, vLSR) # call GetTransitions function >>> SelectMolecule = [] >>> FrequencyWidth = 5.0 >>> ElowMin = 0.0 >>> ElowMax = 3000.0 >>> task_GetTransitions.GetTransitions(obsdata, FreqMin, FreqMax, \ SelectMolecule, FrequencyWidth, \ ElowMin, ElowMax, modeldata )