.. _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 three tables: #. *Partitionfunctions*, #. *Transitions*, #. *LookUp*. 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. For more details see :ref:`api-updatedatabase`. Example call of the **UpdateDatabase** function to download the latest official database file from the CDMS server: :: >>> from xclass import task_UpdateDatabase # call UpdateDatabase function >>> DBUpdateNew = "new" >>> task_UpdateDatabase.UpdateDatabase(DBUpdateNew) In addition it is also possible to download a specific database files from the CDMS server using the download `website `_ . In order to use the downloaded file as default database, please use :: >>> from xclass import task_UpdateDatabase # call UpdateDatabase function >>> DBUpdateNew = "new" >>> DBFileName = "/path/to/database/file" >>> task_UpdateDatabase.UpdateDatabase(DBUpdateNew, DBFileName = DBFileName) .. _databaseQuery: DatabaseQuery ------------- This function sends a given SQL query string to the *XCLASS* database. For more details see Sect. :ref:`api-databasequery`. 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. For more details see Sect. :ref:`api-listdatabase`. 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! For more details see Sect. :ref:`api-gettransitions`. 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 ) .. _AddPrivateEntries: AddPrivateEntries ----------------- The AddPrivateEntries function offers the possibility to add private entries for specific species to a given XCLASS database file. For more details see Sect. :ref:`api-IterativeFitting`. Example call of the **AddPrivateEntries** function :: >>> from xclass import task_LoadASCIIFile >>> from xclass import task_AddPrivateEntries >>> from xclass import task_myXCLASS # download a new database file from CDMS server >>> DBFileName = "" >>> downloadFlag = True # define name of new molecule (add phrase "private" to indicate # entry as private) >>> MoleculeName = "CH3OH-private;v=0;" # set path and name of ASCII file describing transition parameters # format of cat file is described in # https://cdms.astro.uni-koeln.de/classic/general/#format_of_the_egy_file >>> TransFileName = os.path.join(LocalPath, "files/CH3OH__c032504.cat") # set path and name of ASCII file describing partition function .. >>> PFFileName = "" # .. or set path and name of ASCII file describing lower energies # which are used to compute partition function >>> EGYFileName = os.path.join(LocalPath, "files/CH3OH__c032504.egy") # some additional parameters: # set flag for using old format for egy file >>> OldFormatEGYFileFlag = False # set flag for Einstein A coefficient instead of intensity >>> EinsteinAFlag = True # set flag for describing partition function on log-scale >>> logpfFlag = True # set flag for plotting partition function >>> plotpfFlag = True # set flag for using myXCLASS to check new entries >>> myxclassFlag = True ########################################################################### # call AddPrivateEntries function >>> task_AddPrivateEntries.AddPrivateEntries(DBFileName = DBFileName, \ downloadFlag = downloadFlag, \ FinalPath = FinalPath, \ MoleculeName = MoleculeName, \ TransFileName = TransFileName, \ PFFileName = PFFileName, \ EGYFileName = EGYFileName, \ OldFormatEGYFileFlag = OldFormatEGYFileFlag, \ EinsteinAFlag = EinsteinAFlag, \ logpfFlag = logpfFlag, \ plotpfFlag = plotpfFlag, \ myxclassFlag = myxclassFlag) # call DatabaseQuery function to get list of new molecule values >>> QueryString = "select * from transitions where T_Name = " >>> QueryString += "{:s}{:s}{:s}".format(chr(34), MoleculeName, chr(34)) >>> QueryString += " order by T_Frequency" >>> Contents = task_DatabaseQuery.DatabaseQuery(QueryString)