A modern Rust + Python reimplementation of a multicomponent vapor-liquid equilibrium (VLE) thermodynamic calculator, built from two legacy academic codebases using AI-assisted development.

Every point above was computed by this library's Rust engine — the phase-envelope dome (left) traced through each mixture's critical point by Michelsen continuation, with the critical locus from the Heidemann–Khalil solver riding the ridge, and the P–x–y "sail" (right) from the γ-φ bubble/dew solvers. Explore and regenerate them in notebooks/09_3d_phase_surfaces.ipynb.

The classic P–v–T surface of water — 36,000+ state points, every one evaluated by this repo's vle-steam crate (IAPWS-IF97). Legend: the bright sheets are the single-phase regions (the near-vertical liquid wall, the sweeping superheat sheet, and the supercritical region joining them above T_c); the darker inset is the two-phase dome, a ruled surface swept in quality x between the saturated-liquid (green) and saturated-vapor (orange) boundary curves, which merge at the critical point (★, 373.95 °C / 22.064 MPa). Color encodes temperature. Build it step by step in notebooks/14_pvt_surface.ipynb, or regenerate this image with scripts/render_pvt_hero.py.

Why steam is here at all: water properties are the one calculation this project ships that does not come from the research papers it modernizes — they earned their place through practice. In industry, multicomponent VLE almost always lives inside a process simulator; but alongside it, every practicing engineer keeps a steam-table utility within reach, and those utilities are built on IAPWS-IF97, the formulation the International Association for the Properties of Water and Steam maintains as the international standard of the steam power industry (R7-97(2012)) — adopted by ASME for its official steam tables and used for turbine contracting and acceptance testing. The same water-property formulations sit inside the thermal-hydraulics codes behind nuclear and fossil power plants (e.g. RELAP-7 and TRACE), where steam drives the turbines that generate electricity. vle-steam implements IF97 directly — all five regions plus the saturation line — so this "VLE for water only" companion gives every energy balance in the stack a reference-quality water model.

This project modernizes legacy thermodynamic software — originally written in VB6 (1999) and Pascal (1989) — into a fast Rust computation engine with Python bindings (via PyO3) and Jupyter notebooks for interactive exploration.

This is an educational project demonstrating how AI coding tools like Claude Code can be used to understand, analyze, and modernize legacy scientific code. The entire modernization process — from analyzing ~17,500 lines of VB6/Pascal, mapping algorithms to academic references, proposing performance improvements, and planning the new architecture, through implementing and validating the full Rust engine and its Python bindings — was conducted with Claude Code as a development partner.

This work is based on the thesis:

"Desarrollo de un Programa Computacional para el Cálculo del Equilibrio Líquido Vapor de Mezclas Multicomponentes bajo el Ambiente Windows"

Miguel Roberto Jackson Ugueto and Carlos Fernando Mendible Porras

Proyecto de Grado, Universidad Simón Bolívar, Sartenejas, April 1999

Advisors: Prof. Coray M. Colina and Prof. Jean-Marie Ledanois

The VB6 program in turn builds upon an earlier Pascal package:

(4) Da Silva, F. A.; Báez, L. Desarrollo de un Paquete Computacional para la Predicción de Propiedades Termodinámicas y de Equilibrio de Fases. Thesis, Universidad Simón Bolívar, 1989.

The full research paper is available in both English and Spanish in the docs/ directory.

• 22+ cubic equations of state: Peng-Robinson, RKS, van der Waals, Schmidt-Wenzel, Patel-Teja, and 17 more variants
• Chao-Seader liquid fugacity correlation (with special H2/methane handling)
• Second virial equation (Pitzer/Tsonopoulos correlation)
• 6 activity coefficient models: NRTL, Wilson, van Laar, Margules, Scatchard-Hildebrand, Ideal
• 11 mixing rules: Classical (IVDW, IIVDW), Wong-Sandler, Huron-Vidal (original + simplified), MHV1, MHV2, plus 3 C-parameter rules for the three-parameter EOS — all with exact composition derivatives (analytic or dual-number AD, never finite differences)

• Bubble point (temperature and pressure)
• Dew point (temperature and pressure)
• Isothermal flash (Rachford-Rice via Halley in the Leibovici–Neoschil window; tangent-plane stability analysis)
• Adiabatic flash
• Phase-envelope continuation through the critical point (Michelsen)
• Mixture critical point (Heidemann-Khalil algorithm)
• Binary interaction parameter regression (kij)
• Activity model parameter regression (Aij) with analytical Jacobians
• Saturation pressure (Antoine, Riedel, Muller, RPM)
• Residual and excess thermodynamic properties (H, S, G)

• Dimensional analysis via the 7 SI base dimensions (L, M, T, I, Θ, N, J)
• Rust: uom crate for compile-time dimension checking (zero runtime cost)
• Python: pint library for runtime unit conversion
• Supports temperature (K, °C, °F, °R), pressure (kPa, bar, atm, psi, mmHg, torr), energy (kJ/kmol, J/mol, cal/mol, BTU/lbmol), and more
• Works standalone — can be used in other projects

• IAPWS-IF97 industrial water/steam properties — "VLE for water only", the reference standard behind every printed steam table
• All five IF97 regions + the saturation line (closed-form Psat(T) / Tsat(P)) + region-1 backward equations, verified against the R7-97(2012) tables to 9 significant figures
• The practitioner state API: Water(T,P) / (T,x) / (P,x) / (P,h) / (P,s), saturation-table rows, latent heat, two-phase quality
• Python: vle.steam with pint/gauge-pressure inputs and a batch numpy API; Rust: dependency-free crate (pure f64, FFI/embedded-friendly)

• Crude assay → pseudocomponents: a distillation curve plus a gravity becomes a list of ordinary Components, so a barrel of crude flashes with the same code path a two-component mixture uses
• Distillation-curve interconversion: ASTM D86 ↔ TBP ↔ D2887 (SimDist) ↔ EFV, by both the Riazi–Daubert power laws and the API difference procedures 3A1.1 / 3A3.1 / 3A3.2 — validated against Riazi (2005) Examples 3.2–3.5 and two API Technical Data Book examples
• Cutting: equal-volume, equal-boiling-range, or at explicit refinery product boundaries (naphtha / kerosene / diesel / AGO)
• Property correlations: four families (Riazi–Daubert 1980, API/Riazi–Daubert 1987, Kesler–Lee, Twu) for M, Tc, Pc, Vc; Lee–Kesler ω; four Zc correlations; Watson K and the five average boiling points
• Fraction properties: Kesler–Lee ideal-gas Cp° (API 7D3.6) and Maxwell–Bonnell vapor pressure — the correlation that makes vacuum-distillation data usable at all
• Python: vle.petroleum.Assay with cuts(), components() and to_system(); unit strings throughout

• Free-water (decant) flash for steam-stripped feeds: hydrocarbons flash at their partial pressure, vapor saturated with water, free-water leg by balance — System.flash_free_water (the industry approximation, not a three-liquid stability search)
• Grayson–Streed K-values Kᵢ = νᵢγᵢ/φ̂ᵢⱽ and Braun K10 from a now closed-form Maxwell–Bonnell inversion — liquid_model="grayson_streed" / "bk10", constants cached per (T, P); the legacy chao_seader path found to carry the Grayson–Streed 1963 table without γ, kept and documented
• Lee–Kesler enthalpy/entropy departure, pure and mixture, validated by thermodynamic identities; 0.10 ms per 300-component mixture enthalpy from Python
• Peneloux volume translation (SRK, PR) — heavy-liquid density fixed, K-values untouched by construction
• Python: vle.refinery + System.{flash_free_water, lee_kesler_departure, enthalpy_entropy_lee_kesler, peneloux_shifts, translated_density}

The modernization introduces several numerical improvements over the original VB6/Pascal implementations. This table is the original improvement plan proposed by Claude Opus 4.6 during the initial legacy-code analysis (Milestone 0):

The plan was later expanded into PERFORMANCE_PROPOSAL.md — the "numpy for thermo" strategy adding the exact-derivative mixture core (analytic + num-dual dual-number AD, replacing every finite difference), the modern Michelsen flash suite (stability analysis, windowed Halley Rachford-Rice, phase-envelope continuation), a measured performance foundation, and the upcoming batch numpy API — and implemented, largely by Claude Fable 5, in Milestones 8.2–9. In the final architecture the exact analytic/AD Jacobians go further than the Broyden row above: full Newton uses them directly, with Broyden demoted to a fallback. See MODERNIZATION_PLAN.md for full details and justifications.

The table above is kept as written in April 2026 — it is the plan, not a description of today's engine. A great deal changed on the way here. Some rows were superseded (Broyden was demoted to a fallback the moment exact analytic/AD Jacobians landed). Whole tracks were added that the original analysis never imagined — a generalized mixture core, IAPWS-IF97 steam tables, three foreign-language bindings. And in July 2026 an external performance audit re-examined the engine and produced numbers nobody had guessed: some of its textbook-correct recommendations made this code measurably slower and were reverted, while measuring the layer underneath one of them found a 10× win and a latent correctness bug. Every plan and audit behind those changes — what it decided, what shipped, and what was rejected and why — is catalogued in docs/plans/README.md — the Plan & Audit History.

vle-thermo is published on two registries — PyPI for Python, crates.io for Rust. Both track the same version and are built from the same source tree. Every other way to use the engine ships as source plus a build script; see Other ways to use the engine below.

pip install vle-thermo

Distribution name is vle-thermo, import name is vle (like Pillow → PIL):

import vle

Optional extras: pip install "vle-thermo[plot]" (matplotlib), "vle-thermo[db]" (extended component-database seeding via thermo). See python/README.md.

Build a system from component names (critical constants come from the bundled database), then flash it. Temperatures are K and pressures kPa absolute by default, but any input accepts a unit-aware value:

from vle import System
from vle.units import Q_

# n-heptane / n-butane with the RKS equation of state (Chapter IV, Table 4.10).
sys = System(["n-heptane", "n-butane"], eos="RKS")

res = sys.flash_pt(300.0, 100.0, z=[0.5, 0.5])     # or flash_pt(Q_(26.85, "degC"), "1 bar", ...)
print(res.beta, res.x, res.y)                        # vapor fraction, liquid & vapor comps

# The batch API is the "numpy for thermo" path: one FFI crossing per array,
# GIL released, parallel across cores, warm-started along the sweep.
import numpy as np
ts = np.linspace(290.0, 340.0, 100_000)
out = sys.flash_pt_batch(ts, ps=np.array([100.0]), z=[0.5, 0.5])   # ~10× a Python loop
print(out.beta.shape, out.converged.sum())

A full guided tour — installation, the System API, unit handling, the batch API, and plotting — is in notebooks/01_introduction.ipynb.

cargo add vle-thermo
# Optional: the companion units crate for gauge pressure / °C / psi parsing
cargo add vle-units
# Optional: IAPWS-IF97 steam tables (dependency-free, "VLE for water only")
cargo add vle-steam

API docs: https://docs.rs/vle-thermo. See engine/README.md and steam/README.md.

The same Rust core also compiles into Swift (iOS/macOS), Kotlin (Android and — via Compose Multiplatform — Windows desktop) and WebAssembly (a React site where the thermodynamics runs client-side, or the same bundle wrapped by Tauri, Electron or Capacitor). It also ships 21 notebooks that reproduce the source thesis's Chapter IV results.

None of those are published as binaries, by design — the repo distributes the build recipe, and one script per target produces the artifact locally:

git clone https://github.com/miguelju/vle.git && cd vle
scripts/build-ios.sh       # → swift/VleThermo    (add as a local package in Xcode)
scripts/build-android.sh   # → kotlin/VleThermo   (open kotlin/ in Android Studio)
scripts/build-wasm.sh      # → wasm/pkg           (npm install <path-to-vle>/wasm/pkg)

Every one of those channels — the notebooks, all three languages, the per-platform guides, and the C#/.NET route that was evaluated and parked — is documented in distribution/README.md.

Release process and registry maintenance: PUBLISHING.md.

vle/
├── data/                    # Component property database
│   └── components.db        # SQLite database (generated, gitignored)
├── scripts/                 # Data extraction utilities (see scripts/README.md)
├── python/src/vle/          # Python package
│   ├── system.py            # High-level vle.System API (persistent handle, unit-aware)
│   ├── components.py        # Bundled JSON component DB loader (name-based lookup)
│   ├── results.py           # Result dataclasses (Flash/Bubble/Dew/Critical + batch)
│   ├── plots.py             # Pxy / Txy / phase-envelope helpers (matplotlib)
│   ├── steam.py             # IAPWS-IF97 steam tables, unit-aware + batch (M13)
│   ├── petroleum.py         # Crude assay → pseudocomponents (M19)
│   ├── refinery.py          # Lee–Kesler / regular-solution ν / Peneloux building blocks (M20)
│   ├── data/               # Bundled components.json (ships in wheel)
│   ├── db/                  # Component database (connection, queries, models)
│   │   └── sql/             # Bundled schema.sql + seed_chapter4.sql (ship in wheel)
│   └── cli/                 # CLI tool (vle-db)
├── notebooks/               # 21 notebooks (00–16 + 01_introduction + m06) plus index.ipynb; see distribution/NOTEBOOKS.md
│   └── data/                # Pre-computed 3-D surface datasets (CSV, committed)
├── units/                   # Independent units crate (dimensional analysis, gauge pressure, custom units)
├── steam/                   # Independent steam-tables crate `vle-steam` (IAPWS-IF97, dependency-free; M13)
├── engine/                  # Rust computation engine (complete: 22+ EOS, mixture core, flash suite, PyO3 bindings)
│   └── src/petroleum/       # Petroleum characterization: distillation curves, cutting, Tb+SG correlations (M19)
│   └── src/refinery/        # Lee–Kesler departure, Peneloux translation (M20); free water in src/flash/free_water.rs
│   └── data/                # Canonical components.json — bundled Rust DB via the `component-db` feature (M12.2)
├── ffi/                     # UniFFI wrapper crate `vle-ffi` — Swift + Kotlin (never published; M15/M16)
├── wasm/                    # wasm-bindgen wrapper crate `vle-wasm` — JavaScript/TypeScript (never published; M17)
├── swift/VleThermo/         # Local Swift package for iOS/macOS apps (XCFramework generated by scripts/build-ios.sh)
├── kotlin/VleThermo/        # Local Android/Kotlin library module (bindings + .so generated by scripts/build-android.sh)
├── docs/
│   ├── plans/               # Every plan & audit — README.md is the Plan & Audit History
│   │   ├── MODERNIZATION_PLAN.md   # 27-phase implementation plan (the one live plan)
│   │   ├── engine/          # Calculation plans + audits (performance, steam, NRTL, petroleum)
│   │   └── delivery/        # Platform plans (iOS, Android/Kotlin, Web/wasm)
│   ├── en/research-paper/   # English translation (navigatable)
│   ├── en/units/            # Units add-on design document
│   ├── en/ios/              # Rust→Swift FFI learning guide + build instructions (M15)
│   ├── en/android/          # Rust→Kotlin FFI guide — Android + Compose Desktop (M16)
│   ├── en/web/              # Rust→JavaScript guide — WebAssembly for React/Tauri/Electron/Capacitor (M17)
│   ├── en/dotnet/           # C#/.NET route — documented, version-blocked as of 2026-07-12
│   └── es/research-paper/   # Spanish original (pdf/ + markdown/)
├── legacy/
│   ├── vb6/                 # Original VB6 source (~15,000 lines, reference)
│   └── pascal/              # Original Pascal source (~2,500 lines, reference) (4)
├── deploy/                  # Registry publishing only (PyPI + crates.io)
├── distribution/            # Every non-registry channel (notebooks, Swift, Kotlin, wasm)
├── ROADMAP.md               # Milestones and progress tracking
├── TODO.md                  # Tasks with time estimates
├── PASCAL_VB6_COMPARISON.md # Legacy codebase comparison
├── PUBLISHING.md            # Release process (tag → PyPI + crates.io)
└── CLAUDE.md                # Claude Code development guidance and conventions

This project is developed incrementally using Claude Code as an AI development partner. Each milestone follows a plan-then-execute cycle, tracked across three synchronized documents. Every plan and audit ever written for this project — including the ones whose recommendations were measured and rejected — is catalogued in the Plan & Audit History.

# 1. Clone the repository
git clone <repo-url> && cd vle

# 2. Review current progress
cat ROADMAP.md          # Which milestones are done?
cat TODO.md             # Which tasks remain?

 Read the rest on GitHub