========================
line racer documentation
========================

Welcome to the **line racer** documentation. line racer is a Python package designed to compute high-resolution opacities from molecular (and in the future atomic) line lists.

Key features
____________
- Combines two line profile calculation methods to achieve both high accuracy and speed
    1. A direct calculation method using the Humlíček algorithm (`Humlíček, 1982 <https://www.sciencedirect.com/science/article/pii/0022407382900784?via%3Dihub>`_) and a speedup for calculating the line wings based on `Mollière et al. (2015) <https://iopscience.iop.org/article/10.1088/0004-637X/813/1/47>`_ to calculate the lines with the most intensity.
    2. A sampling technique of the line profiles based on `Min (2017) <https://www.aanda.org/articles/aa/pdf/2017/11/aa31612-17.pdf>`_ for an ultra fast calculation of the lower intensity lines.
- Fast installation via `pip <https://pypi.org/project/line-racer/>`_ and easy setup to test the calculation or to compute opacities on your own machine.
- Highly parallelized line opacity calculations using `MPI <https://mpi-forum.org/>`_ via `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ to efficiently calculate very large line lists on clusters (also across nodes).
- Opacities are returned as a function of wavelength, pressure, and temperature. The output can also be returned in pRT format, used by the petitRADTRANS code (`Mollière et al., 2019, <https://www.aanda.org/articles/aa/full_html/2019/07/aa35470-19/aa35470-19.html>`_ `Blain et al., 2024 <https://joss.theoj.org/papers/10.21105/joss.07028.pdf>`_).
- Support for ExoMol and HITRAN/HITEMP line lists. ExoAtom, VALD and Kurucz support to be implemented soon.
- Flexible line cutoff and sub-Lorentzian treatment for the wings of the line profiles.

**To get started with some examples on how to run line racer, see our** `line racer tutorial <content/notebooks/line_racer_notebook_example.html>`_.
**Before that, make sure you download the line lists and other required data correctly as described in the** `downloading line list tutorial <content/downloading_line_list_data.html>`_.
**If you want to run line racer on a cluster, have a look at the** `cluster calculation tutorial <content/line_racer_on_cluster.html>`_.

**If you are interested in how the line calculations are performed in detail, check out the** `physical and computational background of the line profile calculation in line racer <content/line_calculation_explanation.html>`_.

License and how to cite
_______________________

line racer is available under the MIT License

Please cite `Hägele & Mollière (2025) <https://ui.adsabs.harvard.edu/abs/2025JOSS...stillinprep/abstract>`_ when making use of line racer in your research.
In addition to the short `JOSS <https://joss.theoj.org/>`_ paper, a more detailed explanation of the background and methods, as well as comparison to other codes can be found `here <https://keeper.mpdl.mpg.de/f/bf0488acf85e4d2a82b3/>`_ in the master's thesis of David Hägele.

This documentation webpage contains an `installation guide <content/installation.html>`_, a
`general tutorial <content/notebooks/line_racer_notebook_example.html>`_, a `tutorial to run on clusters <content/line_racer_on_cluster.html>`_ , a `explanation of the physical background <content/line_calculation_explanation.html>`_, `community guidelines for contributions  <content/contributing.html>`_, and an `API documentation <autoapi/index.html>`_.

Developers
__________

- David Hägele

.. _contact: haegele@mpia.de


Contributors
____________

- Paul Mollière


.. toctree::
   :maxdepth: 3
   :caption: Content:

   content/installation
   content/downloading_line_list_data
   content/notebooks/line_racer_notebook_example
   content/line_racer_on_cluster
   content/line_calculation_explanation
   content/contributing

.. toctree::
   :maxdepth: 2
   :caption: Code documentation