prbs-eos 0.1.0__tar.gz

prbs_eos-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include pyproject.toml
+include requirements.txt
+include requirements-dev.txt
+recursive-include prbs_eos *.py
+prune prbs_eos/tests

prbs_eos-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: prbs-eos
+Version: 0.1.0
+Summary: PRBS Equation of State — Peng-Robinson with volume-shift and CPA association for petroleum thermodynamics
+Author: PRBS-EOS Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/your-org/prbs-eos
+Project-URL: Repository, https://github.com/your-org/prbs-eos
+Project-URL: Issues, https://github.com/your-org/prbs-eos/issues
+Keywords: thermodynamics,equation-of-state,peng-robinson,petroleum,flash,VLE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Requires-Dist: pyinstaller>=6.0; extra == "dev"
+
+# prbs-eos
+
+**PRBS Equation of State** — a Python library for petroleum thermodynamics.
+
+## Features
+
+- Peng-Robinson EOS (PR) with van der Waals mixing rules and binary interaction parameters (kij)
+- PRBS-EOS: PR + Peneloux volume-shift + CPA-style association (e.g. water, H₂S)
+- Two-phase PT flash (Rachford-Rice + successive substitution)
+- Tangent-plane stability analysis (Michelsen TPD)
+- Bubble-point / dew-point pressure solvers (Wilson K-factor)
+- Enthalpy and entropy departure functions
+- kij regression from VLE data; vapour-pressure / acentric-factor regression
+- Built-in database: methane, ethane, propane, n-butane … n-octane, N₂, CO₂, water, H₂S
+- Command-line interface: `prbs-eos flash`, `prbs-eos bubble`, `prbs-eos properties`, …
+
+## Quick start
+
+```python
+import numpy as np
+import prbs_eos as eos
+
+mix = eos.Mixture([eos.get_component("methane"), eos.get_component("propane")])
+pr  = eos.PREOS(mix)
+
+res = eos.flash_pt(pr, T=250.0, P=1e6, z=np.array([0.6, 0.4]))
+print(f"β = {res.beta:.3f}   x = {res.x}   y = {res.y}")
+```
+
+## CLI
+
+```
+prbs-eos flash   --T 250 --P 1e6 --mix methane:0.6 propane:0.4
+prbs-eos bubble  --T 250         --mix methane:0.5 propane:0.5
+prbs-eos properties methane
+prbs-eos components
+```

prbs_eos-0.1.0/prbs_eos/__init__.py

@@ -0,0 +1,6 @@
+from .constants import R
+from .data import Component, Mixture, get_component, available_components
+from .core import PREOS, PRBSEOS, solve_cubic, select_z
+from .equilibrium import flash_pt, FlashResult, is_stable
+from .thermodynamics import enthalpy_departure, entropy_departure
+from .regression import regress_kij, regress_vpaa

prbs_eos-0.1.0/prbs_eos/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running the CLI via ``python -m prbs_eos``."""
+from .cli import main
+
+main()

prbs_eos-0.1.0/prbs_eos/cli.py

@@ -0,0 +1,308 @@
+"""
+prbs-eos command-line interface.
+
+Usage examples
+--------------
+    prbs-eos components
+    prbs-eos properties methane
+    prbs-eos flash    --T 250 --P 1e6  --mix methane:0.6 propane:0.4
+    prbs-eos zfactor  --T 300 --P 2e6  --mix methane:0.7 propane:0.3 --phase vapor
+    prbs-eos fugacity --T 300 --P 2e6  --mix methane:0.7 propane:0.3 --phase vapor
+    prbs-eos bubble   --T 250          --mix methane:0.5 propane:0.5  --P-guess 2e6
+    prbs-eos dew      --T 250          --mix methane:0.5 propane:0.5  --P-guess 2e6
+    prbs-eos enthalpy --T 300 --P 2e6  --mix methane:0.7 propane:0.3 --phase vapor
+"""
+
+import argparse
+import json
+import sys
+import numpy as np
+
+from . import (
+    Mixture, PREOS, get_component, available_components,
+    flash_pt, enthalpy_departure, entropy_departure,
+)
+from .equilibrium.phase_envelope import bubble_point_P, dew_point_P
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _parse_mix(mix_tokens: list[str]) -> tuple[Mixture, np.ndarray]:
+    """
+    Parse ``['methane:0.6', 'propane:0.4']`` into a (Mixture, z) pair.
+    Mole fractions are normalised to sum to 1.
+    """
+    comps, fracs = [], []
+    for token in mix_tokens:
+        if ":" not in token:
+            _die(f"Bad mixture token '{token}'. Expected format: name:fraction")
+        name, frac_str = token.rsplit(":", 1)
+        try:
+            frac = float(frac_str)
+        except ValueError:
+            _die(f"Cannot parse fraction '{frac_str}' in token '{token}'")
+        if frac < 0:
+            _die(f"Negative mole fraction in token '{token}'")
+        comps.append(get_component(name.strip()))
+        fracs.append(frac)
+    z = np.array(fracs, dtype=float)
+    total = z.sum()
+    if total <= 0:
+        _die("Mole fractions sum to zero.")
+    z /= total
+    return Mixture(comps), z
+
+
+def _die(msg: str) -> None:
+    print(f"ERROR: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def _out(data: dict, as_json: bool) -> None:
+    """Print result as a formatted table or JSON."""
+    if as_json:
+        print(json.dumps(data, indent=2))
+    else:
+        for key, val in data.items():
+            if isinstance(val, dict):
+                print(f"  {key}:")
+                for k2, v2 in val.items():
+                    print(f"    {k2:<20s} {v2}")
+            else:
+                print(f"  {key:<26s} {val}")
+
+
+# ---------------------------------------------------------------------------
+# Sub-command handlers
+# ---------------------------------------------------------------------------
+
+def cmd_components(_args) -> None:
+    print("Built-in components:")
+    for name in available_components():
+        print(f"  {name}")
+
+
+def cmd_properties(args) -> None:
+    try:
+        c = get_component(args.name)
+    except KeyError as e:
+        _die(str(e))
+    data = {
+        "name":         c.name,
+        "Tc (K)":       f"{c.Tc:.2f}",
+        "Pc (MPa)":     f"{c.Pc / 1e6:.4f}",
+        "omega":        f"{c.omega:.4f}",
+        "Mw (g/mol)":   f"{c.Mw:.3f}",
+        "c (m3/mol)":   f"{c.c:.3e}",
+        "epsilon (J/mol)": f"{c.epsilon:.2f}",
+        "kappa":        f"{c.kappa:.4f}",
+        "assoc_sites":  str(c.assoc_sites),
+    }
+    _out(data, args.json)
+
+
+def cmd_flash(args) -> None:
+    try:
+        mix, z = _parse_mix(args.mix)
+    except KeyError as e:
+        _die(str(e))
+    eos = PREOS(mix)
+    res = flash_pt(eos, T=args.T, P=args.P, z=z)
+    names = [c.name for c in mix.components]
+    data = {
+        "T (K)":            f"{args.T:.2f}",
+        "P (MPa)":          f"{args.P / 1e6:.4f}",
+        "vapour fraction beta":f"{res.beta:.6f}",
+        "converged":        str(res.converged),
+        "iterations":       str(res.iterations),
+        "liquid  x": {n: f"{v:.6f}" for n, v in zip(names, res.x)},
+        "vapour  y": {n: f"{v:.6f}" for n, v in zip(names, res.y)},
+        "K-factors": {n: f"{v:.6f}" for n, v in zip(names, res.K)},
+    }
+    _out(data, args.json)
+
+
+def cmd_zfactor(args) -> None:
+    try:
+        mix, z = _parse_mix(args.mix)
+    except KeyError as e:
+        _die(str(e))
+    eos = PREOS(mix)
+    Z = eos.Z_factor(T=args.T, P=args.P, z=z, phase=args.phase)
+    data = {
+        "T (K)":    f"{args.T:.2f}",
+        "P (MPa)":  f"{args.P / 1e6:.4f}",
+        "phase":    args.phase,
+        "Z-factor": f"{Z:.6f}",
+    }
+    _out(data, args.json)
+
+
+def cmd_fugacity(args) -> None:
+    try:
+        mix, z = _parse_mix(args.mix)
+    except KeyError as e:
+        _die(str(e))
+    eos = PREOS(mix)
+    phi = eos.fugacity_coeff(T=args.T, P=args.P, z=z, phase=args.phase)
+    f   = eos.fugacity(T=args.T, P=args.P, z=z, phase=args.phase)
+    names = [c.name for c in mix.components]
+    data = {
+        "T (K)":   f"{args.T:.2f}",
+        "P (MPa)": f"{args.P / 1e6:.4f}",
+        "phase":   args.phase,
+        "fugacity coefficients phi_i": {n: f"{v:.6f}" for n, v in zip(names, phi)},
+        "fugacities f_i (Pa)":        {n: f"{v:.4e}" for n, v in zip(names, f)},
+    }
+    _out(data, args.json)
+
+
+def cmd_bubble(args) -> None:
+    try:
+        mix, z = _parse_mix(args.mix)
+    except KeyError as e:
+        _die(str(e))
+    eos = PREOS(mix)
+    Pb = bubble_point_P(eos, T=args.T, z=z, P_guess=args.P_guess)
+    data = {
+        "T (K)":               f"{args.T:.2f}",
+        "bubble-point P (Pa)": "nan (supercritical or out of range)" if np.isnan(Pb) else f"{Pb:.2f}",
+        "bubble-point P (MPa)":"nan" if np.isnan(Pb) else f"{Pb / 1e6:.4f}",
+    }
+    _out(data, args.json)
+
+
+def cmd_dew(args) -> None:
+    try:
+        mix, z = _parse_mix(args.mix)
+    except KeyError as e:
+        _die(str(e))
+    eos = PREOS(mix)
+    Pd = dew_point_P(eos, T=args.T, z=z, P_guess=args.P_guess)
+    data = {
+        "T (K)":             f"{args.T:.2f}",
+        "dew-point P (Pa)":  "nan (supercritical or out of range)" if np.isnan(Pd) else f"{Pd:.2f}",
+        "dew-point P (MPa)": "nan" if np.isnan(Pd) else f"{Pd / 1e6:.4f}",
+    }
+    _out(data, args.json)
+
+
+def cmd_enthalpy(args) -> None:
+    try:
+        mix, z = _parse_mix(args.mix)
+    except KeyError as e:
+        _die(str(e))
+    eos = PREOS(mix)
+    H = enthalpy_departure(eos, T=args.T, P=args.P, z=z, phase=args.phase)
+    S = entropy_departure(eos,  T=args.T, P=args.P, z=z, phase=args.phase)
+    data = {
+        "T (K)":                 f"{args.T:.2f}",
+        "P (MPa)":               f"{args.P / 1e6:.4f}",
+        "phase":                 args.phase,
+        "H_dep (J/mol)":         f"{H:.4f}",
+        "S_dep (J/mol/K)":        f"{S:.6f}",
+        "G_dep = H-TS (J/mol)":   f"{H - args.T * S:.4f}",
+    }
+    _out(data, args.json)
+
+
+# ---------------------------------------------------------------------------
+# Argument parser
+# ---------------------------------------------------------------------------
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="prbs-eos",
+        description=(
+            "PRBS Equation of State — petroleum thermodynamics toolkit.\n"
+            "Run 'prbs-eos <command> --help' for per-command options."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version="prbs-eos 0.1.0")
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    sub.required = True
+
+    # ---- shared options ------------------------------------------------
+    def add_mix(p):
+        p.add_argument(
+            "--mix", nargs="+", required=True, metavar="NAME:FRAC",
+            help="Mixture components, e.g.  methane:0.6 propane:0.4"
+        )
+    def add_TP(p):
+        p.add_argument("--T", type=float, required=True, metavar="K",
+                       help="Temperature [K]")
+        p.add_argument("--P", type=float, required=True, metavar="Pa",
+                       help="Pressure [Pa]  (e.g. 2e6 = 2 MPa)")
+    def add_phase(p):
+        p.add_argument("--phase", choices=["vapor", "liquid"], default="vapor",
+                       help="Phase selection (default: vapor)")
+    def add_json(p):
+        p.add_argument("--json", action="store_true",
+                       help="Output as JSON")
+    def add_P_guess(p):
+        p.add_argument("--P-guess", type=float, default=1e6, dest="P_guess",
+                       metavar="Pa",
+                       help="Initial pressure guess for bracketing [Pa] (default: 1e6)")
+
+    # ---- components ----------------------------------------------------
+    p = sub.add_parser("components", help="List all built-in components")
+    add_json(p)
+    p.set_defaults(func=cmd_components)
+
+    # ---- properties ----------------------------------------------------
+    p = sub.add_parser("properties", help="Show critical properties of a component")
+    p.add_argument("name", help="Component name (e.g. methane, co2, water)")
+    add_json(p)
+    p.set_defaults(func=cmd_properties)
+
+    # ---- flash ---------------------------------------------------------
+    p = sub.add_parser("flash", help="Two-phase PT flash (Rachford-Rice)")
+    add_TP(p); add_mix(p); add_json(p)
+    p.set_defaults(func=cmd_flash)
+
+    # ---- zfactor -------------------------------------------------------
+    p = sub.add_parser("zfactor", help="Compressibility factor Z")
+    add_TP(p); add_mix(p); add_phase(p); add_json(p)
+    p.set_defaults(func=cmd_zfactor)
+
+    # ---- fugacity ------------------------------------------------------
+    p = sub.add_parser("fugacity", help="Fugacity coefficients and fugacities")
+    add_TP(p); add_mix(p); add_phase(p); add_json(p)
+    p.set_defaults(func=cmd_fugacity)
+
+    # ---- bubble --------------------------------------------------------
+    p = sub.add_parser("bubble", help="Bubble-point pressure at fixed T")
+    p.add_argument("--T", type=float, required=True, metavar="K")
+    add_mix(p); add_P_guess(p); add_json(p)
+    p.set_defaults(func=cmd_bubble)
+
+    # ---- dew -----------------------------------------------------------
+    p = sub.add_parser("dew", help="Dew-point pressure at fixed T")
+    p.add_argument("--T", type=float, required=True, metavar="K")
+    add_mix(p); add_P_guess(p); add_json(p)
+    p.set_defaults(func=cmd_dew)
+
+    # ---- enthalpy ------------------------------------------------------
+    p = sub.add_parser("enthalpy",
+                        help="Enthalpy/entropy departure functions (H_dep, S_dep, G_dep)")
+    add_TP(p); add_mix(p); add_phase(p); add_json(p)
+    p.set_defaults(func=cmd_enthalpy)
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main(argv: list[str] | None = None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

prbs_eos-0.1.0/prbs_eos/constants.py

@@ -0,0 +1 @@
+R = 8.314462618  # J/(mol·K)

prbs_eos-0.1.0/prbs_eos/core/__init__.py

@@ -0,0 +1,4 @@
+from .cubic_solver import solve_cubic, select_z
+from .eos_base import CubicEOS
+from .pr_eos import PREOS
+from .prbs_eos import PRBSEOS

prbs_eos-0.1.0/prbs_eos/core/cubic_solver.py

@@ -0,0 +1,30 @@
+"""
+Analytical and numerical roots of the cubic EOS in Z-factor form:
+  Z³ + p·Z² + q·Z + r = 0
+"""
+import numpy as np
+
+
+def solve_cubic(p: float, q: float, r: float) -> np.ndarray:
+    """Return all real roots of Z³ + p·Z² + q·Z + r = 0, sorted ascending."""
+    coeffs = [1.0, p, q, r]
+    roots = np.roots(coeffs)
+    real_roots = roots[np.abs(roots.imag) < 1e-8].real
+    return np.sort(real_roots)
+
+
+def select_z(roots: np.ndarray, phase: str) -> float:
+    """
+    From the array of real positive Z roots select the thermodynamically
+    correct one for the requested phase ('vapor' or 'liquid').
+    """
+    pos = roots[roots > 0]
+    if len(pos) == 0:
+        raise ValueError("No positive Z root found.")
+    if len(pos) == 1:
+        return float(pos[0])
+    if phase == "vapor":
+        return float(pos.max())
+    if phase == "liquid":
+        return float(pos.min())
+    raise ValueError(f"Unknown phase '{phase}'. Use 'vapor' or 'liquid'.")

prbs_eos-0.1.0/prbs_eos/core/eos_base.py

@@ -0,0 +1,84 @@
+"""Abstract base for cubic EOS implementations."""
+from abc import ABC, abstractmethod
+import numpy as np
+from ..data.mixture import Mixture
+
+
+class CubicEOS(ABC):
+    """
+    Subclasses must implement `_ab_pure` and `_mix_rule`.
+    Public API: `Z_factor`, `fugacity_coeff`.
+    """
+
+    def __init__(self, mixture: Mixture):
+        self.mix = mixture
+
+    # ------------------------------------------------------------------
+    # Abstract
+    # ------------------------------------------------------------------
+    @abstractmethod
+    def _ab_pure(self, T: float) -> tuple[np.ndarray, np.ndarray]:
+        """Return arrays (a_i, b_i) for each component at temperature T."""
+
+    @abstractmethod
+    def _mix_rule(
+        self, T: float, z: np.ndarray
+    ) -> tuple[float, float, np.ndarray]:
+        """
+        Return (a_mix, b_mix, (da/dni)_T) using the van der Waals mixing rule
+        with kij corrections.
+        """
+
+    @abstractmethod
+    def _cubic_coeffs(
+        self, T: float, P: float, a: float, b: float
+    ) -> tuple[float, float, float]:
+        """Return (p, q, r) for Z³ + p·Z² + q·Z + r = 0."""
+
+    @abstractmethod
+    def _ln_phi_i(
+        self,
+        i: int,
+        Z: float,
+        T: float,
+        P: float,
+        z: np.ndarray,
+        a: float,
+        b: float,
+        dai_dn: np.ndarray,
+    ) -> float:
+        """Return ln φ_i for component i."""
+
+    # ------------------------------------------------------------------
+    # Public
+    # ------------------------------------------------------------------
+    def Z_factor(
+        self, T: float, P: float, z: np.ndarray, phase: str = "vapor"
+    ) -> float:
+        from .cubic_solver import solve_cubic, select_z
+        z = np.asarray(z, dtype=float)
+        a, b, _ = self._mix_rule(T, z)
+        p, q, r = self._cubic_coeffs(T, P, a, b)
+        roots = solve_cubic(p, q, r)
+        return select_z(roots, phase)
+
+    def fugacity_coeff(
+        self, T: float, P: float, z: np.ndarray, phase: str = "vapor"
+    ) -> np.ndarray:
+        z = np.asarray(z, dtype=float)
+        a, b, dai_dn = self._mix_rule(T, z)
+        p, q, r = self._cubic_coeffs(T, P, a, b)
+        from .cubic_solver import solve_cubic, select_z
+        roots = solve_cubic(p, q, r)
+        Z = select_z(roots, phase)
+        nc = self.mix.nc
+        ln_phi = np.array(
+            [self._ln_phi_i(i, Z, T, P, z, a, b, dai_dn) for i in range(nc)]
+        )
+        return np.exp(ln_phi)
+
+    def fugacity(
+        self, T: float, P: float, z: np.ndarray, phase: str = "vapor"
+    ) -> np.ndarray:
+        z = np.asarray(z, dtype=float)
+        return z * P * self.fugacity_coeff(T, P, z, phase)

prbs_eos-0.1.0/prbs_eos/core/pr_eos.py

@@ -0,0 +1,66 @@
+"""
+Peng-Robinson EOS (1976).
+  P = RT/(V-b) - a(T)/[V(V+b)+b(V-b)]
+"""
+import numpy as np
+from ..constants import R
+from ..data.mixture import Mixture
+from .eos_base import CubicEOS
+
+
+class PREOS(CubicEOS):
+    # PR universal constants
+    _OmegaA = 0.45723553
+    _OmegaB = 0.07779607
+
+    def __init__(self, mixture: Mixture):
+        super().__init__(mixture)
+
+    # ------------------------------------------------------------------
+    def _kappa(self) -> np.ndarray:
+        w = self.mix.omega
+        return 0.37464 + 1.54226 * w - 0.26992 * w ** 2
+
+    def _ab_pure(self, T: float):
+        Tc = self.mix.Tc
+        Pc = self.mix.Pc
+        kappa = self._kappa()
+        Tr = T / Tc
+        alpha = (1.0 + kappa * (1.0 - np.sqrt(Tr))) ** 2
+        a = self._OmegaA * (R * Tc) ** 2 / Pc * alpha
+        b = self._OmegaB * R * Tc / Pc
+        return a, b
+
+    def _mix_rule(self, T: float, z: np.ndarray):
+        a_i, b_i = self._ab_pure(T)
+        kij = self.mix.kij
+        nc = self.mix.nc
+        # a_ij = sqrt(a_i * a_j) * (1 - kij)
+        a_ij = np.sqrt(np.outer(a_i, a_i)) * (1.0 - kij)
+        a_mix = float(z @ a_ij @ z)
+        b_mix = float(z @ b_i)
+        # da_mix/dn_i  (at constant n_j≠i, normalised mole fraction)
+        dai_dn = 2.0 * (a_ij @ z)
+        return a_mix, b_mix, dai_dn
+
+    def _cubic_coeffs(self, T: float, P: float, a: float, b: float):
+        A = a * P / (R * T) ** 2
+        B = b * P / (R * T)
+        p = B - 1.0
+        q = A - 3.0 * B ** 2 - 2.0 * B
+        r = B ** 3 + B ** 2 - A * B
+        return p, q, r
+
+    def _ln_phi_i(self, i, Z, T, P, z, a, b, dai_dn):
+        a_i, b_i = self._ab_pure(T)
+        A = a * P / (R * T) ** 2
+        B = b * P / (R * T)
+        bi = b_i[i]
+        ln_phi = (
+            bi / b * (Z - 1.0)
+            - np.log(Z - B)
+            - A / (2.0 * np.sqrt(2.0) * B)
+            * (dai_dn[i] / a - bi / b)
+            * np.log((Z + (1.0 + np.sqrt(2.0)) * B) / (Z + (1.0 - np.sqrt(2.0)) * B))
+        )
+        return ln_phi

prbs_eos-0.1.0/prbs_eos/core/prbs_eos.py

@@ -0,0 +1,100 @@
+"""
+PRBS-EOS: Peng-Robinson with Boublik-Mansoori-Carnahan-Starling (BMCS)
+hard-sphere repulsion term and a simplified CPA-style association
+contribution, combined with a Peneloux volume shift.
+
+For non-associating mixtures this reduces to standard PR with a
+volume shift, so it is backward-compatible with PREOS.
+"""
+import numpy as np
+from scipy.optimize import brentq
+from ..constants import R
+from ..data.mixture import Mixture
+from .pr_eos import PREOS
+
+
+class PRBSEOS(PREOS):
+    """
+    PRBS = PR + volume-shift (Peneloux) + optional association (CPA-style).
+
+    Association contribution uses a 4-site model for self-associating
+    components (e.g. water).  Cross-association is neglected here.
+    """
+
+    def __init__(self, mixture: Mixture):
+        super().__init__(mixture)
+        self._c = np.array([comp.c for comp in mixture.components])
+        self._eps = np.array([comp.epsilon for comp in mixture.components])
+        self._kap = np.array([comp.kappa for comp in mixture.components])
+        self._sites = np.array([comp.assoc_sites for comp in mixture.components], dtype=int)
+
+    # ------------------------------------------------------------------
+    # Volume shift: shift molar volume after Z-factor calculation
+    # ------------------------------------------------------------------
+    def _volume_shift(self, z: np.ndarray) -> float:
+        """Return molar volume shift c_mix = Σ z_i c_i  [m³/mol]."""
+        return float(z @ self._c)
+
+    def molar_volume(
+        self, T: float, P: float, z: np.ndarray, phase: str = "vapor"
+    ) -> float:
+        """Volume-shifted molar volume [m³/mol]."""
+        z = np.asarray(z, dtype=float)
+        Z = self.Z_factor(T, P, z, phase)
+        V_raw = Z * R * T / P
+        return V_raw - self._volume_shift(z)
+
+    # ------------------------------------------------------------------
+    # Association  (simplified 4-site CPA)
+    # ------------------------------------------------------------------
+    def _assoc_X(self, T: float, rho_mol: float, z: np.ndarray) -> np.ndarray:
+        """
+        Solve for fraction of unbonded sites X_i ∈ (0,1] for each component.
+        Uses the Michelsen-Hendriks iterative scheme.
+
+        Association strength:  Δ_i = b_i * κ_i * (exp(ε_i / RT) - 1)
+        At low density rho_mol → 0, the site-occupancy denominator vanishes
+        and X_i → 1 (all sites free), which is the correct ideal-gas limit.
+        """
+        nc = self.mix.nc
+        _, b_i = self._ab_pure(T)   # co-volume b_i [m³/mol] for each component
+        X = np.ones(nc)
+        for _ in range(200):
+            X_old = X.copy()
+            for i in range(nc):
+                if self._sites[i] == 0:
+                    continue
+                # Δ = b_i * κ_i * (exp(ε_i / RT) - 1)   [m³/mol]
+                delta = b_i[i] * self._kap[i] * (np.exp(self._eps[i] / (R * T)) - 1.0)
+                X[i] = 1.0 / (1.0 + self._sites[i] * z[i] * rho_mol * delta * X[i])
+            if np.max(np.abs(X - X_old)) < 1e-10:
+                break
+        return X
+
+    def _assoc_lnphi_correction(
+        self, T: float, P: float, z: np.ndarray, phase: str
+    ) -> np.ndarray:
+        """ln φ correction from association for each component."""
+        nc = self.mix.nc
+        if not np.any(self._sites > 0):
+            return np.zeros(nc)
+        V = self.molar_volume(T, P, z, phase)
+        rho_mol = 1.0 / V  # mol/m³
+        X = self._assoc_X(T, rho_mol, z)
+        ln_corr = np.zeros(nc)
+        for i in range(nc):
+            M = self._sites[i]
+            if M == 0:
+                continue
+            ln_corr[i] = M * (np.log(X[i]) - X[i] / 2.0 + 0.5)
+        return ln_corr
+
+    # ------------------------------------------------------------------
+    # Override fugacity_coeff to add association
+    # ------------------------------------------------------------------
+    def fugacity_coeff(
+        self, T: float, P: float, z: np.ndarray, phase: str = "vapor"
+    ) -> np.ndarray:
+        phi_pr = super().fugacity_coeff(T, P, z, phase)
+        ln_assoc = self._assoc_lnphi_correction(T, P, z, phase)
+        return phi_pr * np.exp(ln_assoc)