pyreactlab-core 0.1.8__tar.gz → 0.1.9__tar.gz

{pyreactlab_core-0.1.8 → pyreactlab_core-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyreactlab-core
-Version: 0.1.8
+Version: 0.1.9
 Summary: pyreactlab-core is the core foundation of the PyReactLab ecosystem, offering shared data structures and algorithms for chemical reaction representation, stoichiometry, and reaction analysis.
 Author-email: Sina Gilassi <sina.gilassi@gmail.com>
 License-Expression: Apache-2.0

{pyreactlab_core-0.1.8 → pyreactlab_core-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyreactlab-core"
-version = "0.1.8"
+version = "0.1.9"
 description = "pyreactlab-core is the core foundation of the PyReactLab ecosystem, offering shared data structures and algorithms for chemical reaction representation, stoichiometry, and reaction analysis."
 readme = "README.md"
 requires-python = ">=3.11"

{pyreactlab_core-0.1.8 → pyreactlab_core-0.1.9}/pyreactlab_core/configs/info.py

@@ -1,5 +1,5 @@
 # version
-__version__ = "0.1.8"
+__version__ = "0.1.9"
 # author
 __author__ = "Sina Gilassi"
 # email

pyreactlab_core-0.1.9/pyreactlab_core/core/__init__.py

@@ -0,0 +1,23 @@
+
+# NOTE: chem react
+from .chem_react import (
+    ReactionMode,
+    PhaseRule,
+    Reactant,
+    Product,
+    ChemReact
+)
+from .chem_react_utils import ChemReactUtils
+from .reaction_component_mapper import ReactionComponentMapper
+from .reaction_network_analysis import ReactionNetworkAnalysis
+
+__all__ = [
+    "ReactionMode",
+    "PhaseRule",
+    "Reactant",
+    "Product",
+    "ChemReact",
+    "ChemReactUtils",
+    "ReactionComponentMapper",
+    "ReactionNetworkAnalysis",
+]

pyreactlab_core-0.1.9/pyreactlab_core/core/chem_react.py

@@ -0,0 +1,420 @@
+# import libs
+import logging
+import re
+from typing import Dict, Any, List, Optional, Literal, TypedDict
+from pythermodb_settings.models import Component, ComponentKey
+# locals
+from ..configs.constants import (
+    R_CONST_J__molK,
+    PRESSURE_REF_Pa,
+    TEMPERATURE_REF_K,
+)
+from .chem_react_utils import ChemReactUtils
+from .reaction_component_mapper import ReactionComponentMapper
+from .reaction_network_analysis import ReactionNetworkAnalysis
+
+
+# NOTE: logger
+logger = logging.getLogger(__name__)
+
+# NOTE: Reaction Mode
+ReactionMode = Literal["<=>", "=>", "="]
+
+# NOTE: Phase Rule
+PhaseRule = Literal["gas", "liquid", "aqueous", "solid"]
+
+# SECTION: Models
+# NOTE: reactants
+
+
+class Reactant(TypedDict):
+    coefficient: float
+    molecule: str
+    state: str
+    molecule_state: str
+
+
+class Product(TypedDict):
+    coefficient: float
+    molecule: str
+    state: str
+    molecule_state: str
+
+
+# SECTION: ChemReact class
+class ChemReact(
+    ChemReactUtils,
+    ReactionComponentMapper,
+    ReactionNetworkAnalysis,
+):
+    """
+    Chemical Reaction Utilities
+
+    The ChemReact class provides utilities for analyzing and processing chemical reactions in various phases and conditions. These reactions can be represented in different ways depending on the dominant factors influencing them:
+
+    - Use = → when thermodynamics dominates
+    - Use <=> → when kinetics + thermodynamics matter
+    - Use => → when kinetics only matter
+    - The class supports reactions involving components in gas, liquid, aqueous, and solid phases.
+    - It includes methods for analyzing reactions, counting carbon atoms, determining reaction phases, and more.
+    """
+    # # NOTE: variables
+    # system inputs
+    _system_inputs = None
+    # universal gas constant [J/mol.K]
+    R = R_CONST_J__molK
+    # temperature [K]
+    T_Ref = TEMPERATURE_REF_K
+    # pressure [bar]
+    P_Ref = PRESSURE_REF_Pa/1e5
+
+    # available phases
+    available_phases = PhaseRule.__args__
+
+    # NOTE: id separator
+    # ! used to separate component name and state
+    _id_separator: str = '-'
+
+    # NOTE: component checker
+    _component_checker: bool = False
+
+    # NOTE: stoichiometry source
+    _stoichiometry_source: dict[str, Any] = {}
+
+    def __init__(
+        self,
+        reaction_mode_symbol: ReactionMode,
+        components: Optional[List[Component]],
+        component_keys: Optional[List[ComponentKey]] = None
+    ):
+        """
+        Initialize the ChemReactUtils class.
+
+        Parameters
+        ----------
+        reaction_mode_symbol : ReactionMode, optional
+            The symbol used to separate reactants and products in a reaction equation.
+        components : Optional[List[Component]]
+            A list of Component objects involved in the reaction.
+        component_keys : List[ComponentKey], optional
+            The key used to identify components in the reaction.
+
+        Notes
+        -----
+        - Use "<=>" when kinetics + thermodynamics matter
+        - Use "=" when thermodynamics dominates
+        - Use "=>" when kinetics only matter
+        - If components is None, component IDs will be an empty list.
+        - Component IDs are generated by combining the formula and state of each component, separated by a hyphen such as "H2O-l" for liquid water.
+        """
+        # SECTION: parent class initialization
+        # NOTE: initialize general reaction utility settings
+        ChemReactUtils.__init__(
+            self,
+            available_phases=PhaseRule.__args__,
+        )
+
+        # NOTE: set reaction mode symbol used by this reaction parser
+        self.reaction_mode_symbol = reaction_mode_symbol
+
+        # NOTE: initialize component mapping settings
+        ReactionComponentMapper.__init__(
+            self,
+            components=components,
+            component_keys=component_keys,
+            id_separator=self._id_separator,
+        )
+
+    @property
+    def system_inputs(self) -> Dict[str, Any]:
+        """Get the system inputs."""
+        # check
+        if self._system_inputs is None:
+            raise ValueError("System inputs are not set.")
+        return self._system_inputs
+
+    @property
+    def stoichiometry_source(self) -> Dict[str, Any]:
+        """Get the stoichiometry source."""
+        # res
+        return self._stoichiometry_source
+
+    def analyze_reaction(
+            self,
+            reaction_pack: Dict[str, str],
+            phase_rule: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Analyze a chemical reaction and extract relevant information.
+
+        Parameters
+        ----------
+        reaction_pack : dict
+            A dictionary containing the reaction and its name.
+        phase_rule : str, optional
+            The phase of the reaction, which can be 'gas', 'liquid', 'aqueous', or 'solid'.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the analyzed reaction data, including reactants,
+            products, reaction coefficient, and carbon count.
+        """
+        try:
+            # NOTE: check reaction_pack
+            if not isinstance(reaction_pack, dict):
+                raise ValueError("reaction_pack must be a dictionary.")
+
+            if 'reaction' not in reaction_pack or 'name' not in reaction_pack:
+                raise ValueError(
+                    "reaction_pack must contain 'reaction' and 'name' keys.")
+
+            # NOTE: check phase
+            # set phase
+            phase_set = self.phase_rule_analysis(phase_rule)
+
+            # SECTION: extract data from reaction
+            reaction = reaction_pack['reaction']
+            name = reaction_pack['name']
+
+            # ! Split the reaction into left and right sides
+            sides = reaction.split(self.reaction_mode_symbol.strip())
+
+            # Define a regex pattern to match reactants/products
+            # pattern = r'(\d*)?(\w+)\((\w)\)'
+            # pattern = r'(\d*\.?\d+)?(\w+)\((\w)\)'
+            # pattern = r'(?:(\d*\.?\d+)\s*)?([A-Z][a-zA-Z0-9]*)\s*(?:\((\w)\))?'
+            # NOTE: multi-purpose pattern
+            pattern = r'(?:(\d*\.?\d+)\s*)?(e(?:\{-?1?\}|[+-])?|\[[^\]\s]+\](?:\d+)?(?:\{[^{}\s]+\})?|(?:(?:\((?!(?:g|l|s|aq)\))[A-Za-z0-9]+\)\d*)*[A-Z][A-Za-z0-9]*(?:\((?!(?:g|l|s|aq)\))[A-Za-z0-9]+\)\d*)*)(?:[·*](?:\d+)?(?:(?:\((?!(?:g|l|s|aq)\))[A-Za-z0-9]+\)\d*)*[A-Z][A-Za-z0-9]*(?:\((?!(?:g|l|s|aq)\))[A-Za-z0-9]+\)\d*)*))*(?:\{[^{}\s]+\})?)\s*(?:\((g|l|s|aq)\))?'
+
+            # SECTION: SECTION: Extract reactants and products
+            # Extract reactants
+            reactants_raw = re.findall(pattern, sides[0])
+            reactants: List[Reactant] = [
+                {
+                    'coefficient': float(r[0]) if r[0] else float(1),
+                    'molecule': r[1],
+                    'state': r[2] if r[2] else phase_set,
+                    'molecule_state': ''
+                } for r in reactants_raw
+            ]
+
+            # NOTE: reactants full name
+            reactants_names = []
+            # loop over reactants
+            for i, item in enumerate(reactants):
+                # ! check phase_set and phase_rule
+                if phase_rule is None:
+                    # check item state
+                    if item['state'] == 'empty':
+                        raise ValueError(
+                            f"Phase rule is empty but reactant '{item['molecule']}' has state '{item['state']}'.")
+                else:
+                    # check item state
+                    if item['state'] != phase_set:
+                        raise ValueError(
+                            f"Phase rule is '{phase_set}' but reactant '{item['molecule']}' has state '{item['state']}'.")
+
+                # generate full name
+                full_name = item['molecule'] + "-" + item['state']
+                # append to list
+                reactants_names.append(full_name)
+                # update source
+                reactants[i]['molecule_state'] = full_name
+
+            # Extract products
+            products_raw = re.findall(pattern, sides[1])
+            products: List[Product] = [
+                {
+                    'coefficient': float(p[0]) if p[0] else float(1),
+                    'molecule': p[1],
+                    'state': p[2] if p[2] else phase_set,
+                    'molecule_state': ''
+                } for p in products_raw
+            ]
+
+            # NOTE: products full name
+            products_names = []
+            # loop over products
+            for i, item in enumerate(products):
+                # ! check phase_set and phase_rule
+                if phase_rule is None:
+                    # check item state
+                    if item['state'] == 'empty':
+                        raise ValueError(
+                            f"Phase rule is empty but product '{item['molecule']}' has state '{item['state']}'.")
+                else:
+                    # check item state
+                    if item['state'] != phase_set:
+                        raise ValueError(
+                            f"Phase rule is '{phase_set}' but product '{item['molecule']}' has state '{item['state']}'.")
+
+                # generate full name
+                full_name = item['molecule'] + "-" + item['state']
+                # append to list
+                products_names.append(full_name)
+                # update source
+                products[i]['molecule_state'] = full_name
+
+            # SECTION: all components
+            all_components = reactants_names + products_names
+            # >> remove duplicates
+            all_components: List[str] = list(set(all_components))
+
+            # SECTION: reaction coefficient and stoichiometry
+            reaction_coefficients = 0
+            reaction_stoichiometry = {}
+            reaction_stoichiometry_matrix = []
+
+            # iterate over reactants and products to calculate reaction coefficients
+            # NOTE: reactants
+            for item in reactants:
+                reaction_coefficients += item['coefficient']
+                reaction_stoichiometry[
+                    item['molecule_state']
+                ] = -1 * item['coefficient']
+                # append to stoichiometric matrix
+                reaction_stoichiometry_matrix.append(
+                    -1 * item['coefficient']
+                )
+
+            # NOTE: products
+            for item in products:
+                reaction_coefficients -= item['coefficient']
+                reaction_stoichiometry[
+                    item['molecule_state']
+                ] = item['coefficient']
+                # append to stoichiometric matrix
+                reaction_stoichiometry_matrix.append(
+                    item['coefficient']
+                )
+
+            # SECTION: Carbon count for each component
+            carbon_count = {}
+            for r in reactants:
+                carbon_count[r['molecule_state']] = self.count_carbon(
+                    r['molecule'],
+                    r['coefficient']
+                )
+            for p in products:
+                carbon_count[p['molecule_state']] = self.count_carbon(
+                    p['molecule'],
+                    p['coefficient']
+                )
+
+            # SECTION: reaction state
+            reaction_state = {}
+            for r in reactants:
+                # set
+                reaction_state[r['molecule_state']] = r['state']
+            for p in products:
+                # set
+                reaction_state[p['molecule_state']] = p['state']
+
+            # NOTE: reaction phase
+            # reaction
+            reaction_phase = self.determine_reaction_phase(
+                reaction_state
+            )
+
+            # NOTE: unique states
+            state_count = self.count_reaction_states(
+                reaction_state
+            )
+
+            # SECTION: Symbolic reaction without states
+            symbolic_reaction = ""
+            symbolic_unbalanced_reaction = ""
+
+            # reactants
+            for i, r in enumerate(reactants):
+                if i == 0:
+                    if r['coefficient'] == 1:
+                        symbolic_reaction += f"{r['molecule']}"
+                    else:
+                        symbolic_reaction += f"{r['coefficient']}{r['molecule']}"
+                    # unbalanced
+                    symbolic_unbalanced_reaction += f"{r['molecule']}"
+                else:
+                    if r['coefficient'] == 1:
+                        symbolic_reaction += f" + {r['molecule']}"
+                    else:
+                        symbolic_reaction += f" + {r['coefficient']}{r['molecule']}"
+                    # unbalanced
+                    symbolic_unbalanced_reaction += f" + {r['molecule']}"
+            # reaction mode symbol
+            symbolic_reaction += f" {self.reaction_mode_symbol} "
+            symbolic_unbalanced_reaction += f" {self.reaction_mode_symbol} "
+
+            # products
+            for i, p in enumerate(products):
+                if i == 0:
+                    if p['coefficient'] == 1:
+                        symbolic_reaction += f"{p['molecule']}"
+                    else:
+                        symbolic_reaction += f"{p['coefficient']}{p['molecule']}"
+                    # unbalanced
+                    symbolic_unbalanced_reaction += f"{p['molecule']}"
+                else:
+                    if p['coefficient'] == 1:
+                        symbolic_reaction += f" + {p['molecule']}"
+                    else:
+                        symbolic_reaction += f" + {p['coefficient']}{p['molecule']}"
+                    # unbalanced
+                    symbolic_unbalanced_reaction += f" + {p['molecule']}"
+
+            # SECTION: set id for each component
+            # NOTE: component ids
+            component_ids = {}
+            for i, r in enumerate(reactants):
+                component_ids[r['molecule_state']] = i+1
+            offset = len(reactants)
+            for i, p in enumerate(products):
+                component_ids[p['molecule_state']] = offset + i + 1
+
+            # SECTION: collect components
+            components = self.collect_components(
+                reactants,
+                products
+            )
+
+            # SECTION: map components
+            map_components = self.map_components(
+                reactants,
+                products,
+            )
+
+            # SECTION: build stoichiometry source
+            stoichiometry_source = self.build_stoichiometry_source(
+                reaction_stoichiometry=reaction_stoichiometry
+            )
+
+            # res
+            res = {
+                'name': name,
+                'reaction': reaction,
+                "component_ids": component_ids,
+                "all_components": all_components,
+                "symbolic_reaction": symbolic_reaction,
+                "symbolic_unbalanced_reaction": symbolic_unbalanced_reaction,
+                'reactants': reactants,
+                'reactants_names': reactants_names,
+                'products': products,
+                'products_names': products_names,
+                'reaction_coefficients': reaction_coefficients,
+                'reaction_stoichiometry': reaction_stoichiometry,
+                'reaction_stoichiometry_matrix': reaction_stoichiometry_matrix,
+                'reaction_stoichiometry_source': stoichiometry_source,
+                'carbon_count': carbon_count,
+                'reaction_state': reaction_state,
+                'reaction_phase': reaction_phase,
+                'state_count': state_count,
+                'components': components,
+                'map_components': map_components,
+                'component_checker': self._component_checker,
+            }
+
+            return res
+        except Exception as e:
+            raise Exception(f"Error analyzing reaction: {e}")
+

pyreactlab_core-0.1.9/pyreactlab_core/core/chem_react_utils.py

@@ -0,0 +1,149 @@
+# import libs
+import re
+from typing import Dict, List, Optional
+
+
+# SECTION: ChemReactUtils class
+class ChemReactUtils:
+    """General-purpose helpers for chemical reaction analysis."""
+
+    # NOTE: supported full phase names
+    available_phases = ("gas", "liquid", "aqueous", "solid")
+
+    def __init__(
+        self,
+        available_phases: tuple[str, ...] | None = None,
+    ):
+        """
+        Initialize general chemical reaction utility settings.
+        """
+        # SECTION: phase configuration
+        # NOTE: child classes can override the supported phase names
+        if available_phases is not None:
+            self.available_phases = available_phases
+
+    def count_carbon(self, molecule: str, coefficient: float) -> float:
+        """
+        Count the number of carbon atoms in a molecule.
+        """
+        try:
+            # SECTION: validate inputs
+            # NOTE: molecule formula must be text for regex parsing
+            if not isinstance(molecule, str):
+                raise ValueError("Molecule must be a string.")
+
+            # NOTE: coefficient scales the carbon count
+            if not isinstance(coefficient, (int, float)):
+                raise ValueError("Coefficient must be an integer or float.")
+
+            # SECTION: carbon symbol matching
+            # ! do not count lowercase carbon inside another element symbol
+            if re.search(r'C(?![a-z])', molecule):
+                # NOTE: multiply atom occurrences by stoichiometric coefficient
+                carbon_count = len(re.findall(
+                    r'C(?![a-z])', molecule)) * coefficient
+                return carbon_count
+            else:
+                # NOTE: molecule has no carbon atoms
+                return 0.0
+        except Exception as e:
+            raise Exception(
+                f"Error counting carbon in molecule '{molecule}': {e}")
+
+    def phase_rule_analysis(self, phase_rule: Optional[str] = None) -> str:
+        """
+        Analyze the phase rule of a reaction.
+        """
+        try:
+            # SECTION: default phase rule
+            # NOTE: empty means component states must be present in the reaction
+            if phase_rule is None or phase_rule == 'None':
+                return 'empty'
+
+            # SECTION: validate phase rule
+            # ? keep this aligned with PhaseRule in chem_react.py
+            if phase_rule not in self.available_phases:
+                raise ValueError(
+                    f"Phase rule must be {', '.join(self.available_phases)}.")
+
+            # SECTION: convert full phase name to reaction state symbol
+            if phase_rule == 'gas':
+                phase_symbol = 'g'
+            elif phase_rule == 'liquid':
+                phase_symbol = 'l'
+            elif phase_rule == 'aqueous':
+                phase_symbol = 'aq'
+            elif phase_rule == 'solid':
+                phase_symbol = 's'
+            else:
+                phase_symbol = 'empty'
+
+            # NOTE: return compact state symbol used by parsed components
+            return phase_symbol
+        except Exception as e:
+            raise Exception(f"Error analyzing phase rule: {e}")
+
+    def state_name_set(self, state_set: set) -> List[str]:
+        """
+        Convert state set to full names.
+        """
+        try:
+            # SECTION: state name mapping
+            # NOTE: keys match state symbols parsed from reaction strings
+            state_dict = {
+                'g': 'gas',
+                'l': 'liquid',
+                'aq': 'aqueous',
+                's': 'solid'
+            }
+
+            # NOTE: convert each compact symbol to its full phase name
+            return [state_dict[state] for state in state_set]
+        except Exception as e:
+            raise Exception(f"Error converting state set to full names: {e}")
+
+    def determine_reaction_phase(self, reaction_dict: Dict[str, str]) -> str:
+        """
+        Determine the phase of a reaction based on component states.
+        """
+        try:
+            # SECTION: collect unique states
+            available_states = set(reaction_dict.values())
+            # NOTE: convert state symbols before formatting phase text
+            state_names = self.state_name_set(available_states)
+
+            # SECTION: determine reaction phase label
+            if len(state_names) == 1:
+                # NOTE: single-phase reaction
+                return f'{state_names[0]}'
+            else:
+                # NOTE: multi-phase reaction
+                return f'{"-".join(state_names)}'
+        except Exception as e:
+            raise Exception(f"Error determining reaction phase: {e}")
+
+    def count_reaction_states(self, reaction_dict: Dict[str, str]) -> Dict[str, int]:
+        """
+        Count the number of component states in a reaction.
+        """
+        try:
+            # SECTION: collect component states
+            available_states = reaction_dict.values()
+            # NOTE: initialize all supported state buckets
+            state_count = {
+                'g': 0,
+                'l': 0,
+                'aq': 0,
+                's': 0
+            }
+
+            # SECTION: count state occurrences
+            for state in available_states:
+                # ! ignore unsupported states instead of adding new keys
+                if state in state_count:
+                    state_count[state] += 1
+
+            # NOTE: return counts for every supported state symbol
+            return state_count
+        except Exception as e:
+            raise Exception(f"Error determining reaction phase: {e}")