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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyreactlab-core
-Version: 0.1.8
+Version: 0.2.0
 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.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyreactlab-core"
-version = "0.1.8"
+version = "0.2.0"
 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.2.0}/pyreactlab_core/__init__.py

@@ -1,4 +1,4 @@
-# config
+# NOTE: config
 from .configs.info import (
     __version__,
     __author__,
@@ -8,6 +8,13 @@ from .configs.info import (
     __license__,
 )
 
+# NOTE: configs
+from .configs.constants import (
+    REACTION_SYMBOLIC_MODES,
+    ReactionMode
+)
+
+# NOTE: app
 from .app import (
     rxn,
     rxn_stoichiometry_matrix,
@@ -23,6 +30,9 @@ __all__ = [
     "__description__",
     "__email__",
     "__license__",
+    # configs
+    "REACTION_SYMBOLIC_MODES",
+    "ReactionMode",
     # app
     "rxn",
     "rxn_stoichiometry_matrix",

pyreactlab_core-0.2.0/pyreactlab_core/configs/constants.py

@@ -0,0 +1,95 @@
+# import libs
+from __future__ import annotations
+from typing import Literal
+
+# SECTION: PyThermoDBLink/PyThermoDB
+import math
+DATASOURCE = "datasource"
+EQUATIONSOURCE = "equationsource"
+
+# NOTE: universal gas constant [J/mol.K]
+R_CONST_J__molK = 8.314472
+
+# NOTE: pi
+PI_CONST = math.pi
+
+# NOTE: STP condition
+# pressure [Pa]
+PRESSURE_STP_Pa = 101325
+# temperature [K]
+TEMPERATURE_STP_K = 273.15
+# reference pressure [Pa]
+PRESSURE_REF_Pa = 101325
+# reference temperature [K]
+TEMPERATURE_REF_K = 298.15
+
+# SECTION: Periodic Table Elements
+PERIODIC_TABLE_ELEMENTS = [
+    "H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne",
+    "Na", "Mg", "Al", "Si", "P", "S", "Cl", "Ar",
+    "K", "Ca", "Sc", "Ti", "V", "Cr", "Mn", "Fe", "Co", "Ni",
+    "Cu", "Zn", "Ga", "Ge", "As", "Se", "Br", "Kr",
+    "Rb", "Sr", "Y", "Zr", "Nb", "Mo", "Tc", "Ru", "Rh", "Pd",
+    "Ag", "Cd", "In", "Sn", "Sb", "Te", "I", "Xe",
+    "Cs", "Ba", "La", "Ce", "Pr", "Nd", "Pm", "Sm", "Eu", "Gd",
+    "Tb", "Dy", "Ho", "Er", "Tm", "Yb", "Lu",
+    "Hf", "Ta", "W", "Re", "Os", "Ir", "Pt",
+    "Au", "Hg", "Tl", "Pb", "Bi", "Po", "At", "Rn",
+    "Fr", "Ra", "Ac", "Th", "Pa", "U", "Np", "Pu",
+    "Am", "Cm", "Bk", "Cf", "Es", "Fm", "Md", "No", "Lr",
+    "Rf", "Db", "Sg", "Bh", "Hs", "Mt", "Ds", "Rg", "Cn",
+    "Nh", "Fl", "Mc", "Lv", "Ts", "Og",
+]
+
+# SECTION: Reaction
+REACTION_SYMBOLIC_MODES = {
+    # irreversible
+    "->":  ("irreversible", "forward"),
+    "=>":  ("irreversible", "forward"),
+    "→":   ("irreversible", "forward"),
+    "⇒":   ("irreversible", "forward"),
+
+    # backward irreversible
+    # ! not recommended for use in reaction expressions
+    "<-":  ("irreversible", "backward"),
+    "←":   ("irreversible", "backward"),
+
+    # reversible
+    "<=>": ("reversible", "forward"),
+    "<->": ("reversible", "forward"),
+    "⇌":   ("reversible", "forward"),
+    "↔":   ("reversible", "forward"),
+
+    # thermodynamic equilibrium
+    "=":   ("equilibrium", "forward"),
+}
+
+# NOTE: irreversible reaction mode symbols
+IRREVERSIBLE_REACTION_MODE_SYMBOLS = [
+    "->", "=>", "→", "⇒",
+    "<-", "←"
+]
+
+# NOTE: reversible reaction mode symbols
+REVERSIBLE_REACTION_MODE_SYMBOLS = [
+    "<=>", "<->", "⇌", "↔"
+]
+
+# NOTE: equilibrium reaction mode symbols
+EQUILIBRIUM_REACTION_MODE_SYMBOLS = [
+    "="
+]
+
+# NOTE: all reaction mode symbols
+ALL_REACTION_MODE_SYMBOLS = (
+    IRREVERSIBLE_REACTION_MODE_SYMBOLS +
+    REVERSIBLE_REACTION_MODE_SYMBOLS +
+    EQUILIBRIUM_REACTION_MODE_SYMBOLS
+)
+
+# NOTE: Reaction Mode
+ReactionMode = Literal["<=>", "=>", "="]
+# NOTE: Reaction Type
+ReactionType = Literal["irreversible", "reversible", "equilibrium"]
+# NOTE: Reaction Direction
+ReactionDirection = Literal["forward", "backward"]

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

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

pyreactlab_core-0.2.0/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.2.0/pyreactlab_core/core/chem_react.py

@@ -0,0 +1,421 @@
+# 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,
+    ReactionMode,
+)
+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: 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
+        # >> reaction type
+        self.reaction_type = self.get_reaction_type(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,
+                'reaction_mode_symbol': self.reaction_mode_symbol,
+                'reaction_type': self.reaction_type,
+                "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}")