Downloading line list data

Downloading line list data#

There are currently three main databases of molecular line lists that are supported by line racer: HITRAN, HITEMP, Exomol and ExoAtom. The following notes will explain how to download line lists from these databases for opacity calculations with line racer. The first step is to create a folder in which you will store all the required data. If you want to calculate H2O opacities, for example, your folder structure could look like this: line_list/H2O/

Note

If your favorite database is currently missing, please reach out to us. We will do our best to implement it as fast as possible.

Note

In general the data can be downloaded by using wget which, for example, can be downloaded using homebrew when using mac, as explained in the installation guide. In the right subfolder you can then downloaded the files via wget https://your_link_to_a_file_here.

ExoMol#

Go to the ExoMol website and navigate to the Data tab and then to Molecules. Here you can see an overview of all the available molecules within ExoMol. Click on the molecule you are interested in to go to its data page. On this page (for example H2O) you will find a list of available isotopes for the molecule.

Additionally, there are broadening files (.broad). ExoMol uses quantum number dependent line broadening parameters, a more detailed explanation can be found in Barton et al. (2017) and in Tennyson et al. (2024). The broadening files are provided for (multiple) species, which is denoted by the suffix in the file name (for example 1H2-16O__H2.broad for H2 broadening). Sometimes, the broadening diet (more about that can be found in the upper mentioned literature) is also indicated in the file name (e.g. 1H2-16O__air_a0.broad for the a0 diet). Currently, line racer supports the a0 and m0 diet, but it is planed to include more.

Another feature planned to include in the future is the use of pressure shift parameters from ExoMol, which are also provided on this website (e.g. 1H2-16O__a0.shift). However, currently there are not many molecules with available pressure shift files.

If you want to use one (or multiple) of the broadening species, download the files and put them into your line list folder structure (e.g. line_list/H2O/). If you do not use a broadening file, you can later choose different broadening treatments within line racer (e.g., constant broadening or broadening using the approximation from Sharp and Burrows, 2007, their Eq. 15)

In the isotope list, click on the isotope you are interested in (for example 1H2-16O) to go to its page. Here you will find a list of available line lists for this isotope. Click on the line list you are interested in (for example POKAZATEL) to go to its page. Best practice is to follow the ExoMol recommendation and use the line list that is marked in green.

On the line list page, you will first find the metadata, where one file is the .def file (e.g. 1H2-16O__POKAZATEL.def). This file includes all of the relevant information about the line list, like the number of lines, the temperature range, the isotope mass and the version number (in YYYYMMDD format). Additionally, as the most important part, it contains the parameters Default value of Lorentzian half-width for all lines (in cm-1/bar) and Default value of temperature exponent for all lines, which are needed for the line broadening calculations if no broadening species is chosen.

Below the spectrum overview you can find the download links for the line list files. The first file is the .states file (e.g. 1H2-16O__POKAZATEL.states.bz2), which contains all the energy levels and their properties. This is required to download in any case. Below that are the .trans files, which contain the actual transition data. Depending on the line list, there can be multiple .trans files, which are split in frequency ranges to make downloading easier.

Note

Some of the .trans files are still very large and make it hard to process them with a reasonable amount of memory and multiprocess the calculation later. Therefore, line racer provides the option to split the .trans files into smaller files. More about that can be found in the tutorial called splitting transition files.

Download the files of the wavenumber range of your interest (or just all of them) to your line list folder structure.

Note

The .states and .trans files are usually bz2 compressed. Line racer is able to read these compressed files directly, without the need to decompress them (but it can also read the decompressed files).

Since there are often many .trans files, it is recommended to use a script to download them all at once. An example bash script using wget to download all the .trans files for the POKAZATEL line list of H2O is provided below:

#!/bin/bash

# Adjust the base URL
BASE_URL="https://www.exomol.com/db/H2O/1H2-16O/POKAZATEL/"

# Adjust range as needed; e.g., for 0 to 41200 in steps of 100
for ((i=0; i<=41200; i+=100)); do
    START=$(printf "%05d" $i)
    END=$(printf "%05d" $((i + 100)))
    FILENAME="1H2-16O__POKAZATEL__${START}-${END}.trans.bz2"
    URL="${BASE_URL}/${FILENAME}"

    echo "Downloading ${FILENAME}"
    wget --continue "${URL}" || break  # Stop if a file does not exist
done

If you have named the file download_H2O.sh, you can run it in your terminal via:

./download_H2O.sh

The line calculation is much faster for decompressed files, so if you have enough disk space available it is recommended to decompress the .trans files after downloading them. For many files, you can use the following command in your terminal to decompress all .bz2 files:

cd line_list/H2O/
bunzip2 *.bz2

After the transition files, the last important data is the partition function, which can be found as the .pf file (e.g. 1H2-16O__POKAZATEL.pf). This file contains the partition function values at different temperatures, which are needed for the opacity calculations and should be downloaded to the line list folder structure as well.

HITRAN#

Go to the HITRAN website and navigate to the Line-by-Line Search over the Data Access tab. Here you can select the molecule you are interested in from the molecule list (e.g. CO2). Then you can select the isotopologue(s) you want to download data for. Do not worry too much about that, since you can later choose which isotopologues to use within line racer. After that you can select the desired frequency range, however, it is recommended to download the full range, since the hitran line list files are not that big. For the next step you need to be logged in to download the data. If you do not have an account yet, you can create one for free here. After login, you can download the data. The standard format is the .par format, which is also supported by line racer. It contains all the important information needed for the opacity calculations, including broadening parameters for air and self broadening.

However, if you need other broadening species, you can select Create New Output Format. In the new window, select an Output Format Name and choose [comma] as a Field separator, Windows (CR LF) as Line endings and select the Output header line. Then, on the bottom right, select the desired parameters in Available Parameters, but it is recommended and most easy to just select all parameters. After doing that, please safe this output format. If you choose to use the newly created output format then please make sure to select it on the 4. Select or Create Output Format step on the left side under Available Output Formats.

The line data can now be prepared by clicking on Start Data Search. It might take a while, but you will be directed to a new page, where you can download the Output transition data, as well as look into the List of sources to cite the data properly. Additionally, you can check your output format again, by looking into the readme.txt file. Please add the transition data file to your line data file (e.g. line_list/CO2/).

Similar to ExoMol, you also need the partition function for HITRAN data. It can be found under the HITRAN Documentation tab under Isotopologue Metadata. The partition function files are named after the HITRAN internal global ID as q*globalid*.txt (e.g. q7.txt for the 12C-16O2 isotopologue of CO2). Please download all of the partition function files for the isotopologues you selected before and add them to your line list folder structure.

HITEMP#

The HITEMP database is an extension of the HITRAN database for high temperature applications. It can be found on the HITRAN website under Data Access choosing HITEMP. The line list data can be downloaded by clicking on the Download feature of the HITEMP data table of the molecule you are interested in (e.g. for CH4). For some molecules, there are multiple files, please download all of the relevant files for you. HITEMP line lists automatically contain all the available isotopologues for the molecule and you can later choose which isotopologues to use within line racer.

Important

For HITEMP line lists, please decompress (or unzip) them before adding them to your line list folder structure (e.g. line_list/CH4/).

Similar to HITRAN, you also need the partition function for HITEMP data. It can be found under the HITRAN Documentation tab under Isotopologue Metadata. The partition function files are named after the HITRAN internal globalID as q*globalid*.txt (e.g. q32.txt for the 12C-1H4 isotopologue of CH4). Please download all of the partition function files for the isotopologues you want to use and add them to your line list folder structure.

ExoAtom#

Go to the ExoMol website and navigate to the Databases tab and then to ExoAtom. Here you can see the periodic system of all elements. For all orange colored elements, there is line list data. Click on the element you are interested in to go to its data page. On this page (for example Li) you will find a list of available isotopes (for H and He) or available ions (for almost all) for the element.

If you click on the ion/isotope you are interested in (for example Li I), you will find a list of available line lists for this element. Mostly, this is a NIST line list and a Kurucz line list, but there can also only be one of them. A general recommendation on which line list to use cannot be given, but the NIST line lists are highly accurate, while the Kurucz line lists are much more complete.

For each line list, there is a .adef.json file, which contains all the relevant information about the line list, like the number of lines, the temperature range, the isotope mass and the version number (in YYYYMMDD format). The most important files are the following three: The first file is the .states file (e.g. Li__NIST.states), which contains all the energy levels and their properties. This is required to download in any case. The second file is the .trans file (e.g. Li__NIST.trans), which contains the actual transition data. The third file is the .pf file (e.g. Li__NIST.pf), which contains the partition function values at different temperatures, which are needed for the opacity calculations and should be downloaded to the line list folder structure as well.

A general note on the naming convention of the files and atoms: The files are named after the element and the line list (e.g. Li__NIST for the NIST line list of Li). For ions, the ionization stage is indicated by a _p for positive charge and _n for negative charge. For multiple ionization stages, the number of stages is indicated in front of the charge (e.g. Fe_2p__NIST), while for single ionization, there is no number (e.g. Fe_p__NIST). For H and He, the isotopologues are indicated by the isotope mass (e.g. 3He__NIST for the NIST line list of 3He). So for example, for 3He+, the correct name is 3He_p__NIST. The first part (3He_p) is also what needs to be put into the isotope dictionary in line racer (but more about that in the tutorial). As a last note, for elements other than H/He, ExoAtom provides non-isotope-resolved standard atomic data, which should be labeled with a -NatAbund in line racer, to indicate that. For example, if you are calculating Li cross-sections, you can use the Li__NIST line list, which is not isotope-resolved, and label it as Li-NatAbund in line racer isotope dictionary. For Li II it would be Li-NatAbund_p.

After downloading all the required data, you are ready to use line racer for opacity calculations!

Contents