pyrestoolbox 3.7.5__tar.gz → 3.7.7__tar.gz

pyrestoolbox-3.7.7/.github/complexity-baseline.json

@@ -0,0 +1,34 @@
+{
+  "pyrestoolbox/brine/_lib_vle_engine.py::SWBinaryVLE.calc_gas_solubility": 16,
+  "pyrestoolbox/brine/_lib_vle_engine.py::SWMultiComponentFlash.build_kij_matrix": 18,
+  "pyrestoolbox/brine/_lib_vle_engine.py::SWMultiComponentFlash.calc_equilibrium": 24,
+  "pyrestoolbox/brine/_lib_vle_engine.py::calc_gas_brine_equilibrium": 29,
+  "pyrestoolbox/brine/brine.py::CO2_Brine_Mixture.__init__": 18,
+  "pyrestoolbox/brine/brine.py::SoreideWhitson.__init__": 28,
+  "pyrestoolbox/brine/brine.py::SoreideWhitson._calc_properties": 19,
+  "pyrestoolbox/brine/brine.py::brine_props": 19,
+  "pyrestoolbox/dca/dca.py::fit_decline": 17,
+  "pyrestoolbox/dca/dca.py::fit_decline_cum": 22,
+  "pyrestoolbox/dca/dca.py::forecast": 16,
+  "pyrestoolbox/dca/dca.py::hyp2_from_eur": 18,
+  "pyrestoolbox/gas/_hydrate.py::gas_hydrate": 26,
+  "pyrestoolbox/gas/gas.py::gas_ponz2p": 16,
+  "pyrestoolbox/gas/gas.py::gas_tc_pc": 16,
+  "pyrestoolbox/gas/gas.py::gas_ug": 16,
+  "pyrestoolbox/matbal/matbal.py::gas_matbal": 26,
+  "pyrestoolbox/matbal/matbal.py::oil_matbal": 35,
+  "pyrestoolbox/nodal/nodal.py::Completion.__init__": 21,
+  "pyrestoolbox/nodal/nodal.py::_bb_flow_pattern": 18,
+  "pyrestoolbox/nodal/nodal.py::_prepare_flow_inputs": 16,
+  "pyrestoolbox/nodal/nodal.py::ipr_curve": 27,
+  "pyrestoolbox/nodal/nodal.py::operating_point": 18,
+  "pyrestoolbox/oil/_compressibility.py::oil_co": 16,
+  "pyrestoolbox/oil/_correlations.py::oil_pbub": 16,
+  "pyrestoolbox/oil/_harmonize.py::oil_harmonize": 16,
+  "pyrestoolbox/shared_fns/shared_fns.py::validate_pe_inputs": 43,
+  "pyrestoolbox/simtools/_decks.py::_crawl_deck_includes": 16,
+  "pyrestoolbox/simtools/_decks.py::ix_extract_problem_cells": 41,
+  "pyrestoolbox/simtools/_vfp.py::_format_vfpprod": 19,
+  "pyrestoolbox/simtools/_vfp.py::_vfpprod_axes_to_oilfield": 24,
+  "pyrestoolbox/simtools/_vfp.py::make_vfpinj": 20
+}

pyrestoolbox-3.7.7/.github/scripts/check_complexity.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Cyclomatic-complexity ratchet for pyrestoolbox.
+
+Fails when a function's McCabe complexity exceeds MAX_COMPLEXITY unless that
+function is already recorded in the baseline at its recorded value or lower.
+The point is to stop new branching accreting, not to force a rewrite of the
+functions that are already large - those are listed in the baseline and can only
+get simpler.
+
+Usage:
+    python3 .github/scripts/check_complexity.py            # check
+    python3 .github/scripts/check_complexity.py --update   # rewrite the baseline
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+MAX_COMPLEXITY = 15
+PACKAGE = "pyrestoolbox"
+BASELINE = Path(__file__).resolve().parent.parent / "complexity-baseline.json"
+SKIP_DIRS = ("/tests/", "\\tests\\")
+
+
+def measure():
+    """Return {"path::function": complexity} for every function in the package."""
+    out = subprocess.run(
+        [sys.executable, "-m", "radon", "cc", "-j", PACKAGE],
+        capture_output=True, text=True, check=True,
+    ).stdout
+    scores = {}
+    for path, blocks in json.loads(out).items():
+        if any(d in "/" + path.replace("\\", "/") + "/" for d in ("/tests/",)):
+            continue
+        if isinstance(blocks, dict):  # radon reports parse errors as a dict
+            continue
+        for b in blocks:
+            name = f"{b['classname']}.{b['name']}" if b.get("classname") else b["name"]
+            key = f"{path.replace(chr(92), '/')}::{name}"
+            scores[key] = max(scores.get(key, 0), b["complexity"])
+    return scores
+
+
+def main():
+    scores = measure()
+    over = {k: v for k, v in scores.items() if v > MAX_COMPLEXITY}
+
+    if "--update" in sys.argv:
+        BASELINE.write_text(json.dumps(dict(sorted(over.items())), indent=2) + "\n")
+        print(f"Wrote {len(over)} entries to {BASELINE.name}")
+        return 0
+
+    baseline = json.loads(BASELINE.read_text()) if BASELINE.exists() else {}
+
+    new = {k: v for k, v in over.items() if k not in baseline}
+    worse = {k: (baseline[k], v) for k, v in over.items() if k in baseline and v > baseline[k]}
+    better = {k: (baseline[k], scores.get(k, 0)) for k in baseline
+              if scores.get(k, 0) < baseline[k]}
+
+    for key, (was, now) in sorted(better.items()):
+        print(f"improved  {key}: {was} -> {now}")
+
+    if not new and not worse:
+        if better:
+            print("\nRun with --update to lock in the improvements above.")
+        print(f"\nOK - no function above {MAX_COMPLEXITY} outside the baseline.")
+        return 0
+
+    print(f"\nCyclomatic complexity above {MAX_COMPLEXITY}:")
+    for key, val in sorted(new.items()):
+        print(f"  NEW     {key}: {val}")
+    for key, (was, now) in sorted(worse.items()):
+        print(f"  WORSE   {key}: {was} -> {now}")
+    print(
+        "\nSplit the function, or - if the branching is irreducible - run\n"
+        "  python3 .github/scripts/check_complexity.py --update\n"
+        "and say why in the commit message."
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/.github/workflows/tests.yml

@@ -62,3 +62,37 @@ jobs:
 
       - name: Run full test suite (Rust + parity)
         run: python3 -m pytest pyrestoolbox/tests/ -q
+
+  # ── Complexity ratchet (new code only; existing offenders baselined) ─
+  complexity:
+    name: Complexity ratchet
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install radon
+        run: pip install radon
+
+      - name: Check cyclomatic complexity against baseline
+        run: python3 .github/scripts/check_complexity.py
+
+  # ── Rust lint ratchet (clippy clean; any new warning fails) ─────────
+  rust-lint:
+    name: Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+
+      - name: Install m4 (needed by gmp-mpfr-sys for the rug crate)
+        run: sudo apt-get update -qq && sudo apt-get install -y -qq m4
+
+      - name: Clippy
+        run: cargo clippy --all-targets -- -D warnings

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/.gitignore

@@ -54,4 +54,6 @@ benchmark_*.py
 zstar_*
 pyresToolbox_rust_acceleration_instructions.md
 pyrestoolbox-mcp-email.txt
+DEFECTS-FOUND-*.md
+PORT-SPEC-*.md
 *.zip

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/Cargo.lock

@@ -152,7 +152,7 @@ dependencies = [
 
 [[package]]
 name = "pyrestoolbox-native"
-version = "3.7.5"
+version = "3.7.7"
 dependencies = [
  "pyo3",
  "rug",

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pyrestoolbox-native"
-version = "3.7.5"
+version = "3.7.7"
 edition = "2021"
 license = "GPL-3.0-or-later"
 description = "Rust acceleration extensions for pyResToolbox"

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/PKG-INFO

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

pyrestoolbox-3.7.7/clippy.toml

@@ -0,0 +1,7 @@
+# Reservoir-engineering kernels legitimately carry ~10 physical quantities
+# (composition, criticals, temperature, geometry), and grouping unrelated
+# scalars into a struct just to satisfy a count makes them harder to read, not
+# easier. 12 is the line: past that you are passing a record and should say so,
+# which is why pseudopressure.rs has GasState. Clippy's default of 7 is too low
+# for this crate.
+too-many-arguments-threshold = 12

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/mcp/pyrestoolbox_mcp/server.py

@@ -46,6 +46,13 @@ mcp = FastMCP(
         "recommend_methods(...) if unsure which correlation method suits a "
         "fluid. All inputs default to oilfield units (psia, deg F, ft, mD, "
         "cP); pass metric=True for Eclipse METRIC units where supported. "
+        "IMPORTANT: parameter NAMES keep their oilfield spelling under "
+        "metric=True. `degf` then takes deg C, `p`/`pr`/`pwf` take barsa, and "
+        "lengths take m; the docstring unit notation `(deg F | deg C)` gives "
+        "the field value first and the metric value second. Passing a "
+        "Fahrenheit value to `degf` with metric=True converts it twice and "
+        "returns a wrong answer silently. Standard volumes are always at "
+        "60 deg F and 14.696 psia, so metric sm3 is on that basis. "
         "Full module documentation is available as docs:// resources."
     ),
 )
@@ -104,6 +111,11 @@ def describe(name: str) -> str:
 
     name is 'module.function', e.g. 'gas.gas_z' or 'dca.fit_decline'.
     Also see the docs://<module> resources for worked examples.
+
+    Units live in the docstring, not the signature, which is why annotations
+    are stripped below. A parameter documented `(deg F | deg C)` takes the
+    first under the default and the second when metric=True; the parameter
+    name itself never changes.
     """
     _, obj = _resolve(name)
     target = obj.__init__ if inspect.isclass(obj) else obj
@@ -128,6 +140,10 @@ def call(name: str, arguments: dict = {}) -> dict:
 
     name is 'module.function', e.g. 'gas.gas_z'. arguments is a JSON object
     of keyword arguments, e.g. {"p": 2000, "sg": 0.75, "degf": 200}.
+    That example is oilfield units. With {"metric": true} the same keys take
+    metric values, so `degf` would be deg C and `p` barsa; the names do not
+    change. Call describe(name) first and read its unit notation: `(deg F |
+    deg C)` means field first, metric second.
     Correlation methods are strings (e.g. "zmethod": "DAK"); an invalid
     method string returns an error listing the valid options. Gas and brine
     functions accept lists for pressure-like inputs; oil functions are

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pyrestoolbox"
-version = "3.7.5"
+version = "3.7.7"
 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.5 → pyrestoolbox-3.7.7}/pyrestoolbox/brine/brine.py

@@ -119,6 +119,13 @@ _SPIVEY_SC_MPA = 0.1013
 # Methane specific gravity
 _SG_METHANE = 0.5537
 
+# Maximum passes over the K-value/mixing-rule/cubic block in co2BrineSolubility.
+# The CO2-rich root class (gas or liquid CO2) selects the K_CO2 coefficients but
+# is only known after the cubic, so the block repeats until the assumption is
+# self-consistent. Near the root-selection boundary the two classes can
+# alternate, hence the bound.
+_CO2_SAT_MAX_PASSES = 5
+
 # Spycher-Pruess K-value coefficients (low-temperature, non-saturated CO2)
 _SP_K_CO2_LT = [1.189, 1.304e-2, -5.446e-5]
 _SP_K_H2O_LT = [-2.209, 3.097e-2, -1.098e-4, 2.048e-7]
@@ -906,6 +913,51 @@ class CO2_Brine_Mixture():
     #  DOI 10.1007/s11242-009-9425-y
     #============================================================================
     
+    def solve_root_class(self):
+    #=======================================================================
+    #  K-values, compositions, mixing rules and cubic under one root class
+    #=======================================================================
+        """Solve the CO2-rich phase until its root class is self-consistent.
+
+        K_CO2 needs to know whether that phase is gas or liquid CO2, but that is
+        only settled by the cubic, which raises self.repeat when the root class
+        changes. Repeat until the assumption the K-values were evaluated under is
+        the one the cubic returns. The flag is reset first: left set by an earlier
+        solve on this object (the cw_sat pre-pass half a bar above the target
+        pressure) it would otherwise skip the block and leave a stale molar volume
+        in the fugacity coefficients.
+        """
+        self.repeat = False
+        for _pass in range(_CO2_SAT_MAX_PASSES):
+            #==k-Parameters (y/x partitioning factors) Equations 5 and 6 =========
+            self.K_CO2()
+
+            #== First estimates of yCO2 and xCO2 =================================
+            if not self.low_temp:
+                yCO2 = 1 - self.est_yH2O() # Paper suggests using Psat/P, but this empirical fit appears more accurate
+                xCO2 = yCO2 / self.K[0]
+            else:
+                yCO2 = 1.0
+                xCO2 = 0.0
+
+            self.y = np.array([yCO2, 1.0-yCO2])
+            self.x = np.array([xCO2, 1.0-xCO2])
+
+            # Trigger mixing rules
+            self.aMix_RK()
+            self.bMix_RK()
+
+            #--Solve the Cubic Equation A-2 -------------------------------------
+            self.MolarVolume()
+
+            if not self.repeat:  # Root class matched the assumption - converged
+                return
+        warnings.warn(
+            f"CO2_Brine_Mixture: CO2-rich root class did not settle in "
+            f"{_CO2_SAT_MAX_PASSES} passes at {self.pBar:.2f} bar, "
+            f"{self.degC:.2f} degC; using the last solution"
+        )
+
     def co2BrineSolubility(self):
         """ Calculates CO2-brine mutual solubilities at self.pBar, self.degC
             and self.ppm (Spycher & Pruess 2010). Takes no arguments and
@@ -918,10 +970,11 @@ class CO2_Brine_Mixture():
         """
         if _RUST_AVAILABLE:
             try:
-                xco2, yco2, yh2o, rhogas, gasz, conv = _rust.co2_brine_solubility_rust(
+                xco2, yco2, yh2o, rhogas, gasz, conv, co2_sat = _rust.co2_brine_solubility_rust(
                     self.pBar, self.degC, self.ppm
                 )
                 self.converged = conv
+                self.CO2_sat = co2_sat  # Root class the solve settled on
                 self.x = np.array([xco2, 1.0 - xco2 - (self.xSalt if self.xSalt else 0.0)])
                 self.y = np.array([yco2, yh2o])
                 self.rhoGas = rhogas
@@ -986,33 +1039,9 @@ class CO2_Brine_Mixture():
         
         #==k-Parameters (y/x partitioning factors) Equations 5 and 6 ==========================
         self.K_H2O()
-        i =0
-        while not self.repeat:
-            i+=1
-            if i > 1:
-                break
-                
-            #==k-Parameters (y/x partitioning factors) Equations 5 and 6 ==========================
-            self.K_CO2()
-            
-            #== First estimates of yCO2 and xCO2 ================================================
-            if not self.low_temp:
-                yCO2 = 1 - self.est_yH2O() # Paper suggests using Psat/P, but this empirical fit appears more accurate
-                xCO2 = yCO2 / self.K[0]
-            else:
-                yCO2 = 1.0
-                xCO2 = 0.0
-            
-            self.y = np.array([yCO2, 1.0-yCO2])
-            self.x = np.array([xCO2, 1.0-xCO2])    
-            
-            # Trigger mixing rules
-            self.aMix_RK()
-            self.bMix_RK()
 
-            #--Solve the Cubic Equation A-2 --------------------------------------------
-            self.MolarVolume()
-        
+        self.solve_root_class()
+
         #--Calculate Fugacity Coefficients*Pressure---------------------------------------
         self.fugP()
         

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/pyrestoolbox/brine/pr_vphi.py

@@ -107,12 +107,12 @@ _SW_NAME = {'NC4H10': 'nC4H10'}
 # 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.176510,
-    'H2':   -0.177625,
-    'C2H6': -0.073142,
+    'CH4':  -0.111430,
+    'CO2':  -0.038965,
+    'H2S':  -0.079740,
+    'N2':   -0.176768,
+    'H2':   -0.178503,
+    'C2H6': -0.073843,
     # C3H8 added 2026-07-25. NOT fitted to a densimetric data set, because none
     # exists for propane in water. Set from the only two direct 298 K
     # determinations available, Moore (1982) 70.7 and Zhou & Battino (2001)
@@ -120,7 +120,7 @@ VSHIFT = {
     # is their mean, giving V_phi = 72.85 at 298 K. Those two disagree by 6.1%,
     # which is the honest uncertainty on this gas and is far wider than for any
     # other. It replaces a fallback that sat BELOW both of them (66.99).
-    'C3H8': -0.112963,
+    'C3H8': -0.113326,
     # NC4H10 added 2026-07-25 from Moore (1982) Table I, 76.6 +/- 0.1 cm3/mol
     # (2 runs; his stated overall imprecision is +/-1.5). Two oddities that
     # should not be smoothed over: the shift is POSITIVE, alone among the
@@ -128,7 +128,7 @@ VSHIFT = {
     # run +18.4, +17.8, then +5.9). Adopted because it is the only direct
     # measurement of this quantity, but it is a single lab and two runs, and
     # C4 sits outside the five-gas validated scope.
-    'NC4H10': +0.110924,
+    'NC4H10': +0.110920,
 }
 
 # Gases whose shift rests on 298 K data alone, so their temperature behaviour is
@@ -213,10 +213,12 @@ def V2_inf_raw(gas, T, P, m_nacl=0.0):
     # Switched from finite differences 2026-07-31; the difference evaluation
     # agrees to 4e-5 cm3/mol, its truncation error.
     v = v_water_liquid(T, P, m_nacl)
-    # Pinned to the 'mc3' kij_AQ set, which is what the VSHIFT values below were
-    # fitted against. This must not follow the library's default framework: the
-    # shift and the kij are one calibration and cannot be mixed across sets.
-    kij = _SW.get_kij_aq(_SW_NAME.get(gas, gas), T, m_nacl, framework='mc3')
+    # Pinned to the 'default' kij_AQ set (the published S&W-refresh
+    # recommendation), which is what the VSHIFT values below are fitted
+    # against since 2026-09-01. The pin stays explicit even while it matches
+    # the library default: the shift and the kij are one calibration and must
+    # not silently follow a future default move.
+    kij = _SW.get_kij_aq(_SW_NAME.get(gas, gas), T, m_nacl, framework='default')
     a1, b1 = _ab('H2O', T, m_nacl)
     a2, b2 = _ab(gas, T)
     a12 = np.sqrt(a1 * a2) * (1.0 - kij)

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/pyrestoolbox/brine/vphi_route.py

@@ -48,7 +48,9 @@ DEFAULT_ROUTE = "auto"
 # brine-density data: the seven Tiepel & Gubbins (1972) KCl dilatometry points,
 # fitted as (generated by brine_props/code/relative_salt_shift.py)
 #     V_eff = V_phi(T,P) * (1 + g(m)),  g(m) = -c*m/(1 + d*m)
-# giving -1.56% at 1 molal and -5.85% at 5 molal. Enns and O'Sullivan & Smith
+# giving -1.52% at 1 molal and -5.27% at 5 molal (Tiepel's molar KCl
+# concentrations converted to molality at 25 degC since 2026-09-05; the
+# molar-as-molal fit gave -1.56% / -5.85%). Enns and O'Sullivan & Smith
 # agree on sign and size; the magnitude is known to about a factor of two
 # (O'Sullivan NaCl shallower, Tiepel KCl at this value).
 #
@@ -56,7 +58,7 @@ DEFAULT_ROUTE = "auto"
 # -0.03 to -0.07 cm3/mol per molal, an order of magnitude too small and linear
 # where the measurements saturate. It is therefore not used, and this term
 # carries the whole effect, so there is no double counting.
-SALT_C, SALT_D = 0.017009386, 0.090684173   # 8 sig digits, generated - do not retype
+SALT_C, SALT_D = 0.017061208, 0.12370899    # 8 sig digits, generated - do not retype
 
 
 def salt_fraction(m_nacl: float) -> float:

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/pyrestoolbox/docs/brine.rst

@@ -180,6 +180,8 @@ pyrestoolbox.brine.CO2_Brine_Mixture
    * - CO2 Corrected Brine Viscosity
      - Calabrese et al. (2019) Eq. 25, a temperature-dependent increment fitted to 415 measured brine points. **Changed in 3.7.2**, superseding Islam-Carlson (2012), which carries no temperature dependence and overstates the effect by 3.5x at 366 K and 9.4x at 423 K.
 
+**Known limit near the CO2 critical point**: the CO2-rich phase water content (``.y[1]``) and density (``.rhoGas``) are unreliable between about 31 and 38 degC at 73-100 bar, where they can step sharply with pressure. The low-temperature Redlich-Kwong parameterisation has its own pseudo-critical temperature of 311 K, 7 K above CO2's real 304.13 K, so a spurious two-root region survives above the true critical point and the published root-selection criterion steps between branches inside it. The step is intrinsic to using this cubic there (gating the root selection on the real CO2 phase boundary only relocates it), so it is documented rather than patched. Brine density, brine viscosity and CO2 solubility (``.x``, ``.Rs_sat``) are continuous through it and unaffected.
+
 .. list-table:: Inputs
    :widths: 10 15 40
    :header-rows: 1
@@ -707,9 +709,12 @@ exactly. The PR
 route needs one fitted number per gas against 35 coefficients per gas for the
 correlation, matches or beats it on five of six gases against the calibration
 densimetry, and reproduces an H2S temperature trend the correlation misses.
-The delivered shifts are CH4 -0.109632, CO2 -0.037913, H2S -0.078975,
-N2 -0.176510, H2 -0.177625, C2H6 -0.073142, C3H8 -0.112963 and
-nC4H10 +0.110924.
+The delivered shifts are CH4 -0.111430, CO2 -0.038965, H2S -0.079740,
+N2 -0.176768, H2 -0.178503, C2H6 -0.073843, C3H8 -0.113326 and
+nC4H10 +0.110920. They are fitted against the ``'default'`` kij_AQ set and the
+route pins that framework internally (refitted in 3.7.7; the values before it
+went with the ``'mc3'`` set the route pinned until then). A shift and the kij
+set it was fitted against are one calibration, so the two are never mixed.
 
 Three ceilings should not be conflated: the arithmetic stops at 623.15 K, the
 volume shift stops being fitted at 473.15 K, and **accuracy is claimed only to
@@ -721,9 +726,11 @@ the equation of state unaided.
 **Salinity shift on V_phi** (new in 3.7.3; relative form from 3.7.4). A
 gas-generic dimensionless fraction is applied,
 ``V_eff = V_phi(T,P) * (1 + g(m))`` with
-``g(m) = -1.7009 m/(1 + 0.090684 m)`` percent, giving -1.56% at 1 mol/kg and
--5.85% at 5 mol/kg (for CO2, -0.5 to -2.7 cm3/mol over the working range). It
-is fixed entirely from Tiepel and Gubbins (1972) KCl dilatometry with no
+``g(m) = -1.7061 m/(1 + 0.12371 m)`` percent, giving -1.52% at 1 mol/kg and
+-5.27% at 5 mol/kg (for CO2, -0.5 to -2.4 cm3/mol over the working range). It
+is fixed entirely from Tiepel and Gubbins (1972) KCl dilatometry, their molar
+concentrations converted to molality at 25 degC (from 3.7.7; the 3.7.4 fit
+treated them as molal: -1.56% / -5.85%), with no
 parameter fitted to any brine-density data; the magnitude is known to about a
 factor of two. Freshwater results are unchanged exactly; gas-saturated brine
 densities move by up to a few hundredths of a percent. Pass

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/pyrestoolbox/docs/changelist.rst

@@ -1,3 +1,25 @@
+Changelist in 3.7.7:
+
+- **BRINE DENSITY: the dissolved-gas volume shifts refitted under the published ``'default'`` framework** (``brine.pr_vphi.VSHIFT``). A volume shift and the S&W kij_AQ set it was fitted against are one calibration and cannot be mixed, so the module pinned ``framework='mc3'``. The reference calibration has moved to the published recommendation, the ``'default'`` embedded delta-kij framework, and the shifts move with it: CH4 -0.111430 (was -0.109632), CO2 -0.038965 (-0.037913), H2S -0.079740 (-0.078975), N2 -0.176768 (-0.176510), H2 -0.178503 (-0.177625) and C2H6 -0.073843 (-0.073142), with the two literature-anchored gases re-derived on the same basis at C3H8 -0.113326 and nC4H10 +0.110920. The pin stays explicit at ``'default'`` so that a later move of the library default cannot silently cross the shifts with a kij set they were not fitted against. V_phi moves by up to 0.14% (CH4 at 350 K and 20 MPa, 39.4072 to 39.4624 cm3/mol), gas-saturated brine density by under 0.002%, and Cf_sat, being a difference of two densities, by 0.025%.
+
+- **BRINE DENSITY: the V_phi salinity fraction refitted on molality** (``brine.vphi_route.salt_fraction``). Tiepel and Gubbins' KCl concentrations are molar; the 3.7.4 fit treated them as molal. Converted with the KCl solution density at 25 degC (1, 2, 4 mol/L = 1.033, 2.133, 4.587 mol/kg) and refitted, ``g(m) = -1.7061 m/(1 + 0.12371 m)`` percent replaces ``-1.7009 m/(1 + 0.090684 m)``: -1.52% at 1 mol/kg (was -1.56%) and -5.27% at 5 (was -5.85%). Gas-saturated brine density moves by under 0.03% at 5 mol/kg; freshwater results are unchanged exactly.
+
+- **GAS docstrings carry both unit systems, and the MCP server states the convention.** Every ``gas`` parameter that the code converts under ``metric=True`` now shows both halves on its own parameter line in the ``(field | metric)`` form, 31 lines across nine functions. Parameter *names* never change, so ``degf`` takes deg C under ``metric=True`` and a reader who stops at the name converts twice and is silently wrong. ``pyrestoolbox-mcp``'s instructions, ``call`` and ``describe`` now say so, and also that standard volumes stay on the 60 degF, 14.696 psia basis in both unit systems. Documentation only, no numerical change.
+
+Changelist in 3.7.6:
+
+- **OIL Rs: the Velarde, Blasingame & McCain correlation now refuses fluids it cannot represent, instead of returning negative Rs.** For rich separator gas with a light oil at a high bubble point, the correlation's leading coefficient a0 exceeds 1 and the published form ``rsr = a0*pr^a1 + (1-a0)*pr^a2`` turns negative over most of the pressure range: at 45 API, 200 degF, sg_sp 1.0 and pb 6000 psia it returned -421 scf/stb at 1000 psia, recovering only near Pb where the form is pinned to rsb by construction, and downstream ``oil_viso`` failed on a complex intermediate. The coefficients match the 1997 paper, so this is a range limit rather than a transcription error; a 72,900-case sweep found ``a0 > 1`` an exact test, with every such case non-physical and no ``a0 <= 1`` case affected. The boundary at 200 degF sits near Pb 5000 psia at sg_sp 1.0 with 45 API, or 8100 psia at sg_sp 0.85 with 35 API, falling roughly 10% per 100 degF of heating. ``oil_rs(rsmethod='VELAR')`` now raises ``ValueError`` naming the inputs, the offending coefficient and ``rsmethod='STAN'`` as the working alternative (Valko-McCain is not offered because its own Pb ceiling refuses most of the same corner). The same fluids are refused once at the nodal VLP entry points, where the segment march carries its own copy of the formula and the Rust path would otherwise return NaN silently.
+
+- **OIL DENSITY, Bo AND Co at low GOR: the McCain cofb polynomial is floored at Rsb = 1 scf/stb** (``_COFB_RSB_MIN``, Python and Rust both). cofb takes ln(Rsb) and is unbounded as Rsb falls: 2.6e-05 1/psi at 500 scf/stb, 3.3e-05 at 0.1, 8.9e-04 at 0.01, infinite at zero, and zero GOR is an ordinary state for a dead oil. Before the fix a 35 API dead-oil case returned ``oil_deno`` of infinity at rs = 1e-4 and 2985 kg/m3 (denser than water) at 1e-3, ``oil_bo`` of 0.0 and 0.285, and black-oil tables carried Co = inf in every row on the Rust path; the two paths also disagreed, Python raising ``ZeroDivisionError`` where Rust substituted ln(rsb) = 0 at exactly zero and still diverged either side of it. The polynomial is well behaved from 1 scf/stb upward, so nothing at or above the floor moves; the dead-oil case now returns 803.24 kg/m3 flat from rs = 0 to 0.1, identical on both paths. The correlation's validity floor of 14.696 psia is now stated in the ``oil_deno`` docs; at that floor the SWMH temperature term anchors a dead oil to within 0.6% of the thermally expanded stock-tank density on its own, so no atmospheric pin is applied.
+
+- **OIL Co at p == pb == 14.696 psia returns the undersaturated compressibility instead of zero.** The explicit method clamps its difference stencil to standard pressure below and Pb above; with all three equal the stencil collapsed to a point and the fallback divided a zero numerator, returning -0.0 in every dead-oil table row that reached standard pressure. The stencil now steps forward into the undersaturated branch, where Bo is continuous, giving 2.512e-05 1/psi at 35 API and 200 degF.
+
+- **CO2-BRINE: the liquid-CO2 K-value set is now reachable, and a ``cw_sat=True`` state leak is fixed.** Spycher & Pruess (2010) publish a second log(K0) coefficient set for liquid CO2, selected by the root class of a cubic that only runs after the K-values are used; the loop meant to repeat the block on a root-class change could never take a second pass, so the liquid set was dead code and below 31 degC the K-values came from the gas coefficients while the molar volume came from the liquid root. The block now repeats until the root class is self-consistent (bounded at 5 passes), in Python and Rust both. Effects confine to the liquid-CO2 region: 50 bar at 12 degC now settles on the liquid root, and at 72.2 bar and 32.35 degC the gas water content moves +0.007%, the two coefficient sets being close. Separately, the ``cw_sat=True`` pre-pass could leave the repeat flag set, making the main solve skip its cubic and reuse a stale molar volume (74.65 instead of 167.73 cm3/gmol at 72 bar and 32.35 degC, an 88% error in the CO2-rich phase water content, Python path only), and the Rust path never returned the root class at all, so ``CO2_sat`` read False whenever the extension was loaded. Both fixed; results at the frozen 200 bar / 80 degC and 5000 psia / 275 degF baselines are untouched.
+
+- **CO2-BRINE known limit documented**: the CO2-rich phase water content and density are unreliable between about 31 and 38 degC at 73-100 bar, where they can step sharply with pressure (+85% in one 0.2 bar step at 32.35 degC). The low-temperature RK parameterisation has its own pseudo-critical temperature of 311 K, 7 K above CO2's real 304.13 K, so a spurious two-root region survives above the true critical point. A root-selection gate on the real CO2 phase boundary was implemented, measured and reverted, because it only relocates the step: the model is 42-112% dense against Span-Wagner through that wedge whichever root is taken. Brine density, brine viscosity and CO2 solubility are continuous through it and unaffected, which is why the limit went unnoticed. Stated in ``brine.rst``.
+
+- **Internal: maintainability pass.** Duplicated flow-input handling in nodal and a doubly-written Havlena-Odeh denominator in matbal collapsed into single copies; the three most complex simtools functions decomposed, with nine new deck round-trip tests; per-function cyclomatic-complexity ratchets added to CI for Python (McCabe over 15 fails unless baselined) and Rust (clippy -D warnings, threshold 12); the crate brought clippy-clean. No numerical change.
+
 Changelist in 3.7.5:
 
 - **NEW: gas caloric properties.** ``gas.gas_thermal(p, sg, degf, co2, h2s, n2, h2, tc, pc, metric)`` returns enthalpy, Cp, Cv and the Joule-Thomson coefficient from the BNS 5-component Peng Robinson model (Burgoyne, Nielsen & Stanko 2025, SPE-229932-MS), vectorised over pressure, field or metric units. The library previously had no enthalpy or heat-capacity code at all. BNS only: DAK and HY are Z-factor correlations and carry no caloric content. Two things differ from the reference implementation at github.com/mwburgoyne/5_Component_PengRobinson_Z-Factor: the Peneloux volume shift is carried into the caloric path (leaving Cp and Cv invariant but shifting H by ``-c_mix*p`` and JT by ``+c_mix/Cp``, which takes the JT bias against a reference EOS from +4.2% to +0.7% for pure CO2 and from +12.0% to +5.9% for pure methane), and Gibbs-criterion root selection is shared with ``gas_z`` so Z and the caloric properties can never resolve to different roots. Known limits, stated in the docs: Cp errs by about -24% close to the CO2 critical point, where a cubic cannot represent the heat-capacity ridge, and departure enthalpy for lean hydrocarbon gas carries about a -11% systematic bias. Use a reference EOS for dense-phase CO2.

{pyrestoolbox-3.7.5 → pyrestoolbox-3.7.7}/pyrestoolbox/docs/oil.rst

@@ -44,7 +44,7 @@ pyResToolBox uses class objects to track calculation options through the functio
      - Method for calculating solution gas-oil ratio. Defaults to 'VELAR'
        Options are:
 
-       + 'VELAR': Velarde, Blasingame & McCain (1999)
+       + 'VELAR': Velarde, Blasingame & McCain (1999). Raises ValueError for high-Pb rich-separator-gas fluids (see ``oil_rs``)
        + 'STAN': Standing Correlation (1947)
        + 'VALMC': Valko-McCain Correlation (2003) - Only for oil_rs_bub (Rs at Pb)
    * - comethod
@@ -484,6 +484,8 @@ pyrestoolbox.oil.oil_rs
 
 Returns solution gas oil ratio (scf/stb, or sm3/sm3 if metric=True) calculated with different correlations. Either pb, rsb or both need to be specified. If one is missing, the other will be calculated from correlation
 
+With ``rsmethod='VELAR'`` this raises ``ValueError`` when the fluid falls outside the Velarde correlation's range. The correlation's leading coefficient grows with Pb, separator gas gravity and API, and once it passes 1 the correlation returns negative Rs over the lower part of the pressure range. The affected corner is rich separator gas with a light oil at a high bubble point, and the boundary falls as temperature rises: Pb above about 5900 psia at 100 degF or 4600 psia at 300 degF for sg_sp 1.0 with 45 API, and above about 9500 psia at 100 degF or 7300 psia at 300 degF for sg_sp 0.85 with 35 API. Use ``rsmethod='STAN'`` for those fluids - ``'VALMC'`` usually refuses the same corner, because its bubble point inversion has a ceiling that overlaps it.
+
 .. list-table:: Inputs
    :widths: 10 15 40
    :header-rows: 1