pyrestoolbox 3.7.1__tar.gz → 3.7.2__tar.gz

{pyrestoolbox-3.7.1 → pyrestoolbox-3.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrestoolbox
-Version: 3.7.1
+Version: 3.7.2
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)

{pyrestoolbox-3.7.1 → pyrestoolbox-3.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pyrestoolbox"
-version = "3.7.1"
+version = "3.7.2"
 description = "pyResToolbox - A collection of Reservoir Engineering Utilities"
 license = {text = "GPL-3.0-or-later"}
 authors = [{name = "Mark W. Burgoyne", email = "mark.w.burgoyne@gmail.com"}]

pyrestoolbox-3.7.2/pyrestoolbox/brine/__init__.py

@@ -0,0 +1,5 @@
+from .brine import *
+from . import pr_vphi
+from .pr_vphi import V2_inf as V_phi_pr
+from . import vphi_route
+from .vphi_route import V_phi, route_used

{pyrestoolbox-3.7.1 → pyrestoolbox-3.7.2}/pyrestoolbox/brine/brine.py

@@ -442,7 +442,7 @@ BBL2CUFT = 5.614583333 # cuft in a bbl
 #CO2 Corrected Brine Density    Molar volume of dissolved CO2 estimated with Garcia (2001) equation, used with xCO2 calculated 
 #                               from Spycher & Pruess, and CO2-free brine density from Spivey et al to calculate insitu density
 #Pure Brine viscosity           Mao-Duan (2009) approach for pure brine viscosity
-#CO2 Corrected Brine Viscosity  Used approach from "Viscosity Models and Effects of Dissolved CO2", Islam-Carlson (2012)
+#CO2 Corrected Brine Viscosity  Calabrese et al. (2019) Eq. 25 T-dependent increment (supersedes Islam-Carlson 2012)
 #                               to adjust the pure brine viscosity for xCO2 calculated from Spycher & Pruess
 #===================================================================================================================
 
@@ -1123,7 +1123,7 @@ class CO2_Brine_Mixture():
             2. Brine Salt Correction:         Spivey et al. (modified)
             3. Pure Brine viscosity:          Mao-Duan (2009)
             4. CO2 Corrected Brine Density:   Garcia (2001)
-            5. CO2 Corrected Brine Viscosity: Islam-Carlson (2012)
+            5. CO2 Corrected Brine Viscosity: Calabrese et al. (2019) Eq. 25
             
             pBar: Pressure (Bar)
             degc: Temperature (deg C)
@@ -1229,20 +1229,29 @@ class CO2_Brine_Mixture():
         
         # -- Correcting brine density for dissolved CO2, JE Garcia, LBNL Report# 49023, Oct 2011, "Density of Aqueous Solutions of CO2"
         def garciaDensity(rhoBRnoCO2, tKel, pBar, ppm, xCO2, MwB, MwG):
-            # Algebraic reformulation of Garcia Eq 18: original form
-            #     (1 + mRat*xRat) / (vPhi*xRat/MwB + 1/rhoBRnoCO2) with xRat = xCO2/(1-xCO2)
-            # has a singularity at xCO2 -> 1. Multiplying numerator and denominator by
-            # (1-xCO2)*MwB removes xRat entirely and gives the same result.
-            xNotCO2 = 1.0 - xCO2                         #--Brine (H20+Salt) Mole Fraction
-            mRat = MwG / MwB                             #--Mole Weight Ratio  , Gas/Brine
+            # Garcia Eq 18 written per kg of water, which removes both the
+            # xCO2 -> 1 singularity of the original form and the mole-basis
+            # mismatch it used to carry: xCO2 here is Spycher-Pruess on the
+            # fully-ionised basis (H2O + Na+ + Cl-) while MwB is the paired-NaCl
+            # brine mole weight, so xNotCO2*MwB overstated the solvent mass by
+            # 8% at 5 molal and understated the CO2 densification to match.
+            #
+            # V_phi is defined against the whole gas-free brine, so:
+            #     rho = (Wb + mCO2*MwG) / (Wb/rhoBRnoCO2 + mCO2*vPhi)
+            # with Wb the gas-free brine mass per kg of water and mCO2 the CO2
+            # molality recovered from the ionised-basis mole fraction.
             vPhi = partMolVol(tKel)                      #--Apparent Molar Volume of Dissolved CO2
-            return MwB * (xNotCO2 + mRat * xCO2) / (vPhi * xCO2 + MwB * xNotCO2 / rhoBRnoCO2)
+            mCO2 = xCO2 * (CONMOLA + 2 * m) / (1.0 - xCO2)   #--gram mol CO2 / kg water
+            Wb = 1000.0 + m * MWSAL                          #--gas-free brine mass per kg water, g
+            return (Wb + mCO2 * MwG) / (Wb / rhoBRnoCO2 + mCO2 * vPhi)
         
         # Correct CO2 free brine viscosity for dissolved CO2
-        # Using approach from "Viscosity Models and Effects of Dissolved CO2", Akand W. Islam and Eric S. Carlson (Jul 2012), Energy Fuels 2012, 26, 8, 5330�5336, https://doi.org/10.1021/ef3006228
+        # Calabrese, McBride-Wright, Maitland & Trusler (2019), JCED 64, 3831-3847, Eq. 25
+        # (274-449 K, to 100 MPa, salt-type and molality independent, m <= 6).
+        # Supersedes Islam-Carlson (2012), which overstates the slope 3.5x at 200 degF.
         def co2_vis_brine(cP_brine, xCO2):
             # Uses CO2 free brine viscosity (cP) and mole fraction CO2 in brine (xCO2), and returns cP
-            return cP_brine * (1 + 4.65 * xCO2**1.0134)
+            return cP_brine * np.exp(_CAL_E1 * np.exp(-_CAL_E2 * (tKel / _CAL_T0 - 1.0)) * xCO2)
     
         # Density and viscosity at specified pressure & temperature (No CO2)
         sg_brine, rhowtp = brine_denw(Mpa)                        # rhowtp is density of pure water
@@ -1326,16 +1335,51 @@ def make_pvtw_table(*args, **kwargs):
 # ============================================================================
 # Viscosity correction constants for dissolved gases
 # ============================================================================
-_IC_A_CO2 = 4.65       # Islam-Carlson (2012) CO2 coefficient
-_IC_A_H2S = 1.50       # Calibrated from Murphy & Gaines (1974)
+# H2S: Murphy & Gaines (1974) Table IV, DOI 10.1021/je60063a015, re-based
+# 2026-07-25 onto the solubility source THAT PAPER USED, Burgess & Germann
+# (1969) AIChE J 15:272. Murphy & Gaines report viscosity ratios but no mole
+# fractions; taking x_H2S from Soreide-Whitson instead put it 4.5 to 9.2% high
+# against Burgess & Germann, and since a scales as 1/x it biased the coefficient
+# low by the same amount. Implied coefficients on the correct basis are 2.31,
+# 1.54, 1.98, 1.31 and 0.27; the adopted value is the mean of the four below
+# 35 degC. Was 1.64 (S&W basis), and 1.50 before the primary source was read.
+_IC_A_H2S = 1.79       # Murphy & Gaines Table IV on Burgess & Germann solubility
 _IC_B = 1.0134         # Islam-Carlson exponent
 
+# Calabrese et al. (2019) Eq. 25 CO2 viscosity increment (JCED 64:3831):
+# ln(mu/mu_brine) = e1 * exp(-e2*(T_K/T0 - 1)) * x_CO2
+# 274-449 K, to 100 MPa, salt-type and molality independent (m <= 6).
+# Supersedes the T-independent Islam-Carlson form, which overstates the
+# slope 3.5x at 200 degF (adopted 2026-07-19).
+_CAL_E1 = 65.560
+_CAL_E2 = 2.468
+_CAL_T0 = 142.0        # K
+
 # Ostermann (1985) SPE 14211 CH4 plateau coefficients
 # mu_sat/mu_free = c0 + c1*T + c2*T^2  (T in degF)
 # NOTE: SPE 14211 prints c2 as 1.0933e-5 (typo); correct is 1.0933e-6
-_OST_C0 = 1.109
-_OST_C1 = -5.98e-4
-_OST_C2 = 1.0933e-6
+# CH4 dissolved-gas viscosity: unified Arrhenius x Langmuir, fitted to the FULL
+# Ostermann SPE 14211 dataset (Tables 1a-1c, 23 measurements at 100/150/250 degF
+# and 500-7000 psi):
+#
+#     mu_sat/mu_free = 1 + _CH4_A * exp(_CH4_B / T_K) * x / (_CH4_K + x)
+#
+# One equation, three parameters, no cap. Arrhenius in T (activated flow; the
+# hydration structure carrying the excess is destroyed thermally, B = 1240 K =
+# 10.3 kJ/mol, about half a water hydrogen bond) and Langmuir in x (finite
+# structurable capacity). Linear in x as x -> 0 as the dilute limit requires,
+# and saturating naturally so no min() is needed.
+#
+# Supersedes a four-parameter construction (linear-in-x ramp spliced to a
+# temperature-only plateau by min()) built from the paper's three SUMMARY
+# plateau values. Reading the primary tables overturned its two premises: the
+# measured plateau is not flat (it drifts up 1.0-1.6 pp from 2000 to 7000 psi),
+# and Rsw is tabulated so x need not come from an EOS. Fit quality on the 23
+# points: this form 0.723 pp RMS with 3 parameters, the previous capped ramp
+# 0.713 pp with 4, an unsaturated linear form 1.146 pp with 2.
+_CH4_A = 1.71739196e-03
+_CH4_B = 1239.77535        # K
+_CH4_K = 1.52860547e-03    # half-saturation mole fraction
 
 # HC component molecular weights for SG-based splitting
 _MW_C1 = 16.043
@@ -1368,7 +1412,10 @@ _SW_GAS_MW = {
 }
 
 # Plyasunov model (internal submodule)
-from pyrestoolbox.plyasunov import V_phi as _plyasunov_V_phi, gas_mw as _plyasunov_gas_mw
+from pyrestoolbox.plyasunov import gas_mw as _plyasunov_gas_mw
+from pyrestoolbox.brine.vphi_route import (V_phi as _V_phi,
+                                            DEFAULT_ROUTE as _VPHI_ROUTE,
+                                            ROUTES as _VPHI_ROUTES)
 
 # VLE engine (local copy in brine package)
 from pyrestoolbox.brine._lib_vle_engine import calc_gas_brine_equilibrium as _calc_gas_brine_equilibrium
@@ -1386,8 +1433,11 @@ class SoreideWhitson:
         - Mole fraction of vaporised water in gas phase
         - Water content of gas (stb/mmscf, lb/mmscf)
         - Gas solubility in water (sm3/sm3 or scf/stb) — total and per-gas
-        - Gas-saturated brine density via Garcia (2001) Eq. 18 with Plyasunov V_phi
-        - Gas-saturated brine viscosity with per-gas corrections (Islam-Carlson, Ostermann, Murphy-Gaines)
+        - Gas-saturated brine density via Garcia (2001) Eq. 18. V_phi comes from
+          the S&W modified-PR route by default (vphi_route='auto'), falling back
+          to Plyasunov where PR is not calibrated; 'plyasunov' forces the old
+          default and reproduces results from before 2026-07-25.
+        - Gas-saturated brine viscosity with per-gas corrections (Calabrese CO2, Ostermann CH4, Murphy-Gaines H2S)
         - Brine FVF, compressibility, viscosibility
 
         Supports fresh and saline water (NaCl equivalent).
@@ -1466,7 +1516,17 @@ class SoreideWhitson:
     def __init__(self, pres=None, temp=None, ppm=None, y_CO2=0, y_H2S=0, y_N2=0, y_H2=0,
                  sg=0.65, metric=False, cw_sat=False,
                  framework='proposed', salinity_method='gamma_phi',
+                 vphi_route=_VPHI_ROUTE,
                  *, p=None, degf=None, wt=None):
+        # V_phi source for the Garcia density step. 'auto' (default) is the S&W
+        # modified-PR route with one volume shift per gas, falling back to
+        # Plyasunov where PR is not calibrated; 'plyasunov' forces the pre
+        # 2026-07-25 default. See brine/vphi_route.py.
+        if vphi_route not in _VPHI_ROUTES:
+            raise ValueError(
+                f"vphi_route must be one of {_VPHI_ROUTES}, got {vphi_route!r}")
+        self.vphi_route = vphi_route
+
         # Resolve parameter aliases (p/degf/wt -> pres/temp/ppm)
         if pres is None and p is not None:
             pres = p
@@ -1797,7 +1857,11 @@ class SoreideWhitson:
         rho_sc_brine_gcc = rho_sc_fw_gcc * salt_ratio_sc
 
         # ================================================================
-        # Step 3: Density correction via Garcia Eq. 18 + Plyasunov V_phi
+        # Step 3: Density correction via Garcia Eq. 18 + V_phi.
+        # V_phi comes from the S&W modified-PR route with one volume shift per
+        # gas, falling back to Plyasunov outside its calibration box or for
+        # C3H8/NC4H10. See brine/vphi_route.py for why and for the size of the
+        # step at the boundary.
         # ================================================================
         if self.x_total > 0:
             # Compute mole-fraction-weighted effective V_phi and MW
@@ -1808,17 +1872,25 @@ class SoreideWhitson:
                     continue
                 yi = x_i / self.x_total  # Fraction among dissolved gases
                 gas_ply = _VLE_TO_PLYASUNOV.get(gas_vle, gas_vle.upper())
-                vphi_eff += yi * _plyasunov_V_phi(gas_ply, tKel, Mpa)
+                vphi_eff += yi * _V_phi(gas_ply, tKel, Mpa, self.vphi_route)
                 mw_eff += yi * _plyasunov_gas_mw(gas_ply)
 
             # Garcia Eq. 18 in g/cm3, algebraically reformulated to remove the
             # x1 -> 0 singularity. Multiplying top/bot of
             #     (1 + x2*M2/(M1*x1)) / (x2*V_phi/(M1*x1) + 1/rho1)
             # by M1*x1 gives the equivalent, non-singular form below.
-            x1 = 1.0 - self.x_total
-            M1 = MWWAT
-            numerator = M1 * x1 + self.x_total * mw_eff
-            denominator = self.x_total * vphi_eff + M1 * x1 / rho_brine_gcc
+            #
+            # SOLVENT BASIS: V_phi is defined against the whole gas-free brine
+            # (V_phi = (V_solution - V_brine)/n_gas), so x2*V_phi is added to
+            # the brine volume, not to the water-only part of it. The flash x
+            # is salt-free, so (1-x2) moles of water carry a brine mass of
+            # W = (1-x2)*MWWAT/(1-S), S being the NaCl weight fraction. Using
+            # water mass alone inflates the dissolved-gas density effect by
+            # 1/(1-S): +5.6% at 1 mol/kg, +29% at 5 mol/kg NaCl.
+            S_wt = wt / 100.0
+            W = (1.0 - self.x_total) * MWWAT / (1.0 - S_wt)
+            numerator = W + self.x_total * mw_eff
+            denominator = self.x_total * vphi_eff + W / rho_brine_gcc
             rho_gas_brine_gcc = numerator / denominator
         else:
             rho_gas_brine_gcc = rho_brine_gcc
@@ -1834,12 +1906,13 @@ class SoreideWhitson:
                 continue
             gas_upper = gas_vle.upper()
             if gas_upper == 'CO2':
-                vis_factor *= (1.0 + _IC_A_CO2 * x_i ** _IC_B)
+                T_K = (degf - 32.0) / 1.8 + 273.15
+                vis_factor *= np.exp(_CAL_E1 * np.exp(-_CAL_E2 * (T_K / _CAL_T0 - 1.0)) * x_i)
             elif gas_upper == 'H2S':
                 vis_factor *= (1.0 + _IC_A_H2S * x_i ** _IC_B)
             elif gas_upper == 'CH4':
-                ratio = _OST_C0 + _OST_C1 * degf + _OST_C2 * degf ** 2
-                vis_factor *= max(ratio, 1.0)
+                T_K = (degf - 32.0) / 1.8 + 273.15
+                vis_factor *= 1.0 + _CH4_A * np.exp(_CH4_B / T_K) * x_i / (_CH4_K + x_i)
             # C2H6, N2, H2, C3H8, nC4H10: no correction (factor *= 1.0)
 
         vis_gas_brine = vis_base_cP * vis_factor
@@ -1915,12 +1988,11 @@ class SoreideWhitson:
                     continue
                 yi = x_i / self.x_total
                 gas_ply = _VLE_TO_PLYASUNOV.get(gas_vle, gas_vle.upper())
-                vphi_eff_p1 += yi * _plyasunov_V_phi(gas_ply, tKel, Mpa_p1)
+                vphi_eff_p1 += yi * _V_phi(gas_ply, tKel, Mpa_p1, self.vphi_route)
 
-            # Garcia Eq. 18 at P+1, same algebraically reformulated (non-singular)
-            # form as Step 3 — multiply top/bot through by M1*x1.
-            numerator_p1 = MWWAT * x1 + self.x_total * mw_eff
-            denom_p1 = self.x_total * vphi_eff_p1 + MWWAT * x1 / rho_brine_p1_gcc
+            # Garcia Eq. 18 at P+1, same gas-free-brine solvent basis as Step 3.
+            numerator_p1 = W + self.x_total * mw_eff
+            denom_p1 = self.x_total * vphi_eff_p1 + W / rho_brine_p1_gcc
             rho_p1_gcc = numerator_p1 / denom_p1
         else:
             rho_p1_gcc = rho_brine_p1_gcc

pyrestoolbox-3.7.2/pyrestoolbox/brine/pr_vphi.py

@@ -0,0 +1,246 @@
+"""V2inf of dissolved gases from the Soreide-Whitson modified PR EOS + VSHIFT.
+
+An alternative to `plyasunov_model.V2_inf`, built 2026-07-25. It is NOT a
+replacement: Plyasunov remains the reference and covers 8 gases to 573 K. This
+route exists because it is far more parsimonious and because it repairs the one
+V_phi defect the project has pinned (the H2S temperature trend).
+
+THE EXACT RELATION. For any pressure-explicit EOS the partial molar volume is
+
+    Vbar_2 = -(dP/dn2)_{T,V,n1} / (dP/dV)_{T,n}
+
+and at x2 -> 0 that is V2inf. No flash and no root selection for the solute: the
+volume root is the water-rich LIQUID root, and the gas enters only through b2
+and the cross term a12 = sqrt(a1 a2)(1 - kij). The solute never has a root of
+its own, so there is nothing to "force" into a liquid state.
+
+WHAT TO SAY WHEN CHALLENGED ON PR'S POOR WATER PROPERTIES. Two separate points,
+and the first is a scope point rather than a numerical one:
+
+  1. PR's water volumetrics never reach the delivered answer. This module
+     supplies V_phi ONLY. The solvent density rho1 in the Garcia mixing rule
+     comes from Spivey (`brine_properties.rho_brine`), never from this EOS. So
+     PR's water error is confined to an intermediate quantity that is then
+     calibrated against measured V_phi.
+
+  2. A constant shift absorbs an OFFSET but cannot fix a SHAPE, so the question
+     that matters is whether V_phi's T and P dependence survives. The answer is
+     empirical: one constant s per gas reproduces Hnedkovsky densimetry to 0.5%
+     mean absolute error for H2S, 0.9% for CO2 and 1.4% for CH4 across
+     298-473 K. Lead with that measurement, not with a story about errors
+     cancelling.
+
+Do NOT justify the temperature cap by citing PR's 15-17% water density error -
+that error is a FLAT systematic factor (density ratio PR/IF97 is 0.847 at 298 K
+and 0.820 at 473 K) and is precisely what the shift absorbs. The cap exists for
+two other reasons, given at `T_MAX`.
+
+VOLUME SHIFT. Peneloux translation v = v_EOS - sum(n_i c_i) gives, exactly,
+
+    V2inf(shifted) = V2inf(EOS) - c2,      c2 = s2 * b2
+
+so a constant s2 is a pure offset with no temperature or pressure shape. The
+shift is stored dimensionless (s = c/b, the standard VSHIFT convention) and
+b2 is the gas's PR co-volume.
+
+ONE PARAMETER PER GAS, NOT TWO. A held-out test (`fit_pr_vshift.py`) showed
+s(T) = s0 + s1/T overfits: on the 21 Murphy & Gaines H2S points it scored 1.3%
+mean absolute error against 0.6% for a constant s. Constant s is used.
+
+CALIBRATION BASIS: DIRECT VOLUMETRIC MEASUREMENT ONLY. See `fit_pr_vshift.py`
+for the set and the exclusions. Indirect determinations (solubility-versus-
+pressure, electrochemical) and V_phi inverted from brine density are excluded
+from the fit, the latter because they scatter five to seven times wider.
+
+PROVENANCE. Developed in ~/projects/garcia_extension (`code/pr_vphi_model.py`,
+calibrated by `code/fit_pr_vshift.py`) and ported here 2026-07-25. The S&W alpha,
+the aqueous kij correlations and the critical properties are taken from this
+package's own `_lib_vle_engine`, not re-copied.
+"""
+import numpy as np
+
+from . import _lib_vle_engine as _SW
+from ..plyasunov.iapws_if97 import p_sat_if97
+
+R = 8.31446261815324          # cm3.MPa/(mol.K), so volumes come out in cm3/mol
+
+# PR constants (Peng-Robinson 1976)
+_OMEGA_A = 0.45723553
+_OMEGA_B = 0.07779607
+
+# Validity envelope. Two reasons for the 473.15 K ceiling, neither of them the
+# 15-17% water density error (that is a flat offset and the shift absorbs it):
+#   (a) the calibration data stops there. Hnedkovsky's top point is 473.15 K, so
+#       anything above is unvalidated extrapolation of a fitted shift.
+#   (b) V2inf diverges at the SOLVENT critical point, and a cubic EOS gets the
+#       near-critical behaviour wrong in a way no constant offset can repair.
+#       Measured on this implementation, the PR/IF97 compressibility ratio for
+#       water is 0.27 at 298 K, 0.84 at 473 K, crosses 1.0 near 520 K and reaches
+#       1.32 by 613 K - i.e. a growing SHAPE error, not an offset. It shows up
+#       downstream as H2S drifting 9% by 523 K and 36% by 573 K.
+T_MIN, T_MAX = 273.15, 623.15
+T_CALIBRATED_MAX = 473.15   # top of the calibration data (Hnedkovsky)
+T_VOUCHED_MAX = 450.0       # ~350 degF; the only one of the three that is an
+                            # accuracy claim. T_MAX is where the arithmetic
+                            # stops (IF97 Region 1); T_CALIBRATED_MAX is where
+                            # the fitted shift stops being fitted.
+P_MAX = 100.0
+
+SUPPORTED = ('CH4', 'CO2', 'H2S', 'N2', 'H2', 'C2H6')
+
+# WATER ALPHA INSENSITIVITY, measured 2026-07-25 and worth knowing before
+# porting. The S&W framework uses `alpha_water_soreide` for the sw_original and
+# dropin frameworks but Mathias-Copeman (`alpha_water_mc3`) otherwise, and the
+# ResToolbox3 Dart path uses MC3. Swapping the water alpha moves V2inf_raw by
+# only 0.00 to 0.05 cm3/mol over 298-473 K, i.e. delta-s of 0.0002 to 0.0018,
+# under 2% of the shift values and negligible against the 0.5-1.4% fit error.
+# So ONE VSHIFT set is valid for both water alphas and the ports do not need
+# separate calibrations. (The alpha enters only a1, and its effect largely
+# cancels in the ratio of derivatives.)
+
+# Dimensionless volume shifts s = c2/b2, fitted to direct volumetric
+# measurements only by `fit_pr_vshift.py`. Regenerate with that script if any
+# calibration point changes; the values below are pinned in validation.py.
+VSHIFT = {
+    'CH4':  -0.109632,
+    'CO2':  -0.037913,
+    'H2S':  -0.078975,
+    'N2':   -0.155288,
+    'H2':   -0.177625,
+    'C2H6': -0.073142,
+}
+
+# Gases whose shift rests on 298 K data alone, so their temperature behaviour is
+# the EOS's unaided prediction and is NOT calibrated. Reported, not hidden.
+UNCALIBRATED_IN_T = ('N2', 'H2', 'C2H6')
+
+
+def _ab(species, T, m_nacl=0.0):
+    """PR a(T) and b for one species, cm6.MPa/mol2 and cm3/mol."""
+    c = _SW.COMPONENTS[species]
+    Pc = c.Pc / 1e6
+    Tr = T / c.Tc
+    if species == 'H2O':
+        alpha = _SW.alpha_water_soreide(Tr, m_nacl)
+    else:
+        alpha = _SW.alpha_standard_pr(Tr, c.omega)
+    return (_OMEGA_A * R ** 2 * c.Tc ** 2 / Pc * alpha,
+            _OMEGA_B * R * c.Tc / Pc)
+
+
+def b_covolume(gas):
+    """PR co-volume of the gas, cm3/mol - the normaliser for the VSHIFT."""
+    return _ab(gas, 300.0)[1]
+
+
+def _P_mix(T, V, n1, n2, gas, kij, m_nacl):
+    """PR pressure of the binary water + gas mixture, MPa. V in cm3, n in mol."""
+    a1, b1 = _ab('H2O', T, m_nacl)
+    a2, b2 = _ab(gas, T)
+    n = n1 + n2
+    x1, x2 = n1 / n, n2 / n
+    a12 = np.sqrt(a1 * a2) * (1.0 - kij)
+    am = x1 * x1 * a1 + 2.0 * x1 * x2 * a12 + x2 * x2 * a2
+    bm = x1 * b1 + x2 * b2
+    return (n * R * T / (V - n * bm)
+            - n * n * am / (V * V + 2.0 * n * bm * V - n * n * bm * bm))
+
+
+def v_water_liquid(T, P, m_nacl=0.0):
+    """Smallest real PR root for water/brine, cm3/mol.
+
+    Above water's critical temperature the cubic has one real root; below it the
+    smallest root is the liquid. Taking the minimum root is continuous across
+    both cases, which is what the derivative below needs.
+    """
+    a, b = _ab('H2O', T, m_nacl)
+    A = a * P / (R * T) ** 2
+    B = b * P / (R * T)
+    roots = np.roots([1.0, -(1.0 - B), A - 3.0 * B ** 2 - 2.0 * B,
+                      -(A * B - B ** 2 - B ** 3)])
+    real = roots[np.abs(roots.imag) < 1e-9].real
+    real = real[real > B]
+    if real.size == 0:
+        raise ValueError(f'No admissible PR liquid root for water at {T} K, {P} MPa')
+    return float(real.min()) * R * T / P
+
+
+def _check(gas, T, P):
+    if gas not in SUPPORTED:
+        raise ValueError(
+            f'{gas!r} has no fitted VSHIFT. Supported: {SUPPORTED}. Use '
+            f'plyasunov_model.V2_inf for the other gases.')
+    if not (T_MIN <= T <= T_MAX):
+        raise ValueError(
+            f'T = {T} K is outside the calibrated range {T_MIN}-{T_MAX} K. '
+            f'Above {T_MAX} K the fitted shift is unvalidated (the calibration '
+            f'data stops there) and the near-critical shape error grows; use '
+            f'plyasunov_model.V2_inf instead.')
+    if not (0.0 < P <= P_MAX):
+        raise ValueError(f'P = {P} MPa is outside 0 to {P_MAX} MPa.')
+    psat = float(p_sat_if97(T))
+    if P < psat:
+        raise ValueError(
+            f'P = {P} MPa is below the water saturation pressure {psat:.4f} MPa '
+            f'at {T} K, so the solvent is vapour and V2inf is undefined.')
+
+
+def V2_inf_raw(gas, T, P, m_nacl=0.0):
+    """Unshifted V2inf from the exact EOS relation, cm3/mol. No range guard."""
+    V = v_water_liquid(T, P, m_nacl)
+    kij = _SW.get_kij_aq(gas, T, m_nacl)
+    # dP/dn2 at fixed T, V, n1: one-sided, because n2 = 0 is the boundary
+    h = 1e-7
+    dPdn2 = (_P_mix(T, V, 1.0, h, gas, kij, m_nacl)
+             - _P_mix(T, V, 1.0, 0.0, gas, kij, m_nacl)) / h
+    dV = V * 1e-7
+    dPdV = (_P_mix(T, V + dV, 1.0, 0.0, gas, kij, m_nacl)
+            - _P_mix(T, V - dV, 1.0, 0.0, gas, kij, m_nacl)) / (2.0 * dV)
+    return -dPdn2 / dPdV
+
+
+def V2_inf(gas, T, P, m_nacl=0.0, s=None):
+    """Apparent molar volume of the dissolved gas at infinite dilution, cm3/mol.
+
+    Args:
+        gas: one of SUPPORTED
+        T: K, within T_MIN..T_MAX and above the water saturation pressure
+        P: MPa, up to P_MAX
+        m_nacl: NaCl molality. Enters the S&W water alpha and kij only; there is
+            NO salinity term on the volume shift, consistent with the project's
+            decision that a salt effect on V_phi is real but not applied
+            (see salt_effect_vphi.py). Leave at 0 for the calibrated behaviour.
+        s: override the dimensionless volume shift (for refitting).
+
+    Returns:
+        V2inf in cm3/mol.
+    """
+    _check(gas, T, P)
+    shift = VSHIFT[gas] if s is None else s
+    return V2_inf_raw(gas, T, P, m_nacl) - shift * b_covolume(gas)
+
+
+# `plyasunov_model` exposes V_phi as an alias for V2_inf; mirror that so the two
+# modules are drop-in comparable in scripts.
+V_phi = V2_inf
+
+
+def _demo():
+    print('S&W PR + VSHIFT, V2inf in cm3/mol (Plyasunov in brackets)')
+    from ..plyasunov import V2_inf as V_ply
+    print(f"\n  {'gas':<6}{'s':>10}{'b':>8}  " +
+          ''.join(f'{t:>18.0f} K' for t in (298, 348, 398, 448)))
+    for g in SUPPORTED:
+        cells = []
+        for T in (298.15, 348.15, 398.15, 448.15):
+            cells.append(f'{V2_inf(g, T, 20.0):7.2f} '
+                         f'[{float(V_ply(g, T, 20.0)):6.2f}]')
+        flag = ' *' if g in UNCALIBRATED_IN_T else ''
+        print(f'  {g:<6}{VSHIFT[g]:10.4f}{b_covolume(g):8.2f}  '
+              + ''.join(f'{c:>20}' for c in cells) + flag)
+    print('\n  * temperature behaviour is the EOS unaided: these gases have no '
+          'T-resolved\n    calibration data, only a 298 K cluster.')
+
+
+__all__ = ['V2_inf', 'V_phi', 'V2_inf_raw', 'b_covolume', 'v_water_liquid',
+           'VSHIFT', 'SUPPORTED', 'UNCALIBRATED_IN_T', 'T_MIN', 'T_MAX', 'P_MAX']

pyrestoolbox-3.7.2/pyrestoolbox/brine/vphi_route.py

@@ -0,0 +1,81 @@
+"""Which V_phi route supplies the dissolved-gas molar volume.
+
+DEFAULT CHANGED 2026-07-25: the delivered gas-saturated brine density uses the
+Soreide-Whitson modified-PR route with one dimensionless volume shift per gas,
+falling back to the Plyasunov A12inf model where PR is not calibrated. Plyasunov
+was the default only because it was implemented first.
+
+WHY PR IS PREFERRED. Against direct volumetric measurement PR wins on five of
+six gases (in-sample MAE: CH4 1.4 vs 1.5%, H2S 0.5 vs 1.4%, N2 3.3 vs 4.9%,
+H2 5.1 vs 6.2%, C2H6 3.0 vs 3.4%; it loses CO2, 0.9 vs 0.7%), and it is the only
+route that reproduces the H2S temperature trend - Murphy and Gaines measured
++0.69 cm3/mol between their cold and warm groups, PR gives +0.53, Plyasunov is
+flat at +0.02. It also costs one number per gas rather than 35 at eight
+significant digits plus IAPWS-IF97.
+
+NO TEMPERATURE HANDOVER (2026-07-25). An earlier version fell back to Plyasunov
+above 473 K, the top of the calibration data. It no longer does: PR runs to the
+IAPWS-IF97 Region 1 ceiling of 623.15 K. A mid-range handover bought nothing and
+put a discontinuity in the delivered default.
+
+That is not an accuracy claim. Accuracy is vouched for to about 300-350 degF
+(420-450 K); above that neither route is calibrated and neither is claimed. The
+practical envelope therefore sits inside the calibration data, and within it the
+two routes agree on brine density to 0.12% at worst.
+
+WHERE PR STILL CANNOT BE USED, and what happens instead:
+  * C3H8 and NC4H10 have no fitted volume shift, so they always use Plyasunov.
+  * Outside 273.15-623.15 K, above 100 MPa, or below the water saturation
+    pressure, where V2inf is undefined because the solvent is vapour.
+
+CAVEAT. N2, H2 and C2H6 have shifts fitted to a 298 K cluster only, so for those
+three the temperature dependence of the default route is the EOS unaided rather
+than calibrated. Plyasunov stays available via route='plyasunov'.
+"""
+
+from pyrestoolbox.plyasunov import V_phi as _plyasunov_V_phi
+
+from . import pr_vphi as _pr
+
+ROUTES = ("auto", "pr", "plyasunov")
+DEFAULT_ROUTE = "auto"
+
+
+def pr_applicable(gas: str, T: float, P: float) -> bool:
+    """True if the PR + VSHIFT route is calibrated for this gas and state."""
+    try:
+        _pr._check(gas, T, P)
+        return True
+    except (ValueError, KeyError):
+        return False
+
+
+def route_used(gas: str, T: float, P: float, route: str = DEFAULT_ROUTE) -> str:
+    """Which route V_phi would actually use. For reporting, never for logic."""
+    if route in ("pr", "plyasunov"):
+        return route
+    return "pr" if pr_applicable(gas, T, P) else "plyasunov"
+
+
+def V_phi(gas: str, T: float, P: float, route: str = DEFAULT_ROUTE,
+          m_nacl: float = 0.0) -> float:
+    """Dissolved-gas apparent molar volume at infinite dilution, cm3/mol.
+
+    Args:
+        gas: gas name ('CO2', 'CH4', 'H2S', 'N2', 'H2', 'C2H6', 'C3H8', 'NC4H10')
+        T: temperature, K
+        P: pressure, MPa
+        route: 'auto' uses PR where calibrated and Plyasunov elsewhere; 'pr'
+            forces PR and raises outside its box; 'plyasunov' forces A12inf.
+        m_nacl: NaCl molality, passed to the PR route only, where it enters the
+            S&W water alpha and kij. There is no salinity term on the volume
+            shift itself; leave at 0 for the calibrated behaviour.
+    """
+    if route not in ROUTES:
+        raise ValueError(f"route must be one of {ROUTES}, got {route!r}")
+    if route == "plyasunov":
+        return float(_plyasunov_V_phi(gas, T, P))
+    if route == "pr":
+        return float(_pr.V2_inf(gas, T, P, m_nacl))
+    return (float(_pr.V2_inf(gas, T, P, m_nacl)) if pr_applicable(gas, T, P)
+            else float(_plyasunov_V_phi(gas, T, P)))

{pyrestoolbox-3.7.1 → pyrestoolbox-3.7.2}/pyrestoolbox/docs/brine.rst

@@ -450,11 +450,11 @@ Pure CO2 case at 5000 psia x 275 deg F and 3% NaCl brine:
     >>> from pyrestoolbox import brine
     >>> mix = brine.SoreideWhitson(pres=5000, temp=275, ppm=30000, y_CO2=1.0, metric=False)
     >>> mix.bDen  # Returns [Gas Saturated, Gas-Free Brine, Freshwater]
-    [0.973376988330695, 0.968164592979362, 0.9476497407774847]
+    [0.9731117228519672, 0.968164592979362, 0.9476497407774847]
     >>> mix.Rs  # Returns per-gas Rs dict (scf/stb)
-    {'CO2': 139.57908352590252}
+    {'CO2': 139.5790835259016}
     >>> mix.bw  # Returns [Gas Saturated, Gas-Free, Freshwater]
-    [1.096443890843725, 1.0543023174291248, 1.0542033190822462]
+    [1.096613263262556, 1.0543023174291248, 1.0542033190822462]
 
 Pure CH4 case (SG=0.554) at 5000 psia x 275 deg F and 3% NaCl brine:
 
@@ -464,7 +464,7 @@ Pure CH4 case (SG=0.554) at 5000 psia x 275 deg F and 3% NaCl brine:
     >>> mix.Rs
     {'CH4': 21.21234560600256}
     >>> mix.bDen
-    [0.9641136914617666, 0.968164592979362, 0.9476497407774847]
+    [0.9641391918061833, 0.968164592979362, 0.9476497407774847]
 
 Mixed gas (10% CO2, 5% H2S, SG=0.7) at 200 Bar x 80 degC and 10,000 ppm NaCl: