pyrestoolbox 3.1.4__tar.gz → 3.2.0__tar.gz

{pyrestoolbox-3.1.4 → pyrestoolbox-3.2.0}/PKG-INFO

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

{pyrestoolbox-3.1.4 → pyrestoolbox-3.2.0}/pyproject.toml

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

@@ -2100,9 +2100,12 @@ class SWMultiComponentFlash:
         z = np.asarray(z, dtype=float)
         z = z / np.sum(z)
 
-        # Rust acceleration path — gamma is always passed explicitly
-        # to prevent Rust from using its built-in ks model (which lacks
-        # the specialised Dubessy/Akinfiev models for CO2/H2S).
+        # Rust acceleration path — gamma is always passed explicitly.
+        # The Rust entry point trusts the caller-supplied gamma and never
+        # substitutes its own S&W Eq 8 ks fallback. framework='proposed'
+        # specialised ks models (Dubessy CO2, Akinfiev H2S, Li HC,
+        # Mao-Duan N2, Duan-Sun CO2) are applied in self.calc_gamma()
+        # on the Python side.
         if _RUST_AVAILABLE:
             try:
                 gamma_arr = np.asarray(gamma, dtype=float) if gamma is not None \

{pyrestoolbox-3.1.4 → pyrestoolbox-3.2.0}/pyrestoolbox/brine/brine.py

@@ -456,6 +456,7 @@ class CO2_Brine_Mixture():
                 .Rs      : CO2 Saturated Brine solution gas ratio (sm3/sm3 or scf/stb), relative to standard conditions
                 .Cf_usat : Brine undersaturated compressibility (1/Bar or 1/psi). The compressibility with constant Rs
                 .Cf_sat  : Brine saturated compressibility (1/Bar or 1/psi). The compressibility with reducing Rs under depletion
+                .converged: True if the Spycher-Pruess fugacity iteration reached tolerance, False otherwise
                             
             Usage example for 5000 psia x 275 deg F and 3% NaCl brine:
                 mix = brine.CO2_Brine_Mixture(pres = 5000, temp = 275, ppm = 30000, metric = False)
@@ -523,6 +524,7 @@ class CO2_Brine_Mixture():
         self.Cf_sat = None                # Saturated brine compressibility (1/Bar or 1/psi). Compressibility with changing Rs
         self.CO2_sat = False              # Flag to determine if in P-T range for saturated liquid CO2 K values
         self.repeat = False               # Flag to trigger repeat of calculations depending on whether CO2 is saturated liquid phase
+        self.converged = True             # Spycher-Pruess fugacity iteration convergence flag
         #self.EzrokhiDenA = None           # Ezrokhi coefficient array for density (to be calculated with ezrokhi() function)
         #self.EzrokhiVisB = None           # Ezrokhi coefficient array for viscosity (to be calculated with ezrokhi() function)
         self.Rs_STD = None                # Dissolved CO2 remaining at standard conditions (sm3/sm3)
@@ -1125,6 +1127,7 @@ class CO2_Brine_Mixture():
                 iternum += 1
 
             if err > EPS:
+                self.converged = False
                 import warnings
                 warnings.warn(
                     f"Spycher CO2-brine iteration did not converge in {iternum} iterations "
@@ -1266,11 +1269,14 @@ 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
-            xRat = xCO2 / xNotCO2                        #--Mole Fraction Ratio, Gas/Brine
             mRat = MwG / MwB                             #--Mole Weight Ratio  , Gas/Brine
             vPhi = partMolVol(tKel)                      #--Apparent Molar Volume of Dissolved CO2
-            return (1.0 + mRat * xRat) / (vPhi * xRat / MwB + 1.0 / rhoBRnoCO2) # --Equation 18 of Garcia paper
+            return MwB * (xNotCO2 + mRat * xCO2) / (vPhi * xCO2 + MwB * xNotCO2 / rhoBRnoCO2)
         
         # 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
@@ -1798,23 +1804,15 @@ class SoreideWhitson:
                 vphi_eff += yi * _plyasunov_V_phi(gas_ply, tKel, Mpa)
                 mw_eff += yi * _plyasunov_gas_mw(gas_ply)
 
-            # Garcia Eq. 18 in g/cm3:
-            # rho = (1 + x2*M2/(M1*x1)) / (x2*V_phi/(M1*x1) + 1/rho1)
+            # 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
-            if x1 < 1e-6:
-                # Near-pure gas phase: Garcia mixing rule breaks down
-                import warnings
-                warnings.warn(
-                    f"Gas mole fraction x_total={self.x_total:.4f} is too high for "
-                    "Garcia density mixing rule. Returning unsaturated brine density.",
-                    RuntimeWarning, stacklevel=2
-                )
-                rho_gas_brine_gcc = rho_brine_gcc
-            else:
-                numerator = 1.0 + self.x_total * mw_eff / (M1 * x1)
-                denominator = self.x_total * vphi_eff / (M1 * x1) + 1.0 / rho_brine_gcc
-                rho_gas_brine_gcc = numerator / denominator
+            numerator = M1 * x1 + self.x_total * mw_eff
+            denominator = self.x_total * vphi_eff + M1 * x1 / rho_brine_gcc
+            rho_gas_brine_gcc = numerator / denominator
         else:
             rho_gas_brine_gcc = rho_brine_gcc
 

{pyrestoolbox-3.1.4 → pyrestoolbox-3.2.0}/pyrestoolbox/dca/dca.py

@@ -59,6 +59,13 @@ if _RUST_AVAILABLE:
     from pyrestoolbox import _native as _rust
 
 
+def _fmt_array(a, name):
+    if a is None:
+        return f"{name}=None"
+    arr = np.asarray(a)
+    return f"{name}=ndarray(shape={arr.shape}, dtype={arr.dtype})"
+
+
 @dataclass
 class DeclineResult:
     """Result from decline curve fitting.
@@ -97,6 +104,18 @@ class DeclineResult:
     uptime_mean: Optional[float] = None
     uptime_history: Optional[np.ndarray] = None
 
+    def __repr__(self):
+        scalars = (
+            f"method={self.method!r}, qi={self.qi}, di={self.di}, b={self.b}, "
+            f"a={self.a}, m={self.m}, r_squared={self.r_squared}, "
+            f"uptime_mean={self.uptime_mean}"
+        )
+        return (
+            f"DeclineResult({scalars}, "
+            f"{_fmt_array(self.residuals, 'residuals')}, "
+            f"{_fmt_array(self.uptime_history, 'uptime_history')})"
+        )
+
 
 @dataclass
 class ForecastResult:
@@ -122,6 +141,16 @@ class ForecastResult:
     eur: float
     secondary: Optional[dict] = None
 
+    def __repr__(self):
+        sec = 'None' if self.secondary is None else f"{{{', '.join(self.secondary.keys())}}}"
+        return (
+            f"ForecastResult("
+            f"{_fmt_array(self.t, 't')}, "
+            f"{_fmt_array(self.q, 'q')}, "
+            f"{_fmt_array(self.Qcum, 'Qcum')}, "
+            f"eur={self.eur}, secondary={sec})"
+        )
+
 
 @dataclass
 class RatioResult:
@@ -152,6 +181,13 @@ class RatioResult:
     r_squared: float = 0.0
     residuals: np.ndarray = field(default_factory=lambda: np.array([]))
 
+    def __repr__(self):
+        return (
+            f"RatioResult(method={self.method!r}, a={self.a}, b={self.b}, "
+            f"c={self.c}, domain={self.domain!r}, r_squared={self.r_squared}, "
+            f"{_fmt_array(self.residuals, 'residuals')})"
+        )
+
 
 def arps_rate(qi, di, b, t):
     """Arps decline rate.
@@ -287,10 +323,13 @@ def duong_cum(qi, a, m, t):
     if np.any(t <= 0):
         raise ValueError("Time must be positive for Duong model")
 
-    # Generate fine time grid for integration
+    # Generate fine time grid for integration. Lower bound must be strictly
+    # less than ti to give np.linspace an ascending range, otherwise trapezoid
+    # integrates over a descending axis and returns negative cumulative.
     results = np.zeros_like(t, dtype=float)
     for i, ti in enumerate(t):
-        t_fine = np.linspace(0.001, ti, max(500, int(ti * 10)))
+        lower = min(0.001, ti * 0.001)
+        t_fine = np.linspace(lower, ti, max(500, int(ti * 10)))
         q_fine = qi * t_fine ** (-m) * np.exp(a / (1.0 - m) * (t_fine ** (1.0 - m) - 1.0))
         results[i] = np.trapezoid(q_fine, t_fine)
 
@@ -922,6 +961,12 @@ def forecast(result, t_end, dt=1.0, q_min=0.0, uptime=1.0, ratios=None):
     -------
     ForecastResult
     """
+    if dt <= 0:
+        raise ValueError(f"dt must be positive, got {dt}")
+    if t_end <= 0:
+        raise ValueError(f"t_end must be positive, got {t_end}")
+    if not (0.0 < uptime <= 1.0):
+        raise ValueError(f"uptime must be in (0, 1], got {uptime}")
     t = np.arange(dt, t_end + dt / 2, dt)
 
     if result.method == 'duong':

{pyrestoolbox-3.1.4 → pyrestoolbox-3.2.0}/pyrestoolbox/docs/changelist.rst

@@ -1,3 +1,42 @@
+Changelist in 3.2.0:
+
+- **DCA bug fixes**:
+
+  - ``dca.duong_cum`` — fixed linspace-inversion bug where cumulative volume integrated over a descending axis for ``t < 0.001`` (small-t inputs) and returned a negative value. Lower bound of the integration is now ``min(0.001, t * 0.001)`` so the grid is always ascending.
+  - ``dca.forecast`` — now validates ``dt > 0``, ``t_end > 0`` and ``uptime`` in ``(0, 1]`` at entry with clear ``ValueError`` messages. Previously ``dt = 0`` raised an opaque ``ZeroDivisionError`` and out-of-range ``uptime`` was silently accepted.
+
+- **Rachford-Rice solver consolidation**: ``simtools.rr_solver`` is now a thin wrapper that delegates to the canonical ``pyrestoolbox.brine._lib_vle_engine.rr_solver`` (Nielsen & Lia 2022). Removes ~100 lines of duplicated iterative code plus the dead ``ensure_numpy_array`` helper. Inputs validated for length/sum before delegation; behaviour is preserved (``EPS_T=1e-15``, ``max_iter=100``).
+
+- **Rust Sechenov fallback guard**: ``src/vle/mod.rs::flash_tp_rust`` no longer silently substitutes its S&W Eq 8 ``ks`` fallback when a caller passes all-ones ``gamma`` with ``salinity > 0``. The caller-supplied ``gamma`` is now always trusted, eliminating any risk that Python ``framework='proposed'`` calls bypass the specialised Dubessy/Akinfiev/Li/Mao-Duan/Duan-Sun ``ks`` models. ``calc_equilibrium_rust`` retains the S&W Eq 8 path but now carries a prominent doc warning. Python path unchanged (Python always passes the correct ``gamma``).
+
+- **Convergence flag on ``CO2_Brine_Mixture``**: New ``.converged`` attribute on the class. ``True`` after a successful Spycher-Pruess fugacity iteration, ``False`` when the 100-iteration limit is hit (matching the existing ``RuntimeWarning``). Lets downstream callers detect non-convergence programmatically.
+
+- **``sensitivity.tornado`` robustness**: Raises ``ValueError`` if ``base_result`` is not finite (NaN/Inf), and if any ``ranges[param]`` has ``lo > hi``. Previously returned ``nan`` or ``inf`` sensitivities that silently corrupted tornado plots.
+
+- **``layer`` module dedup**: Five copies of the EXP/LANG dispatch (B-clamp, flow-fraction evaluation) consolidated into three private helpers (``_clamp_b``, ``_b_max``, ``_flow_fraction_at_x``). No behaviour change.
+
+- **``recommend`` module docstrings**: ``sg`` on ``recommend_gas_methods`` and ``well_type`` on ``recommend_vlp_method`` are currently unused by the decision logic. Docstrings now flag them as reserved for future rules. Signatures preserved for backward compatibility.
+
+- 701 validation tests (up from 696 in 3.1.5).
+
+Changelist in 3.1.5:
+
+- **Agent-friendly UX**:
+
+  - ``validate_methods`` invalid-method errors now list valid options (e.g. ``Invalid zmethod: 'NOSUCH'. Valid options: ['DAK', 'HY', 'WYW', 'BNS', 'BUR']``). New ``validate_choice`` helper used by all ``nodal`` public entry points (``fbhp``, ``outflow_curve``, ``ipr_curve``, ``operating_point``) to validate ``well_type``.
+  - ``simtools.zip_check_sim_deck`` and ``simtools.ix_extract_problem_cells`` accept a ``non_interactive=True`` kwarg that raises a ``ValueError`` instead of prompting on ``input()``. Safe for scripts and agents without stdin.
+  - ``simtools.make_vfpinj``/``make_vfpprod`` BHP-failure warnings now use ``warnings.warn`` instead of ``print``.
+  - ``DeclineResult``, ``ForecastResult``, ``RatioResult`` ``__repr__`` now summarise array fields as ``ndarray(shape=..., dtype=...)`` so printing a result doesn't flood agent transcripts.
+  - ``nodal`` unit-validation errors (``Reservoir.__init__``, ``WellSegment.__init__``) echo the user's original value and unit (e.g. ``got -1 m``) rather than the post-conversion internal number.
+
+- **Release-blocking numerical fixes**:
+
+  - **Garcia CO2-brine density**: Algebraic reformulation of Eq 18 (``brine.garciaDensity`` and ``SoreideWhitson._calc_properties``) removes the ``xCO2 → 1`` singularity. Finite rho at ``xCO2 = 1`` equals ``MwG / vPhi``. Mathematically identical to the old formula for ``xCO2 < 1`` (regression: 1e-12).
+  - **``oil.Rs_velarde`` at atmospheric ``pb``**: Now returns ``0.0`` when ``pb <= psc`` instead of emitting NaN from a ``0/0`` division.
+  - **``oil.sg_evolved_gas`` silent NaN**: Now calls ``validate_pe_inputs`` at entry; zero pressure or zero ``sg_sp`` raises ``ValueError`` instead of returning NaN.
+
+- 696 validation tests (up from 691 in 3.1.4).
+
 Changelist in 3.1.4:
 
 - **Tier 4 brine improvements**: Adaptive VLE damping in ``flash_tp`` and ``calc_water_content_with_kij`` (replaces fixed 0.7/0.9 factors), ``V2_inf`` cached via ``functools.lru_cache(256)`` in Plyasunov model, ``build_kij_matrix`` cached per ``(T_K, mode)`` on VLE engine instance. Rust VLE flash updated with matching adaptive damping. All three brine models (``CH4_Brine``, ``CO2_Brine_Mixture``, ``SoreideWhitson``) now accept ``p``/``degf``/``wt`` and ``pres``/``temp``/``ppm`` parameter aliases.

{pyrestoolbox-3.1.4 → pyrestoolbox-3.2.0}/pyrestoolbox/layer/layer.py

@@ -41,6 +41,35 @@ import numpy.typing as npt
 
 from pyrestoolbox.shared_fns import bisect_solve
 
+
+_B_MIN = 1e-6
+_B_MAX_EXP = 709
+_B_MAX_LANG = 25000
+
+
+def _b_max(method: str) -> float:
+    """Upper bookend for B in bisection for the given Lorenz method."""
+    return _B_MAX_LANG if method == "LANG" else _B_MAX_EXP
+
+
+def _clamp_b(B: float, method: str) -> float:
+    """Clamp B to [_B_MIN, _b_max(method)]."""
+    return min(max(B, _B_MIN), _b_max(method))
+
+
+def _flow_fraction_at_x(B: float, x: float, method: str) -> float:
+    """Flow fraction from best phi_h fraction x, given B and method.
+
+    EXP:  (1 - exp(-B*x)) / (1 - exp(-B))
+    LANG: (VL * x) / (PL + x) with PL = 1/B, VL = PL + 1
+    """
+    if method == "LANG":
+        PL = 1 / B
+        VL = PL + 1
+        return (VL * x) / (PL + x)
+    return (1 - np.exp(-B * x)) / (1 - np.exp(-B))
+
+
 def lorenz2b(lorenz: float, lrnz_method: str = "EXP") -> float:
     """ Returns B-factor that characterizes the Lorenz function
         Lorenz: Lorenz coefficient (0-1)
@@ -63,37 +92,22 @@ def lorenz2b(lorenz: float, lrnz_method: str = "EXP") -> float:
         return 0.0  # Homogeneous — no heterogeneity
 
     if lorenz < 0.000333:
-        B = 2 / 1000
-        if method == "LANG":
-            B = 1 / 1000
-        return B
+        return 1 / 1000 if method == "LANG" else 2 / 1000
     if lorenz > 0.997179125528914:
-        B = 709
-        if method == "LANG":
-            B = 25000
-        return B
+        return _b_max(method)
 
-    # Set bookends for B
-    hi = 709
-    if method == "LANG":
-        hi = 25000
-    lo = 0.000001
+    hi = _b_max(method)
+    lo = _B_MIN
     args = (lorenz, method)
 
     def LorenzErr(args, B):
         lorenz, method = args
-        B = max(B, 0.000001)
-        if method == "EXP":
-            B = min(B, 709)
-            err = 2 * ((1 / (np.exp(B) - 1)) - (1 / B)) + 1 - lorenz
-        else:
-            B = min(B, 25000)
+        B = _clamp_b(B, method)
+        if method == "LANG":
             PL = 1 / B
             VL = PL + 1
-            err = (
-                VL - PL * VL * np.log(VL) + PL * VL * np.log(PL) - 0.5
-            ) * 2 - lorenz
-        return err
+            return (VL - PL * VL * np.log(VL) + PL * VL * np.log(PL) - 0.5) * 2 - lorenz
+        return 2 * ((1 / (np.exp(B) - 1)) - (1 / B)) + 1 - lorenz
 
     rtol = 0.0000001
     return bisect_solve(args, LorenzErr, lo, hi, rtol)
@@ -113,16 +127,12 @@ def lorenzfromb(B: float, lrnz_method: str = "EXP") -> float:
     method = lrnz_method.upper()
     if B <= 0:
         return 0.0  # B=0 means homogeneous (Lc=0)
-    B = max(B, 0.000001)
+    B = _clamp_b(B, method)
     if method == "LANG":
-        B = min(B, 25000)
         PL = 1 / B
         VL = PL + 1
-        L = (VL - PL * VL * np.log(VL) + PL * VL * np.log(PL) - 0.5) * 2
-    else:
-        B = min(B, 709)
-        L = 2 * (1 / (np.exp(B) - 1) - (1 / B)) + 1
-    return L
+        return (VL - PL * VL * np.log(VL) + PL * VL * np.log(PL) - 0.5) * 2
+    return 2 * (1 / (np.exp(B) - 1) - (1 / B)) + 1
 
 
 def lorenz_from_flow_fraction(
@@ -155,23 +165,15 @@ def lorenz_from_flow_fraction(
         return lorenzfromb(B, method)
 
     # Set bookends and first guess of B
-    hi = 709
-    lo = 0.000001
+    hi = _B_MAX_EXP
+    lo = _B_MIN
     args = (kh_frac, phih_frac, method)
 
     def BErr(args, B):
         kh_frac, phih_frac, method = args
         method = method.upper()
-        B = max(B, 0.000001)
-        if method == "EXP":
-            B = min(B, 709)
-            err = (1 - np.exp(-B * phih_frac)) / (1 - np.exp(-B)) - kh_frac
-        else:
-            B = min(B, 25000)
-            PL = 1 / B
-            VL = PL + 1
-            err = (VL * phih_frac) / (PL + phih_frac) - kh_frac
-        return err
+        B = _clamp_b(B, method)
+        return _flow_fraction_at_x(B, phih_frac, method) - kh_frac
 
     rtol = 0.0000001
     B = bisect_solve(args, BErr, lo, hi, rtol)
@@ -203,16 +205,8 @@ def lorenz_2_flow_frac(
     if B < 0:  # Need to calculate B
         B = lorenz2b(lorenz=lorenz, lrnz_method=lrnz_method)
 
-    B = max(B, 0.000001)
-    if method == "EXP":
-        B = min(B, 709)
-        fraction = (1 - np.exp(-B * phih_frac)) / (1 - np.exp(-B))
-    else:
-        B = min(B, 25000)
-        PL = 1 / B
-        VL = PL + 1
-        fraction = (VL * phih_frac) / (PL + phih_frac)
-    return fraction
+    B = _clamp_b(B, method)
+    return _flow_fraction_at_x(B, phih_frac, method)
 
 
 def lorenz_2_layers(
@@ -255,11 +249,7 @@ def lorenz_2_layers(
     if B < 0:  # Need to calculate B
         B = lorenz2b(lorenz=lorenz, lrnz_method=lrnz_method)
 
-    B = max(B, 0.000001)
-    if method == "EXP":
-        B = min(B, 709)
-    else:
-        B = min(B, 25000)
+    B = _clamp_b(B, method)
 
     user_layers = False
     if len(phi_h_fracs) > 1:
@@ -280,12 +270,7 @@ def lorenz_2_layers(
     sumkh = []
 
     for layer in phih:
-        if method == "EXP":
-            sumkh.append((1 - np.exp(-B * layer)) / (1 - np.exp(-B)))
-        else:
-            PL = 1 / B
-            VL = PL + 1
-            sumkh.append((VL * layer) / (PL + layer))
+        sumkh.append(_flow_fraction_at_x(B, layer, method))
 
     kh = (
         np.array([sumkh[i] - sumkh[i - 1] for i in range(1, len(sumkh))])

{pyrestoolbox-3.1.4 → pyrestoolbox-3.2.0}/pyrestoolbox/nodal/nodal.py

@@ -47,7 +47,7 @@ import warnings
 import numpy as np
 
 from pyrestoolbox.classes import vlp_method, class_dic
-from pyrestoolbox.validate import validate_methods
+from pyrestoolbox.validate import validate_methods, validate_choice
 from pyrestoolbox.shared_fns import bisect_solve, validate_pe_inputs
 from pyrestoolbox.constants import (BAR_TO_PSI, PSI_TO_BAR, degc_to_degf, degf_to_degc,
                                     M_TO_FT, FT_TO_M, MM_TO_IN, IN_TO_MM,
@@ -306,16 +306,19 @@ class WellSegment:
     def __init__(self, md, id, deviation=0, roughness=None, metric=False):
         if roughness is None:
             roughness = 0.01524 if metric else 0.0006  # 0.0006 in = 0.01524 mm
+        _md_in, _id_in, _rough_in = md, id, roughness
+        _unit_len = 'm' if metric else 'ft'
+        _unit_dia = 'mm' if metric else 'in'
         if metric:
             md = md * M_TO_FT
             id = id * MM_TO_IN
             roughness = roughness * MM_TO_IN
         if md <= 0:
-            raise ValueError(f"Measured depth md must be positive, got {md}")
+            raise ValueError(f"Measured depth md must be positive, got {_md_in} {_unit_len}")
         if id <= 0:
-            raise ValueError(f"Internal diameter id must be positive, got {id}")
+            raise ValueError(f"Internal diameter id must be positive, got {_id_in} {_unit_dia}")
         if roughness < 0:
-            raise ValueError(f"Roughness must be non-negative, got {roughness}")
+            raise ValueError(f"Roughness must be non-negative, got {_rough_in} {_unit_dia}")
         if not (0 <= deviation <= 90):
             raise ValueError(f"Deviation must be between 0 and 90 degrees, got {deviation}")
         self.md = md  # stored in ft
@@ -573,6 +576,9 @@ class Reservoir:
         metric: If True, inputs in metric units (barsa, degC, m, day/sm3). Default False.
     """
     def __init__(self, pr, degf, k, h, re, rw, S=0, D=0, metric=False):
+        # Preserve original user-facing values for error messages
+        _pr_in, _degf_in, _h_in, _re_in, _rw_in = pr, degf, h, re, rw
+        _unit_len = 'm' if metric else 'ft'
         if metric:
             pr = pr * BAR_TO_PSI
             degf = degc_to_degf(degf)
@@ -585,11 +591,14 @@ class Reservoir:
         if k <= 0:
             raise ValueError(f"Permeability k must be positive, got {k}")
         if h <= 0:
-            raise ValueError(f"Net pay thickness h must be positive, got {h}")
+            raise ValueError(f"Net pay thickness h must be positive, got {_h_in} {_unit_len}")
         if rw <= 0:
-            raise ValueError(f"Wellbore radius rw must be positive, got {rw}")
+            raise ValueError(f"Wellbore radius rw must be positive, got {_rw_in} {_unit_len}")
         if re <= rw:
-            raise ValueError(f"Drainage radius re ({re}) must be greater than wellbore radius rw ({rw})")
+            raise ValueError(
+                f"Drainage radius re ({_re_in} {_unit_len}) must be greater than "
+                f"wellbore radius rw ({_rw_in} {_unit_len})"
+            )
         self.pr = pr  # stored in psia
         self.degf = degf  # stored in degF
         self.k = k  # mD (same in both systems)
@@ -1705,6 +1714,7 @@ def fbhp(thp, completion, vlpmethod='WG', well_type='gas',
                 rsb = rsb * SM3_PER_SM3_TO_SCF_PER_STB
 
     validate_pe_inputs(p=thp)
+    validate_choice(well_type, ('gas', 'oil'), 'well_type')
     vlpmethod = validate_methods(["vlpmethod"], [vlpmethod])
 
     # Extract oil PVT parameters if provided (already in oilfield units from OilPVT)
@@ -1791,6 +1801,7 @@ def outflow_curve(thp, completion, vlpmethod='WG', well_type='gas',
                 'rates': list of flow rates (MMscf/d for gas, STB/d for oil; sm3/d if metric)
                 'bhp': list of flowing BHP values (psia; barsa if metric) at each rate
     """
+    validate_choice(well_type, ('gas', 'oil'), 'well_type')
     # Convert metric inputs to oilfield at the boundary
     if metric:
         thp = thp * BAR_TO_PSI
@@ -1877,6 +1888,7 @@ def ipr_curve(reservoir, well_type='gas', gas_pvt=None, oil_pvt=None,
         gsg: Gas specific gravity. Used if gas_pvt not provided
         metric: If True, inputs/outputs in Eclipse METRIC units. Default False.
     """
+    validate_choice(well_type, ('gas', 'oil', 'water'), 'well_type')
     if min_pwf is None:
         min_pwf = 1.01325 if metric else 14.7
     if metric:
@@ -1991,6 +2003,7 @@ def operating_point(thp, completion, reservoir,
             vlp: VLP outflow curve dict
             ipr: IPR inflow curve dict
     """
+    validate_choice(well_type, ('gas', 'oil'), 'well_type')
     # Convert metric inputs to oilfield at the boundary
     if metric:
         thp = thp * BAR_TO_PSI

{pyrestoolbox-3.1.4 → pyrestoolbox-3.2.0}/pyrestoolbox/oil/_correlations.py

@@ -324,6 +324,10 @@ def oil_rs(
             raise ValueError(
                 "Missing one of the required inputs: sg_sp, api, rsb, for the Velarde, Blasingame & McCain Rs calculation"
             )
+        # Degenerate: pb at (or below) atmospheric means no dissolved gas can evolve.
+        # Skip the correlation; the 0/0 in pr would otherwise return NaN silently.
+        if pb - psc <= 0:
+            return 0.0
         xs = [_VEL_RS_A, _VEL_RS_B, _VEL_RS_C]
         a = [
             x[0]

{pyrestoolbox-3.1.4 → pyrestoolbox-3.2.0}/pyrestoolbox/oil/_separator.py

@@ -19,6 +19,7 @@ def sg_evolved_gas(
         api: Stock tank oil density (API)
         sg_sp: Specific gravity of separator gas (relative to air)
     """
+    validate_pe_inputs(p=p, degf=degf, sg=sg_sp)
 
     if (
         p > _SGEVOL_THRESHOLD

{pyrestoolbox-3.1.4 → pyrestoolbox-3.2.0}/pyrestoolbox/recommend/recommend.py

@@ -75,7 +75,9 @@ def recommend_gas_methods(sg: float = 0.65, co2: float = 0, h2s: float = 0,
     Parameters
     ----------
     sg : float
-        Gas specific gravity (default 0.65).
+        Gas specific gravity (default 0.65). Currently unused by the decision
+        logic — accepted for API consistency and reserved for future rules
+        (e.g. heavy gas / condensate-laden streams). Breaking removal deferred.
     co2 : float
         CO2 mole fraction (default 0).
     h2s : float
@@ -90,6 +92,7 @@ def recommend_gas_methods(sg: float = 0.65, co2: float = 0, h2s: float = 0,
     dict of str to MethodRecommendation
         Keys: 'zmethod', 'cmethod'.
     """
+    _ = sg  # reserved, see docstring
     inerts = co2 + h2s + n2 + h2
     recs = {}
 
@@ -204,13 +207,16 @@ def recommend_vlp_method(deviation: float = 0,
     deviation : float
         Maximum wellbore deviation from vertical in degrees (default 0).
     well_type : str
-        'gas' or 'oil' (default 'gas').
+        'gas' or 'oil' (default 'gas'). Currently unused by the decision logic
+        — accepted for API consistency and reserved for future fluid-specific
+        recommendations. Breaking removal deferred.
 
     Returns
     -------
     dict of str to MethodRecommendation
         Key: 'vlp_method'.
     """
+    _ = well_type  # reserved, see docstring
     recs = {}
 
     if deviation <= 30:

{pyrestoolbox-3.1.4 → pyrestoolbox-3.2.0}/pyrestoolbox/sensitivity/sensitivity.py

@@ -39,6 +39,7 @@ __all__ = [
     'SweepResult', 'TornadoEntry', 'TornadoResult',
 ]
 
+import math
 from dataclasses import dataclass, field
 from typing import Callable, Dict, Any, List, Optional
 
@@ -172,11 +173,21 @@ def tornado(func: Callable, base_kwargs: Dict[str, Any],
     base_raw = func(**base_kwargs)
     base_val = _extract_result(base_raw, result_key)
     base_result = float(base_val)
+    if not math.isfinite(base_result):
+        raise ValueError(
+            f"base_result is not finite ({base_result}); "
+            f"tornado sensitivities would be undefined. "
+            f"Check base_kwargs and result_key."
+        )
 
     entries = []
     for param, (lo, hi) in ranges.items():
         if param not in base_kwargs:
             raise ValueError(f"Parameter '{param}' not found in base_kwargs")
+        if lo > hi:
+            raise ValueError(
+                f"ranges['{param}'] = ({lo}, {hi}): low must be <= high"
+            )
 
         kwargs_lo = dict(base_kwargs)
         kwargs_lo[param] = lo