1. Working with HITRAN database using HAPI: HITRAN Application Programming Interface
Roman V. Kochanova,c, Christian Hilla,b, Piotr Wcisloa,d,
Jonas S. Wilzewskie, Iouli E. Gordona, and Laurence S. Rothmana
aHarvard-Smithsonian Center for Astrophysics, Cambridge MA, USA
bUniversity College London, London, UK
cTomsk State University, Tomsk, RUSSIA
dNicolas Copernicus University, Torun, POLAND
eHarvard University, Astronomy Dept, Cambridge MA, USA

2. Introduction What is API?
API, an abbreviation of Application Programming Interface, is a set of routines, protocols, and tools for building software applications. The API specifies how software components should interact and be used in a program code.
A good API makes it easier to develop a program by providing all the building blocks. A programmer then puts the blocks together.
What is HITRAN API (HAPI)?
Python module (library of functions) to work with HITRAN data
Main purpose: extending user's code by the data of HITRAN and functionality of HITRANonline
Offline part of HITRANonline functionality

3. Why is API a powerful tool for creating radiative-transfer codes?
Seamless data format conversion
Parsing data (cross-sections, line-by-line, parameters)
“in a background”
Flexibility
Large number of input parameters to control calculation
Possibility to add custom user code
Possibility to use different line parameters and compare results
Portability
Access to external libraries
Python, Fortran, C++ ...

4. What is HAPI for?
Retrieve and use of HITRANonline data (line lists, cross sections, molecule and isotopologue info...) from a program written in Python (HITRANonline data is parsed automatically)
Reduce the load of HITRANonline web service (calculation of cross sections can be resource-demanding!)
Give more flexibility in data filtering (as in RDB)
Provide a possibility to work with HITRAN data “offline” (locally)

5. Prerequisites 1) Python 2.6+: https://www.python.org/
2) Numpy:
License: open source
=> Scientific Python distribution (“Sage”, “Anaconda” or any other similar distribution)

6. Download http://hitran.org/hapi + Python code + User guide
Zenodo community (DOI for referencing):

7. How to use HAPI? Ways of usage: In interactive Python shell
In a program (script) as a normal library
Jupyter/IPython

8. How to use HAPI? Ways of usage: Where to use?
In interactive Python shell
In a program (script) as a normal library
Jupyter/IPython
Where to use?
Local machine
Remote server (cluster, ssh access)
Cloud service (Wakari, PythonAnywhere, etc…)

9. HAPI architecture Python API LOCAL USER PLAIN TEXT DATABASE XML
HDF5
DATABASE
LOCAL

10. HAPI architecture Python API API functions:
USER
PLAIN TEXT
DATABASE
XML
DATABASE
HDF5
DATABASE
API functions:
→ absorptionCoefficient_HT(…)
→ partitionSum(…)
→ select(…)
→ describeTable ( … )
→ …
LOCAL

11. HITRANonline HAPI architecture Python API API functions:
QUERY
USER
PLAIN TEXT
DATABASE
HITRANonline
XML
DATABASE
HDF5
DATABASE
API functions:
→ absorptionCoefficient_HT(…)
→ partitionSum(…)
→ select(…)
→ describeTable ( … )
→ …
LOCAL
REMOTE

12. (PLAIN TEXT, BINARY, HDF5, ...)
HAPI architecture
Python
API
QUERY
USER
DATA
TRANSPORT FORMAT
(PLAIN TEXT, BINARY, HDF5, ...)
PLAIN TEXT
DATABASE
HITRANonline
XML
DATABASE
HDF5
DATABASE
API functions:
→ absorptionCoefficient_HT(…)
→ partitionSum(…)
→ select(…)
→ describeTable ( … )
→ …
LOCAL
REMOTE

13. Features (1) Fetching data (HITRANonline => local machine)
Filtering and processing the data in SQL-like fashion
Access to conventional Python structures (lists, tuples, dictionaries) for representing spectroscopic data.
Accounting for “non-standard” HITRAN parameters: speed dependence, Dicke narrowing, different broadeners etc…

14. Features (2)
Total internal partition sum (TIPS-2011): R. Gamache et al. Icarus 215 (2011) 391–400
Included information about 51 isotopologues
K temperature range
pCqSDHC line profile: Ngo et al. JQSRT 129 (2013) 89–100 (“Partially Correlated Quadratic Speed dependent Hard Collision Profile”)
a.k.a. Hartmann-Tran profile (HTP)
Can be reduced to VP, RP, qSDVP, qSDRP
Codes are rewritten in Python using Numpy library (fast array operations)

15. Features (3)
High-resolution spectra simulation accounting for pressure, temperature and optical path length. The following spectral functions can be calculated:
absorption coefficient
absorption spectrum
transmittance spectrum
radiance spectrum
Spectral calculation using a number of instrumental functions to simulate experimental spectra.
Possibility to extend the API's functionality by adding custom line profiles, partition sums and instrumental functions.

16. Features (4)
Embedded documentation (getHelp)

17. Data manipulation Similar to SQL (for single table queries)
Spectroscopic parameters are stored in tables
Display data (~ SQL’s select)
Apply filtering conditions (accounting wide range of expressions on parameters, including regexps)
Adding/removing custom parameters
Group by parameter/expression

18. Ipython: Cross section showcase
Download data M I
Range

19. Ipython: Cross section showcase
Filter data

20. Ipython: Cross section showcase
Cross-section calculation

21. Ipython: Cross section showcase
Plotting result

22. Comment on “Radiative forcings for 28 potential Archean greenhouse gases” Clim. Past 10, 1779 (2014)

23. Comment on “Radiative forcings for 28 potential Archean greenhouse gases” Clim. Past 10, 1779 (2014)

24. Plans More data formats (XML, JSON, NetCDF …)
More profiles (soft collisions, line mixing)
New data storage format (less bulky, more efficient)
Update partition sums (TIPS-2013)
Add functions for dealing with HITRAN’s collision-induced absorption cross-sections

25. Acknowledgements Iouli Gordon, Laurence Rothman, Christian Hill,
CfA HITRAN team:
Iouli Gordon, Laurence Rothman, Christian Hill,
Jonas Wilzewski, Piotr Wcisło
NASA Grants: PASCAL, AURA

26. Newsletter, bug reports, feedback …
It’s still work in progress!
Please ask your questions
Report bugs
… and thanks for your attention!