pyROX.utils
===========

.. py:module:: pyROX.utils


Classes
-------

.. autoapisummary::

   pyROX.utils.Broaden_Gharib_Nezhad_ea_2021


Functions
---------

.. autoapisummary::

   pyROX.utils.download
   pyROX.utils.save_to_hdf5
   pyROX.utils.read_from_hdf5
   pyROX.utils.log10_round
   pyROX.utils.display_welcome_message
   pyROX.utils.display_finish_message
   pyROX.utils.update_config_with_args
   pyROX.utils.warn_about_units
   pyROX.utils.find_closest_indices
   pyROX.utils.fixed_resolution_wavelength_grid


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

.. py:function:: download(url, out_dir, out_name=None)

   Downloads a file from a URL if it does not already exist.

   :param url: URL of the file to download.
   :type url: str
   :param out_dir: Output directory.
   :type out_dir: str
   :param out_name: Output file name. Defaults to None.
   :type out_name: str, optional

   :returns: Path to the downloaded file.
   :rtype: str


.. py:function:: save_to_hdf5(file, data, attrs, compression='gzip', **kwargs)

   Saves data to an HDF5 file.

   :param file: Path to the output file.
   :type file: str
   :param data: Dictionary containing the data to save.
   :type data: dict
   :param attrs: Dictionary containing the attributes to save.
   :type attrs: dict
   :param compression: Compression type. Defaults to 'gzip'.
   :type compression: str, optional
   :param \*\*kwargs: Additional arguments for dataset creation.


.. py:function:: read_from_hdf5(file, keys_to_read, return_attrs=False)

   Reads data from an HDF5 file.

   :param file: Path to the input file.
   :type file: str
   :param keys_to_read: List of keys to read from the file.
   :type keys_to_read: list
   :param return_attrs: Whether to return attributes. Defaults to False.
   :type return_attrs: bool, optional

   :returns: Dictionary containing the data.
             dict (optional): Dictionary containing the attributes if return_attrs is True.
   :rtype: dict


.. py:function:: log10_round(array, decimals=3)

   Computes the base-10 logarithm of an array and rounds the result.

   :param array: Input array.
   :type array: array-like
   :param decimals: Number of decimal places to round to. Defaults to 3.
   :type decimals: int, optional

   :returns: Array with rounded base-10 logarithm values.
   :rtype: numpy.ndarray


.. py:function:: display_welcome_message()

   Displays a welcome message.

   :returns: Start time of the process.
   :rtype: float


.. py:function:: display_finish_message(time_start)

   Displays a finish message and the elapsed time.

   :param time_start: Start time of the process.
   :type time_start: float


.. py:function:: update_config_with_args(config=None, **kwargs)

   Updates the configuration object with command-line arguments.

   :param config: Configuration object to update. Defaults to None.
   :type config: object, optional
   :param \*\*kwargs: Keyword arguments representing the parameters to update.

   :returns: Updated configuration object.
   :rtype: object


.. py:function:: warn_about_units(config)

   Displays a warning message about expected units for specific parameters.

   :param config: Configuration object containing parameter definitions.
   :type config: object


.. py:function:: find_closest_indices(a, b)

   Finds the indices of the closest elements in arrays a and b.

   :param a: First array.
   :type a: array-like
   :param b: Second array.
   :type b: array-like

   :returns: Indices of the closest elements in a and b.
   :rtype: tuple


.. py:function:: fixed_resolution_wavelength_grid(wave_min, wave_max, resolution)

   Returns a fixed resolution wavelength grid.

   :param wave_min: Minimum wavelength.
   :type wave_min: float
   :param wave_max: Maximum wavelength.
   :type wave_max: float
   :param resolution: Desired resolution.
   :type resolution: float

   :returns: Wavelength grid.
   :rtype: numpy.ndarray


.. py:class:: Broaden_Gharib_Nezhad_ea_2021(species='AlH')

   Broadening parameterisation from Gharib-Nezhad et al. (2021).


   .. py:method:: _pade_equation(J, a, b)

      Computes the Pade approximation for the broadening coefficient.

      :param J: Rotational quantum number.
      :type J: float
      :param a: Coefficients for the numerator.
      :type a: array-like
      :param b: Coefficients for the denominator.
      :type b: array-like

      :returns: Broadening coefficient.
      :rtype: float



   .. py:method:: gamma_H2(J)

      Calculates the broadening coefficient for H2.

      :param J: Rotational quantum number.
      :type J: float

      :returns: Broadening coefficient.
      :rtype: float



   .. py:method:: gamma_He(J)

      Calculates the broadening coefficient for He.

      :param J: Rotational quantum number.
      :type J: float

      :returns: Broadening coefficient.
      :rtype: float