vle-thermo 0.4.0

Vapor-liquid equilibrium (VLE) thermodynamic calculator: 22+ cubic EOS, activity models, flash algorithms

vle-thermo

Vapor-liquid equilibrium (VLE) thermodynamic calculator with a Rust computation engine and a Python interface.

A modern Rust + Python port of two legacy thermodynamic codebases (VB6 ~15,000 lines + Pascal ~2,500 lines). The Rust core (vle-thermo crate) does the computation; this Python package wraps it for interactive use in scripts and Jupyter notebooks.

Install

pip install vle-thermo

Optional extras:

pip install "vle-thermo[plot]"   # adds matplotlib
pip install "vle-thermo[db]"     # adds `thermo` for extended component-database seeding
pip install "vle-thermo[dev]"    # adds pytest, maturin

The distribution name on PyPI is vle-thermo, but the import name is vle (following the common distribution-vs-import split, like Pillow → import PIL or python-dateutil → import dateutil):

import vle

Status

0.1.x — the component database, CLI, and units layer work today. Numerical kernels (flash algorithms, equation-of-state solvers, parameter regression) are under active development. Treat 0.1.x as pre-release; semver promises begin at 1.0.

See the roadmap for what's shipped vs. planned.

What works today

# Initialize the bundled component database (SQLite) and seed with the 15
# compounds from Chapter IV of the source thesis.
vle-db init
vle-db seed --source chapter4

# Browse and inspect
vle-db list
vle-db show methane
vle-db validate chapter4

from vle.db import list_components, get_component

for c in list_components():
    print(c.name, c.tc, c.pc, c.omega)

methane = get_component("methane")

Unit-aware input/output (gauge pressure, °C, °F, psi, barg, mmHg, …):

from vle.units import ureg, Q_

T = Q_(25, "degC")                # 298.15 K internally
P = Q_(3.5, "bar").to("kPa")      # 350 kPa

Features (full roadmap)

• 22+ cubic equations of state — Peng-Robinson, RKS, van der Waals, Schmidt-Wenzel, Patel-Teja, and more
• 5 activity coefficient models — Wilson, van Laar, Margules, Scatchard-Hildebrand, Ideal
• 11 mixing rules — Classical (IVDW, IIVDW), Wong-Sandler, Huron-Vidal, MHV1/MHV2
• 6 saturation pressure correlations — Antoine, Riedel, Müller, RPM
• 6 flash calculation types — bubble/dew point (T/P), isothermal (Rachford-Rice), adiabatic
• Parameter regression — kij (binary interaction) and Aij (activity model)

Use it in Jupyter

A curated set of notebooks reproducing Chapter IV of the source thesis ships alongside the project at https://github.com/miguelju/vle/tree/main/notebooks. To run them in your own environment:

pip install "vle-thermo[plot]" jupyterlab
git clone https://github.com/miguelju/vle.git
cd vle/notebooks
jupyter lab

For a zero-setup option, the repo ships a self-contained Dockerfile that bundles JupyterLab + vle-thermo + the example notebooks. Build and run it locally:

git clone https://github.com/miguelju/vle.git
cd vle
docker build -f deploy/docker/Dockerfile.standalone -t vle-standalone .
docker run --rm -p 8888:8888 vle-standalone

A publish script (deploy/scripts/publish-docker.sh) is also included if you want to host the image yourself at ghcr.io/<your-user>/vle-thermo for others to docker pull. CI does not currently publish an upstream image — see deploy/README.md for the distribution story.

How the Python package wraps Rust — maturin + PyO3

This project is partly educational, so it's worth explaining the build glue in detail. Two tools split the work:

• PyO3 is a Rust crate that handles the FFI bridge at runtime. You annotate Rust functions with #[pyfunction] and Rust types with #[pyclass], and PyO3's procedural macros generate all the CPython C-API calls — argument unpacking, type conversion (Python dict ↔ Rust HashMap, Python list ↔ Rust Vec, etc.), GIL acquisition, and turning a Result::Err(...) into a Python raise.

• maturin is a build tool that packages a PyO3-using Rust crate into a Python wheel at build time. PyO3 produces a Rust crate that can be a Python extension; maturin does the work of actually shipping it as one.

What "FFI" means in "FFI bridge". FFI stands for Foreign Function Interface — the conventions and machinery that let code in one language call functions written in another. Each language runtime has its own ideas about how arguments are passed, how strings are laid out in memory, how errors propagate, and how memory ownership works; you can't just call a Rust function from Python directly any more than you can plug a US power cord into a UK outlet. The universal adapter in practice is the C ABI (Application Binary Interface): C compilers all agree on how arguments are placed in registers and on the stack, how function names appear in the symbol table, and how stack frames are laid out. Any language that can produce C-compatible function signatures (Rust, Go, Zig, Swift) can be called by any language that can call C (Python, Ruby, Lua, JavaScript via N-API). PyO3 sits exactly on top of that contract: its macros generate C-ABI functions from your Rust code, give them CPython-shaped signatures (taking PyObject* arguments, returning PyObject*), and export the PyInit_<modulename> symbol CPython's import loader looks for. That's the "runtime" part of "runtime FFI bridge" — code that runs on every call into the extension module to convert Python values into Rust values, drive the Rust implementation, and convert the result back. (The build-time counterpart — turning the cdylib into an importable .so and a pip-installable wheel — is the part maturin handles.)

Why this stack (vs. the alternatives)

The numerical kernel needs to be fast — Python alone isn't — but Python is where the user lives (Jupyter, scripts, the data-science ecosystem). So we needed something that:

1. Ships as a normal pip install (no separate Rust toolchain for the end user).
2. Works on every OS Python supports (Linux x86_64/aarch64, macOS arm64, Windows).
3. Marshals types automatically across the boundary.
4. Bridges error handling (Rust Result → Python exception).

The realistic alternatives:

• setuptools-rust — works, but predates pyproject.toml and requires a setup.py shim. More moving parts.
• A hand-rolled setup.py + cargo invocation — possible, fragile, reinvents wheel-packaging logic.
• cffi — only handles C-style FFI, not the higher-level PyO3 ergonomics (typed Python classes, automatic GIL handling, exception bridging).

maturin is the build tool the PyO3 maintainers built and recommend — it's specifically aware of PyO3's abi3 mode, the wheel ABI tags, and the cross-compilation gotchas. The full build configuration is one TOML block.

What maturin actually does

A Python "native extension module" is a shared library — .so on Linux, .dylib on macOS, .pyd on Windows — that CPython's import machinery can dlopen and find a PyInit_<modulename> symbol in. To produce one from a PyO3 Rust crate, maturin runs the following pipeline:

1. Compile the Rust crate as a cdylib (C-compatible dynamic library) with PyO3's #[pymodule] entry-point function compiled in.
2. Link against the right Python ABI. PyO3's abi3-py310 feature builds one wheel that loads on CPython 3.10, 3.11, 3.12, 3.13, and every future 3.x — instead of one wheel per Python version, you ship one per (OS, arch).
3. Rename the resulting .so to Python's import convention (_engine.abi3.so for abi3, _engine.cpython-310-darwin.so otherwise).
4. Pack that file plus the pure-Python sources into a standards-compliant .whl (the binary distribution format pip understands), with the right ABI/platform tags in the filename so pip picks the matching wheel for the user's machine.
5. Repeat (1)–(4) for every (OS, arch) combination in CI — cibuildwheel calls maturin once per platform, producing the matrix of pre-built wheels you see on PyPI.

The end user types pip install vle-thermo, pip selects the wheel matching their platform, and the Rust code lands on their machine already compiled. No Rust toolchain required.

What that looks like in this repo

engine/                       Rust crate
├── Cargo.toml                ├── crate-type = ["cdylib", "rlib"]
│                             └── pyo3 dep, gated behind the "python" feature
└── src/py_bindings.rs        the #[pyfunction] + #[pymodule] glue lives here

python/                       Python package
├── pyproject.toml            [tool.maturin] points at ../engine/Cargo.toml
└── src/vle/                  pure-Python code (vle.db, vle.units, vle.cli, …)
    ├── _engine.abi3.so       ← dropped here by maturin at install time
    └── __init__.py           re-exports from vle._engine + Python helpers

The entire build configuration is the [tool.maturin] block in python/pyproject.toml:

[tool.maturin]
manifest-path = "../engine/Cargo.toml"   # which Rust crate to build
features      = ["python"]                # enables PyO3 in engine/Cargo.toml
python-source = "src"                     # vle.py files live in src/vle/
module-name   = "vle._engine"             # the cdylib becomes this module

Two commands matter day-to-day:

• maturin develop — for local development. Builds the Rust crate, drops the resulting .so into python/src/vle/, and installs the Python package into the active virtualenv in editable mode. Pure-Python edits show up immediately; Rust edits need a re-run.
• maturin build — for distribution. Produces a .whl you can pip install or upload to PyPI.

Tracing a call across the boundary

To see all of this concretely, follow the version() call:

1. Rust side — engine/src/py_bindings.rs declares #[pyfunction] fn version() -> &'static str and registers it inside #[pymodule] fn _engine(...). PyO3's macros expand these into CPython-callable C functions plus the PyInit__engine symbol the OS loader needs.
2. Build — maturin develop compiles engine/ into python/src/vle/_engine.abi3.so with that PyInit__engine symbol.
3. Python side — python/src/vle/__init__.py does from vle._engine import version. The first time Python imports vle._engine, CPython dlopens the .so, calls PyInit__engine, and gets a module object with version already bound.
4. Runtime — vle.version() is now a plain Python function call. PyO3's generated wrapper acquires the GIL, calls into the Rust implementation, converts the returned &'static str to a Python str, and hands it back to the interpreter.

The takeaway: maturin is what makes step 2 a single command. PyO3 is what makes steps 1, 3, and 4 a handful of attributes instead of hundreds of lines of hand-written C glue. Together they collapse "ship Rust to Python users" into a normal Python development workflow.

Origin

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" (Jackson & Mendible, Universidad Simón Bolívar, 1999), with additional models from Da Silva & Báez (1989). See the research paper (English translation) for algorithms, parameters, and their academic references.

License

MIT. See LICENSE.