thermo-utils 0.2.0__py3-none-any.whl

thermo_utils/__init__.py

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

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

thermo_utils/calcs.py

@@ -0,0 +1,269 @@
+"""Registry of calculations: one entry drives both the menu and the command line."""
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from thermo_utils import (
+    activity, chemical_equilibrium, devices, heat, mixtures, properties, substances, surface, vle,
+)
+from thermo_utils.pure import MODELS
+from thermo_utils.units import (
+    CONCENTRATION, LENGTH, MASS_FLOW, MOLAR_FLOW, PRESSURE, TEMPERATURE, MOLAR_VOLUME,
+    parse_quantity,
+)
+
+SUBSTANCE = "substance"
+SUBSTANCES = "substances"
+QUANTITY = "quantity"
+NUMBER = "number"
+INTEGER = "integer"
+CHOICE = "choice"
+TEXT = "text"
+LIST = "list"
+FLOW = "flow"
+
+
+@dataclass
+class Field:
+    name: str
+    label: str
+    type: str
+    qkind: str = None
+    optional: bool = False
+    default: object = None
+    choices: dict = None
+    help: str = ""
+
+
+@dataclass
+class Calc:
+    id: str
+    group: str
+    title: str
+    fn: Callable
+    fields: list = field(default_factory=list)
+    help: str = ""
+
+
+def parse_value(f, text):
+    text = text.strip()
+    if text == "":
+        if f.optional or f.default is not None:
+            return f.default
+        raise ValueError(f"{f.label} is required")
+    if f.type == SUBSTANCE:
+        return substances.get(text)
+    if f.type == SUBSTANCES:
+        return [substances.get(t) for t in _split(text)]
+    if f.type == QUANTITY:
+        return parse_quantity(text, f.qkind)
+    if f.type == NUMBER:
+        return float(text.replace(",", ".")) if "/" not in text else _ratio(text)
+    if f.type == INTEGER:
+        return int(text)
+    if f.type == LIST:
+        return [float(t.replace(",", ".")) for t in _split(text)]
+    if f.type == CHOICE:
+        key = text.lower()
+        if key not in f.choices:
+            raise ValueError(f"Options for {f.label}: {', '.join(f.choices)}")
+        return key
+    if f.type == FLOW:
+        return _parse_flow(text)
+    return text
+
+
+def _split(text):
+    sep = ";" if ";" in text else ","
+    return [t.strip() for t in text.split(sep) if t.strip()]
+
+
+def _ratio(text):
+    a, b = text.split("/")
+    return float(a) / float(b)
+
+
+def _parse_flow(text):
+    from thermo_utils.units import _NUMBER, _norm, _FACTORS, to_si
+    m = _NUMBER.match(text.replace(",", "."))
+    if not m:
+        raise ValueError("Flow must look like '10 kg/s' or '5 kmol/h'")
+    value, unit = float(m.group(1)), _norm(m.group(2) or "kg/s")
+    if unit in _FACTORS[MASS_FLOW]:
+        return ("mass", to_si(value, unit, MASS_FLOW))
+    if unit in _FACTORS[MOLAR_FLOW]:
+        return ("molar", to_si(value, unit, MOLAR_FLOW))
+    raise ValueError(f"Unknown flow unit '{unit}'")
+
+
+MODEL_FIELD = Field("model", "Model", CHOICE, default="auto", choices=MODELS)
+FLOW_FIELD = Field("flow", "Flow rate (e.g. 2 kg/s, 10 kmol/h)", FLOW, optional=True,
+                   help="Optional. Gives the power in kW.")
+
+
+def _q(name, label, qkind, optional=False, default=None, help=""):
+    return Field(name, label, QUANTITY, qkind, optional, default, help=help)
+
+
+def _sub(name="sub", label="Substance"):
+    return Field(name, label, SUBSTANCE, help="Name, formula or CAS")
+
+
+PURE = "Pure fluids"
+HEAT = "Heat effects"
+DEVICES = "Flow devices"
+MIX = "Mixtures"
+PHASE = "Phase equilibrium"
+REACT = "Chemical equilibrium"
+SURF = "Surface phenomena"
+
+CALCS = [
+    Calc("info", PURE, "Substance data (Tc, Pc, ω, Cp, ΔHf...)", properties.substance_info, [_sub()]),
+    Calc("pvt", PURE, "PVT: solve P, V or T (any EOS) + model comparison", properties.pvt, [
+        _sub(), _q("T_", "T", TEMPERATURE, True), _q("P_", "P", PRESSURE, True),
+        _q("V_", "V (molar)", MOLAR_VOLUME, True), MODEL_FIELD,
+    ], "Leave empty the variable you want to calculate."),
+    Calc("state", PURE, "State properties (V, Z, H, S, U, G, A, Cp, φ...)", properties.state_properties, [
+        _sub(), _q("T_", "T", TEMPERATURE, True), _q("P_", "P", PRESSURE, True),
+        Field("x", "Vapor fraction (two-phase only)", NUMBER, optional=True), MODEL_FIELD,
+    ], "Give T and P, or a vapor fraction with T or P."),
+    Calc("delta", PURE, "Property change ΔH, ΔS, ΔU, ΔG, ΔA between two states", properties.property_change, [
+        _sub(), _q("T1", "T1", TEMPERATURE, True), _q("P1", "P1", PRESSURE, True),
+        Field("x1", "Vapor fraction 1 (two-phase only)", NUMBER, optional=True),
+        _q("T2", "T2", TEMPERATURE, True), _q("P2", "P2", PRESSURE, True),
+        Field("x2", "Vapor fraction 2 (two-phase only)", NUMBER, optional=True), MODEL_FIELD,
+    ], "Each state: T and P, or a vapor fraction with T or P. Phase changes are handled."),
+    Calc("saturation", PURE, "Saturation: Psat/Tsat, ΔHvap, saturated volumes", properties.saturation, [
+        _sub(), _q("T_", "T", TEMPERATURE, True), _q("P_", "P", PRESSURE, True), MODEL_FIELD,
+    ], "Give T or P."),
+    Calc("sensible", HEAT, "Sensible heat ∫Cp dT and mean heat capacities", heat.sensible_heat, [
+        _sub(), _q("T1", "T1", TEMPERATURE), _q("T2", "T2", TEMPERATURE),
+        Field("phase", "Phase", CHOICE, default="gas", choices={"gas": "ideal gas", "liquid": "liquid"}),
+    ]),
+    Calc("latent", HEAT, "Latent heats (databank, Riedel, Watson, fusion)", heat.latent_heat, [
+        _sub(), _q("T_", "T (default: normal boiling point)", TEMPERATURE, True),
+    ]),
+    Calc("flame", HEAT, "Adiabatic flame temperature", heat.adiabatic_flame, [
+        _sub("fuel", "Fuel"), Field("excess_air", "Excess air fraction (0.2 = 20 %)", NUMBER, default=0.0),
+        _q("T_in", "Inlet temperature", TEMPERATURE, default=298.15),
+    ]),
+    Calc("device", DEVICES, "Compressor, pump, turbine or valve (one step)", devices.flow_device, [
+        _sub(), Field("kind", "Device", CHOICE, choices={
+            "compressor": "compressor", "pump": "pump", "turbine": "turbine/expander", "valve": "throttle valve"}),
+        _q("T1", "Inlet T", TEMPERATURE), _q("P1", "Inlet P", PRESSURE), _q("P2", "Outlet P", PRESSURE),
+        Field("efficiency", "Isentropic efficiency (0-1)", NUMBER, default=1.0), MODEL_FIELD, FLOW_FIELD,
+    ]),
+]
+
+
+GE_FIELD = Field("model", "Activity model", CHOICE, default="unifac", choices=activity.MODELS)
+PARAMS_FIELD = Field("params", "Model parameters (Margules A12,A21 / van Laar / Wilson Λ12,Λ21 / NRTL b12,b21,α)",
+                     LIST, optional=True, help="Only for models that need them.")
+SUBS_FIELD = Field("subs", "Substances (comma separated)", SUBSTANCES)
+COMP_HELP = "Mole fractions in the same order; the last one may be omitted."
+
+
+def _comp(name="zs", label="Mole fractions"):
+    return Field(name, f"{label} (e.g. 0.3,0.7)", LIST, help=COMP_HELP)
+
+
+CALCS += [
+    Calc("fugacity-mix", MIX, "Fugacity and φ̂ of species in a mixture (PR, SRK or virial)", mixtures.mixture_fugacity, [
+        SUBS_FIELD, _q("T_", "T", TEMPERATURE), _q("P_", "P", PRESSURE), _comp("ys"),
+        Field("model", "Model", CHOICE, default="pr", choices={"pr": "Peng-Robinson", "srk": "SRK", "virial": "virial"}),
+    ]),
+    Calc("activity", MIX, "Activity coefficients, G^E, H^E, mixing properties", mixtures.activity_coefficients, [
+        SUBS_FIELD, _q("T_", "T", TEMPERATURE), _comp("xs"), GE_FIELD, PARAMS_FIELD,
+    ]),
+    Calc("vle", PHASE, "VLE: bubble/dew P or T, flash (γ-φ, modified Raoult, φ-φ)", mixtures.vle_calc, [
+        SUBS_FIELD, Field("kind", "Calculation", CHOICE, choices={
+            "bubble-p": "bubble P (give T, x)", "dew-p": "dew P (give T, y)", "bubble-t": "bubble T (give P, x)",
+            "dew-t": "dew T (give P, y)", "flash": "flash (give T, P, z)"}),
+        _q("T_", "T", TEMPERATURE, True), _q("P_", "P", PRESSURE, True), _comp("zs", "Composition x, y or z"),
+        Field("method", "Method", CHOICE, default="gamma-phi", choices=vle.METHODS), GE_FIELD, PARAMS_FIELD,
+    ]),
+    Calc("diagram", PHASE, "Binary Pxy / Txy / xy diagram and azeotrope", mixtures.binary_diagram, [
+        SUBS_FIELD, _q("T_", "T (for Pxy)", TEMPERATURE, True), _q("P_", "P (for Txy)", PRESSURE, True),
+        Field("method", "Method", CHOICE, default="gamma-phi", choices=vle.METHODS), GE_FIELD, PARAMS_FIELD,
+    ], "Give T for a Pxy diagram or P for a Txy diagram."),
+    Calc("fit", MIX, "Fit Margules / van Laar to P-x-y data (CSV)", mixtures.fit_parameters, [
+        SUBS_FIELD, _q("T_", "T of the data", TEMPERATURE),
+        Field("path", "CSV file with columns P, x1, y1", TEXT),
+        Field("model", "Model", CHOICE, default="margules", choices={"margules": "Margules", "vanlaar": "van Laar"}),
+    ], "Header like 'P (kPa),x1,y1' sets the pressure unit."),
+    Calc("lle", PHASE, "Liquid-liquid equilibrium (binary) + binodal curve", mixtures.lle, [
+        SUBS_FIELD, _q("T_", "T", TEMPERATURE), GE_FIELD, PARAMS_FIELD,
+    ]),
+    Calc("sle", PHASE, "Solid-liquid equilibrium: eutectic diagram (binary)", mixtures.sle, [
+        SUBS_FIELD, Field("model", "Activity model", CHOICE, default="ideal", choices=activity.MODELS), PARAMS_FIELD,
+    ]),
+    Calc("solubility", PHASE, "Solubility of a solid in a liquid", mixtures.solubility, [
+        _sub("solute", "Solid solute"), _q("T_", "T", TEMPERATURE),
+        Field("solvent", "Solvent (optional)", SUBSTANCE, optional=True),
+        Field("model", "Activity model", CHOICE, default="ideal", choices=activity.MODELS),
+    ]),
+    Calc("osmotic", PHASE, "Osmotic pressure", mixtures.osmotic, [
+        _sub("solvent", "Solvent"), _sub("solute", "Solute"), _q("T_", "T", TEMPERATURE),
+        Field("x_solute", "Solute mole fraction", NUMBER),
+        Field("model", "Activity model", CHOICE, default="ideal", choices=activity.MODELS),
+    ]),
+    Calc("k", REACT, "Equilibrium constant K(T), ΔG°, ΔH° of a reaction", chemical_equilibrium.equilibrium_constant, [
+        Field("reaction", "Reaction (e.g. N2 + 3 H2 -> 2 NH3)", TEXT), _q("T_", "T", TEMPERATURE),
+    ]),
+    Calc("equilibrium", REACT, "Equilibrium conversion of one reaction", chemical_equilibrium.single_reaction, [
+        Field("reaction", "Reaction (e.g. CO + H2O -> CO2 + H2)", TEXT), _q("T_", "T", TEMPERATURE),
+        _q("P_", "P", PRESSURE, default=1e5), Field("feed", "Feed in mol (e.g. CO=1, H2O=2, N2=0.5)", TEXT),
+        Field("phase_model", "Phase model", CHOICE, default="ideal", choices={
+            "ideal": "ideal gas", "virial": "gas with virial φ̂", "ideal-liquid": "ideal liquid",
+            "unifac": "liquid with UNIFAC γ"}),
+    ], "Species in the feed that are not in the reaction are inerts."),
+    Calc("gibbs", REACT, "Multi-reaction equilibrium (Gibbs energy minimization)", chemical_equilibrium.gibbs_minimization, [
+        Field("species", "All species that may be present (comma separated)", SUBSTANCES),
+        _q("T_", "T", TEMPERATURE), _q("P_", "P", PRESSURE, default=1e5),
+        Field("feed", "Feed in mol (e.g. CH4=2, H2O=3)", TEXT),
+    ], "Ideal-gas mixture. No need to write the reactions."),
+]
+
+CALCS += [
+    Calc("surface-tension", SURF, "Surface tension σ(T), surface entropy and enthalpy", surface.surface_tension, [
+        _sub(), _q("T_", "T", TEMPERATURE),
+    ]),
+    Calc("kelvin", SURF, "Kelvin equation: vapor pressure over a curved surface", surface.kelvin, [
+        _sub(), _q("T_", "T", TEMPERATURE), _q("r", "Radius of curvature", LENGTH),
+        Field("kind", "Surface", CHOICE, default="drop", choices={
+            "drop": "drop (convex)", "bubble": "bubble or capillary (concave)"}),
+    ]),
+    Calc("adsorption", SURF, "Adsorption isotherms: Langmuir, Freundlich, BET (CSV)", surface.adsorption, [
+        Field("path", "CSV file with columns P, q", TEXT),
+        Field("model", "Model", CHOICE, default="all", choices={
+            "all": "all", "langmuir": "Langmuir", "freundlich": "Freundlich", "bet": "BET"}),
+        Field("adsorbate", "Adsorbate (for BET P0 and area)", SUBSTANCE, optional=True),
+        _q("T_", "T (for BET)", TEMPERATURE, True), _q("P0", "P0 (optional, BET)", PRESSURE, True),
+        Field("cross_section", "Area per molecule in nm² (optional, BET)", NUMBER, optional=True),
+    ], "Header like 'P (kPa),q (mmol/g)' sets the units."),
+    Calc("gibbs-adsorption", SURF, "Gibbs adsorption isotherm (surface excess from σ vs c)", surface.gibbs_adsorption, [
+        Field("path", "CSV file with columns c, σ", TEXT), _q("T_", "T", TEMPERATURE),
+        Field("n", "n (1 nonionic, 2 ionic 1:1 without salt)", INTEGER, default=1),
+    ], "Header like 'c (mmol/L),sigma (mN/m)' sets the units."),
+    Calc("micelles", SURF, "Micellization: CMC and ΔG°mic", surface.micelles, [
+        _q("T_", "T", TEMPERATURE), _q("cmc", "CMC (or leave empty and give a CSV)", CONCENTRATION, True),
+        Field("beta", "Counterion binding β (0 for nonionic)", NUMBER, default=0.0),
+        _q("T2", "Second T (optional, for ΔH)", TEMPERATURE, True),
+        _q("cmc2", "CMC at the second T (optional)", CONCENTRATION, True),
+        Field("path", "CSV file with columns c, σ (optional)", TEXT, optional=True),
+    ]),
+]
+
+
+def by_id(calc_id):
+    for c in CALCS:
+        if c.id == calc_id:
+            return c
+    raise KeyError(calc_id)
+
+
+def groups():
+    out = {g: [] for g in (PURE, HEAT, DEVICES, MIX, PHASE, REACT, SURF)}
+    for c in CALCS:
+        out.setdefault(c.group, []).append(c)
+    return out

thermo_utils/chemical_equilibrium.py

@@ -0,0 +1,218 @@
+"""Chemical reaction equilibrium."""
+
+import math
+
+import numpy as np
+from chemicals.elements import simple_formula_parser
+from scipy.optimize import brentq, minimize
+
+from thermo_utils import activity, reactions, substances, vle
+from thermo_utils.result import Result, row
+from thermo_utils.units import (
+    MOLAR_ENERGY as E, MOLAR_ENTROPY as S, PRESSURE as P, TEMPERATURE as T, R, display, fmt, from_si,
+)
+
+P0 = 1e5
+
+
+def equilibrium_constant(reaction, T_):
+    rx = reactions.parse(reaction)
+    dG, dH = rx.dG(T_), rx.dH(T_)
+    K = math.exp(-dG / (R * T_))
+    K_vh = math.exp(-rx.dG0() / (R * 298.15) - rx.dH0() / R * (1 / T_ - 1 / 298.15))
+    res = Result("Equilibrium constant")
+    res.section(rx.pretty(), [
+        row("ΔG° at 298.15 K", rx.dG0(), E), row("ΔH° at 298.15 K", rx.dH0(), E),
+        row(f"ΔG° at {fmt(T_, T)}", dG, E), row(f"ΔH° at {fmt(T_, T)}", dH, E),
+        row(f"ΔS° at {fmt(T_, T)}", rx.dS(T_), S),
+        row("K (rigorous, ΔCp included)", f"{K:.6g}"),
+        row("ln K", f"{math.log(K):.6g}"),
+        row("K (short-cut van 't Hoff, ΔH constant)", f"{K_vh:.6g}"),
+    ])
+    res.notes.append("Standard state: ideal gas at 1 bar (g) or pure liquid at 1 bar (l).")
+
+    def plot():
+        import matplotlib.pyplot as plt
+        Ts = np.linspace(max(250, T_ - 400), T_ + 400, 120)
+        lnK = [-rx.dG(t) / (R * t) for t in Ts]
+        fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))
+        ax1.plot(1 / Ts, lnK)
+        ax1.plot(1 / T_, math.log(K), "ko")
+        ax1.set_xlabel("1/T (1/K)"); ax1.set_ylabel("ln K"); ax1.set_title("van 't Hoff plot")
+        ax2.plot([from_si(t, display.temperature, T) for t in Ts], [rx.dG(t) / 1000 for t in Ts])
+        ax2.axhline(0, color="k", lw=0.8)
+        ax2.set_xlabel(f"T ({display.temperature})"); ax2.set_ylabel("ΔG° (kJ/mol)"); ax2.set_title("ΔG° vs T")
+        for ax in (ax1, ax2):
+            ax.grid(alpha=0.3)
+        fig.tight_layout()
+        return fig
+
+    res.plot = plot
+    res.plot_name = "lnK"
+    return res
+
+
+# Single reaction
+
+def _parse_feed(text):
+    feed = {}
+    if not text:
+        return feed
+    for part in text.replace(";", ",").split(","):
+        if "=" not in part:
+            raise ValueError("Feed must look like 'CH4=1, H2O=2, N2=0.5' (moles).")
+        k, v = part.split("=", 1)
+        feed[substances.get(k.strip())] = float(v)
+    return feed
+
+
+def _setup(rx, feed):
+    names = [sp.sub for sp in rx.species]
+    n0 = [feed.pop(s, 0.0) for s in names]
+    nu = [sp.nu for sp in rx.species]
+    inert = list(feed.items())
+    return names, n0, nu, inert
+
+
+def single_reaction(reaction, T_, P_, feed, phase_model="ideal"):
+    """Equilibrium extent of one reaction."""
+    rx = reactions.parse(reaction, "l" if phase_model in ("ideal-liquid", "unifac") else "g")
+    feed = _parse_feed(feed)
+    subs, n0, nu, inert = _setup(rx, dict(feed))
+    if sum(n0) <= 0:
+        raise ValueError("Give the feed in moles of at least one reactant.")
+    K = rx.K(T_)
+    liquid = all(sp.phase == "l" for sp in rx.species)
+    lo = max([-n / v for n, v in zip(n0, nu) if v > 0] + [-1e300])
+    hi = min([n / -v for n, v in zip(n0, nu) if v < 0] + [1e300])
+    if hi > 1e299 or lo < -1e299:
+        raise ValueError("The feed must allow the reaction to proceed in both directions or one with limits.")
+    span = hi - lo
+    eps_lo, eps_hi = lo + 1e-12 * span, hi - 1e-12 * span
+    ge = activity.GEModel(subs + [s for s, _ in inert], "unifac") if phase_model == "unifac" else None
+
+    def comp(e):
+        n = [a + v * e for a, v in zip(n0, nu)] + [v for _, v in inert]
+        tot = sum(n)
+        return [x / tot for x in n]
+
+    def ln_activity(e):
+        ys = comp(e)
+        if liquid:
+            g = ge.gammas(T_, ys) if ge else [1.0] * len(ys)
+            return [math.log(max(y, 1e-300) * gi) for y, gi in zip(ys, g)][: len(subs)]
+        phis = [1.0] * len(ys)
+        if phase_model == "virial":
+            phis = vle.virial_phis(subs + [s for s, _ in inert], T_, P_, ys)[0]
+        return [math.log(max(y, 1e-300) * f * P_ / P0) for y, f in zip(ys, phis)][: len(subs)]
+
+    f = lambda e: sum(v * la for v, la in zip(nu, ln_activity(e))) - math.log(K)
+    f_lo, f_hi = f(eps_lo), f(eps_hi)
+    if f_lo * f_hi > 0:
+        eps = eps_hi if f_hi < 0 else eps_lo
+        complete = True
+    else:
+        eps = brentq(f, eps_lo, eps_hi, xtol=1e-14, maxiter=500)
+        complete = False
+    ys = comp(eps)
+    res = Result("Single-reaction equilibrium")
+    res.section(rx.pretty(), [
+        row("T", T_, T), row("P", P_, P), row("K", f"{K:.6g}"), row("ΔG°(T)", rx.dG(T_), E),
+        row("Equilibrium extent ε", f"{eps:.6g} mol"),
+    ])
+    key = next(i for i, v in enumerate(nu) if v < 0 and n0[i] > 0)
+    conv = -nu[key] * eps / n0[key]
+    res.section("Equilibrium", [row(f"Conversion of {subs[key].name}", f"{conv * 100:.5g} %")] + [
+        row(s.name, f"n = {n0[i] + nu[i] * eps:.6g} mol   {'x' if liquid else 'y'} = {ys[i]:.6f}")
+        for i, s in enumerate(subs)
+    ] + [row(f"{s.name} (inert)", f"n = {v:.6g} mol   y = {ys[len(subs) + j]:.6f}") for j, (s, v) in enumerate(inert)])
+    if complete:
+        res.notes.append("K is so far from 1 that the reaction goes to the limit of the feed.")
+    res.notes.append({"ideal": "Ideal-gas mixture: Π(yi P/P°)^νi = K.",
+                      "virial": "Gas with virial fugacity coefficients: Π(yi φ̂i P/P°)^νi = K.",
+                      "ideal-liquid": "Ideal liquid solution: Π(xi)^νi = K.",
+                      "unifac": "Liquid with UNIFAC activity coefficients: Π(xi γi)^νi = K."}[phase_model])
+
+    def plot():
+        import matplotlib.pyplot as plt
+        Ts = np.linspace(max(250, T_ - 300), T_ + 300, 60)
+        xs = []
+        for t in Ts:
+            try:
+                xs.append((from_si(t, display.temperature, T), single_reaction_conv(reaction, t, P_, feed, phase_model)))
+            except Exception:
+                pass
+        fig, ax = plt.subplots(figsize=(8, 5))
+        if xs:
+            ax.plot(*zip(*xs))
+        ax.plot(from_si(T_, display.temperature, T), conv * 100, "ko")
+        ax.set_xlabel(f"T ({display.temperature})"); ax.set_ylabel(f"Conversion of {subs[key].name} (%)")
+        ax.set_title(f"Equilibrium conversion at {fmt(P_, P)}"); ax.grid(alpha=0.3)
+        fig.tight_layout()
+        return fig
+
+    res.plot = plot
+    res.plot_name = "conversion"
+    res.data = {"extent": eps, "conversion": conv}
+    return res
+
+
+def single_reaction_conv(text, T_, P_, feed_dict, phase_model):
+    feed = ", ".join(f"{s.cas}={v}" for s, v in feed_dict.items())
+    return single_reaction(text, T_, P_, feed, phase_model).data["conversion"] * 100
+
+
+# Multi-reaction (Gibbs energy minimization)
+
+def _g0(sub, T_):
+    """Molar Gibbs energy of the ideal gas at T and 1 bar, elements in standard state at 298.15 K."""
+    substances.require(sub, "Hf", "S0")
+    H = sub.Hf + sub.H_ig(298.15, T_)
+    S_ = sub.S0 + sub.S_ig(298.15, T_)
+    return H - T_ * S_
+
+
+def gibbs_minimization(species, T_, P_, feed):
+    """Equilibrium of a gas mixture by minimizing G with element balances."""
+    feed_d = _parse_feed(feed)
+    for s in feed_d:
+        if s not in species:
+            species = species + [s]
+    elements = sorted({el for s in species for el in simple_formula_parser(s.formula)})
+    A = np.array([[simple_formula_parser(s.formula).get(el, 0) for s in species] for el in elements], float)
+    n0 = np.array([feed_d.get(s, 0.0) for s in species])
+    b = A @ n0
+    g = np.array([_g0(s, T_) / (R * T_) for s in species])
+    lnP = math.log(P_ / P0)
+    scale = max(n0.sum(), 1e-12)
+
+    def G(n):
+        n = np.maximum(n, 1e-30)
+        return float(np.sum(n * (g + np.log(n / n.sum()) + lnP))) / scale
+
+    def grad(n):
+        n = np.maximum(n, 1e-30)
+        return (g + np.log(n / n.sum()) + lnP) / scale
+
+    start = np.linalg.lstsq(A, b, rcond=None)[0]
+    start = np.maximum(start, 0) + 0.1 * scale / len(species)
+    start = start * 0.5 + n0 * 0.5 + 1e-6
+    sol = minimize(G, start, jac=grad, method="SLSQP", bounds=[(1e-20, None)] * len(species),
+                   constraints=[{"type": "eq", "fun": lambda n: (A @ n - b) / scale, "jac": lambda n: A / scale}],
+                   options={"ftol": 1e-15, "maxiter": 1000})
+    if not sol.success:
+        raise ValueError(f"Gibbs minimization did not converge: {sol.message}")
+    n = sol.x
+    y = n / n.sum()
+    res = Result("Multi-reaction equilibrium (Gibbs energy minimization)")
+    res.section("Conditions", [row("T", T_, T), row("P", P_, P),
+                               row("Elements", ", ".join(elements)),
+                               row("Total moles at equilibrium", f"{n.sum():.6g} mol")])
+    res.section("Equilibrium composition", [
+        row(s.name, f"n = {ni:.6g} mol   y = {yi:.6f}   (fed {n0i:g})") for s, ni, yi, n0i in zip(species, n, y, n0)
+    ])
+    lam = g + np.log(y) + lnP
+    res.notes.append("Ideal-gas mixture; Lagrange multipliers satisfied when Σ λk aik = Gi/RT for every species.")
+    res.notes.append(f"Max element-balance error: {np.max(np.abs(A @ n - b)):.2e} mol.")
+    res.data = {"n": dict(zip([s.name for s in species], n)), "mu": lam}
+    return res