pyreactlab-core 0.1.0__py3-none-any.whl

pyreactlab_core/docs/chem_utils.py

@@ -0,0 +1,114 @@
+# import libs
+import logging
+from typing import List, Optional
+# locals
+from ..models.reaction import Reaction
+
+# NOTE: configure logger
+logger = logging.getLogger(__name__)
+
+
+def build_stoichiometry_matrix(reactions: List[Reaction]):
+    '''
+    Build stoichiometry matrix for reactions
+
+    Parameters
+    ----------
+    reactions : List[Reaction]
+        List of Reaction instances
+
+    Returns
+    -------
+    component_list: list
+        component list
+    component_dict: dict
+        component dict
+    comp_list: list
+        component list
+    comp_coeff: list
+        component coefficient
+    component_state_list: list
+        component state list
+    '''
+    try:
+        # SECTION: extract reaction results
+        # NOTE: reaction num
+        reaction_num = len(reactions)
+
+        # NOTE: component list
+        component_list = []
+
+        # NOTE: component state list
+        component_state_list = []
+
+        # SECTION: Iterate over reactions and extract reactants and products
+        for item in reactions:
+            # get components
+            _components = item.all_components
+            # store
+            component_list.extend(_components)
+
+        # remove duplicate
+        component_list = list(set(component_list))
+
+        # component id: key, value
+        component_dict = {}
+
+        # loop over component list
+        for i, item in enumerate(component_list):
+            component_dict[item] = i
+
+        # SECTION: Initialize the component list
+        comp_list = [
+            {i: 0.0 for i in component_dict.keys()} for _ in range(reaction_num)
+        ]
+
+        # SECTION: Iterate over reactions and components
+        for j, reaction in enumerate(reactions):
+            for item in component_dict.keys():
+                # NOTE: Check reactants
+                for reactant in reactions[j].reactants:
+                    # matching state
+                    if reactant['molecule_state'] == item:
+                        comp_list[j][item] = -1 * \
+                            float(reactant['coefficient'])
+
+                    # >> component state list
+                    component_state_list.append(
+                        (
+                            reactant['molecule'],
+                            reactant['state'],
+                            reactant['molecule_state']
+                        )
+                    )
+
+                # NOTE: Check products
+                for product in reactions[j].products:
+                    # matching state
+                    if product['molecule_state'] == item:
+                        comp_list[j][item] = float(product['coefficient'])
+
+                    # >> component state list
+                    component_state_list.append(
+                        (
+                            product['molecule'],
+                            product['state'],
+                            product['molecule_state']
+                        )
+                    )
+
+        # Convert comp_list to comp_matrix
+        comp_coeff = [
+            [comp_list[j][item] for item in component_dict.keys()] for j in range(reaction_num)
+        ]
+
+        # res
+        return {
+            "component_list": component_list,
+            "component_dict": component_dict,
+            "component_state_list": component_state_list,
+            "comp_list": comp_list,
+            "comp_coeff": comp_coeff,
+        }
+    except Exception as e:
+        raise Exception(f"Error defining component ID: {e}")

pyreactlab_core/models/reaction.py

@@ -0,0 +1,174 @@
+# import libs
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, List
+from pydantic import BaseModel, Field, computed_field, model_validator
+# local imports
+from ..core.chem_react import (
+    ChemReact,
+    ReactionMode,
+    PhaseRule
+)
+
+
+class Reaction(BaseModel):
+    """
+    A class representing a chemical reaction, including its analysis and properties.
+
+    Attributes
+    ----------
+    name : str
+        The name of the reaction.
+    reaction : str
+        The chemical reaction equation as a string.
+    reaction_mode_symbol : Optional[ReactionMode]
+        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.
+
+    Properties
+    ----------
+    symbolic_reaction : str
+        The symbolic representation of the balanced reaction.
+    symbolic_unbalanced_reaction : str
+        The symbolic representation of the unbalanced reaction.
+    reactants_names : list[str]
+        A list of names of the reactants in the reaction.
+    products_names : list[str]
+        A list of names of the products in the reaction.
+    products : List[Dict[str, Any]]
+        A list of dictionaries representing the products of the reaction.
+    reactants : List[Dict[str, Any]]
+        A list of dictionaries representing the reactants of the reaction.
+    reaction_coefficients : Dict[str, float]
+        A dictionary of reaction coefficients for each component.
+    reaction_stoichiometry : Dict[str, float]
+        A dictionary representing the stoichiometry of the reaction.
+    reaction_stoichiometry_matrix : list[float]
+        A list representing the stoichiometry matrix of the reaction.
+    carbon_count : int
+        The total number of carbon atoms in the reaction.
+    reaction_state : str
+        The state of the reaction (e.g., "balanced", "unbalanced").
+    reaction_phase : Optional[PhaseRule]
+        The phase rule of the reaction, if applicable.
+    state_count : Dict[str, int]
+        A dictionary counting the states of components in the reaction.
+    component_ids : Dict[str, int]
+        A dictionary mapping component names to their IDs.
+    all_components : list[str]
+        A list of all component names involved in the reaction.
+
+    Methods
+    -------
+    _run_existing_analysis(self) -> Reaction
+        Validates and analyzes the reaction after initialization.
+    """
+    name: str
+    reaction: str
+    reaction_mode_symbol: Optional[ReactionMode] = Field(
+        default=None,
+        description="The symbol used to separate reactants and products in a reaction equation."
+    )
+    analysis: Dict[str, Any] = Field(default_factory=dict)
+
+    @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 = "="
+        else:
+            raise ValueError(
+                f"Invalid reaction format in reaction: {self.reaction}"
+            )
+
+        # NOTE: analyze reaction
+        util = ChemReact(reaction_mode_symbol=self.reaction_mode_symbol)
+
+        # NOTE: perform analysis
+        self.analysis = util.analyze_reaction(
+            reaction_pack={
+                "name": self.name,
+                "reaction": self.reaction
+            },
+        )
+        return self
+
+    @computed_field
+    @property
+    def symbolic_reaction(self) -> str:
+        return self.analysis.get("symbolic_reaction", "")
+
+    @computed_field
+    @property
+    def symbolic_unbalanced_reaction(self) -> str:
+        return self.analysis.get("symbolic_unbalanced_reaction", "")
+
+    @computed_field
+    @property
+    def reactants_names(self) -> list[str]:
+        return self.analysis.get("reactants_names", [])
+
+    @computed_field
+    @property
+    def products_names(self) -> list[str]:
+        return self.analysis.get("products_names", [])
+
+    @computed_field
+    @property
+    def products(self) -> List[Dict[str, Any]]:
+        return self.analysis.get("products", [])
+
+    @computed_field
+    @property
+    def reactants(self) -> List[Dict[str, Any]]:
+        return self.analysis.get("reactants", [])
+
+    @computed_field
+    @property
+    def reaction_coefficients(self) -> Dict[str, float]:
+        return self.analysis.get("reaction_coefficients", {})
+
+    @computed_field
+    @property
+    def reaction_stoichiometry(self) -> Dict[str, float]:
+        return self.analysis.get("reaction_stoichiometry", {})
+
+    @computed_field
+    @property
+    def reaction_stoichiometry_matrix(self) -> list[float]:
+        return self.analysis.get("reaction_stoichiometry_matrix", [])
+
+    @computed_field
+    @property
+    def carbon_count(self) -> int:
+        return self.analysis.get("carbon_count", 0)
+
+    @computed_field
+    @property
+    def reaction_state(self) -> str:
+        return self.analysis.get("reaction_state", "unknown")
+
+    @computed_field
+    @property
+    def reaction_phase(self) -> Optional[PhaseRule]:
+        return self.analysis.get("reaction_phase", None)
+
+    @computed_field
+    @property
+    def state_count(self) -> Dict[str, int]:
+        return self.analysis.get("state_count", {})
+
+    @computed_field
+    @property
+    def component_ids(self) -> Dict[str, int]:
+        return self.analysis.get("component_ids", {})
+
+    @computed_field
+    @property
+    def all_components(self) -> list[str]:
+        return self.analysis.get("all_components", [])

pyreactlab_core/utils/tools.py

@@ -0,0 +1,30 @@
+# import libs
+import logging
+from typing import Literal, Optional
+
+# setup logger
+logger = logging.getLogger(__name__)
+
+# NOTE: check if value is number
+
+
+def is_number(value: str) -> bool:
+    try:
+        float(value)
+        return True
+    except (ValueError, TypeError):
+        return False
+
+# NOTE: check if value is integer
+
+
+def is_integer(value: str) -> bool:
+    try:
+        num = float(value)   # handles "10", "10.5", "1e-3", etc.
+    except (ValueError, TypeError):
+        return False
+
+    if num.is_integer():      # built-in float method
+        return True
+    else:
+        return False

pyreactlab_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: pyreactlab-core
+Version: 0.1.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
+Project-URL: Homepage, https://github.com/sinagilassi/PyReactLab-Core
+Project-URL: Documentation, https://pyreactlab-core.readthedocs.io/en/latest/
+Project-URL: Source, https://github.com/sinagilassi/PyReactLab-Core
+Project-URL: Tracker, https://github.com/sinagilassi/PyReactLab-Core/issues
+Keywords: chemical-engineering,chemical-reactions,reaction-representation,reaction-stoichiometry,reaction-analysis
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.4.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: scipy>=1.16.3
+Dynamic: license-file
+
+# 🧪 PyReactLab-Core
+
+[![PyPI Downloads](https://static.pepy.tech/badge/pyreactlab-core/month)](https://pepy.tech/projects/pyreactlab-core)
+![PyPI](https://img.shields.io/pypi/v/pyreactlab-core)
+![Python Version](https://img.shields.io/pypi/pyversions/pyreactlab-core.svg)
+![License](https://img.shields.io/pypi/l/pyreactlab-core)
+![Read the Docs](https://img.shields.io/readthedocs/pyreactlab-core)
+
+**PyReactLab-Core** is the core foundation of the PyReactLab ecosystem, offering shared data structures and algorithms for chemical reaction representation, stoichiometry, and reaction analysis.
+
+## ✨ Features
+
+- **⚗️ Reaction Representation**: Define and manipulate chemical reactions with ease.
+- **⚖️ Stoichiometry Calculations**: Perform stoichiometric calculations for reactions.
+- **🔬 Reaction Analysis**: Analyze reaction properties and behaviors.
+- **🧩 Extensible Design**: Built to be extended by other PyReactLab modules.
+
+## 📦 Installation
+
+You can install PyReactLab-Core via pip:
+
+```bash
+pip install pyreactlab-core
+```
+
+## 🚀 Usage
+
+### Introduce a reaction
+
+A typical reaction can be introduced as follows:
+
+```python
+from pyreactlab_core import Reaction
+
+reaction = Reaction(
+    name="Combustion of Methane",
+    reaction="CO2(g) + 3H2(g) => CH3OH(g) + H2O(g)"
+)
+
+# print analysis
+print(
+    f"[bold underline]Reaction Analysis for: {reaction_1.name}[/bold underline]")
+print(f"Reaction: {reaction_1.reaction}")
+print(f"Reactants: {reaction_1.reactants}")
+print(f"Products: {reaction_1.products}")
+print(f"Reaction Coefficients: {reaction_1.reaction_coefficients}")
+print(f"Reaction Stoichiometry: {reaction_1.reaction_stoichiometry}")
+print(f"State Counts: {reaction_1.state_count}")
+print(f"Reaction Phase: {reaction_1.reaction_phase}")
+print(f"Reaction State: {reaction_1.reaction_state}")
+print(f"Carbon Count: {reaction_1.carbon_count}")
+print(f"Reactants Names: {reaction_1.reactants_names}")
+print(f"Products Names: {reaction_1.products_names}")
+
+# results:
+# Reaction: CO2(g) + 3H2(g) => CH3OH(g) + H2O(g)
+# Component IDs: {'CO2-g': 1, 'H2-g': 2, 'CH3OH-g': 3, 'H2O-g': 4}
+# Reaction Mode Symbol: =>
+# Symbolic Unbalanced Reaction: CO2 + H2 => CH3OH + H2O
+# Symbolic Reaction: CO2 + 3.0H2 => CH3OH + H2O
+# Reactants: [{'coefficient': 1.0, 'molecule': 'CO2', 'state': 'g', 'molecule_state': 'CO2-g'}, {'coefficient': 3.0, 'molecule': 'H2', 'state': 'g', 'molecule_state': 'H2-g'}]
+# Products: [{'coefficient': 1.0, 'molecule': 'CH3OH', 'state': 'g', 'molecule_state': 'CH3OH-g'}, {'coefficient': 1.0, 'molecule': 'H2O', 'state': 'g', 'molecule_state': 'H2O-g'}]
+# Reaction Coefficients: 2.0
+# Reaction Stoichiometry: {'CO2-g': -1.0, 'H2-g': -3.0, 'CH3OH-g': 1.0, 'H2O-g': 1.0}
+# State Counts: {'g': 4, 'l': 0, 'aq': 0, 's': 0}
+# Reaction Phase: gas
+# Reaction State: {'CO2-g': 'g', 'H2-g': 'g', 'CH3OH-g': 'g', 'H2O-g': 'g'}
+# Carbon Count: {'CO2-g': 1.0, 'H2-g': 0.0, 'CH3OH-g': 1.0, 'H2O-g': 0.0}
+# Reactants Names: ['CO2-g', 'H2-g']
+# Products Names: ['CH3OH-g', 'H2O-g']
+```
+
+### Stoichiometric Balance
+
+You can check if a reaction is balanced:
+
+```python
+from pyreactlab_core import Reaction
+from pyreactlab_core.core import balance
+
+# define a reaction
+reaction = Reaction(
+    name="Combustion of Methane",
+    reaction="CO2(g) + 3H2(g) => CH3OH(g) + H2O(g)"
+)
+
+# balance the reaction automatically
+balanced_reaction = balance(reaction)
+print(f"Balanced Reaction: {balanced_reaction.reaction}")
+```
+
+### Stoichiometric Matrix
+
+You can create a stoichiometric matrix for a list of reactions:
+
+```python
+from pyreactlab_core import Reaction
+from pyreactlab_core import rxn, rxn_stoichiometry, rxns_stoichiometry
+
+# NOTE: define reaction string
+reaction_1 = "CO2(g) + 3H2(g) => CH3OH(g) + H2O(g)"
+name_1 = "CO2 Hydrogenation to Methanol"
+
+# second reaction
+reaction_2 = "C2H4(g) + H2(g) => C2H6(g)"
+name_2 = "Ethylene Hydrogenation to Ethane"
+
+# NOTE: create reaction instance
+rxn_1: Reaction = rxn(
+    reaction_str=reaction_1,
+    name=name_1
+)
+
+rxn_2: Reaction = rxn(
+    reaction_str=reaction_2,
+    name=name_2
+)
+
+# NOTE: Get stoichiometry matrices for multiple reactions
+reactions_list = [rxn_1, rxn_2]
+stoichiometry_matrices = rxns_stoichiometry(
+    reactions=reactions_list,
+)
+# log
+print(stoichiometry_matrices)
+
+# results:
+# {
+#     'components': ['CO2-g', 'H2O-g', 'C2H4-g', 'H2-g', 'CH3OH-g', 'C2H6-g'],
+#     'component_ids': {'CO2-g': 0, 'H2O-g': 1, 'C2H4-g': 2, 'H2-g': 3, 'CH3OH-g': 4, 'C2H6-g': 5},
+#     'stoichiometry_matrices_list': [[-1.0, 1.0, 0.0, -3.0, 1.0, 0.0], [0.0, 0.0, -1.0, -1.0, 0.0, 1.0]],
+#     'stoichiometry_matrices_dict': [
+#         {'CO2-g': -1.0, 'H2O-g': 1.0, 'C2H4-g': 0.0, 'H2-g': -3.0, 'CH3OH-g': 1.0, 'C2H6-g': 0.0},
+#         {'CO2-g': 0.0, 'H2O-g': 0.0, 'C2H4-g': -1.0, 'H2-g': -1.0, 'CH3OH-g': 0.0, 'C2H6-g': 1.0}
+#     ]
+# }
+```
+
+## 🤝 Contributing
+
+Contributions are highly welcome — bug fixes, new calculation routines, mixture models, extended unit tests, documentation, etc.
+
+## 📝 License
+
+This project is distributed under the Apache License, Version 2.0, which grants you broad freedom to use, modify, and integrate the software into your own applications or projects, provided that you comply with the conditions outlined in the license. Although Apache 2.0 does not require users to retain explicit author credit beyond standard copyright and license notices, I kindly request that if you incorporate this work into your own software, you acknowledge Sina Gilassi as the original author. Referencing the original repository or documentation is appreciated, as it helps recognize the effort invested in developing and maintaining this project.
+
+## ❓ FAQ
+
+For any question, contact me on [LinkedIn](https://www.linkedin.com/in/sina-gilassi/)
+
+## 👨‍💻 Authors
+
+- [@sinagilassi](https://www.github.com/sinagilassi)

pyreactlab_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+pyreactlab_core/__init__.py,sha256=JGNJu9kdkUlIjNog8OXeCHCpnB9nJfClHqW-BcqoGxQ,453
+pyreactlab_core/app.py,sha256=HWVXNpFHqKWqf5TUaym9SCUjAxEDRYEWCU-EPK-Yi5g,3605
+pyreactlab_core/configs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyreactlab_core/configs/constants.py,sha256=8dpnVqnYwu5On1IH7toELWvNHp4BLgpLnhTRDobKVis,1295
+pyreactlab_core/configs/info.py,sha256=uvzRSHbrnPlbzSn-rGNE11Htq6pIK-N9f0eE8NhD3Oo,448
+pyreactlab_core/core/__init__.py,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+pyreactlab_core/core/chem_react.py,sha256=nMvAfZxw5OysSeYIhg82iaKil59Obc6dCMmq1CoKllw,31174
+pyreactlab_core/docs/__init__.py,sha256=Q_nWMKjz40OCw-WsSHu-8Aenvj1_yY_N47VnCpzeMTA,262
+pyreactlab_core/docs/chem_balance.py,sha256=qU035GBsFvFoEQCV_596OTGtFRqlnfMm4mXimqLdd5M,21503
+pyreactlab_core/docs/chem_utils.py,sha256=jTyo-iMXs4JNqenZJ-g7Np_0SLfWGmu2trPUjWQZMzI,3603
+pyreactlab_core/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyreactlab_core/models/reaction.py,sha256=LiUKwoiKy_49WBboYPsZWyyFzVp9E1pv6JxoluQgC8U,5818
+pyreactlab_core/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyreactlab_core/utils/tools.py,sha256=P8fwEYzXVteRb76BGT6IDtDQj2UJfEiZfyij5OzbA_k,638
+pyreactlab_core-0.1.0.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
+pyreactlab_core-0.1.0.dist-info/METADATA,sha256=IZyxyYBC6_ZaqrKvHtkrdG-l4Zkfrydkj1jb6KkYHog,7286
+pyreactlab_core-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyreactlab_core-0.1.0.dist-info/top_level.txt,sha256=OTJ7aN0HVzzbIM1yAOk9UGg0v4AvpshSY86msqB7uiM,16
+pyreactlab_core-0.1.0.dist-info/RECORD,,

pyreactlab_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+