Cthulhu.broadening
==================

.. py:module:: Cthulhu.broadening


Functions
---------

.. autoapisummary::

   Cthulhu.broadening.det_broad
   Cthulhu.broadening.write_broadening_file
   Cthulhu.broadening.create_SB07
   Cthulhu.broadening.read_H2_He
   Cthulhu.broadening.read_air
   Cthulhu.broadening.read_SB07
   Cthulhu.broadening.read_custom
   Cthulhu.broadening.gamma_L_VALD
   Cthulhu.broadening.gamma_L_impact
   Cthulhu.broadening.read_atom
   Cthulhu.broadening.compute_H2_He
   Cthulhu.broadening.compute_air
   Cthulhu.broadening.compute_SB07


Module Contents
---------------

.. py:function:: det_broad(input_directory)

   Determine the type of broadening that should be used in the case that the user specifies
   'default' broadening. Order of preference is: 1) H2-He, 2) air, 3) SB07

   :param input_directory: Local directory where the broadening file will be stored.
   :type input_directory: String

   :returns: **broadening** -- The type of broadening being used.
   :rtype: String


.. py:function:: write_broadening_file(broadening_file, data, input_dir, species, database, isotope='default', ionization_state=1, linelist='default')

   Write a custom broadening file to the input directory containing line list data.

   :param broadening_file: Name of the custom broadening file.
   :type broadening_file: String
   :param data: 3-d list or array containing the information (J, gamma_L_0, n_L) needed to create a broadening file.
   :type data: list
   :param input_dir: Local directory containing all line list data (for all species).
   :type input_dir: String
   :param species: Name of molecule or atom.
   :type species: String
   :param database: Database line list was downloaded from.
   :type database: String
   :param isotope: Isotopologue of the species, if a molecule. The default is `default`.
   :type isotope: String, optional
   :param ionization_state: Ionization state of the species, if an atom. The default is 1.
   :type ionization_state: int, optional
   :param linelist: Line list of the species. ExoMol has named line lists, the other databases do not. The default is `default`.
   :type linelist: String, optional

   :rtype: None.


.. py:function:: create_SB07(input_directory)

   Create a broadening file according to Eq. 15 of Sharp & Burrows (2007),
   and add it to the input_directory.

   Note: S&B (2007) state Eq. 15 gives the FWHM. Personal communication from
   Richard Freedman indicates the equation actually gives the HWHM.

   :param input_directory: Local directory where the broadening file will be stored.
   :type input_directory: String

   :rtype: None.


.. py:function:: read_H2_He(input_directory)

   Read the H2 and He broadening files from the input directory

   :param input_directory: Local directory where the broadening file is stored.
   :type input_directory: String

   :returns: * **J_max** (*float*) -- RYAN.
             * **gamma_0_H2** (*numpy array*) -- RYAN.
             * **n_L_H2** (*numpy array*) -- RYAN.
             * **gamma_0_He** (*numpy array*) -- RYAN.
             * **n_L_He** (*numpy array*) -- RYAN.


.. py:function:: read_air(input_directory)

   Read the air broadening file from the input directory

   :param input_directory: Local directory where the broadening file is stored.
   :type input_directory: String

   :returns: * **J_max** (*float*) -- RYAN.
             * **gamma_0_air** (*numpy array*) -- RYAN.
             * **n_L_air** (*numpy array*) -- RYAN.


.. py:function:: read_SB07(input_directory)

   Read the Burrows broadening file from the input directory

   :param input_directory: Local directory where the broadening file is stored.
   :type input_directory: String

   :returns: * **J_max** (*float*) -- RYAN.
             * **gamma_0_SB07** (*numpy array*) -- RYAN.


.. py:function:: read_custom(input_directory, broadening_file)

   Read a user-provided broadening file from the input directory

   :param input_directory: Local directory where the broadening file is stored.
   :type input_directory: String

   :returns: * **J_max** (*float*) -- RYAN.
             * **gamma_0_air** (*numpy array*) -- RYAN.
             * **n_L_air** (*numpy array*) -- RYAN.


.. py:function:: gamma_L_VALD(gamma_vdw, m_s, broadener)

   Computes Lorentzian HWHM at 296K and 1 bar for a given broadener from a
   tabulated VALD van der Waals broadening constant.

   :param gamma_vdw: Van der Waals parameter from VALD.
   :type gamma_vdw: float
   :param m_s: Mass of species whose spectral line is being broadened (u).
   :type m_s: float
   :param broadener: Identity of broadening species (H2 or He).
   :type broadener: String

   :returns: * **gamma_L_0** (*float*) -- Lorentzian HWHM at reference T (296K) and P (1 bar).
             * **n_L** (*float*) -- Temperature exponent (fixed to -0.7 for van der Waals theory).


.. py:function:: gamma_L_impact(E_low, E_up, l_low, l_up, species, m_s, broadener)

   Computes Lorentzian HWHM at 296K and 1 bar for a given broadener using
   van der Waals impact theory.

   :param E_low: Lower level energy (cm^-1).
   :type E_low: float
   :param E_up: Upper level energy (cm^-1).
   :type E_up: float
   :param l_low: Lower level orbital angular momentum.
   :type l_low: int
   :param l_up: Upper level orbital angular momentum.
   :type l_up: int
   :param species: Identity of species whose spectral line is being broadened.
   :type species: String
   :param m_s: Mass of species whose spectral line is being broadened (u).
   :type m_s: float
   :param broadener: Identity of broadening species (H2 or He).
   :type broadener: String

   :returns: * **gamma_L_0** (*float*) -- Lorentzian HWHM at reference T (296K) and P (1 bar).
             * **n_L** (*float*) -- Temperature exponent (fixed to -0.7 for van der Waals theory).


.. py:function:: read_atom(species, nu_0, gf, E_low, E_up, J_low, l_low, l_up, gamma_nat, gamma_vdw, alkali, m)

   RYAN

   :param species: Name of atomic species, i.e. 'H' for hydrogen.
   :type species: String
   :param nu_0: RYAN.
   :type nu_0: TYPE
   :param gf: RYAN.
   :type gf: TYPE
   :param E_low: RYAN.
   :type E_low: TYPE
   :param E_up: RYAN.
   :type E_up: TYPE
   :param J_low: RYAN.
   :type J_low: TYPE
   :param l_low: RYAN.
   :type l_low: TYPE
   :param l_up: RYAN.
   :type l_up: TYPE
   :param gamma_nat: RYAN.
   :type gamma_nat: TYPE
   :param gamma_vdw: RYAN.
   :type gamma_vdw: TYPE
   :param alkali: RYAN.
   :type alkali: TYPE
   :param m: RYAN.
   :type m: TYPE

   :returns: * **gamma_0_H2** (*TYPE*) -- DESCRIPTION.
             * **n_L_H2** (*TYPE*) -- DESCRIPTION.
             * **gamma_0_He** (*TYPE*) -- DESCRIPTION.
             * **n_L_He** (*TYPE*) -- DESCRIPTION.


.. py:function:: compute_H2_He(gamma_0_H2, T_ref, T, n_L_H2, P, P_ref, X_H2, gamma_0_He, n_L_He, X_He)

   DESCRIPTION - RYAN

   :param gamma_0_H2: RYAN.
   :type gamma_0_H2: TYPE
   :param T_ref: RYAN.
   :type T_ref: TYPE
   :param T: RYAN.
   :type T: TYPE
   :param n_L_H2: RYAN.
   :type n_L_H2: TYPE
   :param P: RYAN.
   :type P: TYPE
   :param P_ref: RYAN.
   :type P_ref: TYPE
   :param X_H2: RYAN.
   :type X_H2: TYPE
   :param gamma_0_He: RYAN.
   :type gamma_0_He: TYPE
   :param n_L_He: RYAN.
   :type n_L_He: TYPE
   :param X_He: RYAN.
   :type X_He: TYPE

   :returns: **gamma** -- RYAN.
   :rtype: TYPE


.. py:function:: compute_air(gamma_0_air, T_ref, T, n_L_air, P, P_ref)

   DESCRIPTION - RYAN

   :param gamma_0_air: RYAN.
   :type gamma_0_air: TYPE
   :param T_ref: RYAN.
   :type T_ref: TYPE
   :param T: RYAN.
   :type T: TYPE
   :param n_L_air: RYAN.
   :type n_L_air: TYPE
   :param P: RYAN.
   :type P: TYPE
   :param P_ref: RYAN.
   :type P_ref: TYPE

   :returns: **gamma** -- RYAN.
   :rtype: TYPE


.. py:function:: compute_SB07(gamma_0_SB07, P, P_ref)

   DESCRIPTION - RYAN

   :param gamma_0_SB07: RYAN.
   :type gamma_0_SB07: TYPE
   :param P: RYAN.
   :type P: TYPE
   :param P_ref: RYAN.
   :type P_ref: TYPE

   :returns: **gamma** -- RYAN.
   :rtype: TYPE