co2-eos 0.3.0__tar.gz → 0.3.1__tar.gz

{co2_eos-0.3.0 → co2_eos-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: co2-eos
-Version: 0.3.0
+Version: 0.3.1
 Summary: Differentiable CO₂ thermodynamic properties in JAX
 Author-email: John Patrick Therrien <john@flux-tech.de>
 License-Expression: Apache-2.0

{co2_eos-0.3.0 → co2_eos-0.3.1}/co2_eos/__init__.py

@@ -52,7 +52,7 @@ import jax.numpy as jnp
 # Enable float64 for the entire library (also done by submodules).
 jax.config.update("jax_enable_x64", True)
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 # ── Phase hint constants ────────────────────────────────────────────────────
 LIQUID = 0

{co2_eos-0.3.0 → co2_eos-0.3.1}/co2_eos/inversions.py

@@ -54,6 +54,23 @@ _du_drho = jax.grad(sw._scalar_internal_energy, argnums=1)
 
 # ── Phase-aware initial guess ─────────────────────────────────────────────
 
+def _subcritical_branch(T, P):
+    """Which stable branch a (T, P) state below TC lies on, and its bracket.
+
+    Below TC the Span-Wagner isotherm is an analytic continuation through the
+    dome: it loops between the spinodals and can swing far above P_sat (at
+    294 K it reaches 12 MPa near 550 kg/m³), so P(T, ρ) = P_target has spurious
+    roots inside the dome for any P_target below that swing. The only way to
+    pick the physical root is by P against P_sat(T): P ≥ P_sat is compressed
+    liquid, ρ ≥ ρ_l(T); P < P_sat is vapor, ρ ≤ ρ_v(T). Returns
+    (liquid_side, rho_l_T, rho_v_T); the saturation table is used only where
+    T < TC, so its behaviour above TC does not matter here.
+    """
+    rho_l_T, rho_v_T = sat.saturation_densities(T)
+    liquid_side = P >= sat.saturation_pressure(T)
+    return liquid_side, rho_l_T, rho_v_T
+
+
 def _initial_guess(T, P, phase_hint):
     """Return an initial density guess based on phase_hint.
 
@@ -61,10 +78,7 @@ def _initial_guess(T, P, phase_hint):
     Uses jnp.where for JIT traceability.
     """
     subcritical_T = T < sw.TC
-
-    # T-based saturation densities — good for compressed liquid (rho_l at T)
-    # and low-pressure vapor (rho_v at T)
-    rho_l_T, rho_v_T = sat.saturation_densities(T)
+    liquid_side, rho_l_T, rho_v_T = _subcritical_branch(T, P)
 
     # Liquid: saturation liquid density at T (good for compressed liquid),
     # fall back to 2*RHOC for supercritical T
@@ -72,23 +86,22 @@ def _initial_guess(T, P, phase_hint):
     # Vapor: saturation vapor density at T, fall back to ideal gas
     ideal_gas_rho = P / (sw.R * T)
     vapor_guess = jnp.where(subcritical_T, rho_v_T, ideal_gas_rho)
-    # Supercritical: pressure-aware guess near the critical region.
-    # Near PC and TC, use RHOC. Otherwise, vapor-like (P < PC) uses ideal gas,
-    # liquid-like (P > 1.5*PC) uses 2*RHOC.
-    # When T is well below TC (liquid-like regardless of pressure), use
-    # saturated liquid density at T — same logic as the LIQUID branch.
+    # Auto, T >= TC: the isotherm is monotone, so any pressure-aware seed
+    # converges. Near PC and TC use RHOC; liquid-like (P > 1.5*PC) 2*RHOC;
+    # otherwise ideal gas.
     near_critical = jnp.logical_and(
         jnp.abs(P - sw.PC) < 0.2 * sw.PC,
         jnp.abs(T - sw.TC) < 15.0,
     )
-    clearly_liquid = T < sw.TC - 10.0
-    sc_guess = jnp.where(
-        clearly_liquid, rho_l_T,
-        jnp.where(
-            near_critical, sw.RHOC,
-            jnp.where(P > 1.5 * sw.PC, 2.0 * sw.RHOC, ideal_gas_rho)
-        )
+    sc_guess_above_TC = jnp.where(
+        near_critical, sw.RHOC,
+        jnp.where(P > 1.5 * sw.PC, 2.0 * sw.RHOC, ideal_gas_rho)
     )
+    # Auto, T < TC: seed on the stable branch P_sat(T) selects. A seed inside
+    # the dome (RHOC, or the ideal-gas density) lands Halley on a spurious
+    # root of the isotherm's loop, with dP/dρ > 0 and no sign of trouble.
+    sc_guess_below_TC = jnp.where(liquid_side, rho_l_T, rho_v_T)
+    sc_guess = jnp.where(subcritical_T, sc_guess_below_TC, sc_guess_above_TC)
 
     rho0 = jnp.where(
         phase_hint == LIQUID, liquid_guess,
@@ -144,16 +157,16 @@ def _halley_cond(state):
 _BISECT_LO = 1.0       # kg/m³ — lower bound
 _BISECT_HI = 1200.0    # kg/m³ — upper bound
 _BISECT_ITERS = 60      # ~10⁻¹⁸ relative precision
+_BRANCH_TOL = 1e-4      # relative slack around ρ_l(T), ρ_v(T) for the branch tests
 
 
 def _bisection_body(state):
     """One bisection step on f(ρ) = P(T,ρ) − P_target.
 
-    Monotonicity assumption: P(T,ρ) is monotonically increasing in ρ for
-    single-phase stable fluid (∂P/∂ρ > 0).  This does NOT hold inside the
-    spinodal (unstable) region, but that's fine — the bisection is a safety
-    net for near-critical supercritical states where Halley oscillates, not
-    for subcritical dome-crossing (handled by dome detection in state_from_Ph).
+    Monotonicity assumption: P(T,ρ) is monotonically increasing in ρ on the
+    bracket. That holds on any single-phase stable branch (∂P/∂ρ > 0) and
+    fails inside the spinodal loop, so below TC the caller brackets the
+    stable branch (`_bisection_bracket`) instead of the whole [1, 1200] range.
     """
     lo, hi, T, P_target, i = state
     mid = 0.5 * (lo + hi)
@@ -170,16 +183,61 @@ def _bisection_cond(state):
     return jnp.logical_and(i < _BISECT_ITERS, (hi - lo) > 1e-14 * hi)
 
 
-def _bisection_solve(T, P):
-    """Bisection solve for ρ given (T, P). Scalar inputs. Bounds [1, 1200] kg/m³."""
-    init_state = (_BISECT_LO, _BISECT_HI, T, P, jnp.int32(0))
+def _bisection_bracket(T, P, phase_hint):
+    """Density bracket [lo, hi] on which P(T, ρ) is monotone for this state.
+
+    Above TC the whole range. Below TC the stable branch: [ρ_l(T), 1200] on
+    the liquid side, [1, ρ_v(T)] on the vapor side, the side taken from the
+    explicit hint or, under auto, from P against P_sat(T).
+    """
+    subcritical_T = T < sw.TC
+    liquid_side, rho_l_T, rho_v_T = _subcritical_branch(T, P)
+    liquid_side = jnp.where(
+        phase_hint == LIQUID, True,
+        jnp.where(phase_hint == VAPOR, False, liquid_side)
+    )
+    # A slack of _BRANCH_TOL keeps the saturation point itself inside the
+    # bracket (the spline carries ~6e-8 relative error) while excluding the
+    # dome interior, whose roots sit tens of percent away.
+    lo = jnp.where(jnp.logical_and(subcritical_T, liquid_side),
+                   rho_l_T * (1.0 - _BRANCH_TOL), _BISECT_LO)
+    hi = jnp.where(jnp.logical_and(subcritical_T, jnp.logical_not(liquid_side)),
+                   rho_v_T * (1.0 + _BRANCH_TOL), _BISECT_HI)
+    return lo, hi
+
+
+def _bisection_solve(T, P, lo=_BISECT_LO, hi=_BISECT_HI):
+    """Bisection solve for ρ given (T, P) on [lo, hi]. Scalar inputs."""
+    init_state = (jnp.asarray(lo, dtype=jnp.float64), jnp.asarray(hi, dtype=jnp.float64),
+                  T, P, jnp.int32(0))
     final_state = jax.lax.while_loop(_bisection_cond, _bisection_body, init_state)
     lo, hi, _, _, _ = final_state
     return 0.5 * (lo + hi)
 
 
+def _on_requested_branch(T, P, rho, phase_hint):
+    """Under the auto hint below TC, is the converged root on the stable branch?
+
+    A root inside the dome satisfies P(T, ρ) = P_target with ∂P/∂ρ > 0 and
+    passes every residual test, so the only check that catches it is its
+    position relative to the saturation densities. Explicit LIQUID/VAPOR hints
+    are the caller's assertion (a metastable request is legitimate) and are
+    not checked.
+    """
+    subcritical_T = T < sw.TC
+    liquid_side, rho_l_T, rho_v_T = _subcritical_branch(T, P)
+    on_branch = jnp.where(liquid_side, rho >= rho_l_T * (1.0 - _BRANCH_TOL),
+                          rho <= rho_v_T * (1.0 + _BRANCH_TOL))
+    checked = jnp.logical_and(subcritical_T, phase_hint == SUPERCRITICAL)
+    return jnp.logical_or(jnp.logical_not(checked), on_branch)
+
+
 def _solve_density(T, P, phase_hint):
-    """Halley solve for ρ given (T, P, phase_hint), with bisection fallback. Scalar inputs."""
+    """Halley solve for ρ given (T, P, phase_hint), with bisection fallback. Scalar inputs.
+
+    A root on the wrong side of the dome under the auto hint is returned as
+    NaN, the package's failure signal, never as a number.
+    """
     rho0 = _initial_guess(T, P, phase_hint)
     init_state = (rho0, T, P, jnp.int32(0), jnp.bool_(False))
     final_state = jax.lax.while_loop(_halley_cond, _halley_body, init_state)
@@ -187,17 +245,19 @@ def _solve_density(T, P, phase_hint):
 
     # Bisection safety net — only runs when Halley did not converge
     def _bisect_branch(_):
-        rho_bisect = _bisection_solve(T, P)
+        lo, hi = _bisection_bracket(T, P, phase_hint)
+        rho_bisect = _bisection_solve(T, P, lo, hi)
         bisect_residual = jnp.abs(sw._scalar_pressure(T, rho_bisect) - P)
         bisect_ok = bisect_residual < 1e-3 * jnp.maximum(jnp.abs(P), 1.0)
         return jnp.where(bisect_ok, rho_bisect, jnp.nan)
 
-    return jax.lax.cond(
+    rho = jax.lax.cond(
         converged,
         lambda _: rho_halley,
         _bisect_branch,
         None,
     )
+    return jnp.where(_on_requested_branch(T, P, rho, phase_hint), rho, jnp.nan)
 
 
 # ── Implicit differentiation via custom_jvp ───────────────────────────────

{co2_eos-0.3.0 → co2_eos-0.3.1}/co2_eos.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: co2-eos
-Version: 0.3.0
+Version: 0.3.1
 Summary: Differentiable CO₂ thermodynamic properties in JAX
 Author-email: John Patrick Therrien <john@flux-tech.de>
 License-Expression: Apache-2.0

{co2_eos-0.3.0 → co2_eos-0.3.1}/co2_eos.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ co2_eos/data/saturation_table.npz
 co2_eos/data/seed_table.npz
 tests/test_accuracy_vs_coolprop.py
 tests/test_analytic_derivs.py
+tests/test_density_from_PT_branch.py
 tests/test_dome_detection.py
 tests/test_fastpath_validation.py
 tests/test_inversion_gradients.py

{co2_eos-0.3.0 → co2_eos-0.3.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "co2-eos"
-version = "0.3.0"
+version = "0.3.1"
 description = "Differentiable CO₂ thermodynamic properties in JAX"
 readme = "README.md"
 license = "Apache-2.0"

co2_eos-0.3.1/tests/test_density_from_PT_branch.py

@@ -0,0 +1,113 @@
+"""
+density_from_PT below TC must land on the stable branch under the auto hint.
+
+Below TC the Span-Wagner isotherm is an analytic continuation through the dome
+and loops between the spinodals; at 294 K it swings up to about 12 MPa near
+550 kg/m³, so P(T, ρ) = P_target has roots inside the dome for any target below
+that swing, each with ∂P/∂ρ > 0 and a zero residual. A solve seeded inside the
+dome converges to one of them and reports nothing wrong. The regression that
+exposed this: T = 294.15 K (0.02 K above the old `T < TC - 10` liquid guard),
+P = 8.12 and 9.04 MPa, auto hint, returned 499 and 506 kg/m³ against the
+compressed-liquid 821 and 836.
+
+The contract tested here: under the auto hint the seed, the bisection bracket
+and the branch guard all follow P against P_sat(T), so the result matches
+CoolProp on the liquid side (P ≥ P_sat) and on the vapor side (P < P_sat) at
+every subcritical temperature, through jit and vmap, and a root on the wrong
+side of the dome is never returned as a number.
+"""
+
+import numpy as np
+import pytest
+import jax
+import jax.numpy as jnp
+
+jax.config.update("jax_enable_x64", True)
+
+import co2_eos
+from co2_eos import span_wagner as sw
+from co2_eos import saturation as sat
+from co2_eos.inversions import _on_requested_branch
+
+CP = pytest.importorskip("CoolProp.CoolProp")
+
+RTOL = 1e-8
+
+
+def _ref(T, P):
+    return CP.PropsSI("D", "T", float(T), "P", float(P), "CO2")
+
+
+# ── The regression points ───────────────────────────────────────────────────
+
+@pytest.mark.parametrize("T,P", [
+    (294.15, 8.12e6),
+    (294.15, 9.04e6),
+    (294.15, 6.5e6),
+    (296.15, 6.5e6),
+])
+def test_regression_points_match_liquid_hint_and_coolprop(T, P):
+    rho_auto = float(co2_eos.density_from_PT(P, T, co2_eos.AUTO))
+    rho_liq = float(co2_eos.density_from_PT(P, T, co2_eos.LIQUID))
+    ref = _ref(T, P)
+    assert rho_auto == pytest.approx(ref, rel=RTOL)
+    assert rho_liq == pytest.approx(ref, rel=RTOL)
+
+
+# ── Both sides of the dome, every subcritical temperature ───────────────────
+
+def _subcritical_grid():
+    for T in np.linspace(220.0, 304.0, 22):
+        P_sat = CP.PropsSI("P", "T", T, "Q", 0, "CO2")
+        for P in np.geomspace(P_sat * 1.0005, 30e6, 8):
+            yield T, P, "liquid"
+        for P in np.geomspace(0.1e6, P_sat * 0.9995, 5):
+            yield T, P, "vapor"
+
+
+@pytest.mark.parametrize("T,P,side", list(_subcritical_grid()))
+def test_auto_hint_follows_P_sat_below_TC(T, P, side):
+    rho = float(co2_eos.density_from_PT(P, T, co2_eos.AUTO))
+    ref = _ref(T, P)
+    assert np.isfinite(rho), f"NaN at T={T}, P={P} ({side})"
+    assert rho == pytest.approx(ref, rel=RTOL)
+    rho_l, rho_v = sat.saturation_densities(jnp.float64(T))
+    if side == "liquid":
+        assert rho >= float(rho_l) * (1.0 - 1e-4)
+    else:
+        assert rho <= float(rho_v) * (1.0 + 1e-4)
+
+
+# ── jit and vmap through the public surface, mixed hints and sides ──────────
+
+def test_jit_vmap_mixed_hints():
+    P = jnp.array([8.12e6, 9.04e6, 6.5e6, 9.04e6, 12e6, 3.0e6])
+    T = jnp.array([294.15, 294.15, 296.15, 320.0, 310.0, 290.0])
+    hint = jnp.array([co2_eos.AUTO, co2_eos.AUTO, co2_eos.AUTO,
+                      co2_eos.AUTO, co2_eos.LIQUID, co2_eos.AUTO])
+    f = jax.jit(jax.vmap(co2_eos.density_from_PT, in_axes=(0, 0, 0)))
+    rho = np.asarray(f(P, T, hint))
+    ref = np.array([_ref(t, p) for p, t in zip(np.asarray(P), np.asarray(T))])
+    np.testing.assert_allclose(rho, ref, rtol=RTOL)
+
+
+def test_gradient_on_the_liquid_branch_near_the_old_hole():
+    T, P = 294.15, 9.04e6
+    g = float(jax.grad(lambda t: co2_eos.density_from_PT(P, t, co2_eos.AUTO))(T))
+    ref = CP.PropsSI("d(D)/d(T)|P", "T", T, "P", P, "CO2")
+    assert g == pytest.approx(ref, rel=1e-6)
+
+
+# ── The branch guard itself ────────────────────────────────────────────────
+
+def test_branch_guard_rejects_a_dome_root_under_auto_only():
+    T, P = jnp.float64(294.15), jnp.float64(8.12e6)
+    dome_root = jnp.float64(499.33)   # the old spurious answer
+    liquid_root = jnp.float64(820.72)
+    assert not bool(_on_requested_branch(T, P, dome_root, jnp.int32(co2_eos.AUTO)))
+    assert bool(_on_requested_branch(T, P, liquid_root, jnp.int32(co2_eos.AUTO)))
+    # explicit hints are the caller's assertion and are not checked
+    assert bool(_on_requested_branch(T, P, dome_root, jnp.int32(co2_eos.LIQUID)))
+    # above TC nothing is checked
+    assert bool(_on_requested_branch(jnp.float64(sw.TC + 5.0), P, dome_root,
+                                     jnp.int32(co2_eos.AUTO)))