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

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

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

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

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

{pyreactlab_core-0.2.0 → pyreactlab_core-0.3.0}/pyreactlab_core/core/chem_react.py

@@ -13,31 +13,12 @@ from ..configs.constants import (
 from .chem_react_utils import ChemReactUtils
 from .reaction_component_mapper import ReactionComponentMapper
 from .reaction_network_analysis import ReactionNetworkAnalysis
+from ..models.reactions import Reactant, Product, PhaseRule
 
 
 # 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(
@@ -185,7 +166,15 @@ class ChemReact(
             # 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)\))?'
+            # 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)\))?'
+
+            # v2
+            pattern = r'(?:(\d*\.?\d+)\s*)?(e|[A-Z][A-Za-z0-9]*(?:\((?!(?:g|l|s|aq)\))[A-Za-z0-9]+\)\d*)*(?:[·*]\d*[A-Z][A-Za-z0-9]*(?:\((?!(?:g|l|s|aq)\))[A-Za-z0-9]+\)\d*)*)*)\s*(?:\{?((?:\d+)?[+-])\}?)?\s*(?:\((g|l|s|aq)\))?'
+            # ! parse as:
+            # 1. Optional coefficient (digits with optional decimal)
+            # 2. Molecule formula (starting with uppercase letter, followed by alphanumeric characters)
+            # 3. Optional charge (digits with optional sign)
+            # 4. Optional state (g, l, s, aq)
 
             # SECTION: SECTION: Extract reactants and products
             # Extract reactants
@@ -193,8 +182,9 @@ class ChemReact(
             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': self.parse_molecule(r[1], r[2]),
+                    'charge': self.parse_charge(r[2]),
+                    'state': r[3] if r[3] else phase_set,
                     'molecule_state': ''
                 } for r in reactants_raw
             ]
@@ -227,8 +217,9 @@ class ChemReact(
             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': self.parse_molecule(p[1], p[2]),
+                    'charge': self.parse_charge(p[2]),
+                    'state': p[3] if p[3] else phase_set,
                     'molecule_state': ''
                 } for p in products_raw
             ]
@@ -302,6 +293,18 @@ class ChemReact(
                     p['coefficient']
                 )
 
+            # NOTE total carbon count for reactants and products
+            total_carbon_count = self.count_total_carbon(
+                reactants=reactants,
+                products=products
+            )
+            # ? total reactant carbon count
+            total_reactant_carbon_count = total_carbon_count['total_reactant_carbon_count']
+            # ? total product carbon count
+            total_product_carbon_count = total_carbon_count['total_product_carbon_count']
+            # ? net carbon count
+            net_carbon_count = total_carbon_count['net_carbon_count']
+
             # SECTION: reaction state
             reaction_state = {}
             for r in reactants:
@@ -311,6 +314,33 @@ class ChemReact(
                 # set
                 reaction_state[p['molecule_state']] = p['state']
 
+            # SECTION: charge count for each component
+            charge_count = {}
+            for r in reactants:
+                charge_count[r['molecule_state']] = self.count_charge(
+                    r['molecule'],
+                    r['coefficient'],
+                    r['charge']
+                )
+            for p in products:
+                charge_count[p['molecule_state']] = self.count_charge(
+                    p['molecule'],
+                    p['coefficient'],
+                    p['charge']
+                )
+
+            # SECTION: total charge count for reactants and products
+            total_charge_count = self.count_total_charge(
+                reactants=reactants,
+                products=products
+            )
+            # ? total reactant charge
+            total_reactant_charge = total_charge_count['total_reactant_charge']
+            # ? total product charge
+            total_product_charge = total_charge_count['total_product_charge']
+            # ? net charge
+            net_charge = total_charge_count['net_charge']
+
             # NOTE: reaction phase
             # reaction
             reaction_phase = self.determine_reaction_phase(
@@ -408,9 +438,16 @@ class ChemReact(
                 'reaction_stoichiometry_matrix': reaction_stoichiometry_matrix,
                 'reaction_stoichiometry_source': stoichiometry_source,
                 'carbon_count': carbon_count,
+                'total_reactant_carbon_count': total_reactant_carbon_count,
+                'total_product_carbon_count': total_product_carbon_count,
+                'net_carbon_count': net_carbon_count,
                 'reaction_state': reaction_state,
                 'reaction_phase': reaction_phase,
                 'state_count': state_count,
+                'charge_count': charge_count,
+                'total_reactant_charge': total_reactant_charge,
+                'total_product_charge': total_product_charge,
+                'net_charge': net_charge,
                 'components': components,
                 'map_components': map_components,
                 'component_checker': self._component_checker,

pyreactlab_core-0.3.0/pyreactlab_core/core/chem_react_utils.py

@@ -0,0 +1,344 @@
+# import libs
+import re
+from typing import Dict, List, Optional, Any
+# locals
+from ..models.reactions import Reactant, Product
+
+
+# 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
+
+    # ! ::: parse molecule
+    def parse_molecule(
+        self,
+        id: str,
+        charge: Any
+    ) -> str:
+        """
+        Parse molecule Id and charge to a formatted string. Charge is optional and will be appended using {+} or {-} notation if provided.
+        """
+        try:
+            # SECTION: format molecule string
+            # NOTE: parse charge to ensure it is in the correct format
+            charge = self.parse_charge(charge)
+
+            # >> check if charge is non-zero, append it to the molecule Id
+            if charge == 1:
+                return f"{id}{{+}}"
+            elif charge == -1:
+                return f"{id}{{-}}"
+            elif charge > 0:
+                return f"{id}{{{charge}+}}"
+            elif charge < 0:
+                return f"{id}{{{abs(charge)}-}}"
+            elif charge == 0:
+                return id
+            else:
+                return id
+        except Exception as e:
+            raise Exception(
+                f"Error parsing molecule '{id}' with charge '{charge}': {e}"
+            )
+
+    # ! ::: count carbon
+    def count_carbon(self, molecule: str, coefficient: float) -> float:
+        """
+        Count the total number of carbon atoms in a molecule,
+        scaled by the stoichiometric coefficient.
+
+        Examples
+        --------
+        CO2        -> 1 carbon
+        C2H6       -> 2 carbons
+        CH3COOH    -> 2 carbons
+        CaCO3      -> 1 carbon
+        CuSO4      -> 0 carbon
+        C6H12O6    -> 6 carbons
+        """
+        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: find carbon atoms
+            # C(?![a-z]) ensures C is not part of Ca, Cu, Cl, Co, ...
+            # (\d*) captures an optional numeric subscript after C
+            matches = re.findall(r'C(?![a-z])(\d*)', molecule)
+
+            # SECTION: calculate carbon count
+            carbon_count = sum(
+                int(count) if count else 1
+                for count in matches
+            )
+
+            return carbon_count * coefficient
+        except Exception as e:
+            raise Exception(
+                f"Error counting carbon in molecule '{molecule}': {e}")
+
+    # ! ::: count total carbon
+    def count_total_carbon(
+        self,
+        reactants: List[Reactant],
+        products: List[Product]
+    ) -> Dict[str, float]:
+        """
+        Count the total number of carbon atoms in reactants and products.
+        """
+        try:
+            # SECTION: calculate total carbon for reactants
+            total_reactant_carbon = sum(
+                self.count_carbon(r['molecule'], r['coefficient'])
+                for r in reactants
+            )
+
+            # SECTION: calculate total carbon for products
+            total_product_carbon = sum(
+                self.count_carbon(p['molecule'], p['coefficient'])
+                for p in products
+            )
+
+            # NOTE: return total carbon counts as a dictionary
+            return {
+                'total_reactant_carbon_count': total_reactant_carbon,
+                'total_product_carbon_count': total_product_carbon,
+                'net_carbon_count': total_product_carbon - total_reactant_carbon
+            }
+        except Exception as e:
+            raise Exception(f"Error counting total carbon in reaction: {e}")
+
+    # ! :::phase rule analysis
+    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}")
+
+    # ! ::: state name set
+    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}")
+
+    # ! ::: determine reaction phase
+    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}")
+
+    # ! ::: count reaction states
+    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}")
+
+    # ! ::: reaction types
+    def get_reaction_type(self, reaction_mode_symbol: str) -> str:
+        """
+        Determine the type of reaction based on the reaction mode symbol.
+
+        Reaction Mode Symbols:
+        - `Reversible`: "<=>"
+        - `Irreversible`: "=>"
+        - `Equilibrium`: "="
+        """
+        try:
+            # SECTION: validate reaction mode symbol
+            if reaction_mode_symbol not in ("<=>", "=>", "="):
+                raise ValueError(
+                    f"Invalid reaction mode symbol: {reaction_mode_symbol}")
+
+            # SECTION: determine reaction type
+            if reaction_mode_symbol == "<=>":
+                return "reversible"
+            elif reaction_mode_symbol == "=>":
+                return "irreversible"
+            elif reaction_mode_symbol == "=":
+                return "equilibrium"
+            else:
+                raise ValueError(
+                    f"Unknown reaction mode symbol: {reaction_mode_symbol}")
+        except Exception as e:
+            raise Exception(f"Error determining reaction type: {e}")
+
+    # ! ::: parse charge
+    def parse_charge(self, charge: str) -> int:
+        """
+        Convert reaction charge notation to an integer charge.
+        """
+        try:
+            # SECTION: empty or missing charge
+            if charge == "":
+                return 0
+
+            # SECTION: normalize notation
+            charge = charge.strip()
+            if charge in ("+", "-"):
+                return 1 if charge == "+" else -1
+
+            # SECTION: charge magnitude with trailing sign, e.g. 2+ or 3-
+            match = re.fullmatch(r"(\d+)([+-])", charge)
+            if match:
+                magnitude = int(match.group(1))
+                sign = match.group(2)
+                return magnitude if sign == "+" else -magnitude
+
+            # SECTION: signed integer fallback, e.g. +2 or -2
+            return int(charge)
+        except Exception as e:
+            raise Exception(f"Error parsing charge '{charge}': {e}")
+
+    # ! ::: count charge
+    def count_charge(
+        self,
+        molecule: str,
+        coefficient: float,
+        charge: int
+    ) -> float:
+        """
+        Count the total charge of a molecule based on its charge and coefficient.
+        """
+        try:
+            # SECTION: validate inputs
+            if not isinstance(molecule, str):
+                raise ValueError("Molecule must be a string.")
+            if not isinstance(coefficient, (int, float)):
+                raise ValueError("Coefficient must be an integer or float.")
+            if not isinstance(charge, int):
+                raise ValueError("Charge must be an integer.")
+
+            # SECTION: calculate total charge
+            total_charge = charge * coefficient
+            return total_charge
+        except Exception as e:
+            raise Exception(
+                f"Error counting charge in molecule '{molecule}': {e}")
+
+    # ! ::: count total charge in reaction
+    def count_total_charge(
+        self,
+        reactants: List[Reactant],
+        products: List[Product]
+    ) -> Dict[str, float]:
+        """
+        Count the total charge of reactants and products in a reaction.
+        """
+        try:
+            # SECTION: calculate total charge for reactants
+            total_reactant_charge = sum(
+                self.count_charge(r['molecule'], r['coefficient'], r['charge'])
+                for r in reactants
+            )
+
+            # SECTION: calculate total charge for products
+            total_product_charge = sum(
+                self.count_charge(p['molecule'], p['coefficient'], p['charge'])
+                for p in products
+            )
+
+            # NOTE: return total charges as a dictionary
+            return {
+                'total_reactant_charge': total_reactant_charge,
+                'total_product_charge': total_product_charge,
+                'net_charge': total_product_charge - total_reactant_charge
+            }
+        except Exception as e:
+            raise Exception(f"Error counting total charge in reaction: {e}")

{pyreactlab_core-0.2.0 → pyreactlab_core-0.3.0}/pyreactlab_core/models/reaction.py

@@ -28,7 +28,7 @@ class Reaction(BaseModel):
     analysis : Dict[str, Any]
         A dictionary containing the analysis results of the reaction.
     component_keys : List[ComponentKey]
-        The key used to identify components in the reaction analysis, with a default value of ["Formula-State", "Name-State", "Name-Formula"].
+        The key used to identify components in the reaction analysis, with a default value of ["Formula-State", "Name-State", "Name-Formula", "Name-Formula-State"].
 
     Properties
     ----------
@@ -87,6 +87,7 @@ class Reaction(BaseModel):
             "Formula-State",
             "Name-State",
             "Name-Formula",
+            "Name-Formula-State",
         ],
         description="The key used to identify components in the reaction analysis."
     )
@@ -185,6 +186,21 @@ class Reaction(BaseModel):
     def carbon_count(self) -> Dict[str, float]:
         return self.analysis.get("carbon_count", {})
 
+    @computed_field
+    @property
+    def net_carbon_count(self) -> float:
+        return self.analysis.get("net_carbon_count", 0.0)
+
+    @computed_field
+    @property
+    def total_reactant_carbon_count(self) -> float:
+        return self.analysis.get("total_reactant_carbon_count", 0.0)
+
+    @computed_field
+    @property
+    def total_product_carbon_count(self) -> float:
+        return self.analysis.get("total_product_carbon_count", 0.0)
+
     @computed_field
     @property
     def reaction_state(self) -> Dict[str, str]:
@@ -200,6 +216,26 @@ class Reaction(BaseModel):
     def state_count(self) -> Dict[str, int]:
         return self.analysis.get("state_count", {})
 
+    @computed_field
+    @property
+    def charge_count(self) -> Dict[str, int]:
+        return self.analysis.get("charge_count", {})
+
+    @computed_field
+    @property
+    def total_reactant_charge(self) -> int:
+        return self.analysis.get("total_reactant_charge", 0)
+
+    @computed_field
+    @property
+    def total_product_charge(self) -> int:
+        return self.analysis.get("total_product_charge", 0)
+
+    @computed_field
+    @property
+    def net_charge(self) -> int:
+        return self.analysis.get("net_charge", 0)
+
     @computed_field
     @property
     def component_ids(self) -> Dict[str, int]:

pyreactlab_core-0.3.0/pyreactlab_core/models/reactions.py

@@ -0,0 +1,30 @@
+# import libs
+from __future__ import annotations
+from typing import TypedDict, Literal, Dict, List, Optional
+from pydantic import BaseModel, Field
+from pythermodb_settings.models import Component
+# locals
+
+# SECTION: Models
+# NOTE: Phase Rule
+PhaseRule = Literal["gas", "liquid", "aqueous", "solid"]
+
+# NOTE: reactants
+
+
+class Reactant(TypedDict):
+    coefficient: float
+    molecule: str
+    charge: int
+    state: str
+    molecule_state: str
+
+# NOTE: products
+
+
+class Product(TypedDict):
+    coefficient: float
+    molecule: str
+    charge: int
+    state: str
+    molecule_state: str

{pyreactlab_core-0.2.0 → pyreactlab_core-0.3.0}/pyreactlab_core/utils/component_tools.py

@@ -1,6 +1,5 @@
 # import libs
-import logging
-from typing import Dict, Any, List, Optional, Literal
+from typing import List
 from pythermodb_settings.models import Component, ComponentKey
 from pythermodb_settings.utils import set_component_id
 

{pyreactlab_core-0.2.0 → pyreactlab_core-0.3.0}/pyreactlab_core/utils/reaction_tools.py

@@ -1,11 +1,8 @@
 # import libs
 import logging
-from typing import Any, Dict, List, Optional, cast, NamedTuple
+from typing import cast, NamedTuple
 # locals
 from ..configs.constants import (
-    IRREVERSIBLE_REACTION_MODE_SYMBOLS,
-    REVERSIBLE_REACTION_MODE_SYMBOLS,
-    EQUILIBRIUM_REACTION_MODE_SYMBOLS,
     ReactionMode,
     ReactionDirection,
     ReactionType,

{pyreactlab_core-0.2.0 → pyreactlab_core-0.3.0}/pyreactlab_core/utils/tools.py

@@ -2,6 +2,7 @@
 import logging
 from typing import Literal, Optional
 
+
 # setup logger
 logger = logging.getLogger(__name__)
 

{pyreactlab_core-0.2.0 → pyreactlab_core-0.3.0}/pyreactlab_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyreactlab-core
-Version: 0.2.0
+Version: 0.3.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.2.0 → pyreactlab_core-0.3.0}/pyreactlab_core.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ pyreactlab_core/docs/chem_balance.py
 pyreactlab_core/docs/chem_utils.py
 pyreactlab_core/models/__init__.py
 pyreactlab_core/models/reaction.py
+pyreactlab_core/models/reactions.py
 pyreactlab_core/utils/__init__.py
 pyreactlab_core/utils/component_tools.py
 pyreactlab_core/utils/reaction_tools.py

pyreactlab_core-0.2.0/pyreactlab_core/core/chem_react_utils.py

@@ -1,181 +0,0 @@
-# import libs
-import re
-from typing import Dict, List, Optional
-# locals
-from ..configs.constants import REACTION_SYMBOLIC_MODES
-
-
-# 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}")
-
-    # ! reaction types
-
-    def get_reaction_type(self, reaction_mode_symbol: str) -> str:
-        """
-        Determine the type of reaction based on the reaction mode symbol.
-
-        Reaction Mode Symbols:
-        - `Reversible`: "<=>"
-        - `Irreversible`: "=>"
-        - `Equilibrium`: "="
-        """
-        try:
-            # SECTION: validate reaction mode symbol
-            if reaction_mode_symbol not in ("<=>", "=>", "="):
-                raise ValueError(
-                    f"Invalid reaction mode symbol: {reaction_mode_symbol}")
-
-            # SECTION: determine reaction type
-            if reaction_mode_symbol == "<=>":
-                return "reversible"
-            elif reaction_mode_symbol == "=>":
-                return "irreversible"
-            elif reaction_mode_symbol == "=":
-                return "equilibrium"
-            else:
-                raise ValueError(
-                    f"Unknown reaction mode symbol: {reaction_mode_symbol}")
-        except Exception as e:
-            raise Exception(f"Error determining reaction type: {e}")