POSEIDON.chemistry
==================

.. py:module:: POSEIDON.chemistry

.. autoapi-nested-parse::

   Functions to interpolate chemical composition grids.



Functions
---------

.. autoapisummary::

   POSEIDON.chemistry.load_chemistry_grid
   POSEIDON.chemistry.interpolate_log_X_grid


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

.. py:function:: load_chemistry_grid(chemical_species, grid='fastchem', comm=MPI.COMM_WORLD, rank=0)

   Load a chemical abundance grid.

   :param chemical_species: List of chemical species to load mixing ratios from grid.
   :type chemical_species: list or np.array of str
   :param grid: Name of the pre-computed chemical abundance grid. The file should be
                located in the POSEIDON input directory (specified in your .bashrc
                file) with a name format like 'GRID_database.hdf5'
                (e.g. 'fastchem_database.hdf5'). By default, POSEIDON ships with
                an equilibrium chemistry grid computed from the fastchem code:
                https://github.com/exoclime/FastChem
                (Options: fastchem).
   :type grid: str
   :param comm: Communicator used to allocate shared memory on multiple cores.
   :type comm: MPI communicator
   :param rank: Rank used to allocate shared memory on multiple cores.
   :type rank: MPI rank

   :returns:     Dictionary containing the chemical abundance database.
   :rtype: chemistry_grid (dict)


.. py:function:: interpolate_log_X_grid(chemistry_grid, log_P, T, C_to_O, log_Met, chemical_species, return_dict=True)

   Interpolate a pre-computed grid of chemical abundances (e.g. an equilibrium
   chemistry grid) onto a model P-T profile, metallicity, and C/O ratio.

   :param chemistry_grid: Dictionary containing the chemical abundance database.
   :type chemistry_grid: dict
   :param log_P: Pressure profile provided by the user (in log scale and in bar).
                 A single value will be expanded into an array np.full(length, P),
                 where length == max(len(P_array), len(T_array), len(C_O), len(Met)).
                 10^{-7} to 10^{2} bar are supported.
   :type log_P: float or np.array of float
   :param T: Temperature profile provided by the user (K).
             A single value will be expanded into an array np.full(length, T),
             where length == max(len(P_array), len(T_array), len(C_O), len(Met)).
             300 to 4000 K are supported.
   :type T: float or np.array of float
   :param C_to_O: Carbon to Oxygen (C/O) ratio provided by the user.
                  A single value will be expanded into an array np.full(length, C_O),
                  where length == max(len(P_array), len(T_array), len(C_O), len(Met)).
                  0.2 to 2 are supported.
   :type C_to_O: float or np.array of float
   :param log_Met: Planetary metallicity (in log scale. 0 represents 1x solar).
                   A single value will be expanded into an array np.full(length, Met),
                   where length == max(len(P_array), len(T_array), len(C_O), len(Met)).
                   -1 to 4 are supported.
   :type log_Met: float or np.array of float
   :param chemical_species: List of chemical species to interpolate mixing ratios for.
   :type chemical_species: str or np.array of str
   :param return_dict: If False, return an array of shape (len(species), len(P_array)).
   :type return_dict: bool

   :returns:     A dictionary of log mixing ratios with keys being the same names as
                 specified in chemical_species.

             log_X_interp_array (np.array of float) ---> if return_dict=False:
                 An array containing the log mixing ratios for the species specified
                 in chemical_species.
   :rtype: log_X_interp_dict (dict) ---> if return_dict = True