pyThermoEst 0.1.0__tar.gz

pythermoest-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sina Gilassi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pythermoest-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: pyThermoEst
+Version: 0.1.0
+Summary: A Python toolkit for estimating thermodynamic properties
+Author-email: Sina Gilassi <sina.gilassi@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sinagilassi/PyThermoEst
+Project-URL: Documentation, https://pythermoest.readthedocs.io/en/latest/
+Project-URL: Source, https://github.com/sinagilassi/PyThermoEst
+Project-URL: Tracker, https://github.com/sinagilassi/PyThermoEst/issues
+Keywords: chemical-engineering,thermodynamics,property-estimation,joback-method,zabransky-ruzicka-method,group-contribution-methods
+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: pandas>=2.3.3
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: pydantic>=2.12.4
+Requires-Dist: pydantic-settings>=2.12.0
+Provides-Extra: dev
+Requires-Dist: rich>=14.2.0; extra == "dev"
+Dynamic: license-file
+
+# 🧪 PyThermoEst
+
+[![PyPI Downloads](https://static.pepy.tech/badge/pythermoest/month)](https://pepy.tech/projects/pythermoest)
+![PyPI](https://img.shields.io/pypi/v/PyThermoEst)
+![Python Version](https://img.shields.io/pypi/pyversions/PyThermoEst.svg)
+![License](https://img.shields.io/pypi/l/PyThermoEst)
+
+PyThermoEst is a Python toolkit for estimating thermodynamic properties from group-contribution methods. It currently supports the **Joback** method for estimating a wide range of properties and the **Zabransky–Ruzicka** method for predicting the liquid-phase heat capacity.
+
+## 📦 Installation
+
+```bash
+pip install pyThermoEst
+```
+
+## 🚀 Usage
+
+The package exposes convenience helpers in `pyThermoEst.app` for both calculation workflows. See the `examples/` directory for runnable scripts.
+
+### 🧬 Joback property estimation
+
+Provide Joback group contributions along with the total number of atoms, then call `joback_calc`. You can mix field names or their documented aliases when building `JobackGroupContributions`.
+
+```python
+from pyThermoEst import joback_calc
+from pyThermoEst.models import JobackGroupContributions, GroupUnit
+
+payload = {
+    "-CH3": GroupUnit(value=2),
+    "=CH- @ring": GroupUnit(value=3),
+    "=C< @ring": GroupUnit(value=3),
+    "-OH @phenol": GroupUnit(value=1),
+}
+
+joback_groups = JobackGroupContributions(**payload)
+
+# or dict with aliases:
+# joback_groups = {
+#     "-CH3": 2,
+#     "=CH- @ring": 3,
+#     "=C< @ring": 3,
+#     "-OH @phenol": 1,
+# }
+
+result = joback_calc(groups=joback_groups, total_atoms_number=18)
+
+# Evaluate a temperature-dependent property, e.g., heat capacity at 273 K
+cp_273 = result["heat_capacity"]["value"](273)
+print(cp_273)
+```
+
+### 💧 Zabransky–Ruzicka liquid heat capacity
+
+To compute liquid heat capacity, provide required group contributions and optional correction terms, then call `zabransky_ruzicka_calc`.
+
+```python
+from pyThermoEst import zabransky_ruzicka_calc
+from pyThermoEst.models import (
+    ZabranskyRuzickaGroupContributions,
+    ZabranskyRuzickaGroupContributionsCorrections,
+    GroupUnit,
+)
+
+payload = {
+    "C-(H)3(O)": GroupUnit(value=2),
+    "CO-(O)2": GroupUnit(value=1),
+    "O-(C)(CO)": GroupUnit(value=2),
+}
+
+contributions = ZabranskyRuzickaGroupContributions(**payload)
+corrections = ZabranskyRuzickaGroupContributionsCorrections()
+
+# or dicts with aliases:
+# contributions = {
+#     "C-(H)3(O)": 2,
+#     "CO-(O)2": 1,
+#     "O-(C)(CO)": 2,
+# }
+
+result = zabransky_ruzicka_calc(
+    group_contributions=contributions,
+    group_corrections=corrections
+)
+cp_liq_at_300k = result["value"](298.15)
+print(cp_liq_at_300k, result["unit"], result["symbol"])
+```
+
+### 📚 Getting group contribution IDs and names
+
+You can inspect available group contribution identifiers and names for each method:
+
+#### 🧬 Joback group contributions
+
+```python
+from pyThermoEst.docs.joback import (
+    joback_group_contribution_info,
+    joback_group_contribution_names,
+    joback_group_contribution_ids
+)
+
+# Get all group contribution IDs (aliases)
+group_ids = joback_group_contribution_ids()
+
+# Get all group contribution names (field names)
+group_names = joback_group_contribution_names()
+
+# Get both names and IDs as tuples
+names, ids = joback_group_contribution_info()
+```
+
+#### 💧 Zabransky–Ruzicka group contributions
+
+```python
+from pyThermoEst.docs.zabransky_ruzicka import (
+    zabransky_ruzicka_group_contribution_info,
+    zabransky_ruzicka_group_contribution_names,
+    zabransky_ruzicka_group_contribution_ids,
+    zabransky_ruzicka_group_correction_info,
+    zabransky_ruzicka_group_correction_ids,
+    zabransky_ruzicka_group_correction_names
+)
+
+# Get group contribution IDs (aliases)
+group_ids = zabransky_ruzicka_group_contribution_ids()
+
+# Get group contribution names (field names)
+group_names = zabransky_ruzicka_group_contribution_names()
+
+# Get both names and IDs as tuples
+names, ids = zabransky_ruzicka_group_contribution_info()
+
+# Get correction term IDs
+correction_ids = zabransky_ruzicka_group_correction_ids()
+
+# Get correction term names
+correction_names = zabransky_ruzicka_group_correction_names()
+
+# Get both correction names and IDs as tuples
+corr_names, corr_ids = zabransky_ruzicka_group_correction_info()
+```
+
+### 📖 Further examples
+
+- `examples/joback-exp-0.py`: Inspect available Joback group IDs and names.
+- `examples/joback-exp-1.py`: Build Joback group payloads with field names or aliases.
+- `examples/joback-exp-2.py`: Full Joback calculation including temperature evaluation.
+- `examples/zabransky-ruzicka-exp-0.py`: Inspect available Zabransky–Ruzicka group IDs, names, and corrections.
+- `examples/zabransky-ruzicka-exp-1.py`: Zabransky–Ruzicka calculation with optional corrections.
+
+## 🔧 API reference
+
+- `pyThermoEst.app.joback_calc(groups, total_atoms_number)`: Runs Joback method and returns calculated properties.
+- `pyThermoEst.app.zabransky_ruzicka_calc(group_contributions, group_corrections=None)`: Returns an equation for liquid heat capacity plus units and symbol metadata.
+
+Each function accepts either the pydantic models or plain dictionaries keyed by group identifiers; aliases are supported for convenience.
+
+## 📝 License
+
+This project is licensed under the MIT License. You are free to use, modify, and distribute this software in your own applications or projects. However, if you choose to use this app in another app or software, please ensure that my name, Sina Gilassi, remains credited as the original author. This includes retaining any references to the original repository or documentation where applicable. By doing so, you help acknowledge the effort and time invested in creating this project.
+
+## ❓ FAQ
+
+For any question, contact me on [LinkedIn](https://www.linkedin.com/in/sina-gilassi/)

pythermoest-0.1.0/README.md

@@ -0,0 +1,163 @@
+# 🧪 PyThermoEst
+
+[![PyPI Downloads](https://static.pepy.tech/badge/pythermoest/month)](https://pepy.tech/projects/pythermoest)
+![PyPI](https://img.shields.io/pypi/v/PyThermoEst)
+![Python Version](https://img.shields.io/pypi/pyversions/PyThermoEst.svg)
+![License](https://img.shields.io/pypi/l/PyThermoEst)
+
+PyThermoEst is a Python toolkit for estimating thermodynamic properties from group-contribution methods. It currently supports the **Joback** method for estimating a wide range of properties and the **Zabransky–Ruzicka** method for predicting the liquid-phase heat capacity.
+
+## 📦 Installation
+
+```bash
+pip install pyThermoEst
+```
+
+## 🚀 Usage
+
+The package exposes convenience helpers in `pyThermoEst.app` for both calculation workflows. See the `examples/` directory for runnable scripts.
+
+### 🧬 Joback property estimation
+
+Provide Joback group contributions along with the total number of atoms, then call `joback_calc`. You can mix field names or their documented aliases when building `JobackGroupContributions`.
+
+```python
+from pyThermoEst import joback_calc
+from pyThermoEst.models import JobackGroupContributions, GroupUnit
+
+payload = {
+    "-CH3": GroupUnit(value=2),
+    "=CH- @ring": GroupUnit(value=3),
+    "=C< @ring": GroupUnit(value=3),
+    "-OH @phenol": GroupUnit(value=1),
+}
+
+joback_groups = JobackGroupContributions(**payload)
+
+# or dict with aliases:
+# joback_groups = {
+#     "-CH3": 2,
+#     "=CH- @ring": 3,
+#     "=C< @ring": 3,
+#     "-OH @phenol": 1,
+# }
+
+result = joback_calc(groups=joback_groups, total_atoms_number=18)
+
+# Evaluate a temperature-dependent property, e.g., heat capacity at 273 K
+cp_273 = result["heat_capacity"]["value"](273)
+print(cp_273)
+```
+
+### 💧 Zabransky–Ruzicka liquid heat capacity
+
+To compute liquid heat capacity, provide required group contributions and optional correction terms, then call `zabransky_ruzicka_calc`.
+
+```python
+from pyThermoEst import zabransky_ruzicka_calc
+from pyThermoEst.models import (
+    ZabranskyRuzickaGroupContributions,
+    ZabranskyRuzickaGroupContributionsCorrections,
+    GroupUnit,
+)
+
+payload = {
+    "C-(H)3(O)": GroupUnit(value=2),
+    "CO-(O)2": GroupUnit(value=1),
+    "O-(C)(CO)": GroupUnit(value=2),
+}
+
+contributions = ZabranskyRuzickaGroupContributions(**payload)
+corrections = ZabranskyRuzickaGroupContributionsCorrections()
+
+# or dicts with aliases:
+# contributions = {
+#     "C-(H)3(O)": 2,
+#     "CO-(O)2": 1,
+#     "O-(C)(CO)": 2,
+# }
+
+result = zabransky_ruzicka_calc(
+    group_contributions=contributions,
+    group_corrections=corrections
+)
+cp_liq_at_300k = result["value"](298.15)
+print(cp_liq_at_300k, result["unit"], result["symbol"])
+```
+
+### 📚 Getting group contribution IDs and names
+
+You can inspect available group contribution identifiers and names for each method:
+
+#### 🧬 Joback group contributions
+
+```python
+from pyThermoEst.docs.joback import (
+    joback_group_contribution_info,
+    joback_group_contribution_names,
+    joback_group_contribution_ids
+)
+
+# Get all group contribution IDs (aliases)
+group_ids = joback_group_contribution_ids()
+
+# Get all group contribution names (field names)
+group_names = joback_group_contribution_names()
+
+# Get both names and IDs as tuples
+names, ids = joback_group_contribution_info()
+```
+
+#### 💧 Zabransky–Ruzicka group contributions
+
+```python
+from pyThermoEst.docs.zabransky_ruzicka import (
+    zabransky_ruzicka_group_contribution_info,
+    zabransky_ruzicka_group_contribution_names,
+    zabransky_ruzicka_group_contribution_ids,
+    zabransky_ruzicka_group_correction_info,
+    zabransky_ruzicka_group_correction_ids,
+    zabransky_ruzicka_group_correction_names
+)
+
+# Get group contribution IDs (aliases)
+group_ids = zabransky_ruzicka_group_contribution_ids()
+
+# Get group contribution names (field names)
+group_names = zabransky_ruzicka_group_contribution_names()
+
+# Get both names and IDs as tuples
+names, ids = zabransky_ruzicka_group_contribution_info()
+
+# Get correction term IDs
+correction_ids = zabransky_ruzicka_group_correction_ids()
+
+# Get correction term names
+correction_names = zabransky_ruzicka_group_correction_names()
+
+# Get both correction names and IDs as tuples
+corr_names, corr_ids = zabransky_ruzicka_group_correction_info()
+```
+
+### 📖 Further examples
+
+- `examples/joback-exp-0.py`: Inspect available Joback group IDs and names.
+- `examples/joback-exp-1.py`: Build Joback group payloads with field names or aliases.
+- `examples/joback-exp-2.py`: Full Joback calculation including temperature evaluation.
+- `examples/zabransky-ruzicka-exp-0.py`: Inspect available Zabransky–Ruzicka group IDs, names, and corrections.
+- `examples/zabransky-ruzicka-exp-1.py`: Zabransky–Ruzicka calculation with optional corrections.
+
+## 🔧 API reference
+
+- `pyThermoEst.app.joback_calc(groups, total_atoms_number)`: Runs Joback method and returns calculated properties.
+- `pyThermoEst.app.zabransky_ruzicka_calc(group_contributions, group_corrections=None)`: Returns an equation for liquid heat capacity plus units and symbol metadata.
+
+Each function accepts either the pydantic models or plain dictionaries keyed by group identifiers; aliases are supported for convenience.
+
+## 📝 License
+
+This project is licensed under the MIT License. You are free to use, modify, and distribute this software in your own applications or projects. However, if you choose to use this app in another app or software, please ensure that my name, Sina Gilassi, remains credited as the original author. This includes retaining any references to the original repository or documentation where applicable. By doing so, you help acknowledge the effort and time invested in creating this project.
+
+## ❓ FAQ
+
+For any question, contact me on [LinkedIn](https://www.linkedin.com/in/sina-gilassi/)

pythermoest-0.1.0/pyThermoEst/__init__.py

@@ -0,0 +1,21 @@
+from .configs import (
+    __version__,
+    __author__,
+    __description__,
+    __email__,
+    __license__,
+)
+
+from .app import joback_calc, zabransky_ruzicka_calc
+
+__all__ = [
+    # config
+    "__version__",
+    "__author__",
+    "__description__",
+    "__email__",
+    "__license__",
+    # app
+    "joback_calc",
+    "zabransky_ruzicka_calc",
+]

pythermoest-0.1.0/pyThermoEst/app.py

@@ -0,0 +1,109 @@
+# import libs
+import logging
+from typing import Dict, Optional
+# locals
+from .models import (
+    JobackGroupContributions,
+    ZabranskyRuzickaGroupContributions,
+    ZabranskyRuzickaGroupContributionsCorrections,
+    EstimatedProp
+)
+from .core import Joback, ZabranskyRuzicka
+
+
+# NOTE: logger
+logger = logging.getLogger(__name__)
+
+
+# SECTION: Joback Group Contributions
+
+def joback_calc(
+    groups: JobackGroupContributions | Dict[str, int] | Dict[str, float],
+    total_atoms_number: int
+) -> Optional[Dict[str, EstimatedProp]]:
+    """
+    Using Joback method to calculate thermodynamic properties including
+
+    Parameters
+    ----------
+    groups : JobackGroupContributions | Dict[str, float] | Dict[str, int]
+        Group contributions for Joback method.
+    total_atoms_number : int
+        Total number of atoms in the molecule.
+
+    Returns
+    -------
+    Dict[str, EstimatedProp] | None
+        A dictionary containing calculated thermodynamic properties.
+
+    Notes
+    -----
+    You can use either the field names or their aliases to specify group contributions. For example:
+    - methyl has alias '-CH3'
+    - methylene has alias '-CH2- @non-ring'
+    - imine_non_ring has alias '-N= @non-ring'
+    - imine_ring has alias '-N= @ring'
+
+    """
+    try:
+        # SECTION: initialize Joback method
+        Joback_ = Joback(
+            group_contributions=groups,
+            total_atoms_number=total_atoms_number
+        )
+
+        # NOTE: calculate properties
+        return Joback_._calc()
+    except Exception as e:
+        logger.error(f"Error in Joback calculation: {e}")
+        return None
+
+# SECTION: Zabransky-Ruzicka Group Contributions
+
+
+def zabransky_ruzicka_calc(
+    group_contributions: ZabranskyRuzickaGroupContributions | Dict[str, float] | Dict[str, int],
+    group_corrections: Optional[
+        ZabranskyRuzickaGroupContributionsCorrections |
+        Dict[str, float] |
+        Dict[str, int]
+    ] = None
+) -> Optional[EstimatedProp]:
+    """
+    Using Zabransky-Ruzicka method to calculate thermodynamic properties including
+
+    Parameters
+    ----------
+    group_contributions : ZabranskyRuzickaGroupContributions | Dict[str, float] | Dict[str, int]
+        Group contributions for Zabransky-Ruzicka method.
+    group_corrections : Optional[ZabranskyRuzickaGroupContributionsCorrections | Dict[str, float] | Dict[str, int]]
+        Group correction contributions for Zabransky-Ruzicka method.
+
+    Returns
+    -------
+    EstimatedProp | None
+        A dictionary containing calculated thermodynamic properties as:
+        - value: equation to calculate heat capacity.
+        - units: units of the heat capacity (J/mol.K).
+        - symbol: symbol representing heat capacity (Cp_LIQ).
+
+    Notes
+    -----
+    You can use either the field names or their aliases to specify group contributions. For example:
+    - C-(H)3(C)
+    - C-(H)2(C)2
+    - C-(H)(C)3
+
+    """
+    try:
+        # SECTION: initialize Zabransky-Ruzicka method
+        ZabranskyRuzicka_ = ZabranskyRuzicka(
+            group_contributions=group_contributions,
+            group_corrections=group_corrections
+        )
+
+        # NOTE: calculate properties
+        return ZabranskyRuzicka_._calc()
+    except Exception as e:
+        logger.error(f"Error in Zabransky-Ruzicka calculation: {e}")
+        return None

pythermoest-0.1.0/pyThermoEst/configs/__init__.py

@@ -0,0 +1,29 @@
+from .info import (
+    __author__,
+    __description__,
+    __email__,
+    __license__,
+    __version__,
+)
+
+from .settings import (
+    JOBACK_DATA_FILE,
+    JOBACK_TABLE_COLUMN_GROUP,
+    ZABRANSKY_RUZICKA_DATA_FILE_1,
+    ZABRANSKY_RUZICKA_DATA_FILE_2,
+    ZABRANSKY_RUZICKA_TABLE_COLUMN_GROUP,
+    ZABRANSKY_RUZICKA_REFERENCE
+)
+
+__all__ = [
+    "__author__",
+    "__description__",
+    "__email__",
+    "__license__",
+    "__version__",
+    "JOBACK_DATA_FILE",
+    "JOBACK_TABLE_COLUMN_GROUP",
+    "ZABRANSKY_RUZICKA_DATA_FILE_1",
+    "ZABRANSKY_RUZICKA_DATA_FILE_2",
+    "ZABRANSKY_RUZICKA_TABLE_COLUMN_GROUP",
+]

pythermoest-0.1.0/pyThermoEst/configs/info.py

@@ -0,0 +1,10 @@
+# version
+__version__ = "0.1.0"
+# author
+__author__ = "Sina Gilassi"
+# email
+__email__ = "sina.gilassi@gmail.com"
+# license
+__license__ = "MIT"
+# package description
+__description__ = "A Python package for thermodynamic property estimation."

pythermoest-0.1.0/pyThermoEst/configs/settings.py

@@ -0,0 +1,18 @@
+# import libs
+
+# SECTION: Joback method settings
+JOBACK_DATA_FILE = 'joback.csv'
+
+# NOTE: tables
+JOBACK_TABLE_COLUMN_GROUP = 'Group'
+
+# SECTION: zabransky-ruzicka method settings
+ZABRANSKY_RUZICKA_DATA_FILE_1 = 'zabransky-ruzicka-1.csv'
+ZABRANSKY_RUZICKA_DATA_FILE_2 = 'zabransky-ruzicka-2.csv'
+
+# NOTE: tables
+ZABRANSKY_RUZICKA_TABLE_COLUMN_GROUP = 'Group'
+
+# NOTE: reference
+ZABRANSKY_RUZICKA_REFERENCE = """Zábranský, Milan, and Vlastimil Růžička Jr. "Estimation of the heat capacities of organic liquids as a function of temperature using group additivity: an amendment." Journal of physical and chemical reference data 33.4 (2004): 1071-1081.
+"""

pythermoest-0.1.0/pyThermoEst/core/__init__.py

@@ -0,0 +1,7 @@
+from .joback import Joback
+from .zabransky_ruzicka import ZabranskyRuzicka
+
+__all__ = [
+    'Joback',
+    'ZabranskyRuzicka',
+]