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

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

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

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

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

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

@@ -8,6 +8,7 @@ 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
@@ -17,9 +18,6 @@ from .reaction_network_analysis import ReactionNetworkAnalysis
 # NOTE: logger
 logger = logging.getLogger(__name__)
 
-# NOTE: Reaction Mode
-ReactionMode = Literal["<=>", "=>", "="]
-
 # NOTE: Phase Rule
 PhaseRule = Literal["gas", "liquid", "aqueous", "solid"]
 
@@ -116,6 +114,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__(
@@ -393,6 +393,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,
@@ -417,4 +419,3 @@ class ChemReact(
             return res
         except Exception as e:
             raise Exception(f"Error analyzing reaction: {e}")
-

{pyreactlab_core-0.1.9 → pyreactlab_core-0.2.0}/pyreactlab_core/core/chem_react_utils.py

@@ -1,6 +1,8 @@
 # import libs
 import re
 from typing import Dict, List, Optional
+# locals
+from ..configs.constants import REACTION_SYMBOLIC_MODES
 
 
 # SECTION: ChemReactUtils class
@@ -147,3 +149,33 @@ class ChemReactUtils:
             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}")

{pyreactlab_core-0.1.9 → pyreactlab_core-0.2.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"].
 
     Properties
     ----------
@@ -93,17 +93,16 @@ class Reaction(BaseModel):
 
     @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 +111,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 +121,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 +130,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:

pyreactlab_core-0.2.0/pyreactlab_core/utils/reaction_tools.py

@@ -0,0 +1,153 @@
+# import libs
+import logging
+from typing import Any, Dict, List, Optional, cast, NamedTuple
+# locals
+from ..configs.constants import (
+    IRREVERSIBLE_REACTION_MODE_SYMBOLS,
+    REVERSIBLE_REACTION_MODE_SYMBOLS,
+    EQUILIBRIUM_REACTION_MODE_SYMBOLS,
+    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.2.0}/pyreactlab_core.egg-info/PKG-INFO

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

@@ -23,4 +23,5 @@ pyreactlab_core/models/__init__.py
 pyreactlab_core/models/reaction.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",
-]