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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: co2-eos
-Version: 0.3.0
+Version: 0.6.0
 Summary: Differentiable CO₂ thermodynamic properties in JAX
 Author-email: John Patrick Therrien <john@flux-tech.de>
 License-Expression: Apache-2.0
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://github.com/FluxTech-UG/co2-eos
 Project-URL: Repository, https://github.com/FluxTech-UG/co2-eos
 Project-URL: Documentation, https://github.com/FluxTech-UG/co2-eos#readme
 Project-URL: Issues, https://github.com/FluxTech-UG/co2-eos/issues
-Keywords: CO2,equation-of-state,thermodynamics,JAX,autodiff,Span-Wagner
+Keywords: CO2,equation-of-state,thermodynamics,JAX,autodiff,Span-Wagner,NIST IR 8608
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -46,7 +46,7 @@ import co2_eos as co2
 import jax, jax.numpy as jnp
 
 # Simulation hot path: full state from the conserved variables (ρ, u).
-# Batched/array-native — solves T once and reuses the α-derivatives for
+# Batched/array-native: solves T once and reuses the α-derivatives for
 # every property. This is the call a finite-volume code makes each RHS eval.
 rho = jnp.array([300.0, 350.0, 420.0])      # kg/m³
 u   = jnp.array([3.62e5, 3.58e5, 3.42e5])   # J/kg  (specific internal energy)
@@ -70,6 +70,20 @@ T_array = jnp.linspace(280, 340, 100)
 states = jax.vmap(lambda T: co2.state_from_PT(P=8e6, T=T))(T_array)
 ```
 
+## Two equations of state
+
+Every public function takes `eos=`: `"span_wagner"` (Span and Wagner 1996, the default)
+or `"nist2026"` (Lemmon, Harvey and Hellmann, NIST IR 8608, 2026: 24 terms with no
+nonanalytic terms, free of Span-Wagner's near-critical oscillations in c_p, κ_T and
+(∂c_v/∂T)_ρ). The name is static under `jax.jit`, so each backend compiles once.
+
+```python
+s = co2_eos.properties(314.0, 472.0, eos="nist2026")   # Widom crossing at 9.1 MPa
+```
+
+The transport correlations keep their parameters on either backend; their critical parts
+read the selected backend's thermodynamics.
+
 ## Try it without cloning
 
 [`examples/launch_demo.ipynb`](examples/launch_demo.ipynb) is the launch demo: validation against CoolProp, the `state_from_PT` CPU/GPU benchmarks, and a worked example of gradient-based optimisation through `state_from_PT`. (The v0.2 hot-path `(ρ, u)` benchmarks are in [`bench/PROFILING.md`](bench/PROFILING.md).) [Read it on GitHub](https://github.com/FluxTech-UG/co2-eos/blob/main/examples/launch_demo.ipynb) for a static render, or [open it on Colab](https://colab.research.google.com/github/FluxTech-UG/co2-eos/blob/main/examples/launch_demo.ipynb) and switch the runtime to T4 GPU to reproduce the comparison in about 15 minutes, most of that being the CPU baseline.
@@ -83,7 +97,7 @@ But CoolProp is a C++ library with Python bindings. You can't `jax.grad` through
 CO2-EOS solves this for CO₂ by implementing the same reference EOS (Span-Wagner 1996) directly in JAX:
 
 - **Differentiable.** `jax.grad` through any property, any inversion, any combination. No finite differences. The inversions carry hand-written `custom_jvp` rules (implicit function theorem), so forward- and reverse-mode gradients are exact and cheap; validated against central finite differences.
-- **Fast.** JIT-compiled and vectorisable, with hand-coded, transcendental-economized analytic α-derivatives: the Span-Wagner exponent structure (¼-integer τ-powers, integer δ-powers, shared exponential envelopes) is evaluated by sqrt/multiply ladders, so a full six-derivative bundle costs ~12 exps + 3 pows per point instead of ~150 array-exponent pows — the same arithmetic, re-associated, exact to round-off. For simulation codes that carry `(ρ, u)` as conserved variables, `properties_from_rho_u` fuses the whole primitive recovery: a dome-safe table seed plus three unrolled analytic-Cv Newton steps recover `T(ρ, u)` to 1e-12 K, and one shared derivative bundle feeds every property including the transport critical enhancement. On an Apple M2 Pro (float64) the full recovery runs **123 µs for a 64-point batch and 0.53 µs/point at large batches — 7.6–19.9× faster than the v0.1 autodiff path** and 2.6–6.3× faster than v0.2. On an OVH Tesla V100S the inversion reaches **63.7×** vs v0.1 at a 2²⁰-point batch (2 ns/point; full recovery 16 ns/point), and the launch-latency floor at small batches dropped ~1.7× (`bench/compare.py`, `bench/PROFILING.md`, validation in `docs/validation-fastpath-2026-07.md`).
+- **Fast.** JIT-compiled and vectorisable, with hand-coded, transcendental-economized analytic α-derivatives: the Span-Wagner exponent structure (¼-integer τ-powers, integer δ-powers, shared exponential envelopes) is evaluated by sqrt/multiply ladders, so a full six-derivative bundle costs ~12 exps + 3 pows per point instead of ~150 array-exponent pows: the same arithmetic, re-associated, exact to round-off. For simulation codes that carry `(ρ, u)` as conserved variables, `properties_from_rho_u` fuses the whole primitive recovery: a dome-safe table seed plus three unrolled analytic-Cv Newton steps recover `T(ρ, u)` to 1e-12 K, and one shared derivative bundle feeds every property including the transport critical enhancement. On an Apple M2 Pro (float64) the full recovery runs **123 µs for a 64-point batch and 0.53 µs/point at large batches, 7.6–19.9× faster than the v0.1 autodiff path** and 2.6–6.3× faster than v0.2. On an OVH Tesla V100S the inversion reaches **63.7×** vs v0.1 at a 2²⁰-point batch (2 ns/point; full recovery 16 ns/point), and the launch-latency floor at small batches dropped ~1.7× (`bench/compare.py`, `bench/PROFILING.md`, validation in `docs/validation-fastpath-2026-07.md`).
 - **Also fast for `(P, T)`.** The `state_from_PT` workflow that mirrors `PropsSI` includes an iterative density solve and flattens to a few tens of microseconds per point at large batches, roughly 2.7× faster than `CoolProp.PropsSI` in a Python loop on the same inputs (10,000-point batch, Apple M2 Pro; see `examples/launch_demo.ipynb`, section 2). On a Colab T4 GPU it runs at 27,800 states/sec on a 10⁶-point batch (36 μs/pt) versus 1,600 states/sec on Colab CPU (615 μs/pt), a 17× speedup. Its ceiling is the density solve's data-dependent `while_loop` (lockstep across GPU warps); the feed-forward `(ρ, u)` hot path above does not have that bottleneck.
 - **Composable.** `jit`, `vmap`, `grad`, `custom_vjp`: the full JAX transformation stack works. Embed property evaluations inside your own JIT-compiled simulation and differentiate end-to-end.
 - **Phase-aware.** Robust inversions near the critical point using Halley's method with step damping and bisection fallback. Two-phase dome detection that avoids convergence to thermodynamically unstable spinodal states.
@@ -96,6 +110,7 @@ CO2-EOS solves this for CO₂ by implementing the same reference EOS (Span-Wagne
 - Isochoric and isobaric heat capacities (Cv, Cp)
 - Speed of sound
 - Gibbs energy
+- Pressure derivatives (∂P/∂T)_ρ [Pa/K] and (∂P/∂ρ)_T [Pa·m³/kg], keys `dP_dT_rho` and `dP_drho_T` in every full-state dict (what a code that evolves temperature needs for its energy equation)
 
 **Transport properties:**
 
@@ -111,6 +126,7 @@ CO2-EOS solves this for CO₂ by implementing the same reference EOS (Span-Wagne
 
 - `properties_from_rho_u(rho, u)` / `temperature_from_rho_u(rho, u)`: the batched simulation hot path. Carries (ρ, u) as conserved variables; solves `T(ρ, u)` once with a table-seeded fixed-iteration analytic-Cv Newton, then derives every property (and viscosity / thermal conductivity) in one fused pass. `custom_jvp` (implicit function theorem) for exact forward- and reverse-mode gradients.
 - `state_from_Du(rho, u)`: scalar form of the above (vmap for batches).
+- `properties_from_rho_T(rho, T)`: batched full state from (ρ, T), no inversion; the array-native counterpart of the scalar `properties(T, rho)` (ρ first, like `properties_from_rho_u`). One analytic α-derivative pass per point feeds every property.
 - `state_from_PT(P, T)`: Halley's method with pressure-aware critical-region initial guess, step damping, and bisection safety net
 - `state_from_Ph(P, h, phase_hint=)` (phase-aware): detects the two-phase dome at subcritical pressures and returns saturation properties directly, bypassing single-phase Newton iteration inside the dome
 
@@ -123,7 +139,7 @@ one thing worth adopting is the fused hot path.
 If your simulation carried `(ρ, u)` and recovered primitives with separate calls:
 
 ```python
-# v0.1 — separate calls, each re-evaluating α-derivatives
+# v0.1: separate calls, each re-evaluating α-derivatives
 from co2_eos.inversions import temperature_from_Du, SUPERCRITICAL
 from co2_eos import span_wagner as sw, transport
 T  = temperature_from_Du(rho, u, phase)     # nested-autodiff Cv, while_loop
@@ -135,7 +151,7 @@ k  = transport.thermal_conductivity(T, rho)
 replace it with the single fused call:
 
 ```python
-# v0.2 — one fused pass: solve T once, reuse the α-derivatives
+# v0.2: one fused pass that solves T once and reuses the α-derivatives
 import co2_eos as co2
 s = co2.properties_from_rho_u(rho, u)       # phase_hint defaults to SUPERCRITICAL
 T, P, mu, k = s["temperature"], s["pressure"], s["viscosity"], s["thermal_conductivity"]
@@ -191,6 +207,7 @@ CO2-EOS is validated against CoolProp across the full valid range. The test suit
 - Single-phase properties on a dense (T, ρ) grid spanning gas, liquid, and supercritical regions
 - Saturation curve properties from triple point to near-critical
 - Transport properties (viscosity and thermal conductivity) across all phases
+- Bulk viscosity (0.5.0) against a reference table at nine near-critical and supercritical states, the dilute limit against Cramer (2012), and finite forward and reverse gradients (`tests/test_bulk_viscosity.py`)
 - Inversions (P,T → ρ), (P,h → state), (ρ,u → state) including near-critical conditions
 - Comparison of all Helmholtz derivatives against CoolProp's analytical values
 

{co2_eos-0.3.0 → co2_eos-0.6.0}/README.md

@@ -12,7 +12,7 @@ import co2_eos as co2
 import jax, jax.numpy as jnp
 
 # Simulation hot path: full state from the conserved variables (ρ, u).
-# Batched/array-native — solves T once and reuses the α-derivatives for
+# Batched/array-native: solves T once and reuses the α-derivatives for
 # every property. This is the call a finite-volume code makes each RHS eval.
 rho = jnp.array([300.0, 350.0, 420.0])      # kg/m³
 u   = jnp.array([3.62e5, 3.58e5, 3.42e5])   # J/kg  (specific internal energy)
@@ -36,6 +36,20 @@ T_array = jnp.linspace(280, 340, 100)
 states = jax.vmap(lambda T: co2.state_from_PT(P=8e6, T=T))(T_array)
 ```
 
+## Two equations of state
+
+Every public function takes `eos=`: `"span_wagner"` (Span and Wagner 1996, the default)
+or `"nist2026"` (Lemmon, Harvey and Hellmann, NIST IR 8608, 2026: 24 terms with no
+nonanalytic terms, free of Span-Wagner's near-critical oscillations in c_p, κ_T and
+(∂c_v/∂T)_ρ). The name is static under `jax.jit`, so each backend compiles once.
+
+```python
+s = co2_eos.properties(314.0, 472.0, eos="nist2026")   # Widom crossing at 9.1 MPa
+```
+
+The transport correlations keep their parameters on either backend; their critical parts
+read the selected backend's thermodynamics.
+
 ## Try it without cloning
 
 [`examples/launch_demo.ipynb`](examples/launch_demo.ipynb) is the launch demo: validation against CoolProp, the `state_from_PT` CPU/GPU benchmarks, and a worked example of gradient-based optimisation through `state_from_PT`. (The v0.2 hot-path `(ρ, u)` benchmarks are in [`bench/PROFILING.md`](bench/PROFILING.md).) [Read it on GitHub](https://github.com/FluxTech-UG/co2-eos/blob/main/examples/launch_demo.ipynb) for a static render, or [open it on Colab](https://colab.research.google.com/github/FluxTech-UG/co2-eos/blob/main/examples/launch_demo.ipynb) and switch the runtime to T4 GPU to reproduce the comparison in about 15 minutes, most of that being the CPU baseline.
@@ -49,7 +63,7 @@ But CoolProp is a C++ library with Python bindings. You can't `jax.grad` through
 CO2-EOS solves this for CO₂ by implementing the same reference EOS (Span-Wagner 1996) directly in JAX:
 
 - **Differentiable.** `jax.grad` through any property, any inversion, any combination. No finite differences. The inversions carry hand-written `custom_jvp` rules (implicit function theorem), so forward- and reverse-mode gradients are exact and cheap; validated against central finite differences.
-- **Fast.** JIT-compiled and vectorisable, with hand-coded, transcendental-economized analytic α-derivatives: the Span-Wagner exponent structure (¼-integer τ-powers, integer δ-powers, shared exponential envelopes) is evaluated by sqrt/multiply ladders, so a full six-derivative bundle costs ~12 exps + 3 pows per point instead of ~150 array-exponent pows — the same arithmetic, re-associated, exact to round-off. For simulation codes that carry `(ρ, u)` as conserved variables, `properties_from_rho_u` fuses the whole primitive recovery: a dome-safe table seed plus three unrolled analytic-Cv Newton steps recover `T(ρ, u)` to 1e-12 K, and one shared derivative bundle feeds every property including the transport critical enhancement. On an Apple M2 Pro (float64) the full recovery runs **123 µs for a 64-point batch and 0.53 µs/point at large batches — 7.6–19.9× faster than the v0.1 autodiff path** and 2.6–6.3× faster than v0.2. On an OVH Tesla V100S the inversion reaches **63.7×** vs v0.1 at a 2²⁰-point batch (2 ns/point; full recovery 16 ns/point), and the launch-latency floor at small batches dropped ~1.7× (`bench/compare.py`, `bench/PROFILING.md`, validation in `docs/validation-fastpath-2026-07.md`).
+- **Fast.** JIT-compiled and vectorisable, with hand-coded, transcendental-economized analytic α-derivatives: the Span-Wagner exponent structure (¼-integer τ-powers, integer δ-powers, shared exponential envelopes) is evaluated by sqrt/multiply ladders, so a full six-derivative bundle costs ~12 exps + 3 pows per point instead of ~150 array-exponent pows: the same arithmetic, re-associated, exact to round-off. For simulation codes that carry `(ρ, u)` as conserved variables, `properties_from_rho_u` fuses the whole primitive recovery: a dome-safe table seed plus three unrolled analytic-Cv Newton steps recover `T(ρ, u)` to 1e-12 K, and one shared derivative bundle feeds every property including the transport critical enhancement. On an Apple M2 Pro (float64) the full recovery runs **123 µs for a 64-point batch and 0.53 µs/point at large batches, 7.6–19.9× faster than the v0.1 autodiff path** and 2.6–6.3× faster than v0.2. On an OVH Tesla V100S the inversion reaches **63.7×** vs v0.1 at a 2²⁰-point batch (2 ns/point; full recovery 16 ns/point), and the launch-latency floor at small batches dropped ~1.7× (`bench/compare.py`, `bench/PROFILING.md`, validation in `docs/validation-fastpath-2026-07.md`).
 - **Also fast for `(P, T)`.** The `state_from_PT` workflow that mirrors `PropsSI` includes an iterative density solve and flattens to a few tens of microseconds per point at large batches, roughly 2.7× faster than `CoolProp.PropsSI` in a Python loop on the same inputs (10,000-point batch, Apple M2 Pro; see `examples/launch_demo.ipynb`, section 2). On a Colab T4 GPU it runs at 27,800 states/sec on a 10⁶-point batch (36 μs/pt) versus 1,600 states/sec on Colab CPU (615 μs/pt), a 17× speedup. Its ceiling is the density solve's data-dependent `while_loop` (lockstep across GPU warps); the feed-forward `(ρ, u)` hot path above does not have that bottleneck.
 - **Composable.** `jit`, `vmap`, `grad`, `custom_vjp`: the full JAX transformation stack works. Embed property evaluations inside your own JIT-compiled simulation and differentiate end-to-end.
 - **Phase-aware.** Robust inversions near the critical point using Halley's method with step damping and bisection fallback. Two-phase dome detection that avoids convergence to thermodynamically unstable spinodal states.
@@ -62,6 +76,7 @@ CO2-EOS solves this for CO₂ by implementing the same reference EOS (Span-Wagne
 - Isochoric and isobaric heat capacities (Cv, Cp)
 - Speed of sound
 - Gibbs energy
+- Pressure derivatives (∂P/∂T)_ρ [Pa/K] and (∂P/∂ρ)_T [Pa·m³/kg], keys `dP_dT_rho` and `dP_drho_T` in every full-state dict (what a code that evolves temperature needs for its energy equation)
 
 **Transport properties:**
 
@@ -77,6 +92,7 @@ CO2-EOS solves this for CO₂ by implementing the same reference EOS (Span-Wagne
 
 - `properties_from_rho_u(rho, u)` / `temperature_from_rho_u(rho, u)`: the batched simulation hot path. Carries (ρ, u) as conserved variables; solves `T(ρ, u)` once with a table-seeded fixed-iteration analytic-Cv Newton, then derives every property (and viscosity / thermal conductivity) in one fused pass. `custom_jvp` (implicit function theorem) for exact forward- and reverse-mode gradients.
 - `state_from_Du(rho, u)`: scalar form of the above (vmap for batches).
+- `properties_from_rho_T(rho, T)`: batched full state from (ρ, T), no inversion; the array-native counterpart of the scalar `properties(T, rho)` (ρ first, like `properties_from_rho_u`). One analytic α-derivative pass per point feeds every property.
 - `state_from_PT(P, T)`: Halley's method with pressure-aware critical-region initial guess, step damping, and bisection safety net
 - `state_from_Ph(P, h, phase_hint=)` (phase-aware): detects the two-phase dome at subcritical pressures and returns saturation properties directly, bypassing single-phase Newton iteration inside the dome
 
@@ -89,7 +105,7 @@ one thing worth adopting is the fused hot path.
 If your simulation carried `(ρ, u)` and recovered primitives with separate calls:
 
 ```python
-# v0.1 — separate calls, each re-evaluating α-derivatives
+# v0.1: separate calls, each re-evaluating α-derivatives
 from co2_eos.inversions import temperature_from_Du, SUPERCRITICAL
 from co2_eos import span_wagner as sw, transport
 T  = temperature_from_Du(rho, u, phase)     # nested-autodiff Cv, while_loop
@@ -101,7 +117,7 @@ k  = transport.thermal_conductivity(T, rho)
 replace it with the single fused call:
 
 ```python
-# v0.2 — one fused pass: solve T once, reuse the α-derivatives
+# v0.2: one fused pass that solves T once and reuses the α-derivatives
 import co2_eos as co2
 s = co2.properties_from_rho_u(rho, u)       # phase_hint defaults to SUPERCRITICAL
 T, P, mu, k = s["temperature"], s["pressure"], s["viscosity"], s["thermal_conductivity"]
@@ -157,6 +173,7 @@ CO2-EOS is validated against CoolProp across the full valid range. The test suit
 - Single-phase properties on a dense (T, ρ) grid spanning gas, liquid, and supercritical regions
 - Saturation curve properties from triple point to near-critical
 - Transport properties (viscosity and thermal conductivity) across all phases
+- Bulk viscosity (0.5.0) against a reference table at nine near-critical and supercritical states, the dilute limit against Cramer (2012), and finite forward and reverse gradients (`tests/test_bulk_viscosity.py`)
 - Inversions (P,T → ρ), (P,h → state), (ρ,u → state) including near-critical conditions
 - Comparison of all Helmholtz derivatives against CoolProp's analytical values
 

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

@@ -1,30 +1,51 @@
 """CO2-EOS: Differentiable CO₂ thermodynamic properties in JAX.
 
-Pure-JAX Span-Wagner (1996) equation of state for carbon dioxide with hand-coded
+Pure-JAX Helmholtz equations of state for carbon dioxide with hand-coded
 analytic α-derivatives.  JIT-compilable, ``vmap``-able, fully differentiable.
 
+Two backends, selected by the keyword ``eos`` every public function takes (a
+Python string, static under ``jax.jit``: one compiled kernel per backend)::
+
+    eos="span_wagner"   Span & Wagner (1996), the default, bit for bit 0.5.0
+    eos="nist2026"      Lemmon, Harvey & Hellmann, NIST IR 8608 (2026):
+                        24 terms, no nonanalytic terms, free of Span-Wagner's
+                        near-critical oscillations in c_p, κ_T, (∂c_v/∂T)_ρ
+
+``EOS_NAMES`` lists them.  The transport correlations keep their own
+parameters on either backend; their critical parts read the selected
+backend's thermodynamics.
+
 Public API
 ==========
 
-Simulation hot path — full state from the conserved variables (ρ, u).  These are
+Simulation hot path: full state from the conserved variables (ρ, u).  These are
 **batched / array-native**: pass 1-D arrays, get back a dict of 1-D arrays.  A
 single fused pass solves T once and reuses the α-derivatives for every property::
 
     properties_from_rho_u(rho, u, phase_hint=SUPERCRITICAL) -> dict
     temperature_from_rho_u(rho, u, phase_hint=SUPERCRITICAL) -> T   # T only
 
-State functions — **scalar** in their inputs (0-d arrays or Python floats); wrap
+Full state from (ρ, T), for a code that evolves temperature: also batched, no
+inversion (a direct evaluation of the Helmholtz surface)::
+
+    properties_from_rho_T(rho, T) -> dict
+
+State functions: **scalar** in their inputs (0-d arrays or Python floats); wrap
 with ``jax.vmap`` for batches::
 
-    properties(T, rho)              — full state from (T, ρ)
-    state_from_PT(P, T)             — full state from (P, T)
-    state_from_Ph(P, h)             — full state from (P, h)
-    state_from_Du(rho, u)           — full state from (ρ, u)   (scalar form)
-    density_from_PT(P, T)           — ρ from (P, T)
+    properties(T, rho)                full state from (T, ρ)
+    state_from_PT(P, T)               full state from (P, T)
+    state_from_Ph(P, h)               full state from (P, h)
+    state_from_Du(rho, u)             full state from (ρ, u)   (scalar form)
+    density_from_PT(P, T)             ρ from (P, T)
 
-Each full-state dict has keys: ``temperature``, ``density``, ``pressure``,
-``cv``, ``cp``, ``speed_of_sound``, ``enthalpy``, ``internal_energy``,
-``entropy``, ``gibbs_energy``, ``viscosity``, ``thermal_conductivity``.
+Each full-state dict has keys: ``temperature`` [K], ``density`` [kg/m³],
+``pressure`` [Pa], ``cv`` and ``cp`` [J/(kg·K)], ``speed_of_sound`` [m/s],
+``enthalpy``, ``internal_energy`` and ``gibbs_energy`` [J/kg], ``entropy``
+[J/(kg·K)], ``dP_dT_rho`` ((∂P/∂T)_ρ [Pa/K]), ``dP_drho_T`` ((∂P/∂ρ)_T
+[Pa·m³/kg]), ``viscosity`` [Pa·s], ``thermal_conductivity`` [W/(m·K)],
+``bulk_viscosity`` [Pa·s] (ζ = ζ_vib + ζ_crit) and
+``bulk_viscosity_vibrational`` [Pa·s] (its vibrational part ζ_vib alone).
 
 Saturation curve (cubic-spline interpolation of a precomputed Maxwell table)::
 
@@ -35,8 +56,11 @@ Saturation curve (cubic-spline interpolation of a precomputed Maxwell table)::
 
 Transport (scalar; vmap for batches)::
 
-    viscosity(T, rho)               → μ  [Pa·s]
+    viscosity(T, rho)               → μ  [Pa·s]  (no EOS input)
     thermal_conductivity(T, rho)    → λ  [W/(m·K)]
+    bulk_viscosity(T, rho)          → ζ  [Pa·s]  (vibrational + critical)
+
+Every function above also takes ``eos=`` (default ``"span_wagner"``).
 
 Phase hints::
 
@@ -46,13 +70,15 @@ See README "Migrating to v0.2" for the move from the old per-quantity calls to
 the fused ``properties_from_rho_u``.
 """
 
+from functools import partial
+
 import jax
 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.6.0"
 
 # ── Phase hint constants ────────────────────────────────────────────────────
 LIQUID = 0
@@ -61,12 +87,16 @@ SUPERCRITICAL = 2
 AUTO = SUPERCRITICAL  # alias: auto-pick in the dome / supercritical-style guess
 
 # ── Internal modules ────────────────────────────────────────────────────────
+from co2_eos.backends import EOS_NAMES, DEFAULT_EOS, SPAN_WAGNER, NIST2026
 from co2_eos import span_wagner as _sw
 from co2_eos import transport as _tr
 from co2_eos import saturation as _sat
 from co2_eos import inversions as _inv
 from co2_eos import core as _core
 
+# jit with the backend name static: one compiled kernel per backend.
+_jit = partial(jax.jit, static_argnames=("eos",))
+
 # ── Re-exports: saturation curve ────────────────────────────────────────────
 saturation_pressure = _sat.saturation_pressure
 saturation_temperature = _sat.saturation_temperature
@@ -80,28 +110,47 @@ saturation_entropies_P = _sat.saturation_entropies_P
 
 # ── Transport (scalar form; vmap for batches) ───────────────────────────────
 
-@jax.jit
-def viscosity(T, rho):
-    """Dynamic viscosity μ [Pa·s] at scalar (T, ρ). vmap for batches."""
+@_jit
+def viscosity(T, rho, eos=DEFAULT_EOS):
+    """Dynamic viscosity μ [Pa·s] at scalar (T, ρ). vmap for batches.
+
+    Laesecke-Muzny reads no EOS property; ``eos`` is accepted (and checked)
+    so every property function takes the same keyword.
+    """
     T = jnp.asarray(T, dtype=jnp.float64)
     rho = jnp.asarray(rho, dtype=jnp.float64)
-    return _tr._scalar_viscosity(T, rho)
+    return _tr.for_eos(eos)._scalar_viscosity(T, rho)
 
 
-@jax.jit
-def thermal_conductivity(T, rho):
+@_jit
+def thermal_conductivity(T, rho, eos=DEFAULT_EOS):
     """Thermal conductivity λ [W/(m·K)] at scalar (T, ρ). vmap for batches."""
     T = jnp.asarray(T, dtype=jnp.float64)
     rho = jnp.asarray(rho, dtype=jnp.float64)
-    return _tr._scalar_thermal_conductivity(T, rho)
+    return _tr.for_eos(eos)._scalar_thermal_conductivity(T, rho)
+
+
+@_jit
+def bulk_viscosity(T, rho, eos=DEFAULT_EOS):
+    """Bulk viscosity ζ [Pa·s] at scalar (T, ρ). vmap for batches.
+
+    ζ = ζ_vib + ζ_crit, the zero-frequency coefficient: vibrational relaxation
+    (Lin & Trusler 2014, pure CO₂) plus the critical part (Onuki 2007,
+    R_B = 0.03) on the Olchowy-Sengers correlation length the conductivity
+    enhancement uses.  Valid while ω·τ₁₁ ≪ 1, single phase, 270 to 500 K.
+    """
+    T = jnp.asarray(T, dtype=jnp.float64)
+    rho = jnp.asarray(rho, dtype=jnp.float64)
+    return _tr.for_eos(eos)._scalar_bulk_viscosity(T, rho)
 
 
 # ═══════════════════════════════════════════════════════════════════════════
-# Hot path: full state from conserved (ρ, u) — batched / array-native
+# Hot path: full state from conserved (ρ, u), batched / array-native
 # ═══════════════════════════════════════════════════════════════════════════
 
-@jax.jit
-def properties_from_rho_u(rho, u, phase_hint=SUPERCRITICAL):
+@_jit
+def properties_from_rho_u(rho, u, phase_hint=SUPERCRITICAL,
+                          eos=DEFAULT_EOS):
     """Full thermodynamic + transport state from (ρ, u). Batched.
 
     The simulation hot path: solves T once from u(T,ρ)=u via the analytic-Cv
@@ -126,40 +175,71 @@ def properties_from_rho_u(rho, u, phase_hint=SUPERCRITICAL):
     u = jnp.asarray(u, dtype=jnp.float64)
     phase = jnp.broadcast_to(jnp.asarray(phase_hint, dtype=jnp.int32),
                              jnp.shape(rho))
-    return jax.vmap(_core._state_from_rho_u)(rho, u, phase)
+    return jax.vmap(_core.for_eos(eos)._state_from_rho_u)(rho, u, phase)
+
+
+@_jit
+def properties_from_rho_T(rho, T, eos=DEFAULT_EOS):
+    """Full thermodynamic + transport state from (ρ, T). Batched.
+
+    The array-native counterpart of the scalar ``properties(T, rho)`` (note the
+    argument order: ρ first, matching ``properties_from_rho_u``).  A direct
+    evaluation of the Helmholtz surface: no inversion, so no phase hint.  One
+    analytic α-derivative pass per point feeds every property, including
+    ``dP_dT_rho`` and ``dP_drho_T``.  ``rho`` and ``T`` are 1-D arrays of
+    equal length; the result is a dict of 1-D float64 arrays.
+
+    This is ``jax.vmap`` of the same scalar kernel ``properties`` uses, so the
+    two agree bit for bit on Span-Wagner (on nist2026, whose kernel sums its
+    24 terms as one vector reduction, to round-off); it exists as the
+    documented batched entry point.
+
+    Note: inside the two-phase dome (subcritical T, ρ between ρ_v and ρ_l) the
+    EOS returns its unstable single-phase extrapolation (there
+    ``dP_drho_T`` can be negative); the caller keeps its states out of the dome.
+    """
+    rho = jnp.asarray(rho, dtype=jnp.float64)
+    T = jnp.asarray(T, dtype=jnp.float64)
+    if rho.ndim != 1 or T.shape != rho.shape:
+        raise ValueError(
+            f"properties_from_rho_T expects 1-D rho and T of equal shape; "
+            f"got rho {rho.shape}, T {T.shape}")
+    return jax.vmap(_core.for_eos(eos)._state_from_T_rho)(T, rho)
 
 
-@jax.jit
-def temperature_from_rho_u(rho, u, phase_hint=SUPERCRITICAL):
+@_jit
+def temperature_from_rho_u(rho, u, phase_hint=SUPERCRITICAL,
+                           eos=DEFAULT_EOS):
     """Temperature T [K] such that u(T,ρ)=u at fixed ρ. Batched.
 
-    The lean inversion (no property derivation) — use when only T is needed.
+    The lean inversion (no property derivation); use when only T is needed.
     Differentiable: correct jvp/vjp via the implicit function theorem.
     """
     rho = jnp.asarray(rho, dtype=jnp.float64)
     u = jnp.asarray(u, dtype=jnp.float64)
     phase = jnp.broadcast_to(jnp.asarray(phase_hint, dtype=jnp.int32),
                              jnp.shape(rho))
-    return jax.vmap(_core._temperature_from_Du)(rho, u, phase)
+    return jax.vmap(_core.for_eos(eos)._temperature_from_Du)(rho, u,
+                                                            phase)
 
 
 # ═══════════════════════════════════════════════════════════════════════════
-# State functions — scalar in their inputs (vmap for batches)
+# State functions: scalar in their inputs (vmap for batches)
 # ═══════════════════════════════════════════════════════════════════════════
 
-@jax.jit
-def properties(T, rho):
+@_jit
+def properties(T, rho, eos=DEFAULT_EOS):
     """Full thermodynamic + transport state at scalar (T, ρ).
 
     Returns a dict (see module docstring for keys). vmap for batches.
     """
     T = jnp.asarray(T, dtype=jnp.float64)
     rho = jnp.asarray(rho, dtype=jnp.float64)
-    return _core._state_from_T_rho(T, rho)
+    return _core.for_eos(eos)._state_from_T_rho(T, rho)
 
 
-@jax.jit
-def state_from_PT(P, T, phase_hint=AUTO):
+@_jit
+def state_from_PT(P, T, phase_hint=AUTO, eos=DEFAULT_EOS):
     """Full state at (P, T). Phase-aware Halley solve for ρ, then derive all.
 
     ``pressure`` in the returned dict echoes the input ``P`` exactly.
@@ -167,23 +247,23 @@ def state_from_PT(P, T, phase_hint=AUTO):
     P = jnp.asarray(P, dtype=jnp.float64)
     T = jnp.asarray(T, dtype=jnp.float64)
     phase = jnp.asarray(phase_hint, dtype=jnp.int32)
-    rho = _inv._density_from_PT(T, P, phase)
-    state = _core._state_from_T_rho(T, rho)
+    rho = _inv.for_eos(eos)._density_from_PT(T, P, phase)
+    state = _core.for_eos(eos)._state_from_T_rho(T, rho)
     state["pressure"] = P
     return state
 
 
-@jax.jit
-def density_from_PT(P, T, phase_hint=AUTO):
+@_jit
+def density_from_PT(P, T, phase_hint=AUTO, eos=DEFAULT_EOS):
     """Density [kg/m³] at scalar (P, T). Phase-aware Halley solve."""
     P = jnp.asarray(P, dtype=jnp.float64)
     T = jnp.asarray(T, dtype=jnp.float64)
     phase = jnp.asarray(phase_hint, dtype=jnp.int32)
-    return _inv._density_from_PT(T, P, phase)
+    return _inv.for_eos(eos)._density_from_PT(T, P, phase)
 
 
-@jax.jit
-def state_from_Ph(P, h, phase_hint=AUTO):
+@_jit
+def state_from_Ph(P, h, phase_hint=AUTO, eos=DEFAULT_EOS):
     """Full state at (P, h). Dome-aware at subcritical P; else 2-D Newton.
 
     ``pressure`` and ``enthalpy`` echo the inputs.
@@ -191,15 +271,15 @@ def state_from_Ph(P, h, phase_hint=AUTO):
     P = jnp.asarray(P, dtype=jnp.float64)
     h = jnp.asarray(h, dtype=jnp.float64)
     phase = jnp.asarray(phase_hint, dtype=jnp.int32)
-    T, rho = _inv._state_from_Ph(P, h, phase)
-    state = _core._state_from_T_rho(T, rho)
+    T, rho = _inv.for_eos(eos)._state_from_Ph(P, h, phase)
+    state = _core.for_eos(eos)._state_from_T_rho(T, rho)
     state["pressure"] = P
     state["enthalpy"] = h
     return state
 
 
-@jax.jit
-def state_from_Du(rho, u, phase_hint=AUTO):
+@_jit
+def state_from_Du(rho, u, phase_hint=AUTO, eos=DEFAULT_EOS):
     """Full state at scalar (ρ, u). Scalar form of ``properties_from_rho_u``.
 
     ``density`` and ``internal_energy`` echo the inputs.
@@ -207,13 +287,14 @@ def state_from_Du(rho, u, phase_hint=AUTO):
     rho = jnp.asarray(rho, dtype=jnp.float64)
     u = jnp.asarray(u, dtype=jnp.float64)
     phase = jnp.asarray(phase_hint, dtype=jnp.int32)
-    return _core._state_from_rho_u(rho, u, phase)
+    return _core.for_eos(eos)._state_from_rho_u(rho, u, phase)
 
 
 __all__ = [
     "__version__",
+    "EOS_NAMES", "DEFAULT_EOS", "SPAN_WAGNER", "NIST2026",
     "LIQUID", "VAPOR", "SUPERCRITICAL", "AUTO",
-    "properties_from_rho_u", "temperature_from_rho_u",
+    "properties_from_rho_u", "properties_from_rho_T", "temperature_from_rho_u",
     "properties",
     "state_from_PT", "state_from_Ph", "state_from_Du",
     "density_from_PT",
@@ -221,5 +302,5 @@ __all__ = [
     "saturation_densities", "saturation_densities_P",
     "saturation_enthalpies", "saturation_enthalpies_P",
     "saturation_entropies", "saturation_entropies_P",
-    "viscosity", "thermal_conductivity",
+    "viscosity", "thermal_conductivity", "bulk_viscosity",
 ]

co2_eos-0.6.0/co2_eos/backends.py

@@ -0,0 +1,56 @@
+"""The equation-of-state backends and the static switch that selects one.
+
+Every public function of co2-eos takes a keyword ``eos``, a Python string that
+is static under ``jax.jit`` (one compiled kernel per backend; no traced
+branching), with the default ``DEFAULT_EOS``:
+
+  * ``"span_wagner"``: Span & Wagner (1996), the default.  Its surface is
+    ``span_wagner`` (constants, α, the autodiff property functions) and its
+    analytic kernel ``helmholtz``; its tables carry no suffix.
+  * ``"nist2026"``: Lemmon, Harvey & Hellmann, NIST IR 8608 (2026), 24 terms
+    with no nonanalytic terms.  Surface and kernel are both ``nist2026``; its
+    tables carry the suffix ``_nist2026``.
+
+A backend's surface module provides ``TC, RHOC, RHOC_MOLAR, R, R_MOLAR, M,
+PC, T_TRIPLE`` and ``_scalar_pressure``, ``_scalar_enthalpy``,
+``_scalar_internal_energy``, ``_scalar_entropy``; its kernel module provides
+``ideal_derivs``, ``ideal_tau_only``, ``residual_derivs``,
+``residual_tau_prep``, ``residual_tau_fast``, ``residual_tau_derivs``.  Each
+backend carries its own gas constant and molar mass; nothing shared between
+backends assumes Span-Wagner's.
+"""
+
+from pathlib import Path
+from types import SimpleNamespace
+
+from co2_eos import helmholtz as _helmholtz
+from co2_eos import nist2026 as _nist2026
+from co2_eos import span_wagner as _span_wagner
+
+SPAN_WAGNER = "span_wagner"
+NIST2026 = "nist2026"
+EOS_NAMES = (SPAN_WAGNER, NIST2026)
+DEFAULT_EOS = SPAN_WAGNER
+
+DATA_DIR = Path(__file__).parent / "data"
+
+_BACKENDS = {
+    SPAN_WAGNER: SimpleNamespace(name=SPAN_WAGNER, surface=_span_wagner,
+                                 kernel=_helmholtz, suffix=""),
+    NIST2026: SimpleNamespace(name=NIST2026, surface=_nist2026,
+                              kernel=_nist2026, suffix="_nist2026"),
+}
+
+
+def get(eos):
+    """The backend record for ``eos``; raises on an unknown name."""
+    try:
+        return _BACKENDS[eos]
+    except (KeyError, TypeError):
+        raise ValueError(
+            f"unknown eos {eos!r}; choose one of {EOS_NAMES}") from None
+
+
+def table_path(eos, stem):
+    """Path of the backend's table ``<stem><suffix>.npz`` in ``co2_eos/data``."""
+    return DATA_DIR / f"{stem}{get(eos).suffix}.npz"