uclchem.makerates.heating
=========================

.. py:module:: uclchem.makerates.heating

.. autoapi-nested-parse::

   Heating and cooling calculations for UCLCHEM reactions.

   Provides functions to set reaction exothermicities from thermochemical
   databases or custom CSV files with various units.



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


Functions
~~~~~~~~~

.. autoapisummary::

   uclchem.makerates.heating.convert_to_erg
   uclchem.makerates.heating.load_custom_exothermicities
   uclchem.makerates.heating.match_reaction
   uclchem.makerates.heating.parse_species_from_row
   uclchem.makerates.heating.set_custom_exothermicities



Attributes
~~~~~~~~~~

.. autoapisummary::

   uclchem.makerates.heating.AVOGADRO_NUMBER
   uclchem.makerates.heating.CALORIE_TO_JOULE
   uclchem.makerates.heating.ERG_TO_ERG
   uclchem.makerates.heating.ERG_TO_JOULE
   uclchem.makerates.heating.EV_TO_ERG
   uclchem.makerates.heating.EV_TO_JOULE
   uclchem.makerates.heating.JOULE_TO_ERG
   uclchem.makerates.heating.KCAL_TO_ERG
   uclchem.makerates.heating.logger


.. py:function:: convert_to_erg(value: float, unit: str) -> float

   Convert exothermicity to erg per reaction.

   :param value: Exothermicity value
   :type value: float
   :param unit: Unit string (case-insensitive)
   :type unit: str

   :returns: Value in erg per reaction
   :rtype: float


.. py:function:: load_custom_exothermicities(csv_path: str | pathlib.Path) -> pandas.DataFrame

   Load custom exothermicities from CSV.

   Expected columns: reactant1-3, product1-4, exothermicity, unit

   :param csv_path: Path to CSV file
   :type csv_path: str | Path

   :returns: **df** -- DataFrame with custom exothermicities
   :rtype: pd.DataFrame

   :raises ValueError: If the csv is missing certain columns.


.. py:function:: match_reaction(reactants: list[str], products: list[str], reactions: list[uclchem.makerates.reaction.Reaction]) -> uclchem.makerates.reaction.Reaction | None

   Find matching reaction in list.

   :param reactants: List of reactant names
   :type reactants: list[str]
   :param products: List of product names
   :type products: list[str]
   :param reactions: List to search
   :type reactions: list[Reaction]

   :returns: Matching Reaction or None
   :rtype: Reaction | None


.. py:function:: parse_species_from_row(row: pandas.Series, prefix: str) -> list[str]

   Parse species list from CSV row.

   :param row: DataFrame row
   :type row: pd.Series
   :param prefix: 'reactant' or 'product'
   :type prefix: str

   :returns: List of species names (uppercase, NAN for missing)
   :rtype: list[str]


.. py:function:: set_custom_exothermicities(reactions: list[uclchem.makerates.reaction.Reaction], csv_path: str | pathlib.Path, overwrite: bool = True) -> tuple[int, int]

   Set reaction exothermicities from custom CSV.

   :param reactions: List of Reaction objects to modify
   :type reactions: list[Reaction]
   :param csv_path: Path to CSV with custom exothermicities
   :type csv_path: str | Path
   :param overwrite: If False, only set reactions with zero exothermicity.
                     Default = True.
   :type overwrite: bool

   :returns: * **matched** (*int*) -- number of matched reactions
             * **unmatched** (*int*) -- number of unmatched reactions


.. py:data:: AVOGADRO_NUMBER
   :value: 6.02214076e+23


.. py:data:: CALORIE_TO_JOULE
   :value: 4.184


.. py:data:: ERG_TO_ERG
   :value: 1.0


.. py:data:: ERG_TO_JOULE
   :value: 1e-07


.. py:data:: EV_TO_ERG
   :value: 1.602176634e-12


.. py:data:: EV_TO_JOULE
   :value: 1.602176634e-19


.. py:data:: JOULE_TO_ERG
   :value: 10000000.0


.. py:data:: KCAL_TO_ERG
   :value: 41840000000.0


.. py:data:: logger