chemthermo 0.4.0__tar.gz

chemthermo-0.4.0/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+Versions follow PEP 440 and are tagged `v<version>` on one tested commit
+(policy: `.agents/brain/adr/0031-versioned-releases.md`). Releases up to
+0.3.0b1 were GitHub-only; from 0.4.0 the owner also publishes to PyPI by hand
+(ADR-0038).
+
+## 0.4.0 (2026-09-25) - first PyPI release (Beta)
+
+The first release published to PyPI (`pip install chemthermo`), with a short,
+honest README, the reference material moved to `docs/`, and packaging checked
+for PyPI. Beta: validated against independent implementations on macOS arm64
+and Linux x86_64, but the public API may still change before 1.0.
+
+### Breaking
+- **`chemthermo.vlle` is removed** (deprecated since ADR-0013; ADR-0037).
+  `import chemthermo.vlle` raises `ModuleNotFoundError`; three-phase
+  equilibrium is found by `flash_tp` itself (`FlashSettings(max_phases=3)`,
+  the default). `flash_mode="vlle"` still raises `ModelError` with that pointer.
+
+### Packaging
+- PyPI metadata (summary, classifiers, URLs, keywords), `py.typed`, an sdist
+  that carries the library only (tests are excluded: some of their fixtures
+  are not redistributable). Supported and CI-tested on Python 3.11, 3.12 and
+  3.13; CI also runs `twine check --strict`.
+
+### Documentation
+- README rewritten as a summary: quick start, a capability table naming what
+  each claim was checked against, and the limits. The previous detail is in
+  `docs/` (installation, flash, stability, PC-SAFT, CLI, extending,
+  benchmarks). `CONTRIBUTING.md` added.
+
+### Added
+- PC-SAFT **association** temperature derivative: `residual_helmholtz_temperature_derivative`
+  and `residual_properties` now work for water, alcohols and their mixtures
+  (they raised `ModelError` in 0.3.0b1). Checked against FeOs residual entropy
+  and enthalpy (2.1e-15 with matched universal constants). ADR-0034 amendment,
+  ledger Case P-20.
+
+### Fixed
+- `flash_tp` (phi-phi): a split whose two phases are identical (the trivial
+  solution) no longer counts as converged, so the stability-seed ladder runs.
+  Around the Mw 53000 polyethylene ladder state, 29 of 135 neighbouring
+  pressures (+-64 ULP) refused; now none does. The full 2505-state
+  robustness map is unchanged field for field. ADR-0036.
+
+### Changed
+- `stability_tp`: on a `tpd` tie (within 1e-12) the reported minimizing trial
+  is one converged at least 1000x better, when one exists; flagged by
+  `diagnostics["minimizing_trial_tie_break"] = "residual"`. Changes only such
+  ties (none on any captured state). ADR-0035.
+
+### Validation for this release
+- Full 2505-state robustness map at `761fd57` (Linux): 2500 converge, 5
+  by-design gamma-phi refusals, 0 invariant violations; identical state by
+  state to the earlier macOS record at `f852726` (`benchmarks/robustness_761fd57.*`).
+- Default suite on Python 3.11 / 3.12 / 3.13 (numpy 2.4.6 and 2.5.3), and
+  with the validation extras (teqp, FeOs, thermo) on 3.11.
+
+## 0.3.0b1 (2026-09-25) - prerelease
+
+The CLI reaches the equilibrium work, PC-SAFT gains residual caloric
+properties, and the test suite is green on Linux for the first time. A
+prerelease because the CLI contract (ADR-0033) and the two PC-SAFT methods
+(ADR-0034) are new. Validation now spans two platforms (macOS arm64 inherited
+at 0.2.0b1; Linux x86_64 on GitHub Actions and a cloud session for this
+release), but this release's new code was exercised on Linux only.
+There is no 0.2.0b2; its planned content (the cross-platform guards) is here.
+
+### Compatibility
+- Library: additive only (two new `PCSAFTEOS` methods). No existing number
+  moved: the new derivative is a separate function, and no solver was touched.
+- CLI: `cli_schema_version` stays 1; previously valid invocations print
+  byte-identical output (checked on 11 invocations).
+
+### Added
+- **CLI `chemthermo stability-tp`**: tangent-plane stability of a feed with
+  Peng-Robinson or PC-SAFT (`--eos`), JSON or text; `stable` is reported with
+  `stability_scope = "bounded-trial-set"`; an `inconclusive` verdict exits 3
+  with the payload printed. ADR-0033.
+- **CLI `tp-flash --eos {peng-robinson,pc-saft}` and `--max-phases N`**:
+  PC-SAFT flashes (packaged parameters, `kij = 0`, phi-phi) and an explicit
+  phase budget; three-phase answers use the existing name-keyed layout.
+  `cli_schema_version` stays 1 and every previously valid invocation prints
+  byte-identical output. `examples/cli/stability_and_multiphase.sh`.
+
+- **PC-SAFT temperature derivative and residual properties** (non-associating):
+  `PCSAFTEOS.residual_helmholtz_temperature_derivative` and
+  `PCSAFTEOS.residual_properties` (`h_res`, `u_res`, `s_res_tv/tp`,
+  `g_res_tv/tp`, reduced). Checked against teqp `get_Ar10` (<= 5.2e-16 relative
+  over 14 states), Gibbs-Helmholtz through the fugacity route, and
+  `dH_vap = T dS_vap` at saturation. Associating mixtures raise `ModelError`.
+  ADR-0034; `examples/basic/pcsaft_residual_properties_demo.py`.
+
+### Changed (tests and policy only; no library code)
+- Guards that compare against floats captured on macOS arm64 are exact there
+  and, on any other platform, exact on every discrete field and bounded on
+  floats (1e-12 flash fixture, 5e-14 PC-SAFT literals); last-bit ties are
+  counted as ties. Makes the Linux CI and cloud runs green without weakening
+  the capture-platform check. ADR-0032; ledger Cases P-11 and P-17.
+
+### Known limitations found
+- One polymer ladder state (Mw 53000, 15 wt%, 8.1 MPa) refuses at 1 of 17
+  pressures within +-8 ULP of the grid point, and its solver route depends on
+  the last bit; every converged answer is the same tie line.
+- `stability_tp` breaks an exact `tpd` tie by trial order, so the reported
+  `trial_composition` can be the less-converged of two tied trials (good to
+  the stationarity tolerance, 1e-10 residual).
+
+## 0.2.0b1 (2026-09-25) - prerelease
+
+First release of the phase-equilibrium campaign (121 commits and 38
+distinct `Slice:` trailers since `v0.1.0`; ADR-0003 to ADR-0031). A prerelease because its
+validation comes from one development machine plus the release gates of
+ADR-0031, and because the CLI does not yet expose the equilibrium work.
+
+### Added
+- **Phase stability** `chemthermo.stability_tp` (Michelsen tangent-plane
+  distance) with `StabilityResult` / `StabilitySettings` / `StabilityTrial`,
+  incipient-phase compositions and per-trial diagnostics, for an equation of
+  state, an activity model alone (liquid-liquid), or an activity liquid against
+  an ideal-gas vapour (`vapor="ideal"`). ADR-0005, 0007, 0010, 0012, 0021, 0025.
+- **Phase-count discovery in `flash_tp`**: one, two or three phases found by
+  stability analysis, a verified split, post-split stability of every phase,
+  and phase addition/removal (`FlashSettings.max_phases`, default 3), on the
+  EOS (`phi-phi`) and `modified-raoult` paths; liquid-liquid `gamma-gamma`
+  mode (two phases). ADR-0008, 0009, 0011, 0016, 0019, 0020, 0024, 0026, 0029.
+- **PC-SAFT** `chemthermo.PCSAFTEOS`: Gross-Sadowski (2001) hard chain +
+  dispersion with the 2002 association term, analytic composition/density
+  derivatives, density roots, log-space fugacities for long chains; packaged
+  parameters for 11 non-associating compounds; user records incl. association
+  (`PCSAFTRecord`, `PCSAFTAssociationRecord`) and polymers via
+  `segments_per_g` + `Component.custom(...)`. ADR-0014, 0015, 0018, 0022.
+- Peng-Robinson `kij` matrices (ADR-0006); phase labels by compressibility
+  (ADR-0017).
+- CLI `chemthermo tp-flash` (`cli_schema_version` 1; Peng-Robinson phi-phi and
+  deprecated gamma-phi; exit codes 0/1/2/3). ADR-0003, 0004.
+- Internal (not public API) benchmark and robustness harness
+  `python -m chemthermo.bench` (ADR-0023, 0027) and a call-local EOS solve memo
+  (ADR-0030).
+
+### Changed / compatibility
+- `NRTL.activity_coefficients` now implements the standard Renon-Prausnitz
+  equation (column sums); values for **asymmetric** parameters differ from
+  `v0.1.0`, which violated Gibbs-Duhem. Bug fix, not a model change.
+- `flash_tp`: `eos` is optional; `flash_mode=None` infers the mode; phi-phi
+  phase detection defaults to `"tangent-plane"` (`"wilson-heuristic"` keeps the
+  old behaviour). Single-phase tangent-plane results no longer carry
+  `k_min`/`k_max`/`max_delta_k`/`rr_*` diagnostics.
+- `flash_mode="gamma-phi"` and the `chemthermo.vlle` plugin boundary are
+  **deprecated** (docs only; still work). ADR-0013.
+- Package version moves from `0.0.0` to `0.2.0b1`. (The existing `v0.1.0`
+  tag points at a commit whose metadata says `0.0.0`; it is left as published.)
+
+### Known limitations
+- `stability_tp` "stable" means no negative tangent-plane distance was found
+  from a bounded deterministic trial set - not a proof of global stability.
+- PC-SAFT parameters and the association equation rest on secondary sources
+  (primary papers not read); polymer parameters are a labelled test fixture
+  from one secondary source and are **not packaged**; polymers are monodisperse.
+- No temperature derivatives for PC-SAFT: no residual enthalpy/entropy or
+  caloric properties.
+- The robustness map (2505 states, macOS arm64) refuses 5 states, all in the
+  deprecated gamma-phi path by design; it measures coverage, not correctness.
+- The CLI does not expose stability, multiphase flash or PC-SAFT yet.
+- Default test suite takes ~4-5 min; `pytest -m slow` and the full sweep
+  (~37 min) are not run by CI.
+
+## 0.1.0
+
+Tag `v0.1.0` on `a7a8ca7` (Feb 2026). No GitHub release was created and its
+package metadata reads `0.0.0`.

chemthermo-0.4.0/LICENSE

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

chemthermo-0.4.0/MANIFEST.in

@@ -0,0 +1,11 @@
+# sdist contents: the library, its metadata and user-facing docs.
+# tests/ is excluded on purpose: several tests read fixtures that are not
+# redistributable (e.g. DECHEMA-derived NRTL data, test-only by ADR policy),
+# so a partial test tree would not run. Run the tests from a git checkout.
+include LICENSE README.md CHANGELOG.md
+prune tests
+prune .agents
+prune benchmarks
+prune notebooks
+prune database
+prune tools

chemthermo-0.4.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: chemthermo
+Version: 0.4.0
+Summary: Phase equilibrium for chemical engineering: tangent-plane stability, multiphase TP flash, Peng-Robinson, PC-SAFT and NRTL.
+Author: Ahmad Alkadri
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AhmadAlkadri/Chemical-Thermodynamics
+Project-URL: Documentation, https://github.com/AhmadAlkadri/Chemical-Thermodynamics/tree/main/docs
+Project-URL: Changelog, https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/AhmadAlkadri/Chemical-Thermodynamics/issues
+Keywords: thermodynamics,phase equilibrium,flash,stability,PC-SAFT,Peng-Robinson,NRTL,chemical engineering
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: bibtexparser<2,>=1.4.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: nbstripout>=0.7.1; extra == "dev"
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: ruff==0.14.13; extra == "dev"
+Requires-Dist: pyright>=1.1.350; extra == "dev"
+Provides-Extra: validation
+Requires-Dist: thermo>=0.6.0; extra == "validation"
+Requires-Dist: teqp>=0.23; extra == "validation"
+Requires-Dist: feos>=0.10; extra == "validation"
+Dynamic: license-file
+
+# 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
+
+```bash
+pip install chemthermo
+```
+
+or pin a tagged commit from GitHub:
+
+```bash
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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:
+
+```bash
+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
+
+| Capability | Models | Checked against (ledger case) |
+| --- | --- | --- |
+| Tangent-plane stability, incipient-phase composition (`stability_tp`) | Peng-Robinson, PC-SAFT, NRTL (liquid-liquid), NRTL + ideal gas | `thermo` 0.6 Michelsen test, same verdicts (S-4); Tessier et al. (2000) published global minima to 2e-11 (S-6, S-7); teqp (P-4) |
+| TP flash with automatic phase count, 1-3 phases (`flash_tp`) | Peng-Robinson and PC-SAFT (`phi-phi`), NRTL (`gamma-gamma`), NRTL + Raoult (`modified-raoult`) | `thermo` `FlashVL` (F-1); teqp's traced PC-SAFT isotherm, tie lines to 2e-9 (P-5); FeOs flash and chemical potentials (P-7, P-8); a published multiphase Rachford-Rice table (V-4); a ternary VLLE tie triangle (V-1) |
+| Peng-Robinson with per-pair `kij` | cubic EOS | `thermo` PRMIX (K-1); agreement floored at ~1e-4 in `ln phi` by chemthermo's rounded constants (S-4) |
+| PC-SAFT residual Helmholtz, `Z`, `ln phi`, density roots | Gross & Sadowski 2001 | teqp, better than 3e-14 (P-1, P-3) |
+| PC-SAFT association (2B scheme) | Gross & Sadowski 2002 | FeOs, association term to 3e-15 (P-6) |
+| PC-SAFT polymers (segments per mass, long chains in log space) | monodisperse chains | FeOs, 5e-12 with matched constants (P-12 - P-14) |
+| PC-SAFT residual `H`, `S`, `U`, `G` and `d(A^res/RT)/dT` | incl. association | teqp `Ar10` to 5e-16 (P-19); FeOs residual entropy/enthalpy to 2e-15 (P-20) |
+| NRTL activity coefficients | NRTL | `thermo` NRTL to 9e-16 (N-2) |
+| Command line: `tp-flash`, `stability-tp` | PR, PC-SAFT | golden JSON fixtures; exit-code contract |
+
+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](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/installation.md)
+- [TP flash](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/flash.md) - phase detection, flash modes, three phases, `kij`, NRTL
+- [Phase stability](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/stability.md)
+- [PC-SAFT](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/pcsaft.md) - parameters, association, polymers, residual properties, limits and their validation
+- [Command line](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/cli.md)
+- [Extending with a new equation of state](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/extending.md)
+- [Benchmarks and the robustness map](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/benchmarks.md)
+- Runnable scripts: [`examples/`](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/examples/README.md); notebooks: [`notebooks/`](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/notebooks/README.md)
+- [Changelog](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/CHANGELOG.md)
+
+## How it is validated and developed
+
+Every number quoted above has an entry in the validation ledger,
+[`.agents/brain/validation-cases.md`](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/.agents/brain/validation-cases.md), with
+its source, tolerance, achieved value and test. Design decisions are
+recorded as ADRs in [`.agents/brain/adr/`](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/tree/main/.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](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/CONTRIBUTING.md).
+
+## Licence
+
+MIT - see [LICENSE](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/LICENSE).

chemthermo-0.4.0/README.md

@@ -0,0 +1,154 @@
+# 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
+
+```bash
+pip install chemthermo
+```
+
+or pin a tagged commit from GitHub:
+
+```bash
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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:
+
+```bash
+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
+
+| Capability | Models | Checked against (ledger case) |
+| --- | --- | --- |
+| Tangent-plane stability, incipient-phase composition (`stability_tp`) | Peng-Robinson, PC-SAFT, NRTL (liquid-liquid), NRTL + ideal gas | `thermo` 0.6 Michelsen test, same verdicts (S-4); Tessier et al. (2000) published global minima to 2e-11 (S-6, S-7); teqp (P-4) |
+| TP flash with automatic phase count, 1-3 phases (`flash_tp`) | Peng-Robinson and PC-SAFT (`phi-phi`), NRTL (`gamma-gamma`), NRTL + Raoult (`modified-raoult`) | `thermo` `FlashVL` (F-1); teqp's traced PC-SAFT isotherm, tie lines to 2e-9 (P-5); FeOs flash and chemical potentials (P-7, P-8); a published multiphase Rachford-Rice table (V-4); a ternary VLLE tie triangle (V-1) |
+| Peng-Robinson with per-pair `kij` | cubic EOS | `thermo` PRMIX (K-1); agreement floored at ~1e-4 in `ln phi` by chemthermo's rounded constants (S-4) |
+| PC-SAFT residual Helmholtz, `Z`, `ln phi`, density roots | Gross & Sadowski 2001 | teqp, better than 3e-14 (P-1, P-3) |
+| PC-SAFT association (2B scheme) | Gross & Sadowski 2002 | FeOs, association term to 3e-15 (P-6) |
+| PC-SAFT polymers (segments per mass, long chains in log space) | monodisperse chains | FeOs, 5e-12 with matched constants (P-12 - P-14) |
+| PC-SAFT residual `H`, `S`, `U`, `G` and `d(A^res/RT)/dT` | incl. association | teqp `Ar10` to 5e-16 (P-19); FeOs residual entropy/enthalpy to 2e-15 (P-20) |
+| NRTL activity coefficients | NRTL | `thermo` NRTL to 9e-16 (N-2) |
+| Command line: `tp-flash`, `stability-tp` | PR, PC-SAFT | golden JSON fixtures; exit-code contract |
+
+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](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/installation.md)
+- [TP flash](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/flash.md) - phase detection, flash modes, three phases, `kij`, NRTL
+- [Phase stability](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/stability.md)
+- [PC-SAFT](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/pcsaft.md) - parameters, association, polymers, residual properties, limits and their validation
+- [Command line](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/cli.md)
+- [Extending with a new equation of state](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/extending.md)
+- [Benchmarks and the robustness map](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/docs/benchmarks.md)
+- Runnable scripts: [`examples/`](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/examples/README.md); notebooks: [`notebooks/`](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/notebooks/README.md)
+- [Changelog](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/CHANGELOG.md)
+
+## How it is validated and developed
+
+Every number quoted above has an entry in the validation ledger,
+[`.agents/brain/validation-cases.md`](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/.agents/brain/validation-cases.md), with
+its source, tolerance, achieved value and test. Design decisions are
+recorded as ADRs in [`.agents/brain/adr/`](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/tree/main/.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](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/CONTRIBUTING.md).
+
+## Licence
+
+MIT - see [LICENSE](https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/LICENSE).

chemthermo-0.4.0/pyproject.toml

@@ -0,0 +1,103 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chemthermo"
+version = "0.4.0"
+description = "Phase equilibrium for chemical engineering: tangent-plane stability, multiphase TP flash, Peng-Robinson, PC-SAFT and NRTL."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ahmad Alkadri" }]
+keywords = [
+  "thermodynamics",
+  "phase equilibrium",
+  "flash",
+  "stability",
+  "PC-SAFT",
+  "Peng-Robinson",
+  "NRTL",
+  "chemical engineering",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Education",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Chemistry",
+  "Topic :: Scientific/Engineering :: Physics",
+  "Typing :: Typed",
+]
+dependencies = [
+  "numpy>=1.24",
+  "pydantic>=2.0",
+  "bibtexparser>=1.4.0,<2",
+]
+
+[project.urls]
+Homepage = "https://github.com/AhmadAlkadri/Chemical-Thermodynamics"
+Documentation = "https://github.com/AhmadAlkadri/Chemical-Thermodynamics/tree/main/docs"
+Changelog = "https://github.com/AhmadAlkadri/Chemical-Thermodynamics/blob/main/CHANGELOG.md"
+Issues = "https://github.com/AhmadAlkadri/Chemical-Thermodynamics/issues"
+
+[project.scripts]
+chemthermo = "chemthermo.cli:main"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "twine>=5",
+  "nbstripout>=0.7.1",
+  "pytest>=7.4",
+  "ruff==0.14.13",
+  "pyright>=1.1.350",
+]
+validation = [
+  "thermo>=0.6.0",
+  "teqp>=0.23",
+  # FeOs is the reference for the PC-SAFT **association** term (ADR-0018):
+  # teqp's PCSAFT kind does not implement association. It pulls in its own
+  # units package, whose PyPI name is `si-units` and whose import name is
+  # `si_units`; it is not listed separately because feos depends on it.
+  "feos>=0.10",
+]
+
+[tool.pytest.ini_options]
+markers = [
+  "slow: a full validation grid whose representative subset runs by default (e.g. the 188-state PC-SAFT grid of Case F-4), or a repetition of a capability the default run already covers (ADR-0020); deselected by default (see addopts below), opt in with `pytest -q -m slow`. Never the only test of a capability - see `.agents/dev-contract.md`",
+]
+# Deselected, not skipped, by default: `-m slow` on the command line overrides
+# this addopts entry (pytest keeps the last `-m` value), so `pytest -q -m slow`
+# runs exactly the slow-marked tests and nothing else. See
+# `.agents/dev-contract.md` for the full-grid command and CI's choice.
+addopts = "-m 'not slow'"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"chemthermo" = ["py.typed"]
+"chemthermo.data" = ["components.json", "references.bib"]
+"chemthermo.parameters" = ["data/activity/nrtl.json", "data/eos/pcsaft.json"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+exclude = [
+  "database",
+  "notebooks",
+]
+
+[tool.ruff.lint]
+ignore = ["E501"]
+extend-select = ["I"]

chemthermo-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+