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

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

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

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

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

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

@@ -8,38 +8,17 @@ 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
+from ..models.reactions import Reactant, Product, PhaseRule
 
 
 # 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(
@@ -116,6 +95,8 @@ class ChemReact(
 
         # 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__(
@@ -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(
@@ -393,6 +423,8 @@ class ChemReact(
             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,
@@ -406,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,
@@ -417,4 +456,3 @@ class ChemReact(
             return res
         except Exception as e:
             raise Exception(f"Error analyzing reaction: {e}")
-

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.1.9 → pyreactlab_core-0.3.0}/pyreactlab_core/models/reaction.py

@@ -5,11 +5,9 @@ from typing import Any, Dict, Optional, List
 from pydantic import BaseModel, Field, computed_field, model_validator
 from pythermodb_settings.models import Component, ComponentKey
 # local imports
-from ..core.chem_react import (
-    ChemReact,
-    ReactionMode,
-    PhaseRule
-)
+from ..configs.constants import ReactionMode
+from ..core.chem_react import ChemReact
+from ..utils.reaction_tools import get_reaction_mode_symbol, normalize_reaction_expression
 
 # NOTE: set up logger
 logger = logging.getLogger(__name__)
@@ -29,6 +27,8 @@ class Reaction(BaseModel):
         The symbol used to separate reactants and products in a reaction equation.
     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", "Name-Formula-State"].
 
     Properties
     ----------
@@ -87,23 +87,23 @@ class Reaction(BaseModel):
             "Formula-State",
             "Name-State",
             "Name-Formula",
+            "Name-Formula-State",
         ],
         description="The key used to identify components in the reaction analysis."
     )
 
     @model_validator(mode="after")
     def _run_existing_analysis(self):
-        # NOTE: check reaction mode symbol
-        if "<=>" in self.reaction:
-            self.reaction_mode_symbol = "<=>"
-        elif "=>" in self.reaction:
-            self.reaction_mode_symbol = "=>"
-        elif "=" in self.reaction:
-            self.reaction_mode_symbol = "="
+        # NOTE: validate reaction mode symbol
+        if self.reaction_mode_symbol is None:
+            self.reaction_mode_symbol = get_reaction_mode_symbol(self.reaction)
         else:
-            raise ValueError(
-                f"Invalid reaction format in reaction: {self.reaction}"
-            )
+            # validate provided reaction mode symbol
+            if self.reaction_mode_symbol not in ["<=>", "=>", "="]:
+                raise ValueError(
+                    f"Invalid reaction mode symbol: {self.reaction_mode_symbol}. "
+                    f"Must be one of ['<=>', '=>', '=']."
+                )
 
         # NOTE: analyze reaction
         util = ChemReact(
@@ -112,6 +112,9 @@ class Reaction(BaseModel):
             component_keys=self.component_keys
         )
 
+        # NOTE: normalize reaction string
+        self.reaction = normalize_reaction_expression(self.reaction)
+
         # NOTE: perform analysis
         self.analysis = util.analyze_reaction(
             reaction_pack={
@@ -119,6 +122,8 @@ class Reaction(BaseModel):
                 "reaction": self.reaction
             },
         )
+
+        # ! return self to allow for method chaining or further processing if needed
         return self
 
     @computed_field
@@ -126,6 +131,11 @@ class Reaction(BaseModel):
     def symbolic_reaction(self) -> str:
         return self.analysis.get("symbolic_reaction", "")
 
+    @computed_field
+    @property
+    def reaction_type(self) -> str:
+        return self.analysis.get("reaction_type", "")
+
     @computed_field
     @property
     def symbolic_unbalanced_reaction(self) -> str:
@@ -176,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]:
@@ -191,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.1.9 → 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.3.0/pyreactlab_core/utils/reaction_tools.py

@@ -0,0 +1,150 @@
+# import libs
+import logging
+from typing import cast, NamedTuple
+# locals
+from ..configs.constants import (
+    ReactionMode,
+    ReactionDirection,
+    ReactionType,
+    REACTION_SYMBOLIC_MODES,
+)
+
+# NOTE: logger
+logger = logging.getLogger(__name__)
+
+# ! reaction mode
+
+
+class ReactionSymbolInfo(NamedTuple):
+    reaction: str
+    symbol: str
+    type: ReactionType
+    mode: ReactionMode
+    direction: ReactionDirection
+
+
+def check_reaction(
+    reaction: str,
+) -> ReactionSymbolInfo:
+    """
+Determine the reaction mode symbol, type, and direction from a given reaction string.
+
+    Parameters
+    ----------
+    reaction : str
+        The chemical reaction equation as a string.
+
+    Returns
+    -------
+    ReactionSymbolInfo
+        A named tuple containing the reaction mode symbol, type, and direction.
+    """
+    try:
+        # SECTION: check for reaction mode symbols in the reaction string
+        rxn_direction = None
+        rxn_mode = None
+        rxn_symbol = None
+
+        # Longest symbols first to avoid "=" matching "<=>"
+        symbols = sorted(
+            REACTION_SYMBOLIC_MODES,
+            key=len,
+            reverse=True,
+        )
+
+        for symbol in symbols:
+            if symbol in reaction:
+                mode, direction = REACTION_SYMBOLIC_MODES[symbol]
+                rxn_mode = mode
+                rxn_direction = direction
+                rxn_symbol = symbol
+                # replace the symbol with :::
+                reaction = reaction.replace(symbol, ":::")
+                # break after finding the first valid symbol
+                break
+
+        # NOTE: if a valid reaction mode symbol is found, return it
+        if (
+            rxn_symbol is not None and
+            rxn_symbol is not None and
+            rxn_direction is not None
+        ):
+            if rxn_mode == "irreversible":
+                return ReactionSymbolInfo(
+                    reaction=reaction.replace(":::", '=>'),
+                    symbol=rxn_symbol,
+                    type=cast(ReactionType, "irreversible"),
+                    mode=cast(ReactionMode, "=>"),
+                    direction=cast(ReactionDirection, "forward")
+                )
+            elif rxn_mode == "reversible":
+                return ReactionSymbolInfo(
+                    reaction=reaction.replace(":::", '<=>'),
+                    symbol=rxn_symbol,
+                    type=cast(ReactionType, "reversible"),
+                    mode=cast(ReactionMode, "<=>"),
+                    direction=cast(ReactionDirection, "forward")
+                )
+            elif rxn_mode == "equilibrium":
+                return ReactionSymbolInfo(
+                    reaction=reaction.replace(":::", '='),
+                    symbol=rxn_symbol,
+                    type=cast(ReactionType, "equilibrium"),
+                    mode=cast(ReactionMode, "="),
+                    direction=cast(ReactionDirection, "forward")
+                )
+            else:
+                raise ValueError(f"Unknown reaction type: {rxn_mode}")
+
+        # NOTE: no valid reaction mode found
+        raise
+    except Exception as e:
+        raise Exception(f"Error determining reaction mode: {e}")
+
+# ! get reaction mode symbol
+
+
+def get_reaction_mode_symbol(reaction: str) -> ReactionMode:
+    """
+    Determine the reaction mode symbol from a given reaction string.
+
+    Parameters
+    ----------
+    reaction : str
+        The chemical reaction equation as a string.
+
+    Returns
+    -------
+    ReactionMode
+        The reaction mode symbol.
+    """
+    try:
+        # SECTION: check for reaction mode symbols in the reaction string
+        rxn_symbol_info = check_reaction(reaction)
+        return rxn_symbol_info.mode
+    except Exception as e:
+        raise Exception(f"Error determining reaction mode symbol: {e}")
+
+# ! get reaction expression
+
+
+def normalize_reaction_expression(reaction: str) -> str:
+    """
+    Normalize the reaction expression by removing the reaction mode symbol and updating the symbol to a standard form including "<=>", "=>", or "=".
+
+    Parameters
+    ----------
+    reaction : str
+        The chemical reaction equation as a string.
+
+    Returns
+    -------
+    str
+        The reaction expression without the mode symbol.
+    """
+    try:
+        # SECTION: check for reaction mode symbols in the reaction string
+        rxn_symbol_info = check_reaction(reaction)
+        return rxn_symbol_info.reaction
+    except Exception as e:
+        raise Exception(f"Error determining reaction expression: {e}")

{pyreactlab_core-0.1.9 → 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.1.9 → pyreactlab_core-0.3.0}/pyreactlab_core.egg-info/PKG-INFO

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

@@ -21,6 +21,8 @@ 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/utils/tools.py

pyreactlab_core-0.1.9/pyreactlab_core/configs/constants.py

@@ -1,40 +0,0 @@
-# import libs
-
-# 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",
-]

pyreactlab_core-0.1.9/pyreactlab_core/core/chem_react_utils.py

@@ -1,149 +0,0 @@
-# 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}")