Hapi2

<h1>HAPI2: Second Generation of the HITRAN Application Programming Interface</h1>

The first generation of the HITRAN Application Programming Interface (HAPI) <a href="https://doi.org/10.1016/j.jqsrt.2016.03.005">[Kochanov et al. JQSRT 2016]</a> has proven to be a convenient tool for acquiring and working with HITRAN data. The HAPI library provided a means of downloading and filtering the spectroscopic transitions for molecules provided by the HITRANonline <a href="http://dx.doi.org/10.1016/j.jqsrt.2015.12.012">[Hill et al. JQSRT 2016]</a> web server, using a range of partition sums and spectral line parameters. A significant feature of HAPI was the ability to calculate absorption coefficients based on the line-by-line spectroscopic parameters. For a more detailed description of this software library, we refer readers to the dedicated paper and corresponding user manual available online <a href="https://hitran.org/hapi">(https://hitran.org/hapi)</a>.<br><br> Although the first generation of HAPI allows users to build new functions, it does not have the functionality to make use the whole range of spectroscopic data currently available in the HITRAN database. For instance, the first version of the REST-API used by HAPI only allowed line-by-line data to be downloaded.<br> For this eason, an extended version of HAPI (with greater functionality) is provided as part of HITRAN2020 database (<a href="https://doi.org/10.1016/j.jqsrt.2021.107949">Gordon et al. JQSRT 2022</a>, <a href="https://hitran.org">https://hitran.org</a>). This extended version, named “HAPI2”, includes all the functionality of HAPI but with a new Python library and has been designed to be backward-compatible. To take advantage of the more advanced features in the “second generation” extension library, users will be required to upgrade to HAPI2.<br><br> One main feature of HAPI2 will be the ability to consider more objects available for downloading. This essentially means users will now be able to access the vast library of absorption cross sections, CIA, and more. This was achieved by revisiting the HITRAN server’s REST API. A new version is able to access the information for a number of entities available in HITRAN. Among these entities are molecule information, reference sources, line-byline transitions, monomer and collision-induced absorption crosssections, and metadata on line parameters. <br><br> Secondly, for applications that require numerous transitions to be considered in absorption coefficient calculations (such as at high-temperatures), the speed of calculation is of paramount importance. Although the first generation of HAPI contained some Numpy-based optimizations, it lacked the means for fast cross-section computation. In HAPI2, efficient coding for HT and SDV profiles that makes use of the “Just-in-time” compilation approach, has provided a significant speed increase for the spectral simulation.</br><br> HAPI2 local database structure relies on the SQLAlchemy (<a href="https://www.sqlalchemy.org/">https://www.sqlalchemy.org/</a>) interface to a number of the relational database management systems (RDBMS) which permit high-throughput analytics on a large number of spectral transitions. SQLALchemy provides object-relational mapping for main parts of HITRAN.<br><br> Last, but not least, HAPI2 has the modular structure, making it relatively easy to add custom plugins with new functional (e.g. adding new LBL calculation plugins, new SQLAlchemy backends etc...)

<h1>Installation</h1> <h2>Pulling from Github</h2> <ol> <li>git clone https://github.com/hitranonline/hapi2.git</li> <li>cd hapi2</li> <li>pip install .</li> </ol> <h2>From Python Package index</h2>

<em>To be done</em>

<h2>From Docker Hub</h2>

<em>To be done</em>

<h1>Quick start tutorial</h1>

<em>This is a short tutorial on how to use basic functions of the HAPI2 library. More advanced tutorials will be added in the future.</em><br>

Firts, lets do some imports.

import json
from getpass import getpass

%matplotlib notebook

import pylab as pl
import matplotlib as mpl

from hapi2 import *

HAPI2 version:  0.1
Updated SETTINGS_DEFAULT by local config file (C:\work\Activities\HAPI\HAPI2\git-repo\hapi2-all\hapi2\showcase\config.json).
Database name: local
Database engine: sqlite
Database path: ./
Web API TODO: include fetch_info() into init
jeanny, Ver.3.0

<h2>Getting the API key</h2>

Most HAPI2 main features are controllable through the config JSON file named "config.json". To work properly, this file should always be in the current working directory. The settings include information about the local database, debugging flags, REST API settings, and the API key.

with open('config.json') as f:
    print(f.read())

{
   "engine": "sqlite",
   "database": "local",
   "user": "root",
   "pass": null,
   "database_dir": "./",
   "echo": false,
   "debug": false,
   "display_fetch_url": false,
   "proxy": null,
   "host": "https://hitran.org",
   "api_version": "v2",
   "tmpdir": "~tmp",
   "api_key": ""
}

Unlike the previous version of the HITRAN API, the second generation of the API demands registration at the HITRANonline web site in order to get the API key.<br> The API key is essential for HAPI2 to connect to the HITRANonline web site and retrieve the data. This key
permits accessing the new functions of the HITRAN API v2 such as fetching the molecules, sources, cross-sections etc.<br> It can be obtained from the HITRANonline user profile web page: <a href="https://hitran.org/profile/">https://hitran.org/profile/</a>.<br> To be able to go through the rest of this tutorial, go to the link above and paste your API key to the form below.

SETTINGS['api_key'] = getpass('Enter valid API key:')
fetch_info()

Enter valid API key:········

Header for info is fetched from https://hitran.org

BEGIN DOWNLOAD: info
  1048576 bytes written to ~tmp\af306ba0-adcd-4ea1-8430-1e7b1aa2d84f.json
END DOWNLOAD
PROCESSED





{'status': 'OK',
 'message': '',
 'content': {'class': 'Info',
  'format': 'json',
  'data': {'static_root': 'data',
   'xsec_dir': 'data/xsec',
   'results_dir': 'results',
   'hapi_latest_version': None}},
 'timestamp': '2022-06-08 15:45:58.400858',
 'source': 'HITRANonline'}

To simplify the authentication process, one can store the API key in the config.json configuration file.<br><br>

<b><em>Please note, that user should keep the API key private. To regenerate the compromised API key, go to the HITRANonline <a href="https://hitran.org/profile/">user profile</a> page and press the "Generate API key" button.</em></b><br><br>

Now, lets download some molecular data necessary for the tutorial.

<h2>Molecules</h2>

New version of the HITRAN API permits user downloading the infomation not only on spectral lines, but also on molecules, isotopic species, publications, experimental cross-sections, partition sums, and collisiotn induced absorption. Each such entity corresponds to the partiucular section of the API schema.<br> Fetching such objects is done using the "fetch" functions of the API. Let's fetch the informations on the molecules in the current version of the HITRAN database. HAPI2 will automatically create the Python objects for each of the molecules, and save them to the local database.

mols = fetch_molecules() # fetch molecules

Header for molecules is fetched from https://hitran.org

BEGIN DOWNLOAD: molecules
  1048576 bytes written to ~tmp\c10d4283-b2ce-4c71-bdaa-619a042aada8.json
END DOWNLOAD
PROCESSED

By default, all data is passed in the JSON format. To discover the fields of the JSON records, use the ".dump()" method:

Molecule('Water').dump()

{'id': 1,
 'common_name': 'Water',
 'ordinary_formula': 'H2O',
 'ordinary_formula_html': 'H<sub>2</sub>O',
 'stoichiometric_formula': 'H2O',
 'inchi': 'InChI=1S/H2O/h1H2',
 'inchikey': 'XLYOFNOQVPJJNP-UHFFFAOYSA-N',
 '__class__': 'Molecule',
 '__identity__': 'common_name'}

Each of the fields can be accessed directly as a Python object attribute:

mol = Molecule('Water')
print(mol.common_name, mol.ordinary_formula)

Water H2O

To search for the molecule in the local database, use one of its names (or "aliases"). To see, which aliases are attached to the current molecule, use the ".aliases" attribute:

Molecule('Water').aliases

[7732-18-5,
 water vapor,
 Distilled water,
 XLYOFNOQVPJJNP-UHFFFAOYSA-N,
 NSC 147337,
 R-718,
 InChI=1S/H2O/h1H2,
 Dihydrogen monoxide,
 Dihydrogen oxide,
 HITRAN-mol-1,
 H2O,
 Water,
 R718,
 R 718,
 Hydrogen oxide (H2O)]

Using any of the aliases given above, you can find the very same molecule. For example, we will use the InChIKey this time to find the Water molecule:

Molecule('XLYOFNOQVPJJNP-UHFFFAOYSA-N') is Molecule('Water')

True

This greatly simplifies the molecule search in the local database. Also note, that the case doesn't matter:

Molecule('water') is Molecule('Water')

True

<h2>Isotopologues</h2>

Each molecule has a number of isotopic species, which can also be fetched from the HITRAN web site. In order to do thatm oe should already have the molecules fetched. Lets download all isotopologues for the Water molecule.

# Fetch isotopologues for Water molecula. 
isos = fetch_isotopologues([
    Molecule('Water'),
])
`