thermo-utils 0.2.0__tar.gz

thermo_utils-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dspavier
+
+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.

thermo_utils-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: thermo-utils
+Version: 0.2.0
+Summary: A thermodynamics calculator for chemical engineering, from homework to plant design
+License-Expression: MIT
+License-File: LICENSE
+Keywords: thermodynamics,chemical engineering,equation of state,phase equilibrium,calculator
+Author: Dspavier
+Requires-Python: >=3.12
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Provides-Extra: dev
+Requires-Dist: CoolProp (>=7.0.0)
+Requires-Dist: chemicals (>=1.5.0)
+Requires-Dist: matplotlib (>=3.9.0)
+Requires-Dist: numpy (>=2.0.0)
+Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
+Requires-Dist: rich (>=13.0.0)
+Requires-Dist: scipy (>=1.16.3,<2.0.0)
+Requires-Dist: thermo (>=0.6.0)
+Requires-Dist: typer (>=0.20.0,<1.0.0)
+Project-URL: Homepage, https://github.com/eggplanta/thermo-utils
+Project-URL: Issues, https://github.com/eggplanta/thermo-utils/issues
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/eggplanta/thermo-utils/main/docs/logo-dark.png">
+  <img src="https://raw.githubusercontent.com/eggplanta/thermo-utils/main/docs/logo-light.png" alt="thermo-utils" width="560">
+</picture>
+
+![status](https://img.shields.io/badge/status-working-brightgreen)
+![python](https://img.shields.io/badge/python-3.12%2B-blue)
+[![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
+
+</div>
+
+**thermo-utils** is a command-line thermodynamics calculator for chemical engineering.
+It covers pure fluids, heat effects, flow devices, mixtures, phase equilibrium, chemical equilibrium and surface phenomena, and is accurate enough for design work.
+You only type the substance name: Tc, Pc, ω, Cp, ΔHf, Psat and the other data come from built-in databanks.
+
+## Screenshots
+
+<div align="center">
+
+<table>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/eggplanta/thermo-utils/main/docs/screenshots/menu.png" width="420"><br><sub>Main menu</sub></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/eggplanta/thermo-utils/main/docs/screenshots/property-change.png" width="420"><br><sub>Property change between two states</sub></td>
+  </tr>
+</table>
+
+</div>
+
+## Installation
+
+```bash
+pipx install thermo-utils
+```
+
+or `uv tool install thermo-utils`, or `pip install thermo-utils` inside a virtual environment.
+
+## Usage
+
+Run `thermo-utils` to open the interactive menu (Esc exits; the program closes after showing a result), or run a calculation directly:
+
+```bash
+thermo-utils delta water T1=25C P1=1atm T2=300C P2=20bar
+thermo-utils pump water T1=25C P1=1atm P2=50bar efficiency=0.75 flow=10kg/s
+thermo-utils diagram ethanol,water P=1atm --plot --open
+thermo-utils gibbs CH4,H2O,CO,CO2,H2 T=1000 P=1 feed=CH4=2,H2O=3
+thermo-utils list           # every calculation and its inputs
+thermo-utils info ammonia   # databank values of a substance
+```
+
+- **Units:** type them with the value (`25C`, `10atm`, `300cm3/mol`, `5kmol/h`), with no space so no quotes are needed. Without a unit the defaults are K, bar, cm³/mol and J/mol. Output units can be changed in the menu (`u`) or with `--T-unit`, `--P-unit`, `--E-unit`, `--V-unit`.
+- **Substances:** English names, formulas or CAS numbers (`water`, `H2O`, `7732-18-5`), right after the calculation name. Mixtures are comma separated (`ethanol,water`).
+- **Devices:** `pump`, `compressor`, `turbine` and `valve` are shortcuts for `device kind=...`.
+- **Plots:** saved as PNG in `./thermo-plots` (or `$THERMO_UTILS_PLOTS`) and opened on request.
+
+## Calculations
+
+**Pure fluids**
+- PVT with ideal gas, virial, van der Waals, RK, SRK, Peng-Robinson, fitted Peng-Robinson and reference EOS, with a side-by-side comparison
+- State properties: V, Z, H, S, U, G, A, Cp, Cv, φ, fugacity, κ, β, μJT, speed of sound
+- Property changes ΔH, ΔS, ΔU, ΔG, ΔA between two states, including phase change, with the residual-property path
+- Saturation (Psat, Tsat, ΔHvap)
+
+**Heat effects**
+- Sensible and latent heats (Riedel, Watson)
+- Adiabatic flame temperature
+
+**Flow devices**
+- One-step devices: compressor, pump, turbine and valve, with efficiency and power for a given flow
+
+**Mixtures**
+- Fugacity of species in mixtures (PR, SRK, virial) and the Lewis-Randall rule
+- Activity coefficients and excess properties: Margules, van Laar, Wilson, NRTL, UNIQUAC, UNIFAC, UNIFAC-Dortmund
+- Margules and van Laar fits from P-x-y data (CSV)
+
+**Phase equilibrium**
+- VLE: bubble/dew P and T and flash, using γ-φ, modified Raoult, Raoult or φ-φ, for multicomponent mixtures
+- Pxy, Txy and xy diagrams with azeotrope detection
+- LLE with the binodal curve, SLE (eutectic), solubility of solids, osmotic pressure
+
+**Chemical equilibrium**
+- K(T), ΔG° and ΔH° with rigorous ΔCp integration and the van 't Hoff plot
+- Equilibrium conversion of one reaction: ideal gas, gas with virial φ̂, ideal liquid or UNIFAC
+- Multi-reaction equilibrium by Gibbs energy minimization (no need to write the reactions)
+
+**Surface phenomena**
+- Surface tension σ(T) with surface entropy and enthalpy (databank, Brock-Bird, parachor)
+- Kelvin equation (vapor pressure over drops, bubbles and pores)
+- Adsorption isotherms (Langmuir, Freundlich, BET with specific surface area) fitted to CSV data
+- Gibbs adsorption isotherm (Szyszkowski fit), micellization (CMC, ΔG°mic)
+
+## Accuracy
+
+| Model | Use | Typical error |
+|---|---|---|
+| Reference EOS ([CoolProp](https://coolprop.org)) | ~120 common fluids (water, CO₂, hydrocarbons, refrigerants, air gases...) | < 0.1 % in density and enthalpy |
+| Fitted Peng-Robinson (Twu α + volume translation) | any substance in the databank | ~1 % in Psat, ~2 % in liquid density |
+| Peng-Robinson / SRK | any substance in the databank | 1-5 % for gases, 5-30 % for liquid volumes |
+| Virial (Pitzer) | gases at low to moderate pressure | < 1-2 % when Vr > 2 |
+| UNIFAC / NRTL / UNIQUAC (ChemSep) | liquid mixtures | azeotropes within ~0.5 K for common systems |
+
+The `auto` model uses the reference EOS when available and the fitted Peng-Robinson otherwise. Its α function and volume shift are fitted to the databank vapor pressure and liquid density of each substance.
+
+Every result starts with the equations used in the calculation.
+H, S, U, G and A share one reference state (ideal gas at 298.15 K and 1 bar), so differences between models are meaningful.
+Data come from [chemicals](https://github.com/CalebBell/chemicals), [thermo](https://github.com/CalebBell/thermo) and CoolProp.
+
+## Contributing
+
+Contributions are very welcome! thermo-utils still has a lot of room to grow, and I'd be happy to get your help.
+Found a wrong result, a missing substance or a bug? Have an idea for a new calculation? Open an [issue](https://github.com/eggplanta/thermo-utils/issues) or send a pull request.
+

thermo_utils-0.2.0/README.md

@@ -0,0 +1,112 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/eggplanta/thermo-utils/main/docs/logo-dark.png">
+  <img src="https://raw.githubusercontent.com/eggplanta/thermo-utils/main/docs/logo-light.png" alt="thermo-utils" width="560">
+</picture>
+
+![status](https://img.shields.io/badge/status-working-brightgreen)
+![python](https://img.shields.io/badge/python-3.12%2B-blue)
+[![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
+
+</div>
+
+**thermo-utils** is a command-line thermodynamics calculator for chemical engineering.
+It covers pure fluids, heat effects, flow devices, mixtures, phase equilibrium, chemical equilibrium and surface phenomena, and is accurate enough for design work.
+You only type the substance name: Tc, Pc, ω, Cp, ΔHf, Psat and the other data come from built-in databanks.
+
+## Screenshots
+
+<div align="center">
+
+<table>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/eggplanta/thermo-utils/main/docs/screenshots/menu.png" width="420"><br><sub>Main menu</sub></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/eggplanta/thermo-utils/main/docs/screenshots/property-change.png" width="420"><br><sub>Property change between two states</sub></td>
+  </tr>
+</table>
+
+</div>
+
+## Installation
+
+```bash
+pipx install thermo-utils
+```
+
+or `uv tool install thermo-utils`, or `pip install thermo-utils` inside a virtual environment.
+
+## Usage
+
+Run `thermo-utils` to open the interactive menu (Esc exits; the program closes after showing a result), or run a calculation directly:
+
+```bash
+thermo-utils delta water T1=25C P1=1atm T2=300C P2=20bar
+thermo-utils pump water T1=25C P1=1atm P2=50bar efficiency=0.75 flow=10kg/s
+thermo-utils diagram ethanol,water P=1atm --plot --open
+thermo-utils gibbs CH4,H2O,CO,CO2,H2 T=1000 P=1 feed=CH4=2,H2O=3
+thermo-utils list           # every calculation and its inputs
+thermo-utils info ammonia   # databank values of a substance
+```
+
+- **Units:** type them with the value (`25C`, `10atm`, `300cm3/mol`, `5kmol/h`), with no space so no quotes are needed. Without a unit the defaults are K, bar, cm³/mol and J/mol. Output units can be changed in the menu (`u`) or with `--T-unit`, `--P-unit`, `--E-unit`, `--V-unit`.
+- **Substances:** English names, formulas or CAS numbers (`water`, `H2O`, `7732-18-5`), right after the calculation name. Mixtures are comma separated (`ethanol,water`).
+- **Devices:** `pump`, `compressor`, `turbine` and `valve` are shortcuts for `device kind=...`.
+- **Plots:** saved as PNG in `./thermo-plots` (or `$THERMO_UTILS_PLOTS`) and opened on request.
+
+## Calculations
+
+**Pure fluids**
+- PVT with ideal gas, virial, van der Waals, RK, SRK, Peng-Robinson, fitted Peng-Robinson and reference EOS, with a side-by-side comparison
+- State properties: V, Z, H, S, U, G, A, Cp, Cv, φ, fugacity, κ, β, μJT, speed of sound
+- Property changes ΔH, ΔS, ΔU, ΔG, ΔA between two states, including phase change, with the residual-property path
+- Saturation (Psat, Tsat, ΔHvap)
+
+**Heat effects**
+- Sensible and latent heats (Riedel, Watson)
+- Adiabatic flame temperature
+
+**Flow devices**
+- One-step devices: compressor, pump, turbine and valve, with efficiency and power for a given flow
+
+**Mixtures**
+- Fugacity of species in mixtures (PR, SRK, virial) and the Lewis-Randall rule
+- Activity coefficients and excess properties: Margules, van Laar, Wilson, NRTL, UNIQUAC, UNIFAC, UNIFAC-Dortmund
+- Margules and van Laar fits from P-x-y data (CSV)
+
+**Phase equilibrium**
+- VLE: bubble/dew P and T and flash, using γ-φ, modified Raoult, Raoult or φ-φ, for multicomponent mixtures
+- Pxy, Txy and xy diagrams with azeotrope detection
+- LLE with the binodal curve, SLE (eutectic), solubility of solids, osmotic pressure
+
+**Chemical equilibrium**
+- K(T), ΔG° and ΔH° with rigorous ΔCp integration and the van 't Hoff plot
+- Equilibrium conversion of one reaction: ideal gas, gas with virial φ̂, ideal liquid or UNIFAC
+- Multi-reaction equilibrium by Gibbs energy minimization (no need to write the reactions)
+
+**Surface phenomena**
+- Surface tension σ(T) with surface entropy and enthalpy (databank, Brock-Bird, parachor)
+- Kelvin equation (vapor pressure over drops, bubbles and pores)
+- Adsorption isotherms (Langmuir, Freundlich, BET with specific surface area) fitted to CSV data
+- Gibbs adsorption isotherm (Szyszkowski fit), micellization (CMC, ΔG°mic)
+
+## Accuracy
+
+| Model | Use | Typical error |
+|---|---|---|
+| Reference EOS ([CoolProp](https://coolprop.org)) | ~120 common fluids (water, CO₂, hydrocarbons, refrigerants, air gases...) | < 0.1 % in density and enthalpy |
+| Fitted Peng-Robinson (Twu α + volume translation) | any substance in the databank | ~1 % in Psat, ~2 % in liquid density |
+| Peng-Robinson / SRK | any substance in the databank | 1-5 % for gases, 5-30 % for liquid volumes |
+| Virial (Pitzer) | gases at low to moderate pressure | < 1-2 % when Vr > 2 |
+| UNIFAC / NRTL / UNIQUAC (ChemSep) | liquid mixtures | azeotropes within ~0.5 K for common systems |
+
+The `auto` model uses the reference EOS when available and the fitted Peng-Robinson otherwise. Its α function and volume shift are fitted to the databank vapor pressure and liquid density of each substance.
+
+Every result starts with the equations used in the calculation.
+H, S, U, G and A share one reference state (ideal gas at 298.15 K and 1 bar), so differences between models are meaningful.
+Data come from [chemicals](https://github.com/CalebBell/chemicals), [thermo](https://github.com/CalebBell/thermo) and CoolProp.
+
+## Contributing
+
+Contributions are very welcome! thermo-utils still has a lot of room to grow, and I'd be happy to get your help.
+Found a wrong result, a missing substance or a bug? Have an idea for a new calculation? Open an [issue](https://github.com/eggplanta/thermo-utils/issues) or send a pull request.

thermo_utils-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "thermo-utils"
+version = "0.2.0"
+description = "A thermodynamics calculator for chemical engineering, from homework to plant design"
+
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Dspavier" }]
+keywords = ["thermodynamics", "chemical engineering", "equation of state", "phase equilibrium", "calculator"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "typer (>=0.20.0,<1.0.0)",
+    "rich (>=13.0.0)",
+    "scipy (>=1.16.3,<2.0.0)",
+    "numpy (>=2.0.0)",
+    "CoolProp (>=7.0.0)",
+    "thermo (>=0.6.0)",
+    "chemicals (>=1.5.0)",
+    "matplotlib (>=3.9.0)"
+]
+
+[project.urls]
+Homepage = "https://github.com/eggplanta/thermo-utils"
+Issues = "https://github.com/eggplanta/thermo-utils/issues"
+
+[project.optional-dependencies]
+dev = ["pytest (>=8.0.0)"]
+
+[project.scripts]
+thermo-utils = "thermo_utils.cli:main"
+
+[tool.poetry]
+packages = [{include = "thermo_utils", from = "src"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

thermo_utils-0.2.0/src/thermo_utils/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

thermo_utils-0.2.0/src/thermo_utils/activity.py

@@ -0,0 +1,118 @@
+"""Excess Gibbs energy models."""
+
+import math
+
+import numpy as np
+from thermo import NRTL, UNIQUAC, IdealSolution
+from thermo.interaction_parameters import IPDB
+from thermo.unifac import DOUFIP2016, DOUFSG, UFIP, UFSG, UNIFAC
+
+from thermo_utils.units import R
+
+MODELS = {
+    "unifac": "UNIFAC (predictive, original)",
+    "unifac-do": "Modified UNIFAC (Dortmund)",
+    "nrtl": "NRTL (ChemSep parameters or yours)",
+    "uniquac": "UNIQUAC (ChemSep parameters)",
+    "wilson": "Wilson (binary, your Λ12 and Λ21)",
+    "margules": "Margules two-parameter (binary, your A12 and A21)",
+    "vanlaar": "van Laar (binary, your A'12 and A'21)",
+    "ideal": "Ideal solution (γ = 1, Raoult)",
+}
+
+
+class GEModel:
+    """Activity coefficients for a fixed set of components."""
+
+    def __init__(self, subs, name="unifac", params=None):
+        self.subs = subs
+        self.name = name
+        self.params = list(params or [])
+        self.notes = []
+        n = len(subs)
+        if name in ("margules", "vanlaar", "wilson") and n != 2:
+            raise ValueError(f"{name} is implemented for binary mixtures.")
+        if name in ("margules", "vanlaar", "wilson") and len(self.params) != 2:
+            raise ValueError(f"{name} needs two parameters, e.g. params=1.2,0.8")
+        if name == "nrtl" and not self.params:
+            cas = [s.cas for s in subs]
+            self._b = IPDB.get_ip_asymmetric_matrix("ChemSep NRTL", cas, "bij")
+            self._alpha = IPDB.get_ip_asymmetric_matrix("ChemSep NRTL", cas, "alphaij")
+            if not any(any(r) for r in self._b):
+                raise ValueError("No NRTL parameters in the databank for this mixture; give b12,b21,alpha or use UNIFAC.")
+            self.notes.append("NRTL parameters from the ChemSep databank (τij = bij/T).")
+        elif name == "nrtl":
+            if n != 2 or len(self.params) not in (2, 3):
+                raise ValueError("Give NRTL params as b12,b21[,alpha] in K (binary).")
+            b12, b21 = self.params[:2]
+            a = self.params[2] if len(self.params) == 3 else 0.3
+            self._b = [[0, b12], [b21, 0]]
+            self._alpha = [[0, a], [a, 0]]
+        if name == "uniquac":
+            cas = [s.cas for s in subs]
+            self._b = IPDB.get_ip_asymmetric_matrix("ChemSep UNIQUAC", cas, "bij")
+            if not any(any(r) for r in self._b):
+                raise ValueError("No UNIQUAC parameters in the databank for this mixture; use UNIFAC.")
+            self.notes.append("UNIQUAC parameters from the ChemSep databank.")
+        if name.startswith("unifac"):
+            for s in subs:
+                if not s.unifac_groups:
+                    raise ValueError(f"No UNIFAC groups for {s.name}.")
+
+    def _thermo(self, T, xs):
+        n = len(xs)
+        if self.name == "nrtl":
+            return NRTL(T=T, xs=xs, tau_bs=self._b, alpha_cs=self._alpha)
+        if self.name == "uniquac":
+            return UNIQUAC(T=T, xs=xs, rs=[s.r for s in self.subs], qs=[s.q for s in self.subs], tau_bs=self._b)
+        if self.name == "unifac":
+            return UNIFAC.from_subgroups(T=T, xs=xs, chemgroups=[s.unifac_groups for s in self.subs],
+                                         version=0, interaction_data=UFIP, subgroups=UFSG)
+        if self.name == "unifac-do":
+            groups = [s._constants.UNIFAC_Dortmund_groups[0] for s in self.subs]
+            return UNIFAC.from_subgroups(T=T, xs=xs, chemgroups=groups, version=1,
+                                         interaction_data=DOUFIP2016, subgroups=DOUFSG)
+        return IdealSolution(T=T, xs=xs) if n else None
+
+    def ln_gammas(self, T, xs):
+        xs = [max(float(x), 0.0) for x in xs]
+        if self.name == "margules":
+            A12, A21 = self.params
+            x1, x2 = xs
+            return [x2**2 * (A12 + 2 * (A21 - A12) * x1), x1**2 * (A21 + 2 * (A12 - A21) * x2)]
+        if self.name == "vanlaar":
+            A12, A21 = self.params
+            x1, x2 = xs
+            d = A12 * x1 + A21 * x2
+            return [A12 * (A21 * x2 / d) ** 2, A21 * (A12 * x1 / d) ** 2]
+        if self.name == "wilson":
+            L12, L21 = self.params
+            x1, x2 = xs
+            s = L12 / (x1 + x2 * L12) - L21 / (x2 + x1 * L21)
+            return [-math.log(x1 + x2 * L12) + x2 * s, -math.log(x2 + x1 * L21) - x1 * s]
+        return [math.log(g) for g in self._thermo(T, _safe(xs)).gammas()]
+
+    def gammas(self, T, xs):
+        return [math.exp(v) for v in self.ln_gammas(T, xs)]
+
+    def GE(self, T, xs):
+        return R * T * sum(x * lg for x, lg in zip(xs, self.ln_gammas(T, xs)))
+
+    def HE(self, T, xs, dT=0.01):
+        g = lambda t: self.GE(t, xs) / t
+        return -T**2 * (g(T + dT) - g(T - dT)) / (2 * dT)
+
+    def SE(self, T, xs):
+        return (self.HE(T, xs) - self.GE(T, xs)) / T
+
+
+def _safe(xs):
+    xs = [max(x, 1e-12) for x in xs]
+    s = sum(xs)
+    return [x / s for x in xs]
+
+
+def binary_curve(model, T, n=101):
+    x1 = np.linspace(0, 1, n)
+    ln_g = np.array([model.ln_gammas(T, [max(x, 1e-9), max(1 - x, 1e-9)]) for x in x1])
+    return x1, ln_g