chemthermo

Phase equilibrium for chemical engineering in Python: tangent-plane stability, multiphase TP flash, Peng-Robinson, PC-SAFT (with association and polymers) and NRTL, in SI units, with every numerical claim traceable to a recorded cross-check.

Status: beta (0.4.0). The science is checked against independent implementations, but the public API may still change before 1.0. Python

= 3.11; tested on macOS arm64 and Linux x86_64. MIT licence.

Install

pip install chemthermo

or pin a tagged commit from GitHub:

pip install "chemthermo @ git+https://github.com/AhmadAlkadri/Chemical-Thermodynamics.git@v0.4.0"

Runtime dependencies: numpy, pydantic, bibtexparser (< 2).

Quick start

A flash that decides for itself how many phases there are:

import chemthermo as ct

mixture = ct.Mixture.from_database(["Methane", "Ethane", "Propane"], [0.5, 0.3, 0.2])
result = ct.flash_tp(mixture, temperature_K=240.0, pressure_Pa=3.0e6, eos=ct.PengRobinsonEOS())

print(result.phase_names())                 # ['liquid', 'vapor']
print(result.vapor_fraction)                # 0.468...
print(result.phases["vapor"].composition.fractions)

Stability of a feed, and the phase it would split off:

check = ct.stability_tp(
    ct.Mixture.from_database(["Methane", "n-Hexane"], [0.5, 0.5]),
    temperature_K=300.0, pressure_Pa=2.0e6, eos=ct.PengRobinsonEOS(),
)
print(check.status, check.tpd_min)          # unstable -1.2558...
print(check.phase_branch, check.trial_composition)

Three liquids, PC-SAFT, and residual properties:

from chemthermo.eos import PCSAFTEOS

three = ct.flash_tp(
    ct.Mixture.from_database(["Water", "Ethanol", "n-Hexane"], [0.2, 0.4, 0.4]),
    temperature_K=280.0, pressure_Pa=101325.0, eos=ct.PengRobinsonEOS(),
)
print(three.phase_names())                  # ['liquid1', 'liquid2', 'liquid3']

water = PCSAFTEOS(components=("Water",))
rho = max(water.density_roots(temperature_K=300.0, pressure_Pa=1.0e5, composition=[1.0]))
props = water.residual_properties(temperature_K=300.0, density_mol_m3=rho, composition=[1.0])
print(props["h_res"], props["s_res_tp"])    # H^res/RT and S^res/R (ideal gas at same T, P)

From the command line:

chemthermo tp-flash --components Methane,Ethane,Propane --z 0.5,0.3,0.2 \
    --temperature-k 240 --pressure-pa 3e6 --format json
chemthermo stability-tp --components Methane,n-Hexane --z 0.5,0.5 \
    --temperature-k 300 --pressure-pa 2e6 --eos pc-saft

What it does

Packaged data: critical constants, acentric factors and Antoine coefficients for 82 components (from Koretsky, Engineering and Chemical Thermodynamics); PC-SAFT parameters for 16 (11 non-associating, plus water, methanol, ethanol, 1-propanol and n-butanol with 2B association).

What "checked" means here. The comparisons above are code against independent implementations (teqp, FeOs, thermo) or published worked problems. They show the equations are implemented correctly. They say nothing about how well a model with these parameters matches experiment, and nothing in this repository claims that.

Limits, stated plainly

• "Stable" is not a proof. It means no negative tangent-plane distance was found from a deterministic set of trial compositions. A phase that no trial reaches can be missed, and a flash's phase count inherits that limit.
• Bring your own interaction parameters. No binary kij table ships. The two packaged NRTL pairs are synthetic placeholders for demos: real NRTL work needs your own parameters (NRTLParameters.from_pairs). PC-SAFT with kij = 0 gets water / hydrocarbon mutual solubilities badly wrong.
• Residual properties only. No ideal-gas heat capacities are packaged, so no total enthalpy, entropy or Cp; no Cp^res yet.
• PC-SAFT scope: no polar terms; only the 2B association scheme is validated; no induced association; polymers are monodisperse; no polymer parameters are packaged.
• Modified Raoult is a low-pressure model (ideal vapour, no Poynting correction); Antoine ranges are enforced, never extrapolated.
• Cost: a Peng-Robinson or activity-model flash takes milliseconds; PC-SAFT flashes take up to a few seconds (polymer and associating states the longest), and a three-phase PC-SAFT flash about 35 s.
• Deprecated: flash_mode="gamma-phi" (kept for the CLI v1 contract; emits DeprecationWarning). chemthermo.vlle was removed in 0.4.0.

Longer, model-specific limits are in the docs below.

Documentation

• Installation and development setup
• TP flash - phase detection, flash modes, three phases, kij, NRTL
• Phase stability
• PC-SAFT - parameters, association, polymers, residual properties, limits and their validation
• Command line
• Extending with a new equation of state
• Benchmarks and the robustness map
• Runnable scripts: examples/; notebooks: notebooks/
• Changelog

How it is validated and developed

Every number quoted above has an entry in the validation ledger, .agents/brain/validation-cases.md, with its source, tolerance, achieved value and test. Design decisions are recorded as ADRs in .agents/brain/adr/. The tests that compare against teqp, FeOs and thermo run with pip install -e ".[validation]" and skip cleanly otherwise. A 2505-state robustness map (python -m chemthermo.bench robustness) sweeps every model family; its only refusals are 5 states of the deprecated gamma-phi path.

Contributions: see CONTRIBUTING.md.

Licence

MIT - see LICENSE.